Skip navigation links

oracle.irm.engine.rights.context
Class ContextOperationsInstance

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

public final class ContextOperationsInstance

extends Object

Context related operations. The context related operations cover the tasks that a context manager would typically perform on a ContextInstance. This includes altering ContextInstance names and descriptions, specifying the set of ContextInstance managers and setting ContextInstance level ItemCode exclusions. Journal operations are also included. The content journal contains a log of all activity performed on Context sealed content. This includes actions performed while off-line as well as on-line. It includes actions performed on the desktop as well as actions perform on the server. The journal is filled automatically when users perform actions on content, e.g. when content is opened or printed. Failed actions are also added to the journal.

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

Method Summary

static void	addContextManagers(ContextInstance context, Collection<Account> accounts) Add one or managers to a context.
static void	addInspectors(Domain domain, Collection<Account> accounts) Add one or inspectors to a domain.
static boolean	contextExists(UUID uuid) Check for a context's existence.
static int	countContextsByTemplate(ContextTemplate template) Count the number of contexts created from a template.
static ContextInstance	createContextFromTemplate(UUID uuid, ContextTemplate template, Collection<Label> labels, ContextInstance.Visibility visibility, Collection<Account> managers) Create a context.
static void	deleteContext(ContextInstance context) Delete a context.
static int	deleteContextJournalEntries(ContextInstance context) Deletes all journal entries relating to a context.
static int	deleteJournalEntriesByRange(TimeRange range) Delete journal entries that fall in the given time range.
static KeySet	generateKeySetForContext(ContextInstance context) Generate a new key set for a context.
static ContextInstance.Role	getRole(Account account) Find out if an account has any context based role.
static ContextInstance.Role	getRoleForContext(ContextInstance context, Account account) Find out what role an account has within a context.
static ContextInstance.Role	getRoleForDomain(Domain domain, Account account) Find out what (context related) role an account has within a domain.
static Collection<Account>	listContextManagers(ContextInstance context) List context managers.
static Collection<ContextInstance>	listContexts(PageRange pageRange) List contexts that the authenticated principal is authorized to access.
static Collection<ContextInstance>	listContextsByAccount(Account account, ContextInstance.Role filter, PageRange pageRange) List contexts managed by a specified account.
static Collection<ContextInstance>	listContextsByDomain(Domain domain, PageRange pageRange) List contexts owned by a domain.
static Collection<Account>	listInspectors(Domain domain) List inspectors.
static Collection<ContextInstance>	listOrphanedContexts(Domain domain) List orphaned contexts.
static Collection<ContextInstance>	listTrustedContexts(ContextInstance context) List trusted contexts.
static Collection<ContextInstance>	manageOrphanedContexts(Domain domain) Gain management rights for all orphaned contexts.
static ContextCookie	peekContent(byte[] content) Peek sealed content.
static ContextInstance	refreshContext(ContextInstance context) Refresh a context's properties.
static void	removeContextManagers(ContextInstance context, Collection<Account> accounts) Remove one or managers from a context.
static void	removeInspectors(Domain domain, Collection<Account> accounts) Remove one or inspectors from a domain.
static ContextInstance	saveChangesToContext(ContextInstance context, ContextInstance delta) Save changes to a context.
static Collection<ContextJournalEntry>	searchJournal(Collection<String> accountNames, Collection<ItemCode> items, TimeRange timeRange, PageRange pageRange, ContextJournalSorting sorting) Search the context journal.
static void	uploadJournalEntries(Collection<ContextJournalEntry> entries) Uploads a set of context journal entries.

Methods inherited from class java.lang.Object

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

Method Detail

createContextFromTemplate

public static ContextInstance createContextFromTemplate(UUID uuid,
                                                        ContextTemplate template,
                                                        Collection<Label> labels,
                                                        ContextInstance.Visibility visibility,
                                                        Collection<Account> managers)
                                                 throws InactiveContextTemplateException,
                                                        UnknownContextTemplateException,
                                                        ContextInstanceAlreadyExistsException,
                                                        IllegalArgumentException,
                                                        UnsupportedCryptoSchemaException,
                                                        AuthorizationDeniedException

