Skip navigation links

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

public interface DocumentRoleOperationsEndpoint

Web Service end point interface for Document Role Operations. The document role operations include role management operations such as creating, editing and copying roles. The document role operations also include role assignment roles and re-assignment.

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_role_operations?wsdl
 

Endpoint URL

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

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

Method Summary

DocumentRole[]	copyRoles(DocumentRoleRef[] roles, DomainRef domain) Copy a set of roles.
void	deleteRoles(DocumentRoleRef[] roles) Delete a set of roles.
DocumentRole[]	listRoles(DomainRef domain) List document roles owned by a domain.
DocumentRole[]	listRolesForContext(ContextInstanceRef context) List document roles available to a context.
DocumentRole	saveChangesToRole(DocumentRole role, DocumentRole delta) Save changes to a document role.
DocumentRole	saveNewRole(DomainRef domain, DocumentRole role) Save a new document role.

Method Detail

listRoles

DocumentRole[] listRoles(DomainRef domain)
                         throws UnknownDomainFault,
                                AuthorizationDeniedFault

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

Authorization

This method can be invoked by users that have the Domain Administrator role in the related domain. This role can be assigned using the addDomainAdministrators method. This method can be invoked by users that have the Domain Manager role in the related domain. This role can be assigned using the addDomainManagers method.

Parameters:

domain - the domain.

Returns:

the list of roles owned by the domain. If there are no roles an empty collection is returned.

Throws:

UnknownDomainFault - the domain does not exist.

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

listRolesForContext

DocumentRole[] listRolesForContext(ContextInstanceRef context)
                                   throws UnknownContextFault,
                                          AuthorizationDeniedFault

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

Authorization

This method can be invoked by users that have the Domain Administrator role in the related domain. This role can be assigned using the addDomainAdministrators method. This method can be invoked by users that have the Context Manager role in the related context. This role can be assigned using the addContextManagers method. This method can be invoked by users that have the Inspector role in the related context. This role can be assigned using the addInspectors method.

Parameters:

context - the context.

Returns:

the list of roles available to a context. If there are no roles an empty collection is returned.

Throws:

UnknownContextFault - the context does not exist.

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

saveNewRole

DocumentRole saveNewRole(DomainRef domain,
                         DocumentRole role)
                         throws DocumentRoleAlreadyExistsFault,
                                InvalidFeaturesFault,
                                InvalidTimePeriodFault,
                                UnknownDomainFault,
                                AuthorizationDeniedFault

Save a new document role. The document role will be owned by the specified Domain.

Authorization

This method can be invoked by users that have the Domain Administrator role in the related domain. This role can be assigned using the addDomainAdministrators method.

Impact

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

Create a new document role

