6.3 Using the Oracle IRM Web Service Code

This section contains the following topics:

6.3.1 Introduction

The following section provides example code that can be used with IRM provided JAX-WS web service proxies.

6.3.2 Class Path

The code samples in this section require the following jar files to be added to the class path. These jar files contain the web service proxy code and objects equivalent to those that would be generated with a web service proxy generated.

  • irm-common.jar

  • irm-engine.jar

  • irm-ws.jar

These jar files also provide the WSDL and XSD files required to use the web service proxies.

Note:

These jar files are not required if other WSDL web service proxy code generators are used (such as the JDeveloper web service proxy generator).

6.3.3 Differences from the JDeveloper Generated Code

The Oracle IRM provided web service proxies are functionality identical to the ones generated by JDeveloper (or any other web service proxy generator). However there are a few code differences:

  • UUID types use java.util.UUID rather than java.lang.String.

  • Date types use java.util.Date rather than javax.xml.datatype.XMLGregorianCalendar.

  • The classification cookie can be provided as a ContextCookie object rather than an XML document.

  • The classification cookie property modifier is called setCookie rather than setAny.

  • Objects that represent XML types have a constructor that allows all the properties to be provided on construction.

  • Constant values, such as the context classification UUID are available as static final variables.

6.3.4 Creating a Domain

The following code demonstrates how to create a domain. The sample code uses a fixed domain UUID so that all sample code can work against a known domain. A new domain would typically be given a new random UUID value. The authenticated user becomes the domain administrator. When a domain is created, a set of human-readable labels can be given to the domain for the target language audience.

Example 6-20

import static oracle.irm.j2ee.jws.rights.context.DomainOperations.getDomainOperationsEndpoint;
 
 import java.util.Locale;
 import java.util.UUID;
 
 import oracle.irm.engine.types.core.general.Label;
 import oracle.irm.engine.types.rights.context.Domain;
 import oracle.irm.j2ee.jws.rights.context.DomainOperationsEndpoint;
 
 public class SaveNewDomainWS {
 
     public static void main(String[] args) throws Exception {
 
         String hostPort = args[0];
         String username = args[1];
         String password = args[2];
         
         // Get the domain operations web service
         DomainOperationsEndpoint domainOperations = getDomainOperationsEndpoint(hostPort, username, password);
 
         // Domain has one English label
         Label label = new Label(Locale.ENGLISH, "Sample Domain", "This is a domain created from sample code.");
 
         // Domain UUID is fixed for sample code
         UUID domainUUID = UUID.fromString("6fab93fd-2858-461a-a0b3-34e261dbf8fd");
 
         Domain domain = new Domain(domainUUID,new Label[] { label });
         
         // Save the new domain
         domainOperations.saveNewDomain(domain);
     }
 }

6.3.5 Creating a 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.

Example 6-21

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.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 {
 
         String hostPort = args[0];
         String username = args[1];
         String password = args[2];
         
         // 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, false);
         Feature seal = new Feature(SEAL_FEATURE_ID, Feature.Use.IMMEDIATE, false);
         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, username, password);
 
         // 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);
     }
 }

6.3.6 Creating a Context Template

The following code demonstrates how to create a context template. The sample code uses a fixed template UUID so that all sample code can work with a known template. A new template would typically be given a new random UUID value. The sample template has one role and is active. This template is used to create contexts in the create context code sample.

Example 6-22