Create a context. A context is created from a template. The template defines the structure of the context and what roles are available to assign to accounts. Only active templates can be provided when creating contexts. Changes to the template (post context creation) dynamically affect the context. e.g. adding a role to the template makes the role available to the context.

When a context is created a KeySet is also generated and associated with 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 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:

uuid - uUID for the context. If this UUID is not provided one will be generated automatically. Providing an explicit UUID can be useful to make the context identity deterministic. This parameter is optional, it is valid to pass null.

template - the template.

labels - the context's names and descriptions. This parameter is optional, it is valid to pass null or an empty collection.

visibility - context visibility to inspectors.

managers - additional context managers. This parameter is optional, it is valid to pass null or an empty collection.

Returns:

the context. This method will never return null.

Throws:

InactiveContextTemplateException - inactive context. When creating a context from a template the template must be marked as active.

UnknownContextTemplateException - the context template does not exist.

ContextInstanceAlreadyExistsException - a context instance with the same UUID already exists.

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

UnsupportedCryptoSchemaException - unsupported cryptographic schema.

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

saveChangesToContext

public static ContextInstance saveChangesToContext(ContextInstance context,
                                                   ContextInstance delta)
                                            throws UnknownContextException,
                                                   IllegalArgumentException,
                                                   AuthorizationDeniedException

Save changes to a context. Save changes to a ContextInstance by providing two copies. Changes are made by comparing the two copies of the context. 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 context then a new label will be added.

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 to compare to the delta.

delta - the changes. The Template and Uuid properties must match with the context parameter.

Returns:

the context with the updated changes. This method will never return null.

Throws:

UnknownContextException - the context does not exist.

IllegalArgumentException - illegal argument. If the Template and Uuid properties of the delta parameter do not match the context parameter.

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

deleteContext

public static void deleteContext(ContextInstance context)
                          throws CannotRemoveContextInstanceException,
                                 AuthorizationDeniedException

Delete a context. Delete a ContextInstance and associated cryptography keys.

WARNING - deleting a ContextInstance also deletes the content related cryptography keys, making content sealed against this Context permanently inaccessible. Deleting a context also deletes any related journal entries.

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.

Throws:

CannotRemoveContextInstanceException - the context cannot be removed as rights are assigned within the context. A context cannot be deleted if there are any contexts assignments within the context. The context can only be deleted after the rights are unassigned.

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

listContexts

public static Collection<ContextInstance> listContexts(PageRange pageRange)
                                                throws AuthorizationDeniedException,
                                                       IllegalArgumentException

List contexts that the authenticated principal is authorized to access. A context can be accessed by any of it's context managers. Any inspector for the related domain (a context is related to a domain via it's context template) will be able to access the context as long as the context is visible to inspectors. Contexts are visible to inspectors by setting the Visibility property to the DOMAIN.

Parameters:

pageRange - page range for the search result.

Returns:

the list of contexts. If no contexts 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 contexts. 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.

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.

listContextsByAccount

public static Collection<ContextInstance> listContextsByAccount(Account account,
                                                                ContextInstance.Role filter,
                                                                PageRange pageRange)
                                                         throws IllegalArgumentException

List contexts managed by a specified account. Context managers can view and alter context related details. If the account provided is a context manager this operation lists all the ContextInstance instances an account can manage.

Inspectors can also view context related details. If the account provided is an inspector, this operation lists all the ContextInstance instances an inspector can view.

In an account is a context manager and an inspector a consolidated list of ContextInstance instances will be returned.

Parameters:

account - the user account.

filter - the context role filter. This filter allows the contexts to be listed that the account can manage, inspector or both.

pageRange - page range for the search result.

Returns:

the list of contexts. If no contexts 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:

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.

listContextsByDomain

public static Collection<ContextInstance> listContextsByDomain(Domain domain,
                                                               PageRange pageRange)
                                                        throws UnknownDomainException,
                                                               IllegalArgumentException

List contexts owned by a domain.

Parameters:

domain - the domain.

pageRange - page range for the search result.

Returns:

the list of contexts. If no contexts 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:

UnknownDomainException - the domain 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.

listOrphanedContexts

public static Collection<ContextInstance> listOrphanedContexts(Domain domain)
                                                        throws UnknownDomainException,
                                                               AuthorizationDeniedException

