Skip navigation links

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

public interface DocumentRightOperationsEndpoint

Web Service end point interface for Document Right Operations. Document right operations include checking in rights, altering item restrictions, listing rights and checking items across sets of rights.

WSDL

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

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

Endpoint URL

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

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

Method Summary

DocumentRight[]	assignRole(ContextInstanceRef context, DocumentRoleRef role, AccountRef[] accounts, ItemCode[] items) Assign a document role.
DocumentRight[]	checkInRightsForAccount(AccountRef account) Check all rights in use by an account.
DocumentRight[]	listRightsByAccount(AccountRef account) List rights for an account.
DocumentRight[]	listRightsByContext(ContextInstanceRef context, PageRange pageRange) List rights assigned within a context.
DocumentRight[]	reassignRole(DocumentRightRef[] rights, DocumentRoleRef role, ItemCode[] items) Alter role assignments.
DocumentRight[]	saveChangesToItems(DocumentRightRef[] rights, ItemCode[] itemCodes, ItemCode[] delta) Alter the item restrictions for a set of rights.
void	unassignRights(DocumentRightRef[] rights) Un-assign a set of rights.

Method Detail

assignRole

DocumentRight[] assignRole(ContextInstanceRef context,
                           DocumentRoleRef role,
                           AccountRef[] accounts,
                           ItemCode[] items)
                           throws AccountAlreadyAssignedFault,
                                  UnsupportedDocumentRoleFault,
                                  UnknownContextFault,
                                  UnknownDocumentRoleFault,
                                  AuthorizationDeniedFault

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.

Assigning a role to a user

The following code demonstrates how to assign a role to a user. To assign a role, the role, context and user or group must be specified. If the role is restricted to individual items then items can also be specified as in the assign role method.

 import static oracle.irm.j2ee.jws.rights.context.DocumentRightOperations.getDocumentRightOperationsEndpoint;
 
 import java.net.Authenticator;
 import java.net.PasswordAuthentication;
 import java.net.URLEncoder;
 import java.util.UUID;
 
 import oracle.irm.engine.types.core.account.AccountRef;
 import oracle.irm.engine.types.rights.context.ContextInstanceRef;
 import oracle.irm.engine.types.rights.context.DocumentRoleRef;
 import oracle.irm.engine.types.rights.context.DomainRef;
 import oracle.irm.j2ee.jws.rights.context.DocumentRightOperationsEndpoint;
 
 public class AssignRoleWS {
 
     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");
         
         DomainRef domainRef = new DomainRef(domainUUID);
 
         // Document Role UUID is for the "Sample Role" role
         UUID documentRoleUUID = UUID.fromString("ee82c3f9-152b-440d-afd7-dbf36b0c8188");
         
         DocumentRoleRef roleRef = new DocumentRoleRef(documentRoleUUID, domainRef);
 
         // Context UUID is fixed for sample code
         UUID contextUUID = UUID.fromString("46f910d9-dd30-476e-b060-4d01f88f8b05");
 
         ContextInstanceRef contextInstanceRef = new ContextInstanceRef(contextUUID);
         
         // Get the document right operations endpoint
         DocumentRightOperationsEndpoint rightOperations = getDocumentRightOperationsEndpoint(hostPort);
 
         // Reference the account by user name
         AccountRef accountRef = new AccountRef("urn:user:" + URLEncoder.encode(username, "utf-8"));
 
         // Assign the role to the account
         rightOperations.assignRole(
             contextInstanceRef, 
             roleRef, 
             new AccountRef[] { accountRef }, 
             null); // no item constraints
     }
 }

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.

Throws:

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

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

UnknownContextFault - the context does not exist.

UnknownDocumentRoleFault - the role does not exist.

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

reassignRole

DocumentRight[] reassignRole(DocumentRightRef[] rights,
                             DocumentRoleRef role,
                             ItemCode[] items)
                             throws UnsupportedDocumentRoleFault,
                                    UnknownDocumentRoleFault,
                                    UnknownDocumentRightFault,
                                    AuthorizationDeniedFault

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.

Altering the role assigned to a user or group

