Skip navigation links

oracle.irm.engine.rights.context
Class DocumentRoleOperationsInstance

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

public final class DocumentRoleOperationsInstance

extends Object

Document role operations. The document role operations include role management operations such as creating, editing and copying roles. The document role operations also include role assignment roles and re-assignment.

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.DocumentRoleOperationsInstance.*;

Method Summary

static DocumentRole	appendFeaturesToRole(DocumentRole role, String[] featureIds) Add features to a role.
static DocumentRole	clearTimeConstraints(DocumentRole role) Clear the time constraints on a role.
static DocumentRole	copyRole(DocumentRole role, Domain domain) Copy a role.
static Collection<DocumentRole>	copyRoles(Collection<DocumentRole> roles, Domain domain) Copy a set of roles.
static void	deleteRole(DocumentRole role) Delete a role.
static void	deleteRoles(Collection<DocumentRole> roles) Delete a set of roles.
static boolean	documentRoleExists(UUID uuid, Domain domain) Check for a document role's existence.
static Collection<TimePeriod>	getDefaultRefreshPeriods() List default refresh periods.
static boolean	getFeatureRecording(DocumentRole role) Infer whether feature recording has been set on a document role.
static DocumentRole.TimeConstraints	getTimeConstraints(DocumentRole role) Get the time constraints set on a document role.
static Collection<DocumentRole>	listRoles(Domain domain) List document roles owned by a domain.
static Collection<DocumentRole>	listRolesForContext(ContextInstance context) List document roles available to a context.
static DocumentRole	refreshDocumentRole(DocumentRole role) Refresh a document role's properties.
static DocumentRole	saveChangesToRole(DocumentRole role, DocumentRole delta) Save changes to a document role.
static DocumentRole	saveNewRole(Domain domain, DocumentRole role) Save a new document role.
static DocumentRole	setAbsoluteTimeConstraints(DocumentRole role, Date startTime, Date stopTime) Set absolute time constraints on a role.
static DocumentRole	setFeatureRecording(DocumentRole role, boolean record) Set whether feature use is recorded.
static DocumentRole	setRelativeAssignmentTimeConstraints(DocumentRole role, TimePeriod period) Set relative to assignment time constraints on a role.
static DocumentRole	setRelativeClassificationTimeConstraints(DocumentRole role, TimePeriod period) Set relative to classification time constraints on a role.
static Collection<Feature>	updateExportConstraints(Collection<Feature> features, DocumentRole.ExportConstraints constraints) Update a set of features based on export constraints.

Methods inherited from class java.lang.Object

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

Method Detail

getDefaultRefreshPeriods

public static Collection<TimePeriod> getDefaultRefreshPeriods()

List default refresh periods. When creating a DocumentRole a refresh period must be specified. This method returns a list of recommended default refresh periods that can be used, for example, as a pick-list in a user interface that creates or edits document roles.

State

The collection returned by this method is an unmodifiable view on the internal collection state of the object.

Returns:

the value of the property. If this collection is empty this method returns an empty collection rather than returning null.

listRoles

public static Collection<DocumentRole> listRoles(Domain domain)
                                          throws UnknownDomainException,
                                                 AuthorizationDeniedException

List document roles owned by a domain. Document roles are owned by a Domain. Roles are created using saveNewRole and the domain that owns the role must be provided at this time.

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. This method can be invoked by users that have the Domain Manager role in the related domain. This role can be assigned using the addDomainManagers method.

Parameters:

domain - the domain.

Returns:

the list of roles owned by the domain. If there are no roles an empty collection is returned. 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.

listRolesForContext

public static Collection<DocumentRole> listRolesForContext(ContextInstance context)
                                                    throws UnknownContextException,
                                                           AuthorizationDeniedException

List document roles available to a context. The set of roles available to a context are based on the roles of associated template. Changes in the template's roles affect which roles are available to the context.

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. This method can be invoked by users that have the Context Manager role in the related context. This role can be assigned using the addContextManagers method. This method can be invoked by users that have the Inspector role in the related context. This role can be assigned using the addInspectors method.

Parameters:

context - the context.

Returns:

the list of roles available to a context. If there are no roles an empty collection is returned. If applicable, this method will return an empty collection rather than null to indicate no results.

Throws:

UnknownContextException - the context does not exist.

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

saveNewRole

public static DocumentRole saveNewRole(Domain domain,
                                       DocumentRole role)
                                throws DocumentRoleAlreadyExistsException,
                                       InvalidFeaturesException,
                                       InvalidTimePeriodException,
                                       UnknownDomainException,
                                       IllegalArgumentException,
                                       AuthorizationDeniedException

Save a new document role. The document role will be owned by the specified 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 that owns this role.

role - the role.

Returns:

the new role. This method will never return null.

Throws:

DocumentRoleAlreadyExistsException - a role already exists with the same UUID within the specified domain.

InvalidFeaturesException - invalid features specified.

InvalidTimePeriodException - invalid time period specified.