import static oracle.irm.j2ee.jws.rights.context.ContextTemplateOperations.getContextTemplateOperationsEndpoint;
 
 import java.util.Locale;
 import java.util.UUID;
 
 import oracle.irm.engine.types.core.general.Label;
 import oracle.irm.engine.types.rights.context.ContextTemplate;
 import oracle.irm.engine.types.rights.context.DocumentRoleRef;
 import oracle.irm.engine.types.rights.context.DomainRef;
 import oracle.irm.j2ee.jws.rights.context.ContextTemplateOperationsEndpoint;
 
 public class SaveNewContextTemplateWS {
 
     public static void main(String[] args) throws Exception {
 
         String hostPort = args[0];
         String username = args[1];
         String password = args[2];
         
         // Context Template UUID is fixed for sample code
         UUID contextTemplateUUID = UUID.fromString("930876e6-a505-4a10-8d93-bc43d9a37c23");
 
         ContextTemplate template = new ContextTemplate();
         
         // The UUID value that identifies this role within the domain
         template.setUuid(contextTemplateUUID);
 
         // Context Template has one English label
         Label label = new Label(Locale.ENGLISH, "Sample Template", "This is a template created from sample code.");
 
         // The human readable labels
         template.setLabels( new Label[] { label } );
 
         // The template is active
         template.setStatus(ContextTemplate.Status.ACTIVE);
         
         // Domain UUID is fixed for sample code
         UUID domainUUID = UUID.fromString("6fab93fd-2858-461a-a0b3-34e261dbf8fd");
 
         DomainRef domain = new DomainRef(domainUUID);
 
         // Document Role UUID is fixed for sample code
         UUID documentRoleUUID = UUID.fromString("ee82c3f9-152b-440d-afd7-dbf36b0c8188");
 
         DocumentRoleRef documentRole = new DocumentRoleRef(documentRoleUUID, domain);
         
         // Template has one role
         template.setRoles( new DocumentRoleRef[] { documentRole });
         
         // Get the context template operations web service
         ContextTemplateOperationsEndpoint templateOperations = getContextTemplateOperationsEndpoint(hostPort, username, password);
 
         // Save the new template
         templateOperations.saveNewContextTemplate(domain, template);
     }
 }

6.3.7 Creating 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.

Example 6-23

import static oracle.irm.j2ee.jws.rights.context.ContextOperations.getContextOperationsEndpoint;
 
 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 {
 
         String hostPort = args[0];
         String username = args[1];
         String password = args[2];
         
         // 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, username, password);
 
         // 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
     }
 }

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

Example 6-24

import static oracle.irm.j2ee.jws.rights.context.DocumentRightOperations.getDocumentRightOperationsEndpoint;
 
 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 {
 
         String hostPort = args[0];
         String username = args[1];
         String password = args[2];
 
         // 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, username, password);
 
         // 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
     }
 }

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

Example 6-25

import static oracle.irm.j2ee.jws.rights.context.DocumentRightOperations.getDocumentRightOperationsEndpoint;
 
 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 {
 
         String hostPort = args[0];
         String username = args[1];
         String password = args[2];
 
         // Get the document right operations web service
         DocumentRightOperationsEndpoint rightOperations = getDocumentRightOperationsEndpoint(hostPort, username, password);
 
         // 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());
                 }
             }
         }
     }
 }

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

Example 6-26

import static oracle.irm.j2ee.jws.rights.context.DocumentRightOperations.getDocumentRightOperationsEndpoint;
 
 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 {
 
         String hostPort = args[0];
         String username = args[1];
         String password = args[2];
 
         // Get the document right operations web service
         DocumentRightOperationsEndpoint rightOperations = getDocumentRightOperationsEndpoint(hostPort, username, password);
 
         // 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 });
     }
 }

6.3.11 Sealing a File

The following code demonstrates how to seal a file. The content to seal can be provided as any type of InputStream; this example uses a file input stream. The sample writes the resulting stream out as a file with a sealed file name inferred from the unsealed file name. The file is sealed using the context classification system, specifying a context with a known UUID value and an item code.

Example 6-27

