Skip navigation links

oracle.irm.engine.rights.context
Interface DocumentRightOperations

public interface DocumentRightOperations

Document right operations. Document right operations include checking in rights, altering item restrictions, listing rights and checking items across sets of rights.

Instance

The methods on DocumentRightOperations can be invoked using DocumentRightOperationsInstance.

Method Summary

Collection<DocumentRight>	assignRole(ContextInstance context, DocumentRole role, Collection<Account> accounts, Collection<ItemCode> items) Assign a document role.
Collection<DocumentRight>	checkInRightsForAccount(Account account) Check all rights in use by an account.
int	countRightsByContext(ContextInstance context) Count the number of rights assigned within a context.
int	countRightsByRole(DocumentRole role) Count the number of rights assigned to a role.
int	countRightsByTemplate(ContextTemplate template, DocumentRole role) Count the number of rights assigned to a role, with a relationship to the specified template.
Collection<DocumentRight>	filterRightsByAccounts(ContextInstance context, Collection<Account> accounts) List a filtered set of rights assigned within a context based on account details.
Collection<DocumentRight>	listRightsByAccount(Account account) List rights for an account.
Collection<DocumentRight>	listRightsByAccounts(Collection<Account> accounts) List rights for one or more accounts.
Collection<DocumentRight>	listRightsByContext(ContextInstance context, PageRange pageRange) List rights assigned within a context.
Collection<DocumentRight>	reassignRole(Collection<DocumentRight> rights, DocumentRole role, Collection<ItemCode> items) Alter role assignments.
DocumentRight	refreshDocumentRight(DocumentRight right) Refresh a right's properties.
Collection<DocumentRight>	saveChangesToItems(Collection<DocumentRight> rights, Collection<ItemCode> itemCodes, Collection<ItemCode> delta) Alter the item restrictions for a set of rights.
Collection<DocumentRight>	searchRightsByAccount(Account account, Context context) Search rights assigned to an account, optionally filtered on a context.
Collection<DocumentRight>	searchRightsByAccounts(Collection<Account> accounts, Context context) Search rights assigned to one or more accounts, optionally filtered by a context.
void	unassignRight(DocumentRight right) Un-assign a right.
void	unassignRights(Collection<DocumentRight> rights) Un-assign a set of rights.
int	unassignRightsByContext(ContextInstance context) Un-assign rights assigned to a context.

Method Detail

assignRole

Collection<DocumentRight> assignRole(ContextInstance context,
                                     DocumentRole role,
                                     Collection<Account> accounts,
                                     Collection<ItemCode> items)
                                     throws AccountAlreadyAssignedException,
                                            UnsupportedDocumentRoleException,
                                            UnknownContextException,
                                            UnknownDocumentRoleException,
                                            AuthorizationDeniedException

Assign a document role. A document role can be assigned, within a context, to one or more accounts. An account can only have one role assigned within a Context. If any of the provided accounts already has the role assigned the account is silently ignored and the role is not re-assigned.

Authorization

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.

Impact

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

Parameters:

context - the context.

role - the role.

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

items - item restrictions. Can be empty. This parameter is optional, it is valid to pass null or an empty collection.

Returns:

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

Throws:

AccountAlreadyAssignedException - an account is already assigned a role. An account can only be assigned one role within a Context.

UnsupportedDocumentRoleException - the Context does not support the provided document role.

UnknownContextException - the context does not exist.

UnknownDocumentRoleException - the role does not exist.

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

reassignRole

Collection<DocumentRight> reassignRole(Collection<DocumentRight> rights,
                                       DocumentRole role,
                                       Collection<ItemCode> items)
                                       throws UnsupportedDocumentRoleException,
                                              UnknownDocumentRoleException,
                                              UnknownDocumentRightException,
                                              AuthorizationDeniedException

Alter role assignments. Change the role assigned to an account. This also resets any item restrictions placed on the assigned right. As an account can only have one role assigned within a Context this method can be used to alter the role assignment without a two-step unassign right and assign role.