List orphaned contexts. A context is managed by a set of users. If all of these users have been deleted from the external user store the context is orphaned and cannot be managed. This method lists all the contexts (for the specified domain) that are orphaned.

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

domain - the domain.

Returns:

the orphaned contexts. 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.

listTrustedContexts

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

List trusted contexts. If the trusted contexts of a conetxt are not accessible to the context manager or an inspector this method allows the trusted contexts details to be obtained. A context may not be accessible if the authenticated user is not a context manager of the context, the user does not have the inspector role, or if the user is an inspector, the context is not visible to inspectors.

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:

context - the context.

Returns:

the trusted context details. 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.

countContextsByTemplate

public static int countContextsByTemplate(ContextTemplate template)
                                   throws UnknownContextTemplateException

Count the number of contexts created from a template.

Parameters:

template - the context template.

Returns:

the number of contexts

Throws:

UnknownContextTemplateException - the context template does not exist.

refreshContext

public static ContextInstance refreshContext(ContextInstance context)
                                      throws UnknownContextException,
                                             AuthorizationDeniedException

Refresh a context'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:

context - the context.

Returns:

the refreshed context. This method will never return null.

Throws:

UnknownContextException - the context does not exist.

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

contextExists

public static boolean contextExists(UUID uuid)

Check for a context's existence.

Parameters:

uuid - the context UUID.

Returns:

true if the context exists, otherwise false.

listContextManagers

public static Collection<Account> listContextManagers(ContextInstance context)
                                               throws UnknownContextException,
                                                      AuthorizationDeniedException

List context managers. Context managers are individuals who manage the rights associated with content sealed using this ContextInstance classification. A context manager can also specify the context names and descriptions using saveChangesToContext. A context manager can also specify the context level item exclusions using the same saveChangesToContext method.

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.

Returns:

the list of context managers. This will contains at least one manager. 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.

See Also:

addContextManagers

addContextManagers

public static void addContextManagers(ContextInstance context,
                                      Collection<Account> accounts)
                               throws AccountAlreadyManagerException,
                                      UnknownContextException,
                                      AuthorizationDeniedException

Add one or managers to a context. A ContextInstance will always have at least one manager. When a ContextInstance has multiple managers, each manager will have equal permissions to perform ContextInstance related activities.

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.

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 context manager.

UnknownContextException - the context does not exist.

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

removeContextManagers

public static void removeContextManagers(ContextInstance context,
                                         Collection<Account> accounts)
                                  throws CannotRemoveManagersException,
                                         UnknownContextException,
                                         AuthorizationDeniedException

Remove one or managers from a context. A ContextInstance must have at least one manager.

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.

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

Throws:

CannotRemoveManagersException - managers cannot be removed, as it would leave the context with no managers.

UnknownContextException - the context does not exist.

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

manageOrphanedContexts

public static Collection<ContextInstance> manageOrphanedContexts(Domain domain)
                                                          throws UnknownDomainException,
                                                                 AuthorizationDeniedException

Gain management rights for all orphaned contexts. A context is managed by a set of users. If all of these users have been deleted from the external user store the context is orphaned and cannot be managed. This method makes the authenticated user a context manager for all orphaned contexts. The existing orphaned managers are not removed by calling this method.

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:

domain - the domain.

Returns:

the orphaned contexts that are managed by the authenticated user. 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.

listInspectors

public static Collection<Account> listInspectors(Domain domain)
                                          throws UnknownDomainException,
                                                 AuthorizationDeniedException

List inspectors. List the inspectors for a domain, previously made inspectors using addInspectors.

Inspectors are individuals who can examine which accounts have document related rights within a ContextInstance.

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 inspectors. If there are no inspectors then an empty collection will be 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.

addInspectors

public static void addInspectors(Domain domain,
                                 Collection<Account> accounts)
                          throws AccountAlreadyInspectorException,
                                 UnknownDomainException,
                                 AuthorizationDeniedException

Add one or inspectors to a domain. A domain can have zero of more inspectors.

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:

AccountAlreadyInspectorException - one of the provided accounts is already an inspector.

UnknownDomainException - the domain does not exist.

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

removeInspectors

public static void removeInspectors(Domain domain,
                                    Collection<Account> accounts)
                             throws UnknownDomainException,
                                    AuthorizationDeniedException

Remove one or inspectors 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.