import static oracle.irm.engine.classifications.context.ContextConstants.CONTEXT_CLASSIFICATION_SYSTEM_UUID;
 import static oracle.irm.engine.content.type.ContentTypeOperationsInstance.getContentTypeFromPath;
 import static oracle.irm.engine.content.type.ContentTypeOperationsInstance.getSealedFileName;
 import static oracle.irm.engine.core.classification.ClassificationConstants.UNSPECIFIED_KEY_SET_UUID;
 import static oracle.irm.j2ee.jws.content.sealing.SealingServices.getSealingServicesEndpoint;
 
 import java.io.File;
 import java.io.FileInputStream;
 import java.io.FileOutputStream;
 import java.io.InputStream;
 import java.net.URI;
 import java.util.Date;
 import java.util.UUID;
 
 import oracle.irm.engine.content.type.ContentType;
 import oracle.irm.engine.types.classifications.context.ContextCookie;
 import oracle.irm.engine.types.classifications.context.ContextRef;
 import oracle.irm.engine.types.classifications.item.ItemCode;
 import oracle.irm.engine.types.content.key.KeySetRef;
 import oracle.irm.engine.types.content.sealing.SealingOptions;
 import oracle.irm.engine.types.core.classification.Classification;
 import oracle.irm.engine.types.core.classification.ClassificationSystemRef;
 import oracle.irm.j2ee.jws.content.sealing.SealingServicesEndpoint;
 
 public class SealFile {
 
     public static void main(String[] args) throws Exception {
 
         String hostPort = args[0];
         String username = args[1];
         String password = args[2];
         
         // The server URI. for example https://irm.example.com/irm_desktop
         URI serverURI = URI.create(args[3]);
 
         // The filename to seal
         String unsealedFilename = args[4];
 
         // Context UUID is fixed for sample code
         ContextRef context = new ContextRef(UUID.fromString("46f910d9-dd30-476e-b060-4d01f88f8b05"));
 
         // Provide an explicit item code value and time
         ItemCode itemCode = new ItemCode();
         itemCode.setValue(new File(unsealedFilename).getName());
         itemCode.setTime(new Date());
 
         // Create a context cookie for the classification - this specifies which context to use as
         // well as the item code for the content.
         ContextCookie cookie = new ContextCookie();
         cookie.setContext(context);
         cookie.setItemCode(itemCode);
         
         // Create the classification details used in the sealing options
         Classification classification = new Classification();
         
         // For the context classification system the classification Id is the context UUID value.
         classification.setId("46f910d9-dd30-476e-b060-4d01f88f8b05");
         
         // Context classification system
         classification.setSystem(new ClassificationSystemRef(CONTEXT_CLASSIFICATION_SYSTEM_UUID));
         
         // As the key set is not known get the sealing process to automatically fill this in
         classification.setKeySet(null);
         
         // URL sealed into content that tells the desktop where to go to get licenses
         classification.setUri(serverURI);
         
         // Classification time set explicitly to the current time
         classification.setClassificationTime(new Date());
         
         // As the labels are not known get the sealing process to automatically fill these in
         classification.setLabels(null);
         
         // Set the context and item code details
         classification.setCookie(cookie);
         
         // The classification is the only mandatory property for sealing options
         SealingOptions sealingOptions = new SealingOptions();
 
         sealingOptions.setClassification(classification);
 
         // Get the MIME type of the file to seal, this is inferred from the unsealed file name
         ContentType contentType = getContentTypeFromPath(unsealedFilename);
 
         String mimeType = contentType.getMimeTypes()[0];
         
         // Seal the file
         FileInputStream unsealedInputStream = new FileInputStream(unsealedFilename);
 
         // Get the sealing services web service
         SealingServicesEndpoint sealingServices = getSealingServicesEndpoint(hostPort, username, password);
 
         InputStream sealedInputStream = sealingServices.seal(unsealedInputStream, mimeType, sealingOptions);
 
         // Close the file stream
         unsealedInputStream.close();
 
         // Get the sealed equivalent of the unsealed filename
         String sealedFilename = getSealedFileName(unsealedFilename);
 
         // Write the sealed stream out to a file
         FileOutputStream sealedOutputStream = new FileOutputStream(sealedFilename);
 
         int start = 0;
         int read = 0;
 
         byte buffer[] = new byte[8194];
 
         while ((read = sealedInputStream.read(buffer, start, buffer.length)) != -1) {
             sealedOutputStream.write(buffer, 0, read);
         }
 
         sealedInputStream.close();
         sealedOutputStream.close();
     }
 }