The following code demonstrates how to alter a role assignment using the reassignRole method over web services. The sample code adds an item code exclusion to a role assignment. Typically this method is used to alter the role, but as the sample code only has one demonstration role it shows how to alter the item restrictions.

 import static oracle.irm.j2ee.jws.rights.context.DocumentRightOperations.getDocumentRightOperationsEndpoint;
 
 import java.net.Authenticator;
 import java.net.PasswordAuthentication;
 import java.net.URLEncoder;
 
 import oracle.irm.engine.types.classifications.item.ItemCode;
 import oracle.irm.engine.types.core.account.AccountRef;
 import oracle.irm.engine.types.rights.context.DocumentRight;
 import oracle.irm.engine.types.rights.context.DocumentRightRef;
 import oracle.irm.engine.types.rights.context.DocumentRoleRef;
 import oracle.irm.engine.types.rights.context.DomainRef;
 import oracle.irm.j2ee.jws.rights.context.DocumentRightOperationsEndpoint;
 
 public class ReassignRoleWS {
 
     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());
             }
         });
 
         // Get the document right operations web service
         DocumentRightOperationsEndpoint rightOperations = getDocumentRightOperationsEndpoint(hostPort);
 
         // Reference the account by user name
         AccountRef accountRef = new AccountRef("urn:user:" + URLEncoder.encode(username, "utf-8"));
         
         // Get all rights assigned to the account
         DocumentRight[] rights = rightOperations.listRightsByAccount(accountRef);
 
         // Take the first one on the list
         DocumentRight right = rights[0];
 
         DocumentRightRef rightRef = new DocumentRightRef(right.getUuid());
 
         // Get a reference to the role to be reassigned
         DomainRef domainRef = right.getRole().getDomain();
 
         DocumentRoleRef roleRef = new DocumentRoleRef(right.getRole().getUuid(), domainRef);
 
         // Change the item exclusion list to contain one sample item
         ItemCode itemCode = new ItemCode();
         itemCode.setValue("sample-item-code");
 
         // Reassign the role to the account
         rightOperations.reassignRole(new DocumentRightRef[] { rightRef }, roleRef, new ItemCode[] { itemCode });
     }
 }

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.

Throws:

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

UnknownDocumentRoleFault - the role does not exist.

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

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

checkInRightsForAccount

DocumentRight[] checkInRightsForAccount(AccountRef account)
                                        throws AuthorizationDeniedFault

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.

Throws:

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

DocumentRight[] saveChangesToItems(DocumentRightRef[] rights,
                                   ItemCode[] itemCodes,
                                   ItemCode[] delta)
                                   throws UnknownDocumentRightFault,
                                          AuthorizationDeniedFault

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.

Alter item restrictions associated with a right

The following code demonstrates how to alter the item locks or exclusions associated with a right. The sample code replaces one item code with two item codes.

 import static oracle.irm.j2ee.jws.rights.context.DocumentRightOperations.getDocumentRightOperationsEndpoint;
 
 import java.net.Authenticator;
 import java.net.PasswordAuthentication;
 import java.net.URLEncoder;
 import java.util.Date;
 
 import oracle.irm.engine.types.classifications.item.ItemCode;
 import oracle.irm.engine.types.core.account.AccountRef;
 import oracle.irm.engine.types.rights.context.DocumentRight;
 import oracle.irm.engine.types.rights.context.DocumentRightRef;
 import oracle.irm.j2ee.jws.rights.context.DocumentRightOperationsEndpoint;
 
 public class SaveChangesToItemsWS {
 
     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());
             }
         });
 
         // Get the document right operations web service
         DocumentRightOperationsEndpoint rightOperations = getDocumentRightOperationsEndpoint(hostPort);
 
         // Reference the account by user name
         AccountRef accountRef = new AccountRef("urn:user:" + URLEncoder.encode(username, "utf-8"));
         
         // Get all rights assigned to the account
         DocumentRight[] rights = rightOperations.listRightsByAccount(accountRef);
 
         // Take the first one on the list
         DocumentRight right = rights[0];
 
         DocumentRightRef rightRef = new DocumentRightRef(right.getUuid());
 
         // The save change method allows items to be added and/or removed in the same call.
         // It does this be comparing two sets of items and applying the differences.
         
         // Item codes
         ItemCode sampleItemCode = new ItemCode();
         sampleItemCode.setValue("sample-item-code");
         
         ItemCode sampleItemCodeOne = new ItemCode();
         sampleItemCodeOne.setValue("sample-item-code-one");
         sampleItemCodeOne.setTime(new Date());
         
         ItemCode sampleItemCodeTwo = new ItemCode();
         sampleItemCodeTwo.setValue("sample-item-code-two");
         sampleItemCodeTwo.setTime(new Date());
         
         // This example shows a delta where item "sample-item-code" is removed
         // and items "sample-item-code-one" and "sample-item-code-two" are added.
         ItemCode[] itemCodes = new ItemCode[] { sampleItemCode };
         ItemCode[] deltaItemCodes = new ItemCode[] { sampleItemCodeOne, sampleItemCodeTwo };
                  
         // Alter the items
         rightOperations.saveChangesToItems(new DocumentRightRef[] { rightRef },itemCodes, deltaItemCodes);
     }
 }

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.