UnknownDomainException - the domain does not exist.

IllegalArgumentException - illegal argument. The role provided must NOT have it's Domain property specified. This is to protect against passing in a role that has already been saved. Duplicate features and time spans are also not allowed.

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

saveChangesToRole

public static DocumentRole saveChangesToRole(DocumentRole role,
                                             DocumentRole delta)
                                      throws InvalidFeaturesException,
                                             InvalidTimePeriodException,
                                             ImmutableDocumentRoleException,
                                             UnknownDocumentRoleException,
                                             IllegalArgumentException,
                                             AuthorizationDeniedException

Save changes to a document role. Save changes to a DocumentRole by providing two copies. Changes are made by comparing the two copies of the role. 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 Feature as compared to the role then a new role will be associated with the template.

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:

role - the document role to compare to the delta.

delta - the changes. The Domain and Uuid properties must match with the role parameter.

Returns:

the document role with the updated changes. This method will never return null.

Throws:

InvalidFeaturesException - invalid features specified.

InvalidTimePeriodException - invalid time period specified.

ImmutableDocumentRoleException - the role has been assigned to a user or group and the item constraints cannot be changed.

UnknownDocumentRoleException - the role does not exist.

IllegalArgumentException - illegal argument. If the Domain and Uuid properties of the delta parameter do not match the role parameter. Also thrown in the role provided does not have it's Domain property specified. Duplicate features and time spans are not allowed.

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

deleteRole

public static void deleteRole(DocumentRole role)
                       throws CannotRemoveDocumentRoleException

Delete a role. Deleting a role also automatically unassigns the rights assigned against this role. This method silently ignores roles that do not exist.

Impact

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

Parameters:

role - the role.

Throws:

CannotRemoveDocumentRoleException - the role cannot be removed as it is in use. A document role cannot be deleted if there are any contexts assignments using the role. The document role can only be deleted after the associated rights have been unassigned.

deleteRoles

public static void deleteRoles(Collection<DocumentRole> roles)
                        throws CannotRemoveDocumentRoleException,
                               AuthorizationDeniedException

Delete a set of roles. Deleting a role also automatically unassigns the rights assigned against this role. This method silently ignores roles that do not exist.

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:

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

Throws:

CannotRemoveDocumentRoleException - the role cannot be removed as it is in use. A document role cannot be deleted if there are any contexts assignments using the role. The document role can only be deleted after the associated rights have been unassigned.

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

copyRole

public static DocumentRole copyRole(DocumentRole role,
                                    Domain domain)
                             throws UnknownDomainException,
                                    UnknownDocumentRoleException,
                                    IllegalArgumentException

Copy a role. Copy a document role to another Domain. When roles are copied the rights assigned to those roles are not copied.

Labels are also copied and altered to reflect that the result is a copy of the role. For example, in English, the role Contributor would turn into Copy Of Contributor.

Impact

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

Parameters:

role - the role.

domain - the domain.

Returns:

the copied document role. This method will never return null.

Throws:

UnknownDomainException - the domain does not exist.

UnknownDocumentRoleException - the role does not exist.

IllegalArgumentException - illegal argument. The role provided must have it's Domain property specified.

copyRoles

public static Collection<DocumentRole> copyRoles(Collection<DocumentRole> roles,
                                                 Domain domain)
                                          throws UnknownDomainException,
                                                 UnknownDocumentRoleException,
                                                 IllegalArgumentException,
                                                 AuthorizationDeniedException

Copy a set of roles. Copy a set of document roles to another Domain. When roles are copied the rights assigned to those roles are not copied.

Labels are also copied and altered to reflect that the result is a copy of the role. For example, in English, the role Contributor would turn into Copy Of Contributor.

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:

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

domain - the domain.

Returns:

the copied document roles. If applicable, this method will return an empty collection rather than null to indicate no results.

Throws:

UnknownDomainException - the domain does not exist.

UnknownDocumentRoleException - the role does not exist.

IllegalArgumentException - illegal argument. If any of the roles provided are not associated with a Domain.

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

refreshDocumentRole

public static DocumentRole refreshDocumentRole(DocumentRole role)
                                        throws UnknownDocumentRoleException,
                                               AuthorizationDeniedException

Refresh a document role'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. This method can be invoked by users that have the Domain Manager role in the related domain. This role can be assigned using the addDomainManagers method.

Impact

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

Parameters:

role - the role.

Returns:

the refreshed document role. This method will never return null.

Throws:

UnknownDocumentRoleException - the role does not exist.

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

documentRoleExists

public static boolean documentRoleExists(UUID uuid,
                                         Domain domain)

Check for a document role's existence.

Parameters:

uuid - the role UUID.

domain - the owning domain.

Returns:

true if the role exists, otherwise false.

appendFeaturesToRole

public static DocumentRole appendFeaturesToRole(DocumentRole role,
                                                String[] featureIds)
                                         throws UnknownFeatureException

