Skip navigation links

oracle.irm.j2ee.jws.rights.context
Interface DomainOperationsEndpoint

public interface DomainOperationsEndpoint

Web Service end point interface for Domain Operations.

WSDL

The WSDL for this end point interface can be downloaded from the server using the following URL:

 http://irm.example.com/irm_services/domain_operations?wsdl
 

Endpoint URL

Requests for this web service should be sent to the following URL:

 https://irm.example.com/irm_services/domain_operations
 

Method Summary

void	addDomainAdministrators(DomainRef domain, AccountRef[] accounts) Add one or more administrators to a domain.
void	addDomainManagers(DomainRef domain, AccountRef[] accounts) Add one or more managers to a domain.
void	deleteDomain(DomainRef domain) Delete a domain.
Account[]	listAccountDetails(AccountRef[] accounts) Retrieve the name and account type from one or more account UUID values.
AccountRef[]	listDomainAdministrators(DomainRef domain) List domain administrators.
AccountRef[]	listDomainManagers(DomainRef domain) List domain managers.
Domain[]	listDomains() List domains that the calling principal is authorized to access.
void	removeDomainAdministrators(DomainRef domain, AccountRef[] accounts) Remove one or more administrators from a domain.
void	removeDomainManagers(DomainRef domain, AccountRef[] accounts) Remove one or more domain managers from a domain.
Domain	saveChangesToDomain(Domain domain, Domain delta) Save changes to a domain.
Domain	saveNewDomain(Domain domain) Create a new domain.
Domain	saveNewDomainWithAdministrator(Domain domain, AccountRef administrator) Create a new domain.

Method Detail

saveNewDomain

Domain saveNewDomain(Domain domain)
                     throws DomainAlreadyExistsFault

Create a new domain. The calling principal will be made the domain administrator.

Impact

Invoking this method may cause the state of the system to change.

Create a new domain

The following code demonstrates how to create a domain. The sample code uses a fixed domain UUID so that all sample code can work against a known domain. A new domain would typically be given a new random UUID value. The authenticated user becomes the domain administrator. When a domain is created a set of human readable labels can be given to the domain for the target language audience.

 import static oracle.irm.j2ee.jws.rights.context.DomainOperations.getDomainOperationsEndpoint;
 
 import java.net.Authenticator;
 import java.net.PasswordAuthentication;
 import java.util.Locale;
 import java.util.UUID;
 
 import oracle.irm.engine.types.core.general.Label;
 import oracle.irm.engine.types.rights.context.Domain;
 import oracle.irm.j2ee.jws.rights.context.DomainOperationsEndpoint;
 
 public class SaveNewDomainWS {
 
     public static void main(String[] args) throws Exception {
 
         final String hostPort = args[0];
         final String username = args[1];
         final String password = args[2];
         
         // Configure an authenticator to provide the credentials
         // for the web service
         Authenticator.setDefault(new Authenticator() {
             @Override
             protected PasswordAuthentication getPasswordAuthentication() {
                 return new PasswordAuthentication(username, password.toCharArray());
             }
         });
         
         // Get the domain operations web service
         DomainOperationsEndpoint domainOperations = getDomainOperationsEndpoint(hostPort);
 
         // Domain has one English label
         Label label = new Label(Locale.ENGLISH, "Sample Domain", "This is a domain created from sample code.");
 
         // Domain UUID is fixed for sample code
         UUID domainUUID = UUID.fromString("6fab93fd-2858-461a-a0b3-34e261dbf8fd");
 
         Domain domain = new Domain(domainUUID,new Label[] { label });
         
         // Save the new domain
         domainOperations.saveNewDomain(domain);
     }
 }

Parameters:

domain - the domain.

Returns:

the saved domain.

Throws:

DomainAlreadyExistsFault - the domain already exists.

See Also:

saveNewDomainWithAdministrator

saveNewDomainWithAdministrator

Domain saveNewDomainWithAdministrator(Domain domain,
                                      AccountRef administrator)
                                      throws DomainAlreadyExistsFault

Create a new domain. The provided account will be made the domain administrator.

Impact

Invoking this method may cause the state of the system to change.

Parameters:

domain - the domain.

administrator - the domain administrator.

Returns:

the saved domain.

Throws:

DomainAlreadyExistsFault - the domain already exists.

See Also:

saveNewDomain

saveChangesToDomain

Domain saveChangesToDomain(Domain domain,
                           Domain delta)
                           throws UnknownDomainFault,
                                  AuthorizationDeniedFault