The following code demonstrates how to create a role. The sample code uses a fixed role UUID so that all sample code can work with a known role. A new role would typically be given a new random UUID value. The sample role is set up to allow all the content operations required by the sample code. When assigned to a user, this role allows sealing, unsealing, resealing and (validated) peeking. This is done by a providing an appropriate set of features and export constraints.

 import static oracle.irm.engine.core.feature.FeatureConstants.OPEN_FEATURE_ID;
 import static oracle.irm.engine.core.feature.FeatureConstants.RESEAL_FEATURE_ID;
 import static oracle.irm.engine.core.feature.FeatureConstants.SEAL_FEATURE_ID;
 import static oracle.irm.j2ee.jws.rights.context.DocumentRoleOperations.getDocumentRoleOperationsEndpoint;
 
 import java.net.Authenticator;
 import java.net.PasswordAuthentication;
 import java.util.Locale;
 import java.util.UUID;
 
 import oracle.irm.engine.types.classifications.item.ItemConstraints;
 import oracle.irm.engine.types.core.feature.Feature;
 import oracle.irm.engine.types.core.general.Label;
 import oracle.irm.engine.types.core.license.LicenseCriteria;
 import oracle.irm.engine.types.core.time.TimePeriod;
 import oracle.irm.engine.types.rights.context.DocumentRole;
 import oracle.irm.engine.types.rights.context.DomainRef;
 import oracle.irm.j2ee.jws.rights.context.DocumentRoleOperationsEndpoint;
 
 public class SaveNewRoleWS {
 
     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());
             }
         });
         
         // Document Role UUID is fixed for sample code
         UUID documentRoleUUID = UUID.fromString("ee82c3f9-152b-440d-afd7-dbf36b0c8188");
 
         DocumentRole role = new DocumentRole();
         
         // The UUID value that identifies this role within the domain
         role.setUuid(documentRoleUUID);
 
         // Role has one English label
         Label label = new Label(Locale.ENGLISH, "Sample Role", "This is a role created from sample code.");
 
         // The human readable labels
         role.setLabels( new Label[] { label } );
 
         // This role allows the user to access content while offline by persisting licenses on the desktop
         role.setStorage(LicenseCriteria.Storage.PERSISTENT);
 
         // This role allows content to be saved in the clear (unsealing and copying)
         role.setExportConstraints(DocumentRole.ExportConstraints.NONE);
         
         // This role allows opening, sealing, resealing
         Feature open = new Feature(OPEN_FEATURE_ID, Feature.Use.IMMEDIATE, true);
         Feature seal = new Feature(SEAL_FEATURE_ID, Feature.Use.IMMEDIATE, true);
         Feature reseal = new Feature(RESEAL_FEATURE_ID, Feature.Use.IMMEDIATE, false);
         
         role.setFeatures( new Feature[] { open, seal, reseal });
         
         // Role allows document exclusions to be listed, by default all items are allowed
         role.setItemConstraints(ItemConstraints.Type.EXCLUSIONS);
         
         // This role allows content to be opened for one hour before refreshing the rights from the server
         TimePeriod value = new TimePeriod(1, TimePeriod.Units.HOURS);
         
         role.setRefreshPeriod(value);
         
         // This role has no additional time constraints
         role.setTimeSpans(null);
         
         // Get the document role operations web service
         DocumentRoleOperationsEndpoint roleOperations = getDocumentRoleOperationsEndpoint(hostPort);
 
         // Domain UUID is fixed for sample code
         UUID domainUUID = UUID.fromString("6fab93fd-2858-461a-a0b3-34e261dbf8fd");
 
         DomainRef domain = new DomainRef(domainUUID);
 
         // Save the new role
         roleOperations.saveNewRole(domain, role);
     }
 }

Parameters:

domain - the domain that owns this role.

role - the role.

Returns:

the new role.

Throws:

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

InvalidFeaturesFault - invalid features specified.

InvalidTimePeriodFault - invalid time period specified.

UnknownDomainFault - the domain does not exist.

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

saveChangesToRole

DocumentRole saveChangesToRole(DocumentRole role,
                               DocumentRole delta)
                               throws InvalidFeaturesFault,
                                      InvalidTimePeriodFault,
                                      ImmutableDocumentRoleFault,
                                      UnknownDocumentRoleFault,
                                      AuthorizationDeniedFault

Save changes to a document role. Save changes to a DocumentRole by providing two copies. Changes are made by comparing the two copies of the role. If there are no differences in a property then no changes are made to persistent storage for that property. Changes in collection based properties cause additions or removals to occur in persistent storage. For example, if the delta contains a new Feature as compared to the role then a new role will be associated with the template.

Authorization

This method can be invoked by users that have the Domain Administrator role in the related domain. This role can be assigned using the addDomainAdministrators method.

Impact

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

Parameters:

role - the document role to compare to the delta.

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

Returns:

the document role with the updated changes.

Throws:

InvalidFeaturesFault - invalid features specified.

InvalidTimePeriodFault - invalid time period specified.

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

UnknownDocumentRoleFault - the role does not exist.

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

deleteRoles

void deleteRoles(DocumentRoleRef[] roles)
                 throws CannotRemoveDocumentRoleFault,
                        AuthorizationDeniedFault

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

Authorization

This method can be invoked by users that have the Domain Administrator role in the related domain. This role can be assigned using the addDomainAdministrators method.

Impact

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

Parameters:

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

Throws:

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

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

copyRoles

DocumentRole[] copyRoles(DocumentRoleRef[] roles,
                         DomainRef domain)
                         throws UnknownDomainFault,
                                UnknownDocumentRoleFault,
                                AuthorizationDeniedFault

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

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

Authorization

This method can be invoked by users that have the Domain Administrator role in the related domain. This role can be assigned using the addDomainAdministrators method.

Impact

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

Parameters:

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

domain - the domain.

Returns:

the copied document roles.

Throws:

UnknownDomainFault - the domain does not exist.

UnknownDocumentRoleFault - the role does not exist.

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

Skip navigation links