getRoleForContext

public static ContextInstance.Role getRoleForContext(ContextInstance context,
                                                     Account account)
                                              throws UnknownContextException

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

Parameters:

context - the context.

account - the account.

Returns:

the role type. This method will never return null.

Throws:

UnknownContextException - the context does not exist.

getRoleForDomain

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

Find out what (context related) role an account has within a domain. An account can either be an inspector or have no context based 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.

getRole

public static ContextInstance.Role getRole(Account account)

Find out if an account has any context based role. An account can either be a context manager or an inspector (or have no context based role). If an account is both a manager and an inspector then the manager role is returned.

Parameters:

account - the account.

Returns:

the role type. This method will never return null.

searchJournal

public static Collection<ContextJournalEntry> searchJournal(Collection<String> accountNames,
                                                            Collection<ItemCode> items,
                                                            TimeRange timeRange,
                                                            PageRange pageRange,
                                                            ContextJournalSorting sorting)
                                                     throws AuthorizationDeniedException,
                                                            IllegalArgumentException

Search the context journal. Search the context journal entries for activity on content for the specified accounts and/or document items. This search is restricted to the contexts available to the calling principal - i.e. the caller must be a context manager or inspector.

If a large number of entries are identified a sub-set of entries in the requested time range will be provided.

Parameters:

accountNames - the account names. The accounts names are used to perform a sub-string search for context journal entries containing the account names. The number of accounts names that can be provided has an upper limit. The maximum number of account names that can be passed to this function is defined by ContextOperations.MAXIMUM_JOURNAL_SEARCH_ACCOUNTS. This parameter is optional, it is valid to pass null or an empty collection.

items - the item codes. The item code value is used to perform a sub-string search for context journal entries. For example an item code value of 'report' would match documents where the item code is 'report.doc' and 'report.xls'. This parameter is optional, it is valid to pass null or an empty collection.

timeRange - time range for the search. This parameter is optional, it is valid to pass null.

pageRange - page range for the search result.

sorting - sorting criteria. This parameter is optional, it is valid to pass null.

Returns:

the results of the search. If no journal entries have been found results are still provided. 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 search any contexts.

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.

uploadJournalEntries

public static void uploadJournalEntries(Collection<ContextJournalEntry> entries)

Uploads a set of context journal entries. Adds entries to the database.

Impact

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

Parameters:

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

deleteJournalEntriesByRange

public static int deleteJournalEntriesByRange(TimeRange range)

Delete journal entries that fall in the given time range. The time range is inclusive.

Impact

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

Parameters:

range - the time range.

Returns:

the count of the deleted context journal entries.

deleteContextJournalEntries

public static int deleteContextJournalEntries(ContextInstance context)
                                       throws UnknownContextException

Deletes all journal entries relating to a context. All journal entries relating to the context will be removed from the database. This method is called when a context is deleted.

Impact

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

Parameters:

context - the context for whose journal entries to delete.

Returns:

the number of journal entries deleted.

Throws:

UnknownContextException - the context does not exist.

See Also:

deleteContext

peekContent

public static ContextCookie peekContent(byte[] content)
                                 throws UnsupportedClassificationSystemException,
                                        ContentParseException,
                                        IOException

Peek sealed content. Peek content sealed using the context classification system. This method will extract the Context and ItemCode from the sealed content public header.

This method does not attempt to check the public header against its declared signature.

Parameters:

content - sealed content.

Returns:

the context and item code cookie details. This method will never return null.

Throws:

UnsupportedClassificationSystemException - if the sealed content is not sealed using the context classification system.

ContentParseException - indicates that there was an issue parsing the sealed content. The exception will contains a reason that identifies which section of the sealed content which caused the parsing to fail.

IOException - an input/output/sealing error occurred peeking the content.

generateKeySetForContext

public static KeySet generateKeySetForContext(ContextInstance context)
                                       throws UnknownContextException

Generate a new key set for a context. A context is associated with one or more key sets. This method generates a new key set for a context and makes it the active key set (the key set that is used by default when sealing content). The default cryptography schema is used when generating the key set.

Impact

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

Parameters:

context - the context.

Returns:

the new key set. This method will never return null.

Throws:

UnknownContextException - the context does not exist.

See Also:

generateKeySet

Skip navigation links