In this tutorial you use Oracle JDeveloper to compile a set of sample Java classes that illustrate the use of Oracle IRM web services.
Approximately 20-30 minutes.
Click here to download the OBE and OBE support files in a zip file format.
This tutorial covers the following topics:
Place the cursor over this icon to load and view all the screenshots for this tutorial.
(Caution: This action loads all screenshots simultaneously, so response time may be slow depending on your Internet connection.)
Note: Alternatively, you can place the cursor over an individual icon in the following steps to load and view only the screenshot associated with that step. You can hide an individual screenshot by clicking it.
Oracle Information Rights Management (IRM) is a Fusion Middleware security service that uses encryption to secure and track all copies of an organization's sensitive documents and emails - regardless of how many copies are made, or where those copies are stored and used - even when copies are sent outside the firewall.
In Oracle IRM terminology the process of encrypting documents and emails is known as "sealing". The Oracle IRM Server exposes a comprehensive set of IRM web services to enable the easy integration of "sealing" within the workflows of content management repositories, collaborative web applications, content filtering/monitoring systems, etc.
This tutorial provides an introduction to calling the IRM web services from Java, using Oracle's JDeveloper development environment.
You want to integrate Oracle IRM "sealing" services into your Java application, for example automatically sealing files as they are uploaded into a file share, content management repository or collaborative workspace. Another example would be the automatic sealing of files as an enforcement action of a content filtering, monitoring or data leakage solution.
Before starting this tutorial you should:
| 1. |
Have installed JDeveloper 10g (10.1.3.2.0 or 10.1.3.3.0). |
||||||||||||
| 2. |
Have started JDeveloper by double-clicking <jdev_home>\jdeveloper.exe. If you receive a message asking if you want to migrate
from a previous version,
|
||||||||||||
| 3. |
Have access to an Oracle IRM Server appropriately configured to support IRM web services. This tutorial assumes that you are using an Internet-accessible IRM Server hosted by the IRM Development team, details of which are given in the table below. NOTE: This development IRM Server is hosted exclusively for the evaluation of the IRM web services. It is not a production server, and should not be used for securing confidential information.
|
||||||||||||
| 4. |
This tutorial requires several files which are included in the associated ZIP archive Oracle IRM Web Services Samples - JDeveloper.zip. There are four sets of files, placed in different folders within the ZIP archive (so you may find it easier to first extract the ZIP to a temporary folder, so that it is easier to copy files to their ultimate destinations, without the ZIP utility automatically creating these sub-folders): - Oracle IRM Web Services Samples - JDeveloper.pdf
- in the doc folder within the ZIP archive. This is the document
you are currently reading. |
||||||||||||
The Oracle IRM web service samples are simple Java command-line applications. In this tutorial you will create a simple JDeveloper application and project into which you will include the sample files, and then use JDeveloper to 'connect' them to the IRM web services.
To create the JDeveloper application and project, perform the following steps:
| 1. |
In the Applications Navigator, right-click the Applications node and select New Application from the context menu.
|
| 2. |
In the Create Application dialog, enter the Application Name of IRM-ws-client. From the Application Template drop down list, select No Template [All Technologies]. Leave the Application Package Prefix blank. Click OK.
|
| 3. |
In the Create Project dialog, enter a Project Name of Samples and click OK. Note: it is important to accurately follow the names used in this tutorial, to ensure that the samples and generated code components reference each other correctly.
|
JDeveloper imports the WSDL description of the IRM web services and automatically generates a set of web proxy classes, which provide a standard Java interface which the sample code will call. The web proxy classes then hide all the functionality required to convert these local Java calls into remote web service invocations.
To import the IRM WSDL and generate the web proxy classes, perform the following steps:
| 1. | In the Applications Navigator, right-click the Samples
project and select New… from the context menu.
|
| 2. |
In the New Gallery, expand the Business Tier node in the Categories list, select the Web Services node, and then in the Items list select Web Service Proxy. Click OK.
|
| 3. |
If the Welcome page of the Create Web Service Proxy dialog displays, click Next. In the Web Service Description page of the wizard enter the URL of the Oracle IRM WSDL file. This is served over HTTP by the Oracle IRM Server, from a URL of the form http://<IRM Server host name>/sm/wsdl/oracleirm.wsdl. Click Next.
|
| 4. |
You should see a progress dialog of the form:
For an as yet unknown reason this fetch always seems to fail on its first attempt, with the following error message.
You can verify the WSDL URL by copying it into a web browser. Simply press Next again on the Web Service Description page of the wizard should successfully fetch the WSDL file and proceed to building the web proxy model, showing the progress dialog:
|
| 5. |
In the Port Endpoints page of the wizard you can just click Next.
|
| 6. |
In the Custom Mappings page of the wizard you can just click Next.
|
| 7. |
In the Defined Handlers page of the wizard you can just click Next.
|
| 8. |
In the Default Mapping Options page of the wizard you can accept all the defaults, but uncheck the Unwrapped Wrapped Parameters check box to ensure that the proxy classes pass parameters in a manner consistent with the Java application sample code (i.e. using separate parameters, rather than wrapped parameters).
|
| 9. |
In the Support Files page of the wizard you can just click Next.
|
| 10. |
In the Finish page of the wizard breathe a deserved sigh of relief and click Finish.
|
| 11. |
Generating the proxy classes can take a few minutes, during which you should see the progress dialog:
|
| 12. |
Once the proxy classes have been generated you are returned to the JDeveloper main window. If you expand the Samples node in the Applications Navigator and click on the OracleIRMServiceProxy node you will see the many Java classes that have been generated from the Oracle IRM WSDL. Some of these classes are themselves automatically generated sample code, illustrating how to call the generated proxy classes. One such example, ResourceServicesClient.java, should be open in the main edit window.
|
The Oracle IRM web service client samples are simple Java command-line applications that each illustrate one aspect of using the Oracle IRM web services.
To add the samples to your JDeveloper project and 'connect' them to the web service proxy classes generated in the last section, perform the following steps:
| 1. |
Extract the nine (9) sample Java files into the src folder within your JDeveloper application/project folder, e.g. <JDeveloper folder>\IRM-ws-client\Samples\src.
|
| 2. |
In the Applications Navigator expand the Samples project node, expand the Application Sources node and then click on the Refresh toolbar button.
|
| 3. |
You should see the added sample Java files appear in the Applications Navigator, under the Application Sources node.
|
| 4. |
If you double click on the source file SealingFileExample.java you can look through its code to see how easy it is to instantiate and use the web proxy classes.
|
| 5. |
In the Applications Navigator, right-click the Samples project node and select Rebuild from the context menu.
|
| 6. |
Check the Messages - Log window and JDeveloper status bar. You should see successful compilation messages and a message: Successful compilation: 0 errors, 0 warnings.
|
Minor defects in the proxy generator included in JDeveloper 10g result in web service proxy classes that compile but fail to correctly serialise certain IRM objects across the web, resulting in both the IRM Server and the IRM samples throwing exceptions. To correct this it is necessary to patch some of the JDeveloper-generated proxy files.
To patch the JDeveloper-generated proxy files, perform the following steps:
| 1. |
On your file system, locate the file ComponentObject_InterfaceSOAPSerializer.java.
It will be in the project folder <JDeveloper folder>\IRM-ws-client\Samples\src\
|
| 2. |
Replace this file with the patched version included in the patch folder of the IRM web services sample ZIP archive. (If you keep the original you can compare it with the patched version to see the nature of the patches.) |
| 3. |
In the Applications Navigator, right-click the Samples project node and select Rebuild from the context menu (see screen shot in previous section).
|
| 4. |
Check the Messages - Log window and JDeveloper status bar. You should see successful compilation messages and a message: Successful compilation: 0 errors, 0 warnings.
|
There are many ways of running and debugging Java applications within JDeveloper, one of which is described in this tutorial. This section will guide you through the steps to run the IRM web service client sample application ListContextsExample.java. You can then follow a similar process to run the other samples.
To run the ListContextsExample.java sample, perform the following steps:
| 1. |
In the Applications Navigator, double click the ListContextsExample.java node.
|
| 2. |
The sample code for listing IRM contexts and some of their properties should open in the main JDeveloper edit window. Each of the samples requires two or more command line arguments, which you will pass to the sample via a JDeveloper run configuration. To create a run configuration for the ListContextsExample.java sample click on the green play triangle pull down over the edit window and select Manage Run Configurations…
|
| 3. |
Leave the Use Project Settings box checked and click on the New… button to create a new Run Configuration.
|
| 4. |
For the ListContextExample.java sample create a new Run Configuration called ListContexts and click OK.
|
| 5. |
Select the newly created Run Configuration ListContexts and click on the Edit… button.
|
| 6. |
Use the Browse… button to locate the sample file ListContextsExample.java on the file system. It should be in the project folder <JDeveloper folder>\IRM-ws-client\Samples\src. Uncheck the Attempt to Run Active File Before Default check box. Add the following command line (program) arguments: - "Sample Admin" - this is the username of an administrator
account on the IRM Server. Note that arguments containing spaces must
be entered within quotes. Click OK.
|
| 7. |
Click OK to close the Project Properties dialog and return to the main JDeveloper window.
|
| 8. |
Now, to run the ListContextsExample.java sample you just need to select the ListContexts run configuration from the green play triangle pull down over the edit window.
|
| 9. |
If all goes well the ListContextsExample.java sample should execute and direct console output (such as shown below) to a JDeveloper Log window. At the end of the running log there should be a message Process exited with exit code 0.
|
| 10. |
The ListContextsExample.java uses IRM web services to recover the set of IRM contexts (classifications) for which the authenticated user has view access; the IRM roles defined in the contexts; the offline periods associated with the contexts; and the users or groups assigned roles in the contexts.
|
To run the remaining samples simply follow the instructions from the previous section, creating a Run Configuration for each sample. The following tables briefly describe each sample and their required command line arguments.
Only required if you want to run this tutorial against
your own IRM Server:
The tables also includes the IRM Server configuration
required for each sample, including the required end user and administrative
rights, as documented in the IRM web services documentation and help.
It is suggested that you experiment with the samples in the order below.
| ListContextsExample.java |
| Arguments (sample) |
"Sample Admin" my!wordpass |
| Arguments | <service username> <password> |
| Description |
The service request authenticates using the supplied service username and password, then lists the set of IRM contexts for which the service user has the administrative rights to view. |
| IRM Server Configuration |
Two
IRM contexts "Acquisition Alpha" and "Project X" |
| ListSealableContextsExample.java |
| Arguments (sample) |
"Sample Admin" my!wordpass "Sample User" |
| Arguments | <service username> <password> <target username> |
| Description |
The service request authenticates using the supplied service username and password, then lists the set of IRM contexts to which the target user has the rights to "seal" content. |
| IRM Server Configuration |
Two
IRM contexts "Acquisition Alpha" and "Project X"Sample
Admin: ContextSealingServices.ListSealableContexts server-level admin
right |
| SealingBytesExample.java |
| Arguments (sample) |
"Sample Admin" my!wordpass "Acquisition Alpha" "c:\temp\sample.doc" "c:\temp\sample.sdoc" |
| Arguments | <service username> <password> <context> <input path> <output path> |
| Description |
The service request authenticates using the supplied service username and password, then seals the input file - creating an output sealed file (with a sealed file extension). A sample file sample.doc is provided in the sample ZIP archive which accompanies this tutorial. Copy this to your c:\temp folder. You can open the sealed file by double-clicking on it (assuming you have installed the Oracle IRM Desktop) and entering your "Sample User" credentials (user: "Sample User" pwd: "my!wordpass"). NOTE: the IRM service used in this sample actually sends the unsealed file to the IRM Server over the network, and reads the sealed file back over the network - so the IRM Server can be located anywhere. Other IRM services pass filenames over the network, in which case the IRM Server would need to have access to the referenced file share. |
| IRM Server Configuration |
IRM
context "Acquisition Alpha" |
| ResealingBytesExample.java |
| Arguments (sample) |
"Sample Admin" my!wordpass "Sample User" "Project X" c:\temp\sample.sdoc c:\temp\sample2.sdoc |
| Arguments | <service username> <password> <seal as user> <context> <input path> <output path> |
| Description |
The service request authenticates using the supplied service username and password, then reseals the input file (assuming it is already sealed) to another context, performing the operation on behalf on a named user. This is a common workflow as documents become more or less sensitive during their lifecycle. You can reseal the file you sealed in the SealingBytes example above. NOTE: The IRM service used in this sample actually sends the unsealed file to the IRM Server over the network, and reads the sealed file back over the network - so the IRM Server can be located anywhere. Other IRM services pass filenames over the network, in which case the IRM Server would need to have access to the referenced file share. |
| IRM Server Configuration |
Two
IRM contexts "Acquisition Alpha" and "Project X" |
| SealingFileExample.java |
| Arguments (sample) |
"Sample User" my!wordpass "Acquisition Alpha" "c:\temp\sample.doc" "c:\temp\sample.sdoc" |
| Arguments | <service username> <password> <context> <input path> <output path> |
| Description |
The service request authenticates using the supplied service username and password, then seals the input file - creating an output sealed counterpart. NOTE: This service refers to files by their full pathname, which the IRM Server hosting the web service must be able to resolve. The file contents are not passed over the web service. This sample cannot therefore be run against the development IRM Server used in the other samples. |
| IRM Server Configuration |
IRM
context "Acquisition Alpha" |
| PeekingExample.java |
| Arguments (sample) |
"Sample Admin" my!wordpass "c:\temp\sample.sdoc" |
| Arguments | <service username> <password> <input path> |
| Description |
The service request authenticates using the supplied service username and password, then extracts IRM metadata from the sealed input file (an operation known as 'peeking'). NOTE: The IRM service used in this sample actually sends the unsealed file to the IRM Server over the network, and reads the sealed file back over the network - so the IRM Server can be located anywhere. Other IRM services pass filenames over the network, in which case the IRM Server would need to have access to the referenced file share. |
| IRM Server Configuration |
Sample Admin: UnSealingServices.ExtractAttributesFromBytes server-level admin right |
| SaveNewUserExample.java |
| Arguments (sample) |
"Sample Admin" my!wordpass "test user 42" |
| Arguments | <service username> <password> <new username> |
| Description |
The service request authenticates using the supplied service username and password, then creates a new (disabled) user account. NOTE: On the shared IRM development server please adhere to the "test user nnn" naming convention. |
| IRM Server Configuration |
Sample Admin: AccountAPI.SaveNewUserWithAuthentication server-level admin right |
| EditUserExample.java |
| Arguments (sample) |
"Sample Admin" my!wordpass "test user 42" |
| Arguments | <service username> <password> <new user> |
| Description |
The service request authenticates using the supplied service username and password, then updates some of the attributes of a named user account. NOTE: You cannot run this sample against the shared IRM development server, because "Sample Admin" does not have this admin right. Running the sample will generate a "You do not have rights for this operation" exception. |
| IRM Server Configuration |
Sample Admin: AccountAPI.SaveChangesToUser server-level admin right |
| DeleteUserExample.java |
| Arguments (sample) |
"Sample Admin" my!wordpass "test user 42" |
| Arguments | <service username> <password> <user to delete> |
| Description |
The service request authenticates using the supplied service username and password, then deletes the named user account. NOTE: You cannot run this sample against the shared IRM development server, because "Sample Admin" does not have this admin right. Running the sample will generate a "You do not have rights for this operation" exception. |
| IRM Server Configuration |
Sample Admin: AccountAPI.DeleteAccount server-level admin right |
In this tutorial, you learned how to:
|
Took a set of simple Java classes illustrating the use of the Oracle IRM web services and imported them into JDeveloper. | |
|
Generated a set of Java web proxy classes from the WSDL contract published by the Oracle IRM Server. | |
|
'Connected' your imported Java samples to the generated proxy classes and were then able to invoke the remote IRM web services without needing to understand anything web services, SOAP, etc. | |
|
Gained some familiarity with the structure of the IRM web services and how to use them to "seal" files and perform administrative IRM operations, such as adding new users. | |
To learn more about Oracle Information Rights Management (IRM), Oracle JDeveloper and web services in general, refer to:
- Oracle
Information Rights Management on OTN
- Oracle
JDeveloper on OTN
- Service-Oriented
Architecture Technology Center on OTN
Place the cursor over this icon to hide all screenshots.