Skip navigation links

oracle.irm.engine.rights.context
Interface DomainOperations

public interface DomainOperations

Domain methods.

Instance

The methods on DomainOperations can be invoked using DomainOperationsInstance.

Method Summary

void	addDomainAdministrators(Domain domain, Collection<Account> accounts) Add one or more administrators to a domain.
void	addDomainManagers(Domain domain, Collection<Account> accounts) Add one or more managers to a domain.
int	countDomains() Count the number of domains.
void	deleteDomain(Domain domain) Delete a domain.
boolean	domainExists(UUID uuid) Check for a domain's existence.
Domain	getDomain() Get a domain.
Domain.Role	getRoleForDomain(Domain domain, Account account) Find out what role an account has within a domain.
Domain	installDomain() Create a new domain with the standard set of roles and templates.
void	installStandardSystem(Domain domain) Install the standard set of roles and templates.
Collection<Account>	listAccountDetails(Collection<Account> accounts) Retrieve the name and account type from one or more account UUID values.
Collection<DomainAccount>	listDomainAccounts(Domain domain) Find out what accounts have a role within this domain.
Collection<Account>	listDomainAdministrators(Domain domain) List domain administrators.
Collection<Account>	listDomainManagers(Domain domain) List domain managers.
Collection<Domain>	listDomains() List domains that the calling principal is authorized to access.
Collection<Domain>	listDomainsForAccount(Account account, Domain.Role filter) List domains administered by an account.
Collection<Label>	listStandardLabels(UUID uuid, Locale[] locales) Obtain the labels for standard set of context templates and document roles.
Domain	refreshDomain(Domain domain) Refresh a domain's properties.
void	removeDomainAccounts(Domain domain, Collection<DomainAccount> accounts) Remove domain accounts.
void	removeDomainAdministrators(Domain domain, Collection<Account> accounts) Remove one or more administrators from a domain.
void	removeDomainManagers(Domain domain, Collection<Account> 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, Account administrator) Create a new domain.

Method Detail

saveNewDomain

Domain saveNewDomain(Domain domain)
                     throws DomainAlreadyExistsException

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.

Parameters:

domain - the domain.

Returns:

the saved domain. This method will never return null.

Throws:

DomainAlreadyExistsException - the domain already exists.

See Also:

saveNewDomainWithAdministrator

saveNewDomainWithAdministrator

Domain saveNewDomainWithAdministrator(Domain domain,
                                      Account administrator)
                                      throws DomainAlreadyExistsException

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. This method will never return null.

Throws:

DomainAlreadyExistsException - the domain already exists.

See Also:

saveNewDomain

saveChangesToDomain

Domain saveChangesToDomain(Domain domain,
                           Domain delta)
                           throws UnknownDomainException,
                                  IllegalArgumentException,
                                  AuthorizationDeniedException

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. This method will never return null.

Throws:

UnknownDomainException - the domain does not exist.

IllegalArgumentException - illegal argument. If the Uuid property of the delta parameter does not match the domain parameter.

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

installDomain

Domain installDomain()

Create a new domain with the standard set of roles and templates. This method is intended for use by installation/first use scenarios where the first domain needs to be created. If a domain already exists this method attempts to return the domain to the caller. If multiple domains exists, the first one is returned. If the caller is not allowed to access any domains null is returned. If a domain is created the authenticated user is made the domain administrator.

Impact

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

Returns:

the new domain, or the existing installed domain, or null. This method can return null.

deleteDomain

void deleteDomain(Domain domain)
                  throws AuthorizationDeniedException

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.

Parameters:

domain - the domain.

Throws:

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

listDomains

Collection<Domain> listDomains()
                               throws AuthorizationDeniedException

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. If applicable, this method will return an empty collection rather than null to indicate no results.

Throws:

AuthorizationDeniedException - 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.

getDomain

Domain getDomain()
                 throws DomainNotAvailableException,
                        AuthorizationDeniedException

Get a domain. This method returns the first domain the authenticated user is allowed to access. A user can obtain a domain if they have been assigned either the domain administrator or domain manager role. If the user is not allowed to access any domains null is returned.

Returns:

the domain. If the user is not allowed to access any domains null is returned. This method can return null.

Throws:

DomainNotAvailableException - thrown if no domains exist in the system. This exception indicates that there are no domains. A domain should be created using the installDomain or saveNewDomain methods.

AuthorizationDeniedException - if the authenticated user is not allowed to access any 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. If the user is still a valid user then this method returns null if the user is not allowed access to any domains.

refreshDomain

Domain refreshDomain(Domain domain)
                     throws UnknownDomainException,
                            AuthorizationDeniedException

Refresh a domain's properties.

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.

Returns:

the refreshed domain. This method will never return null.

Throws:

UnknownDomainException - the domain does not exist.

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

countDomains

int countDomains()

Count the number of domains. This method is used internally to detect the presence of at least one domain.

Returns:

the number of domains.

domainExists