Save changes to a domain. Save changes to a Domain by providing two copies. Changes are made by comparing the two copies of the domain. If there are no differences in a property then no changes are made to persistent storage for that property. Changes in collection based properties cause additions or removals to occur in persistent storage. For example, if the delta contains a new Label as compared to the domain then a label will be added to the domain.

Authorization

This method can be invoked by users that have the Domain Administrator role in the related domain. This role can be assigned using the addDomainAdministrators method.

Impact

Invoking this method may cause the state of the system to change.

Parameters:

domain - the domain to compare to the delta.

delta - the changes. The Uuid property must match with the template parameter.

Returns:

the domain with the updated changes.

Throws:

UnknownDomainFault - the domain does not exist.

AuthorizationDeniedFault - authorization denied. The authenticated user is not authorized to call this operation.

deleteDomain

void deleteDomain(DomainRef domain)
                  throws AuthorizationDeniedFault

Delete a domain. Deleting a Domain destroys all roles, context templates, contexts and assigned rights.

WARNING - deleting a domain also destroys the content related encryption keys, making content sealed against any ContextInstance within the domain inaccessible.

Authorization

This method can be invoked by users that have the Domain Administrator role in the related domain. This role can be assigned using the addDomainAdministrators method.

Impact

Invoking this method may cause the state of the system to change.

Delete a domain

The following code demonstrates how to delete a domain. The sample code uses a fixed domain UUID for the new domain so that all sample code can work will a known domain. A new domain would typically be given a new random UUID value. The authenticated user must be a domain administrator. When a domain is deleted all the associated roles, templates and contexts are also deleted.

 import static oracle.irm.j2ee.jws.rights.context.DomainOperations.getDomainOperationsEndpoint;
 
 import java.net.Authenticator;
 import java.net.PasswordAuthentication;
 import java.util.UUID;
 
 import oracle.irm.engine.types.rights.context.DomainRef;
 import oracle.irm.j2ee.jws.rights.context.DomainOperationsEndpoint;
 
 public class DeleteDomainWS {
 
     public static void main(String[] args) throws Exception {
 
         final String hostPort = args[0];
         final String username = args[1];
         final String password = args[2];
         
         // Configure an authenticator to provide the credentials
         // for the web service
         Authenticator.setDefault(new Authenticator() {
             @Override
             protected PasswordAuthentication getPasswordAuthentication() {
                 return new PasswordAuthentication(username, password.toCharArray());
             }
         });
         
         // Domain UUID is fixed for sample code
         UUID domainUUID = UUID.fromString("6fab93fd-2858-461a-a0b3-34e261dbf8fd");
         
         // Get the domain operations web service
         DomainOperationsEndpoint domainOperations = getDomainOperationsEndpoint(hostPort);
 
         DomainRef domain = new DomainRef(domainUUID);
         
         // Delete the domain using the domain reference
         domainOperations.deleteDomain(domain);
     }
 }

Parameters:

domain - the domain.

Throws:

AuthorizationDeniedFault - authorization denied. The authenticated user is not authorized to call this operation.

listDomains

Domain[] listDomains()
                     throws AuthorizationDeniedFault

List domains that the calling principal is authorized to access. A domain can be accessed by a user if the user is a domain administrator or domain manager.

Returns:

the list of domains. If no domains are available then an empty collection will be returned.

Throws:

AuthorizationDeniedFault - if the authenticated user is not allowed to list domains. This will typically indicate that the authenticated user no longer exists in the user store. e.g. session is still valid but the user has been deleted from the user store.

listDomainAdministrators

AccountRef[] listDomainAdministrators(DomainRef domain)
                                      throws UnknownDomainFault,
                                             AuthorizationDeniedFault

List domain administrators. Domain administrators are individuals who define a domain's security policies regarding the use of sealed content. A Domain administrator defines what DocumentRole definitions are available for use within the Domain. A Domain administrator also defines what ContextTemplate definitions are available. These definitions are used by domain managers to create Context classifications.

Authorization

This method can be invoked by users that have the Domain Administrator role in the related domain. This role can be assigned using the addDomainAdministrators method.

Parameters:

domain - the domain.

Returns:

the list of administrators. This list will always contain at least one administrator.

Throws:

UnknownDomainFault - the domain does not exist.

AuthorizationDeniedFault - authorization denied. The authenticated user is not authorized to call this operation.

See Also:

addDomainAdministrators

addDomainAdministrators

void addDomainAdministrators(DomainRef domain,
                             AccountRef[] accounts)
                             throws AccountAlreadyAdministratorFault,
                                    UnknownDomainFault,
                                    AuthorizationDeniedFault