Authorization

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.

Impact

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

Parameters:

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

role - the role.

items - item restrictions. Can be empty. This parameter is optional, it is valid to pass null or an empty collection.

Returns:

the re-assigned rights. If applicable, this method will return an empty collection rather than null to indicate no results.

Throws:

UnsupportedDocumentRoleException - the role provided is not supported by a context associated by one of the supplied rights.

UnknownDocumentRoleException - the role does not exist.

UnknownDocumentRightException - at least one of the rights does not exist.

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

checkInRightsForAccount

Collection<DocumentRight> checkInRightsForAccount(Account account)
                                                  throws AuthorizationDeniedException

Check all rights in use by an account. If a user's device fails, or has issues with desktop installations, the rights that are in use can be force-ably checked in. This allows the account to request the rights on another device. If the account does not exist an empty collection is returned.

The checked-in rights are restricted to the contexts that the caller is a context manager.

Impact

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

Parameters:

account - the account.

Returns:

the rights that were in use by the specified account. 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 check in rights. 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.

saveChangesToItems

Collection<DocumentRight> saveChangesToItems(Collection<DocumentRight> rights,
                                             Collection<ItemCode> itemCodes,
                                             Collection<ItemCode> delta)
                                             throws UnknownDocumentRightException,
                                                    AuthorizationDeniedException

Alter the item restrictions for a set of rights. Alter the item restrictions on one or more DocumentRight. Changes are made to the list of item restrictions by comparing the two copies of the item codes provided and either removing or adding item restrictions by looking at the delta.

For example if the delta (as compared to the first list of items) contains additional ItemCode instances then new items will be added to the rights. However, if the delta (as compared to the first list of items) does not contain an ItemCode instance then the items will be removed from the rights.

Authorization

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.

Impact

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

Parameters:

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

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

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

Returns:

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

Throws:

UnknownDocumentRightException - the document right does not exist.

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

unassignRight

void unassignRight(DocumentRight right)

Un-assign a right. If the right has already been unassigned this method will not report an error.

Impact

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

Parameters:

right - the right to un-assign.

unassignRights

void unassignRights(Collection<DocumentRight> rights)
                    throws AuthorizationDeniedException

Un-assign a set of rights. If the right has already been unassigned this method will not report an error.

Authorization

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.

Impact

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

Parameters:

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

Throws:

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

unassignRightsByContext

int unassignRightsByContext(ContextInstance context)
                            throws UnknownContextException

Un-assign rights assigned to a context. This method is used internally to un-assign rights when a context is deleted.

Impact

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

Parameters:

context - the context.

Returns:

the number of rights un-assigned.

Throws:

UnknownContextException - the context does not exist.

countRightsByRole

int countRightsByRole(DocumentRole role)
                      throws UnknownDocumentRoleException

Count the number of rights assigned to a role.

Parameters:

role - the role.

Returns:

the number of rights assigned.

Throws:

UnknownDocumentRoleException - the role does not exist.

countRightsByContext

int countRightsByContext(ContextInstance context)
                         throws UnknownContextException

Count the number of rights assigned within a context.

Parameters:

context - the context.

Returns:

the number of rights assigned.

Throws:

UnknownContextException - the context does not exist.

countRightsByTemplate

int countRightsByTemplate(ContextTemplate template,
                          DocumentRole role)
                          throws UnknownContextTemplateException,
                                 UnknownDocumentRoleException

Count the number of rights assigned to a role, with a relationship to the specified template.

Parameters:

template - the template.

role - the role.

Returns:

the number of rights using the specified role.

Throws:

UnknownContextTemplateException - the context template does not exist.

UnknownDocumentRoleException - the role does not exist.

listRightsByContext

Collection<DocumentRight> listRightsByContext(ContextInstance context,
                                              PageRange pageRange)
                                              throws UnknownContextException,
                                                     IllegalArgumentException,
                                                     AuthorizationDeniedException

