Skip navigation links

oracle.irm.engine.rights.context
Class DomainOperationsInstance

java.lang.Object
oracle.irm.engine.rights.context.DomainOperationsInstance

public final class DomainOperationsInstance

extends Object

Domain methods.

This class provides static methods for a set of procedural style methods. The methods can be made to appear as global methods by using import static. e.g.

import static oracle.irm.engine.rights.context.DomainOperationsInstance.*;

Method Summary

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

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

saveNewDomain

public static 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

public static 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

public static 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

public static 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

public static 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

public static 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

public static 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

public static 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

public static 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

public static boolean domainExists(UUID uuid)

Check for a domain's existence.

Parameters:

uuid - the domain UUID.

Returns:

true if the domain exists, otherwise false.

listDomainsForAccount

public static 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

public static 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

public static 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

public static 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

public static 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

public static 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

public static 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

public static 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

public static 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

public static 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

public static 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

public static 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

public static 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