boolean domainExists(UUID uuid)

Check for a domain's existence.

Parameters:

uuid - the domain UUID.

Returns:

true if the domain exists, otherwise false.

listDomainsForAccount

Collection<Domain> listDomainsForAccount(Account account,
                                         Domain.Role filter)

List domains administered by an account. An account can administer zero or more domains. This operations lists all the domains an account can administer. An account can access a domain if they are either a domain administrator or domain manager.

Parameters:

account - the user account.

filter - the domain role filter. This filter allows the domains to be listed that the account can administer, manage, inspect or both.

Returns:

the list of domains. If no domains are available then an empty collection will be returned. If applicable, this method will return an empty collection rather than null to indicate no results.

listDomainAdministrators

Collection<Account> listDomainAdministrators(Domain domain)
                                             throws UnknownDomainException,
                                                    AuthorizationDeniedException

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. If applicable, this method will return an empty collection rather than null to indicate no results.

Throws:

UnknownDomainException - the domain does not exist.

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

See Also:

addDomainAdministrators

addDomainAdministrators

void addDomainAdministrators(Domain domain,
                             Collection<Account> accounts)
                             throws AccountAlreadyAdministratorException,
                                    UnknownDomainException,
                                    AuthorizationDeniedException

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:

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

UnknownDomainException - the domain does not exist.

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

removeDomainAdministrators

void removeDomainAdministrators(Domain domain,
                                Collection<Account> accounts)
                                throws CannotRemoveAdministratorsException,
                                       UnknownDomainException,
                                       AuthorizationDeniedException

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:

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

UnknownDomainException - the domain does not exist.

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

listDomainManagers

Collection<Account> listDomainManagers(Domain domain)
                                       throws UnknownDomainException,
                                              AuthorizationDeniedException

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. If applicable, this method will return an empty collection rather than null to indicate no results.

Throws:

UnknownDomainException - the domain does not exist.

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

See Also:

addDomainManagers

addDomainManagers

void addDomainManagers(Domain domain,
                       Collection<Account> accounts)
                       throws AccountAlreadyManagerException,
                              UnknownDomainException,
                              AuthorizationDeniedException

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:

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

UnknownDomainException - the domain does not exist.

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

removeDomainManagers

void removeDomainManagers(Domain domain,
                          Collection<Account> accounts)
                          throws UnknownDomainException,
                                 AuthorizationDeniedException

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:

UnknownDomainException - the domain does not exist.

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

getRoleForDomain

Domain.Role getRoleForDomain(Domain domain,
                             Account account)
                             throws UnknownDomainException

Find out what role an account has within a domain. An account can either be a manager or an administrator (or have no role within a domain).

Parameters:

domain - the domain.

account - the account.

Returns:

the role type. This method will never return null.

Throws:

UnknownDomainException - the domain does not exist.

listDomainAccounts

Collection<DomainAccount> listDomainAccounts(Domain domain)
                                             throws UnknownDomainException,
                                                    AuthorizationDeniedException

Find out what accounts have a role within this 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.

Parameters:

domain - the domain.

Returns:

the list of accounts that have a role within this domain. If applicable, this method will return an empty collection rather than null to indicate no results.

Throws:

UnknownDomainException - the domain does not exist.

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

removeDomainAccounts

void removeDomainAccounts(Domain domain,
                          Collection<DomainAccount> accounts)
                          throws CannotRemoveAdministratorsException,
                                 UnknownDomainException,
                                 AuthorizationDeniedException

Remove domain accounts. Allows inspectors, domain administrators and domain managers to be removed in one method call.

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:

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

UnknownDomainException - the domain does not exist.

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

listAccountDetails

Collection<Account> listAccountDetails(Collection<Account> accounts)
                                       throws AuthorizationDeniedException

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. If applicable, this method will return an empty collection rather than null to indicate no results.

Throws:

AuthorizationDeniedException - 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.

installStandardSystem

void installStandardSystem(Domain domain)
                           throws UnknownDomainException

Install the standard set of roles and templates. The context classification system comes with a standard set context templates and document roles. This method can be used to add these templates and roles to a domain. It is safe to call this method repeatedly as checks are made to see if the standard templates and roles already exist. This behaviour can be used to re-add any standard roles or templates that have been deleted since installation.

Impact

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

Parameters:

domain - the domain into which to add the roles and templates.

Throws:

UnknownDomainException - the domain does not exist.

listStandardLabels

Collection<Label> listStandardLabels(UUID uuid,
                                     Locale[] locales)

Obtain the labels for standard set of context templates and document roles. The context classification system comes with a standard set context templates and document roles. This method can be used obtain the labels for the templates and roles.

Impact

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

Parameters:

uuid - the role or template UUID value.

locales - the required locales. If no locales are specified all the available labels are returned. This parameter is optional, it is valid to pass null.

Returns:

the standard set of labels for the provided entity. If applicable, this method will return an empty collection rather than null to indicate no results.

Skip navigation links