List rights assigned within a context. This method lists rights assigned within a context, ordered by the date the role was assigned (most recent rights first). If large numbers of rights are assigned the page range parameter can be used to retrieve the rights in smaller chunks.

Authorization

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.

pageRange - page range for the search result.

Returns:

the list of rights or an empty collection if the context does not have any document rights. If applicable, this method will return an empty collection rather than null to indicate no results.

Throws:

UnknownContextException - the context does not exist.

IllegalArgumentException - the page range is invalid. The page range is limited to a page size of 5000 items. This is the maximum number of items that can be returned in one request.

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

filterRightsByAccounts

Collection<DocumentRight> filterRightsByAccounts(ContextInstance context,
                                                 Collection<Account> accounts)
                                                 throws UnknownContextException,
                                                        AuthorizationDeniedException

List a filtered set of rights assigned within a context based on account details. This method lists rights assigned within a context, filtered by account. The matching rights are ordered by the date the role was assigned (most recent rights first). This method can be used to find out whether an account (or set of accounts) has been assigned a role within a context.

Authorization

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.

accounts - accounts filter. At least one account must be specified.

Returns:

the list of rights or an empty collection if the context and account filter does not matched any assigned document rights. 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.

listRightsByAccount

Collection<DocumentRight> listRightsByAccount(Account account)
                                              throws AuthorizationDeniedException

List rights for an account. Rights listed for an account include rights obtained indirectly through group membership. If the account does not exist an empty collection is returned.

Only rights that the caller is allowed to view will be returned. The caller can view rights if they are a context manager or inspector (for the related context).

Parameters:

account - the account.

Returns:

the list of rights or an empty collection if the account does not have any document rights. 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 rights. 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.

listRightsByAccounts

Collection<DocumentRight> listRightsByAccounts(Collection<Account> accounts)

List rights for one or more accounts. This method can be used to determine which rights have been assigned directly to a user and their associated groups.

Only rights that the caller is allowed to view will be returned. The caller can view rights if they are a context manager or inspector (for the related context).

Parameters:

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

Returns:

the list of rights or an empty collection if the accounts do not have any document rights. If applicable, this method will return an empty collection rather than null to indicate no results.

searchRightsByAccount

Collection<DocumentRight> searchRightsByAccount(Account account,
                                                Context context)
                                                throws UnknownContextException

Search rights assigned to an account, optionally filtered on a context. This method can be used to list rights for an account, optionally filtered on a context. This method can be used to determine which rights have been assigned directly and indirectly (via group membership) to a user or group. Internally this method is used by the desktop synchronize and request processes to list all the rights associated with the authenticated user. Request provides a context extracted from the classification cookie. Synchronize does not provide a context.

Parameters:

account - the account.

context - the optional context. This parameter is optional, it is valid to pass null.

Returns:

the list of rights or an empty collection if there are no rights matching the search criteria. If applicable, this method will return an empty collection rather than null to indicate no results.

Throws:

UnknownContextException - the context does not exist.

searchRightsByAccounts

Collection<DocumentRight> searchRightsByAccounts(Collection<Account> accounts,
                                                 Context context)
                                                 throws UnknownContextException

Search rights assigned to one or more accounts, optionally filtered by a context. This method can be used to list rights for one or more accounts, optionally filtered on a context. This method is used to determine which rights have been assigned directly to a user and associated groups.

Parameters:

accounts - the accounts.

context - the optional context. This parameter is optional, it is valid to pass null.

Returns:

the list of rights or an empty collection if there are no rights matching the search criteria. If applicable, this method will return an empty collection rather than null to indicate no results.

Throws:

UnknownContextException - the context does not exist.

refreshDocumentRight

DocumentRight refreshDocumentRight(DocumentRight right)
                                   throws UnknownDocumentRightException,
                                          AuthorizationDeniedException

Refresh a right's properties.

Authorization

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.

Impact

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

Parameters:

right - the right.

Returns:

the refreshed right. This method will never return null.

Throws:

UnknownDocumentRightException - the right does not exist.

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

Skip navigation links