Skip navigation links

oracle.irm.j2ee.jws.rights.context
Interface ContextOperationsEndpoint

public interface ContextOperationsEndpoint

Web Service end point interface for Context 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.

WSDL

The WSDL for this end point interface can be downloaded from the server using the following URL:

 http://irm.example.com/irm_services/context_operations?wsdl
 

Endpoint URL

Requests for this web service should be sent to the following URL:

 https://irm.example.com/irm_services/context_operations
 

Method Summary

void	addContextManagers(ContextInstanceRef context, AccountRef[] accounts) Add one or managers to a context.
void	addInspectors(DomainRef domain, AccountRef[] accounts) Add one or inspectors to a domain.
ContextInstance	createContextFromTemplate(UUID uuid, ContextTemplateRef template, Label[] labels, ContextInstance.Visibility visibility, AccountRef[] managers) Create a context.
void	deleteContext(ContextInstanceRef context) Delete a context.
AccountRef[]	listContextManagers(ContextInstanceRef context) List context managers.
ContextInstance[]	listContexts(PageRange pageRange) List contexts that the authenticated principal is authorized to access.
AccountRef[]	listInspectors(DomainRef domain) List inspectors.
void	removeContextManagers(ContextInstanceRef context, AccountRef[] accounts) Remove one or managers from a context.
void	removeInspectors(DomainRef domain, AccountRef[] accounts) Remove one or inspectors from a domain.
ContextInstance	saveChangesToContext(ContextInstance context, ContextInstance delta) Save changes to a context.
ContextJournalEntry[]	searchJournal(String[] accountNames, ItemCode[] items, TimeRange timeRange, PageRange pageRange, ContextJournalSorting sorting) Search the context journal.

Method Detail

createContextFromTemplate

ContextInstance createContextFromTemplate(UUID uuid,
                                          ContextTemplateRef template,
                                          Label[] labels,
                                          ContextInstance.Visibility visibility,
                                          AccountRef[] managers)
                                          throws InactiveContextTemplateFault,
                                                 UnknownContextTemplateFault,
                                                 ContextInstanceAlreadyExistsFault,
                                                 UnsupportedCryptoSchemaFault,
                                                 AuthorizationDeniedFault

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.

Create a context

The following code demonstrates how to create a context from a context template. The sample code uses a fixed context template reference (information that identifies the template) and provides a fixed UUID value for the new context. The authenticated user becomes the context manager. The context is created with two labels, English and German. This context is used in the sample code that assigns a role, as well as the sealing, unsealing, resealing, reclassification and peeking code samples.

 import static oracle.irm.j2ee.jws.rights.context.ContextOperations.getContextOperationsEndpoint;
 
 import java.net.Authenticator;
 import java.net.PasswordAuthentication;
 import java.util.Locale;
 import java.util.UUID;
 
 import oracle.irm.engine.types.core.general.Label;
 import oracle.irm.engine.types.rights.context.ContextTemplateRef;
 import oracle.irm.engine.types.rights.context.DomainRef;
 import oracle.irm.engine.types.rights.context.ContextInstance.Visibility;
 import oracle.irm.j2ee.jws.rights.context.ContextOperationsEndpoint;
 
 public class CreateContextFromTemplateWS {
 
     public static void main(String[] args) throws Exception {
 
         final String hostPort = args[0];
         final String username = args[1];
         final String password = args[2];
         
         // Configure an authenticator to provide the credentials
         // for the web service
         Authenticator.setDefault(new Authenticator() {
             @Override
             protected PasswordAuthentication getPasswordAuthentication() {
                 return new PasswordAuthentication(username, password.toCharArray());
             }
         });
         
         // Domain UUID is fixed for sample code
         UUID domainUUID = UUID.fromString("6fab93fd-2858-461a-a0b3-34e261dbf8fd");
         
         // Context Template UUID is for the "standard" template automatically installed with a domain       
         UUID templateUUID = UUID.fromString("930876e6-a505-4a10-8d93-bc43d9a37c23");
         
         // Context UUID is fixed for sample code
         UUID contextUUID = UUID.fromString("46f910d9-dd30-476e-b060-4d01f88f8b05");
         
         // Use the first domain available
         DomainRef domainRef = new DomainRef(domainUUID);
 
         // Use the first template available
         ContextTemplateRef templateRef = new ContextTemplateRef(templateUUID, domainRef);
 
         // Get the context operations web service
         ContextOperationsEndpoint contextOperations = getContextOperationsEndpoint(hostPort);
 
         // Context has two labels, English and German
         Label english = new Label(Locale.ENGLISH, "Sample Classification", "Created from sample code.");
         Label german = new Label(Locale.GERMAN, "Beispielklassifikation", "Verursacht vom Beispielcode.");
         
         // Create a context based on that template
         contextOperations.createContextFromTemplate(
             contextUUID, // context UUID value 
             templateRef, // context template
             new Label[] { english, german }, // labels
             Visibility.DOMAIN, // visibility 
             null); // additional context managers
     }
 }

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.

Throws:

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

UnknownContextTemplateFault - the context template does not exist.

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