Add one or more administrators to a domain. A Domain will always have at least one administrator. When a Domain has multiple administrators, each administrator will have equal permissions to perform Domain related activities.

If any of the provided accounts is a domain manager the account will be upgraded to a domain administrator.

Authorization

This method can be invoked by users that have the Domain Administrator role in the related domain. This role can be assigned using the addDomainAdministrators method.

Impact

Invoking this method may cause the state of the system to change.

Parameters:

domain - the domain.

accounts - the accounts. Duplicates are ignored. This parameter is optional, it is valid to pass null or an empty collection.

Throws:

AccountAlreadyAdministratorFault - one of the provided accounts is already a domain administrator.

UnknownDomainFault - the domain does not exist.

AuthorizationDeniedFault - authorization denied. The authenticated user is not authorized to call this operation.

removeDomainAdministrators

void removeDomainAdministrators(DomainRef domain,
                                AccountRef[] accounts)
                                throws CannotRemoveAdministratorsFault,
                                       UnknownDomainFault,
                                       AuthorizationDeniedFault

Remove one or more administrators from a domain. An Domain must have at least one administrator.

Authorization

This method can be invoked by users that have the Domain Administrator role in the related domain. This role can be assigned using the addDomainAdministrators method.

Impact

Invoking this method may cause the state of the system to change.

Parameters:

domain - the domain.

accounts - the accounts. This parameter is optional, it is valid to pass null or an empty collection.

Throws:

CannotRemoveAdministratorsFault - the administrator accounts cannot be removed, as it would leave the domain with no administrators.

UnknownDomainFault - the domain does not exist.

AuthorizationDeniedFault - authorization denied. The authenticated user is not authorized to call this operation.

listDomainManagers

AccountRef[] listDomainManagers(DomainRef domain)
                                throws UnknownDomainFault,
                                       AuthorizationDeniedFault

List domain managers. Domain managers are the only individuals who can create new Context instances using createContextFromTemplate.

Authorization

This method can be invoked by users that have the Domain Administrator role in the related domain. This role can be assigned using the addDomainAdministrators method.

Parameters:

domain - the domain.

Returns:

the list of managers. This will contains at least one administrator.

Throws:

UnknownDomainFault - the domain does not exist.

AuthorizationDeniedFault - authorization denied. The authenticated user is not authorized to call this operation.

See Also:

addDomainManagers

addDomainManagers

void addDomainManagers(DomainRef domain,
                       AccountRef[] accounts)
                       throws AccountAlreadyManagerFault,
                              UnknownDomainFault,
                              AuthorizationDeniedFault

Add one or more managers to a domain.

Authorization

This method can be invoked by users that have the Domain Administrator role in the related domain. This role can be assigned using the addDomainAdministrators method.

Impact

Invoking this method may cause the state of the system to change.

Parameters:

domain - the domain.

accounts - the accounts. Duplicates are ignored. This parameter is optional, it is valid to pass null or an empty collection.

Throws:

AccountAlreadyManagerFault - one of the provided accounts is already a domain manager (or domain administrator).

UnknownDomainFault - the domain does not exist.

AuthorizationDeniedFault - authorization denied. The authenticated user is not authorized to call this operation.

removeDomainManagers

void removeDomainManagers(DomainRef domain,
                          AccountRef[] accounts)
                          throws UnknownDomainFault,
                                 AuthorizationDeniedFault

Remove one or more domain managers from a domain.

Authorization

This method can be invoked by users that have the Domain Administrator role in the related domain. This role can be assigned using the addDomainAdministrators method.

Impact

Invoking this method may cause the state of the system to change.

Parameters:

domain - the domain.

accounts - the accounts. This parameter is optional, it is valid to pass null or an empty collection.

Throws:

UnknownDomainFault - the domain does not exist.

AuthorizationDeniedFault - authorization denied. The authenticated user is not authorized to call this operation.

listAccountDetails

Account[] listAccountDetails(AccountRef[] accounts)
                             throws AuthorizationDeniedFault

Retrieve the name and account type from one or more account UUID values. This method can be used to identify the user or group name when only the account UUID is available. If any of the provided UUID values do not correspond to a user or group the account is not returned in the results.

Parameters:

accounts - the accounts. This parameter is optional, it is valid to pass null or an empty collection.

Returns:

the account details.

Throws:

AuthorizationDeniedFault - if the authenticated user is not allowed to list accounts. A user is allowed to list accounts if they have any domain administrator, domain manager, inspector or context manager role.

Skip navigation links