6.3.12 Peeking a Sealed File

The following code demonstrates how to extract the metadata from sealed content using the peek method. This method sends the sealed content to the sealing server, the server extracts the metadata and returns this information to the caller. The sealed content can be provided as any type of InputStream; this example uses a file input stream. Once peeked the file metadata, which includes the Classification details, can be examined. The sample code prints out the human readable classification details (the labels) that were sealed into the content.

Example 6-28

import static oracle.irm.j2ee.jws.content.sealing.SealingServices.getSealingServicesEndpoint;
 
 import java.io.FileInputStream;
 
 import oracle.irm.engine.types.content.sealing.ContentDescription;
 import oracle.irm.engine.types.core.classification.Classification;
 import oracle.irm.engine.types.core.general.Label;
 import oracle.irm.j2ee.jws.content.sealing.SealingServicesEndpoint;
 
 public class PeekFile {
 
     public static void main(String[] args) throws Exception {
 
         String hostPort = args[0];
         String username = args[1];
         String password = args[2];
 
         // The name of the file to peek
         String unsealedFilename = args[3];
 
         // Get the sealing services web service
         SealingServicesEndpoint sealingServices = getSealingServicesEndpoint(hostPort, username, password);
 
         // Perform the peek, providing a stream to the sealed file
         FileInputStream stream = new FileInputStream(unsealedFilename);
         
         ContentDescription contentDescription = sealingServices.peek(stream);
 
         // Close the file stream
         stream.close();
 
         // Extract the classification details from the content
         Classification classification = contentDescription.getClassification();
 
         // Show all the labels sealed into content (assumes labels are available)
         for (Label label : classification.getLabels()) {
             System.out.println(label.getLocale().getDisplayName() + " : " + label.getName());
         }
     }
 }

6.3.13 Peeking a Sealed File and Checking the Digital Signature

The following code demonstrates how to extract the metadata from sealed content using the validatedPeek method. This method sends the sealed content to the sealing server, the server extracts the metadata and returns this information to the caller. The sealed content can be provided as any type of InputStream; this example uses a file input stream. Once peeked the file metadata, which includes the Classification details, can be examined. The sample code prints out the human readable classification details (the labels) that were sealed into the content.

Example 6-29

import static oracle.irm.j2ee.jws.content.sealing.SealingServices.getSealingServicesEndpoint;
 
 import java.io.FileInputStream;
 
 import oracle.irm.engine.types.content.sealing.ContentDescription;
 import oracle.irm.engine.types.core.classification.Classification;
 import oracle.irm.engine.types.core.general.Label;
 import oracle.irm.j2ee.jws.content.sealing.SealingServicesEndpoint;
 
 public class ValidatedPeekFile {
 
     public static void main(String[] args) throws Exception {
 
         String hostPort = args[0];
         String username = args[1];
         String password = args[2];
 
         // The name of the file to peek
         String unsealedFilename = args[3];
 
         // Get the sealing services web service
         SealingServicesEndpoint sealingServices = getSealingServicesEndpoint(hostPort, username, password);
 
         // Perform the peek, providing a stream to the sealed file
         FileInputStream stream = new FileInputStream(unsealedFilename);
         
         ContentDescription contentDescription = sealingServices.validatedPeek(stream);
 
         // Close the file stream
         stream.close();
 
         // Extract the classification details from the content
         Classification classification = contentDescription.getClassification();
 
         // Show all the labels sealed into content (assumes labels are available)
         for (Label label : classification.getLabels()) {
             System.out.println(label.getLocale().getDisplayName() + " : " + label.getName());
         }
     }
 }