Add features to a role. Adds a list of features, specified using a feature identity, to a role's features. This method is provided as a utility that calls getFeature and then adds the resultant feature to the role's Features.

The changes to the role are not persisted - a call to saveNewRole or saveChangesToRole is required to persist changes to the features.

Parameters:

role - the role.

featureIds - the array of feature Ids.

Returns:

the altered role. This method will never return null.

Throws:

UnknownFeatureException - one of the specified feature Ids is invalid.

clearTimeConstraints

public static DocumentRole clearTimeConstraints(DocumentRole role)

Clear the time constraints on a role. The changes to the role are not persisted - a call to saveNewRole or saveChangesToRole is required to persist changes to the time constraints.

Parameters:

role - the role.

Returns:

the altered role. This method will never return null.

See Also:

NONE, TimeSpans

setAbsoluteTimeConstraints

public static DocumentRole setAbsoluteTimeConstraints(DocumentRole role,
                                                      Date startTime,
                                                      Date stopTime)

Set absolute time constraints on a role. Absolute time constraints restrict the use of the role to a particular time window, specified by a start and/or stop time. e.g. restrict a role so that it can only be used from the 1st January 2008 to the 31st December 2008.

The changes to the role are not persisted - a call to saveNewRole or saveChangesToRole is required to persist changes to the time constraints.

Parameters:

role - the role.

startTime - start time. The start time is optional if a stop time has been provided. This parameter is optional, it is valid to pass null.

stopTime - stop time. The stop time is optional if a start time has been provided. This parameter is optional, it is valid to pass null.

Returns:

the altered role. This method will never return null.

See Also:

ABSOLUTE, TimeSpans

setRelativeAssignmentTimeConstraints

public static DocumentRole setRelativeAssignmentTimeConstraints(DocumentRole role,
                                                                TimePeriod period)

Set relative to assignment time constraints on a role. Relative time constraints restrict the use of the role relative to the date it was assigned. e.g. restrict a role so that it can only be used six months after the role was assigned.

The changes to the role are not persisted - a call to saveNewRole or saveChangesToRole is required to persist changes to the time constraints.

Parameters:

role - the role.

period - the time period. e.g. three months.

Returns:

the altered role. This method will never return null.

See Also:

RELATIVE_ASSIGNMENT, TimeSpans, AssignedTime

setRelativeClassificationTimeConstraints

public static DocumentRole setRelativeClassificationTimeConstraints(DocumentRole role,
                                                                    TimePeriod period)

Set relative to classification time constraints on a role. Relative time constraints restrict the use of the role relative to the date content was classified. e.g. restrict a role so that it can only be used to access content for one months after the content was sealed.

The changes to the role are not persisted - a call to saveNewRole or saveChangesToRole is required to persist changes to the time constraints.

Parameters:

role - the role.

period - the time period. e.g. one day.

Returns:

the altered role. This method will never return null.

See Also:

ClassificationTime, TimeSpans, RELATIVE_CLASSIFICATION

getTimeConstraints

public static DocumentRole.TimeConstraints getTimeConstraints(DocumentRole role)

Get the time constraints set on a document role. Time constraints can be inferred from a role by examining what TimeSpans the role allows. This methods is provided as an alternative way to working out what the time constraints are rather than manually examining the time spans property.

Parameters:

role - the role.

Returns:

the time constraints. This method will never return null.

setFeatureRecording

public static DocumentRole setFeatureRecording(DocumentRole role,
                                               boolean record)

Set whether feature use is recorded. Altering the feature recording setting automatically sets the a appropriate Record value on each Feature present in the list of Features. This methods is provided as an alternative way of altering each feature's Record property manually.

The changes to the role are not persisted - a call to saveNewRole or saveChangesToRole is required to persist changes to the export constraints.

Parameters:

role - the role.

record - feature use is recorded (true) or not recorded (false).

Returns:

the altered role. This method will never return null.

See Also:

Features

getFeatureRecording

public static boolean getFeatureRecording(DocumentRole role)

Infer whether feature recording has been set on a document role. Feature recording can be inferred from a role by examining the role's Features. This methods is provided as an alternative way to examining the features individually.

Parameters:

role - the role.

Returns:

feature use is recorded (true) or not recorded (false).

updateExportConstraints

public static Collection<Feature> updateExportConstraints(Collection<Feature> features,
                                                          DocumentRole.ExportConstraints constraints)

Update a set of features based on export constraints. Export constraints control how sealed content can be resealed to other classifications, or copied between sealed content. Export constraints are realized in a license by adding either the copy to or copy and save unsealed Feature. This method can be used to add in these features based on the required export constraints. The Record property value of these added features will be set to match the features provided. If any the provided features are marked to have their usage recorded, the added feature will also be marked to have their usage recorded.

Parameters:

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

constraints - the required export constraints.

Returns:

the altered features. If applicable, this method will return an empty collection rather than null to indicate no results.

See Also:

Destinations

Skip navigation links