UnsupportedCryptoSchemaFault - unsupported cryptographic schema.

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

saveChangesToContext

ContextInstance saveChangesToContext(ContextInstance context,
                                     ContextInstance delta)
                                     throws UnknownContextFault,
                                            AuthorizationDeniedFault

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.

Throws:

UnknownContextFault - the context does not exist.

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

deleteContext

void deleteContext(ContextInstanceRef context)
                   throws CannotRemoveContextInstanceFault,
                          AuthorizationDeniedFault

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:

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

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

listContexts

ContextInstance[] listContexts(PageRange pageRange)
                               throws AuthorizationDeniedFault

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.

Throws:

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

listContextManagers

AccountRef[] listContextManagers(ContextInstanceRef context)
                                 throws UnknownContextFault,
                                        AuthorizationDeniedFault

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.

Throws:

UnknownContextFault - the context does not exist.

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

See Also:

addContextManagers

addContextManagers

void addContextManagers(ContextInstanceRef context,
                        AccountRef[] accounts)
                        throws AccountAlreadyManagerFault,
                               UnknownContextFault,
                               AuthorizationDeniedFault

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:

AccountAlreadyManagerFault - one of the provided accounts is already a context manager.

UnknownContextFault - the context does not exist.

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

removeContextManagers

void removeContextManagers(ContextInstanceRef context,
                           AccountRef[] accounts)
                           throws CannotRemoveManagersFault,
                                  UnknownContextFault,
                                  AuthorizationDeniedFault

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:

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

UnknownContextFault - the context does not exist.

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

listInspectors

AccountRef[] listInspectors(DomainRef domain)
                            throws UnknownDomainFault,
                                   AuthorizationDeniedFault

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.

Throws:

UnknownDomainFault - the domain does not exist.

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

addInspectors

void addInspectors(DomainRef domain,
                   AccountRef[] accounts)
                   throws AccountAlreadyInspectorFault,
                          UnknownDomainFault,
                          AuthorizationDeniedFault

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:

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

UnknownDomainFault - the domain does not exist.

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

removeInspectors

void removeInspectors(DomainRef domain,
                      AccountRef[] accounts)
                      throws UnknownDomainFault,
                             AuthorizationDeniedFault

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:

UnknownDomainFault - the domain does not exist.

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

searchJournal

ContextJournalEntry[] searchJournal(String[] accountNames,
                                    ItemCode[] items,
                                    TimeRange timeRange,
                                    PageRange pageRange,
                                    ContextJournalSorting sorting)
                                    throws AuthorizationDeniedFault

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.

Searching the context journal using web services

The following code demonstrates how to search the content usage for context classified content. The sample code searches for all entries for the last twenty four hours and displays a short summary for the first one hundred entries.

 import static oracle.irm.j2ee.jws.rights.context.ContextOperations.getContextOperationsEndpoint;
 
 import java.net.Authenticator;
 import java.net.PasswordAuthentication;
 import java.util.Calendar;
 import java.util.Date;
 
 import oracle.irm.engine.types.core.general.PageRange;
 import oracle.irm.engine.types.core.time.TimeRange;
 import oracle.irm.engine.types.rights.journal.ContextJournalEntry;
 import oracle.irm.j2ee.jws.rights.context.ContextOperationsEndpoint;
 
 public class SearchJournalWS {
 
     public static void main(String[] args) throws Exception {
 
         // The server address. e.g. https://irm.example.com
         final String hostPort = args[0];
         final String username = args[1];
         final String password = args[2];
         
         // Configure an authenticator to provide the credentials
         // for the web service
         Authenticator.setDefault(new Authenticator() {
             @Override
             protected PasswordAuthentication getPasswordAuthentication() {
                 return new PasswordAuthentication(username, password.toCharArray());
             }
         });
 
         // Search for all records from the last 24 hours
         Date end = new Date();
 
         // Use a calendar to work out the time range
         Calendar calendar = Calendar.getInstance();
 
         calendar.setTime(end);
         calendar.add(Calendar.DAY_OF_MONTH, -1);
 
         Date begin = calendar.getTime();
 
         TimeRange timeRange = new TimeRange(begin, end);
 
         // Get the context operations web service
         ContextOperationsEndpoint contextOperations = getContextOperationsEndpoint(hostPort);
 
         // Search the context journal
         PageRange pageRange = new PageRange(1, 100);
         
         ContextJournalEntry[] journalResults = contextOperations.searchJournal(
             null, // no accounts filter
             null, // no item codes filter
             timeRange, 
             pageRange, 
             null); // no sorting details
 
         if (journalResults.length == 0)
             return;
 
         // Display the timestamp, URI and and feature for each entry
         for (ContextJournalEntry entry : journalResults) {
             
             System.out.print("Timestamp : " + entry.getTime());
             System.out.print(" Account   : " + entry.getAccount().getName());
             System.out.print(" Content   : " + (entry.getUri() != null ? entry.getUri() : ""));
             System.out.print(" Feature   : " + entry.getFeature().getId());
         }
     }
 }

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.

Throws:

AuthorizationDeniedFault - if the authenticated user is not allowed to search any contexts.

Skip navigation links