6.3.14 Changing 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.

Example 6-30

import static oracle.irm.j2ee.jws.rights.context.DocumentRightOperations.getDocumentRightOperationsEndpoint;
 
 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 {
 
         String hostPort = args[0];
         String username = args[1];
         String password = args[2];
 
         // Get the document right operations web service
         DocumentRightOperationsEndpoint rightOperations = getDocumentRightOperationsEndpoint(hostPort, username, password);
 
         // 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);
     }
 }

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

Example 6-31

import static oracle.irm.j2ee.jws.rights.context.DocumentRightOperations.getDocumentRightOperationsEndpoint;
 
 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 {
 
         String hostPort = args[0];
         String username = args[1];
         String password = args[2];
 
         // Get the document right operations web service
         DocumentRightOperationsEndpoint rightOperations = getDocumentRightOperationsEndpoint(hostPort, username, password);
 
         // 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);
     }
 }

6.3.16 Reclassifying a File

The following code demonstrates how to reclassify a sealed file using the reclassify method. The content to reclassify can be provided as any type of InputStream; this example uses a file input stream. The sample changes the labels of the classification and then writes the resulting stream out as a file.

Example 6-32

import static oracle.irm.j2ee.jws.content.sealing.SealingServices.getSealingServicesEndpoint;
 
 import java.io.FileInputStream;
 import java.io.FileOutputStream;
 import java.io.InputStream;
 import java.util.Locale;
 
 import oracle.irm.engine.types.content.sealing.ContentDescription;
 import oracle.irm.engine.types.core.classification.Classification;
 import oracle.irm.engine.types.core.general.Label;
 import oracle.irm.j2ee.jws.content.sealing.SealingServicesEndpoint;
 
 public class ReclassifyFile {
 
        public static void main(String[] args) throws Exception {
            
         String hostPort = args[0];
         String username = args[1];
         String password = args[2];
         
         // Get the file to reclassify
         String filename = args[3];
         
         // Get the label to apply to the classification
         String labelName = args[4];
         
         // Get a sealing services end point
         SealingServicesEndpoint sealingServices = getSealingServicesEndpoint(hostPort,username,password); 
         
         // Peek the contents of the file to obtain the classification details of the provided file
         FileInputStream inputStream = new FileInputStream(filename);
         
         ContentDescription contentDescription = sealingServices.peek(inputStream);
         
         inputStream.close();
         
         // Extract the classification from the content description
         Classification classification = contentDescription.getClassification();
         
         // Replace the labels with one
         Label label = new Label(
             Locale.ENGLISH,
             labelName,
             null);
         
         classification.setLabels(new Label[] { label });
         
         // Reclassify the sealed file with the new classification
         inputStream = new FileInputStream(filename); 
         
         InputStream reclassifiedStream = sealingServices.reclassify(inputStream,classification);
         
         inputStream.close();
 
         // Write the stream out to a file
         FileOutputStream reclassifiedOutputStream = new FileOutputStream(filename);
         
         int start = 0;
         int read = 0;
                     
         byte buffer[] = new byte[8194];
         
         while ((read = reclassifiedStream.read(buffer, start, buffer.length)) != -1)
         {
             reclassifiedOutputStream.write(buffer, 0, read);
         }
         
         reclassifiedStream.close();
         reclassifiedOutputStream.close();
        }
 }

6.3.17 Resealing a File with Different Custom Data

The following code demonstrates how to reseal a sealed file using the reseal method. The content to reseal can be provided as any type of InputStream; this example uses a file input stream. The sample adds XML-based custom data to the sealed file.

Example 6-33