Throws:

UnknownDocumentRightFault - the document right does not exist.

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

unassignRights

void unassignRights(DocumentRightRef[] rights)
                    throws AuthorizationDeniedFault

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.

Unassigning rights assigned to a user

The following code demonstrates how to unassign rights that have been assigned to a user. The sample first lists all the rights directly assigned to the user and unassigns them. To unassign the right the authenticated user must be a context manager for the related context.

 import static oracle.irm.j2ee.jws.rights.context.DocumentRightOperations.getDocumentRightOperationsEndpoint;
 
 import java.net.Authenticator;
 import java.net.PasswordAuthentication;
 import java.net.URLEncoder;
 
 import oracle.irm.engine.types.core.account.AccountRef;
 import oracle.irm.engine.types.rights.context.DocumentRight;
 import oracle.irm.engine.types.rights.context.DocumentRightRef;
 import oracle.irm.j2ee.jws.rights.context.DocumentRightOperationsEndpoint;
 
 public class UnassignRightsWS {
 
     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());
             }
         });
 
         // Get the document right operations web service
         DocumentRightOperationsEndpoint rightOperations = getDocumentRightOperationsEndpoint(hostPort);
 
         // Reference the account by user name
         AccountRef accountRef = new AccountRef("urn:user:" + URLEncoder.encode(username, "utf-8"));
         
         // Get all rights assigned to the account
         DocumentRight[] rights = rightOperations.listRightsByAccount(accountRef);
 
         DocumentRightRef[] rightRefs = new DocumentRightRef[rights.length];
 
         for (int i = 0; i < rightRefs.length; ++i) {
             rightRefs[i] = new DocumentRightRef(rights[i].getUuid());
         }
 
         // Unassign the rights
         rightOperations.unassignRights(rightRefs);
     }
 }

Parameters:

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

Throws:

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

listRightsByContext

DocumentRight[] listRightsByContext(ContextInstanceRef context,
                                    PageRange pageRange)
                                    throws UnknownContextFault,
                                           AuthorizationDeniedFault

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.

Throws:

UnknownContextFault - the context does not exist.

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

listRightsByAccount

DocumentRight[] listRightsByAccount(AccountRef account)
                                    throws AuthorizationDeniedFault

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

Listing rights assigned to a user or group

The following code demonstrates how to list the rights that have been assigned to a user or group. The code displays the role label and the context UUID from each right.

 import static oracle.irm.j2ee.jws.rights.context.DocumentRightOperations.getDocumentRightOperationsEndpoint;
 
 import java.net.Authenticator;
 import java.net.PasswordAuthentication;
 import java.net.URLEncoder;
 
 import oracle.irm.engine.types.classifications.item.ItemCode;
 import oracle.irm.engine.types.core.account.AccountRef;
 import oracle.irm.engine.types.rights.context.DocumentRight;
 import oracle.irm.j2ee.jws.rights.context.DocumentRightOperationsEndpoint;
 
 public class ListRightsByAccountWS {
 
     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());
             }
         });
 
         // Get the document right operations web service
         DocumentRightOperationsEndpoint rightOperations = getDocumentRightOperationsEndpoint(hostPort);
 
         // Reference the account by user name, allowed formats are
         //  urn:user:xxxx
         //  urn:group:xxxx
         //  00000000-0000-0000-0000-000000000000
         AccountRef accountRef = new AccountRef("urn:user:" + URLEncoder.encode(username, "utf-8"));
         
         // Get all of the rights assigned to the account
         DocumentRight[] rights = rightOperations.listRightsByAccount(accountRef);
 
         // Display a summary of each right
         for (DocumentRight right : rights) {
             System.out.println("Account: " + right.getAccount().getUuid());
             System.out.println(" Context: " + right.getContext().getUuid());
             System.out.println(" Role: " + right.getRole().getUuid());
 
             // Show items
             ItemCode[] itemCodes = right.getItemCodes();
             
             if (itemCodes != null) {
                 for (ItemCode itemCode : itemCodes) {
                     System.out.println(" ItemCode: " + itemCode.getValue());
                 }
             }
         }
     }
 }

Parameters:

account - the account.

Returns:

the list of rights or an empty collection if the account does not have any document rights.

Throws:

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

Skip navigation links