import static oracle.irm.j2ee.jws.content.sealing.SealingServices.getSealingServicesEndpoint;
 
 import java.io.FileInputStream;
 import java.io.FileOutputStream;
 import java.io.InputStream;
 import java.util.UUID;
 
 import javax.xml.parsers.DocumentBuilder;
 import javax.xml.parsers.DocumentBuilderFactory;
 
 import oracle.irm.engine.types.content.sealing.CustomData;
 import oracle.irm.j2ee.jws.content.sealing.SealingServicesEndpoint;
 
 import org.w3c.dom.Document;
 import org.w3c.dom.Element;
 
 public class ResealFile {
 
        public static void main(String[] args) throws Exception {
            
         String hostPort = args[0];
         String username = args[1];
         String password = args[2];
         
         // Get the file to reseal
         String filename = args[3];
         
         // Get a sealing services end point
         SealingServicesEndpoint sealingServices = getSealingServicesEndpoint(hostPort,username,password); 
         
         // Custom data is provided as XML
         DocumentBuilderFactory documentBuilderFactory = DocumentBuilderFactory.newInstance();
         DocumentBuilder documentBuilder = documentBuilderFactory.newDocumentBuilder();
         Document document = documentBuilder.newDocument();
 
         Element element = document.createElement("SampleCustomData");
         element.setTextContent("Some example custom data provided as an XML text element");
         
         CustomData data = new CustomData();
         
         // UUID identifies the custom data, in this case just use a random UUID value
         data.setUuid(UUID.randomUUID());
         
         // Custom data is XML document
         data.setData(element);
         
         // Reseal the sealed file with the new custom data
         InputStream inputStream = new FileInputStream(filename); 
         
         InputStream reclassifiedStream = sealingServices.reseal(inputStream, new CustomData[] {data});
         
         inputStream.close();
 
         // Write the stream out to a file
         FileOutputStream reclassifiedOutputStream = new FileOutputStream(filename);
         
         int start = 0;
         int read = 0;
                     
         byte buffer[] = new byte[8194];
         
         while ((read = reclassifiedStream.read(buffer, start, buffer.length)) != -1)
         {
             reclassifiedOutputStream.write(buffer, 0, read);
         }
         
         reclassifiedStream.close();
         reclassifiedOutputStream.close();
        }
 }

6.3.18 Unsealing a File

The following code demonstrates how to unseal a sealed file using the unseal method. The content to unseal can be provided as any type of InputStream; this example uses a file input stream. The sample writes the resulting unsealed stream out to a file.

Example 6-34

import static oracle.irm.j2ee.jws.content.sealing.SealingServices.getSealingServicesEndpoint;
 
 import java.io.FileInputStream;
 import java.io.FileOutputStream;
 import java.io.InputStream;
 
 import oracle.irm.j2ee.jws.content.sealing.SealingServicesEndpoint;
 
 public class UnsealFile {
 
     public static void main(String[] args) throws Exception {
 
         String hostPort = args[0];
         String username = args[1];
         String password = args[2];
 
         // The file to unseal
         String sealedFilename = args[3];
 
         // The unsealed file name
         String unsealedFilename = args[4];
 
         // Get the sealing services web service
         SealingServicesEndpoint sealingServices = getSealingServicesEndpoint(hostPort, username, password);
 
         // Unseal the sealed file
         FileInputStream sealedFileStream = new FileInputStream(sealedFilename);
 
         InputStream unsealedStream = sealingServices.unseal(sealedFileStream);
 
         // Close the file stream
         sealedFileStream.close();
 
         // Write the stream out to a file
         FileOutputStream unsealedStreamOutputStream = new FileOutputStream(unsealedFilename);
 
         int start = 0;
         int read = 0;
 
         byte buffer[] = new byte[8194];
 
         while ((read = unsealedStream.read(buffer, start, buffer.length)) != -1) {
             unsealedStreamOutputStream.write(buffer, 0, read);
         }
 
         // Close the streams
         unsealedStream.close();
         unsealedStreamOutputStream.close();
     }
 }

6.3.19 Listing Classifications

The following code demonstrates how to list classification details from a sealing server using the listClassifications method. The sample code displays the list of Classifications details available to the authenticated user.

Example 6-35

import static oracle.irm.j2ee.jws.core.storage.DesktopServices.getDesktopServicesEndpoint;
 
 import java.net.URI;
 
 import oracle.irm.engine.types.core.classification.Classification;
 import oracle.irm.engine.types.core.general.Label;
 import oracle.irm.j2ee.jws.core.storage.DesktopServicesEndpoint;
 
 public class ListClassificationsWS {
 
     public static void main(String[] args) throws Exception {
 
         String hostPort = args[0];
         String username = args[1];
         String password = args[2];
 
         // The server URI. for example https://irm.example.com/irm_desktop
         URI serverURI = URI.create(args[3]);
 
         // Get the desktop services web service
         DesktopServicesEndpoint desktopServices = getDesktopServicesEndpoint(hostPort, username, password);
 
         // Synchronize with the specified server
         Classification[] classifications = desktopServices.listClassifications(serverURI);
 
         // Display the labels of the classifications
         for (Classification classification : classifications) {
 
             for (Label label : classification.getLabels()) {
                 System.out.println(label.getLocale().getDisplayName() + " : " + label.getName());
             }
         }
     }
 }

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

Example 6-36

import static oracle.irm.j2ee.jws.rights.context.ContextOperations.getContextOperationsEndpoint;
 
 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. for example https://localhost
         String hostPort = args[0];
         String username = args[1];
         String password = args[2];
 
         // 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, username, password);
 
         // 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());
         }
     }
 }

6.3.21 Checking in Licenses

The following code demonstrates how to check in licenses currently checked out to a sealing server. When the sealing server processes content it will usually check out licenses for the authenticated user. These licenses can no longer be used from other locations (for example, the Oracle IRM Desktop) until they expire or are manually checked in.

Example 6-37

import static oracle.irm.j2ee.jws.core.storage.DesktopServices.getDesktopServicesEndpoint;
 
 import java.net.URI;
 
 import oracle.irm.j2ee.jws.core.storage.DesktopServicesEndpoint;
 
 public class CheckInWS {
 
     public static void main(String[] args) {
 
         String hostPort = args[0];
         String username = args[1];
         String password = args[2];
         
         // Get the desktop services web service
         DesktopServicesEndpoint desktopServices = getDesktopServicesEndpoint(hostPort, username, password);
 
         // The server URI. for example https://irm.example.com/irm_desktop
         URI serverURI = URI.create(args[3]);
 
         // Check in all the licenses currently within the
         // desktop store for the given server
         desktopServices.checkIn(serverURI);
     }

6.3.22 Deleting a Domain

The following code demonstrates how to delete a domain. The sample code uses a fixed domain UUID for the new domain so that all sample code can work with a known domain. A new domain would typically be given a new random UUID value. The authenticated user must be a domain administrator. When a domain is deleted all the associated roles, templates and contexts are also deleted.

Example 6-38

import static oracle.irm.j2ee.jws.rights.context.DomainOperations.getDomainOperationsEndpoint;
 
 import java.util.UUID;
 
 import oracle.irm.engine.types.rights.context.DomainRef;
 import oracle.irm.j2ee.jws.rights.context.DomainOperationsEndpoint;
 
 public class DeleteDomainWS {
 
     public static void main(String[] args) throws Exception {
 
         String hostPort = args[0];
         String username = args[1];
         String password = args[2];
         
         // Domain UUID is fixed for sample code
         UUID domainUUID = UUID.fromString("6fab93fd-2858-461a-a0b3-34e261dbf8fd");
         
         // Get the domain operations web service
         DomainOperationsEndpoint domainOperations = getDomainOperationsEndpoint(hostPort, username, password);
 
         DomainRef domain = new DomainRef(domainUUID);
         
         // Delete the domain using the domain reference
         domainOperations.deleteDomain(domain);
     }
 }