Using Oracle IRM Web Services with Eclipse WTP 1.5.4

Purpose

In this tutorial you use the Eclipse Web Tools Platform (WTP) to compile a set of sample Java classes that illustrate the use of Oracle IRM web services.

Time to Complete

Approximately 20-30 minutes.

Click here to download the OBE and OBE support files in a zip file format.

Topics

This tutorial covers the following topics:

 Overview
 Scenario
 Prerequisites
 Configuring Eclipse WTP
 Creating a New Eclipse Project
 Creating the Web Service Proxy Classes
 Adding the Sample IRM Client Applications
 Running the First Sample
 Running the Remaining Samples
 Summary
 Related Information

Viewing Screenshots

 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.

Overview

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 the Eclipse Web Tools Platform (WTP) development environment.

Back to Topic List

Scenario

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.

Back to Topic List

Prerequisites

Before you perform this tutorial, you should:

1.

Have installed the Eclipse Web Tools Platform (WTP 1.5.4):

For more information on Eclipse WTP see:

- http://www.eclipse.org/webtools/main.php for details on Eclipse setup and WTP prerequisites.
- http://www.eclipse.org/webtools/community/communityresources.php for Eclipse WTP web services tutorials.

 

2.

Have started Eclipse by double-clicking <Eclipse install folder>\eclipse.exe.

 

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.

Oracle IRM Development Server
Test URL

http://dev-irm01.sealedmedia.com/ping

Type this URL into your web browser to verify that you have network access to the development IRM Server and that it is operational. You should see a brief return page of the form:
[Oracle Development IRM Server,ukdevirm01.sm2.local,5.4 release 3 build 0,09 Aug 2007 08:55:13 UTC]

WSDL URL

http://dev-irm01.sealedmedia.com/sm/wsdl/oracleirm.wsdl

This URL is required later to show Eclipse where to find the WSDL contract describing the IRM web services, but it can also be typed into your web browser as a test.

Admin User Account

A sample admin user has been configured on the development IRM Server, with sufficient administrative permissions to run the samples. To use the IRM web services you must first authenticate, using this user's username and credentials.

User: "Sample Admin" Password: "my!wordpass"
(Without the quotes, password is case-sensitive)

End User Account

A sample end user has been configured on the development IRM Server, with sufficient end user permissions to open the documents sealed in this tutorial, and to reseal documents between the IRM contexts used in this tutorial. You use these credentials to authenticate to the Oracle IRM Desktop.

User: "Sample User" Password: "my!wordpass"
(Without the quotes, password is case-sensitive)

Contact

If you encounter problems using the Oracle IRM Development Server please contact Oracle IRM product management.

If you want to run this tutorial against your own IRM Server instance the required administrative and end user permissions are listed in the per-sample tables at the end of this tutorial.

 

4.

This tutorial requires several files which are included in the associated ZIP archive Oracle IRM Web Services Samples - Eclipse.zip. There are three (3) 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 - Eclipse.pdf - in the doc folder within the ZIP archive. This is the document you are currently reading.
- A set of Java classes (e.g. DeleteUserExample.java) in the root folder of the ZIP archive. These are the sample files showing how to call the IRM web services from Java.
- Sample.doc - in the doc folder within the ZIP archive. A sample Word document that you can seal during this tutorial, which also illustrates IRM dynamic watermarking.

Back to Topic List

Configuring Eclipse WTP

You need to make a couple of changes to the Eclipse WTP 1.5.4 development environment for it to work with the Oracle IRM web services. These changes involve upgrading the Axis SOAP libraries from 1.3 to 1.4 and changing an Axis configuration setting.

To configure Eclipse for compatibility with the Oracle IRM web services, perform the following steps:

1.

A defect in the Axis 1.3 SOAP libraries means that they cannot handle the xsd:anyType parameters used by the Oracle IRM web services, so you need to upgrade the libraries to Axis 1.4.

You can obtain the Axis 1.4 libraries from http://ws.apache.org/axis/. Extract the contents of the Axis 1.4 library archive (e.g. axis-bin-1_4.zip on Windows) into the plugins folder of your Eclipse installation - <Eclipse install folder>\plugins. Your archive utility should place all the files in an axis-1_4 sub-folder.

 

2.

Right click the IRM-ws-client project in the Package Explorer and click Properties. In the project Properties dialog select Java Build Path in the tree view and the Libraries tab in the right hand pane. Select the six (6) Axis libraries and click Remove.

NOTE: Be careful not to remove the JRE System Library.

 

3.

Staying in the Java Build Path properties in the project Properties dialog click the Add External JARs… button.

 

4.

In the JAR Selection file selection box select the six (6) Axis 1.4 libraries that you added to your Eclipse installation (in <Eclipse install folder>\plugins\axis-1_4\lib). The Jars you require are axis.jar, commons-discovery-0.2.jar, commons-logging-1.0.4.jar, jaxrpc.jar, saaj.jar and wsdl4j-1.5.1.jar.

Click Open and then OK to close the project Properties dialog.

 

5.

Select the Preferences… item from the Window menu, select the Web Services node and then the Axis Emitter node in the tree view, and ensure that the Generate code for all elements, even unreferenced ones box is checked.

Click OK.

 

Back to Topic List

Creating a New Eclipse Project

The Oracle IRM web service samples are simple Java command-line applications. In this tutorial you will create a simple Eclipse project into which you will include the sample files, and then use Eclipse to 'connect' them to the IRM web services.

To create the Eclipse project, perform the following steps:

1. Pull down the new component menu from the menu button above the Package Explorer and select the Project… item.

 

2.

In the New Project dialog, select the Java Project node and click Next.

 

3.

In the New Java Project dialog, enter a Project Name of IRM-ws-client and click Finish.

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.

 

Back to Topic List

Creating the Web Service Proxy Classes

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

Select the Launch the Web Services Explorer item from the Run menu of the main Eclipse window.

Click on the WSDL Page button at the top right of the Web Services Explorer pane (even though the button seems disable it activates on mouse over).

 

2.

Click the WSDL Main node in the Web Services Explorer and 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 Go.

 

3.

The Web Services Explorer pane should shortly show a list of bindings for the Oracle IRM web services.

 

4.

In the Navigator pane of the Web Services Explorer click on the WSDL node and then click on the Launch Web Service Wizard toolbar button in the Actions pane.

 

5.

In the Launch Web Service Wizard accept the default selection Web Service Client and click Go.

 

6.

In the Web Service Client dialog click on the Client project: WebServiceProject link.

 

7.

In the Specify Client Project Settings dialog select IRM-ws-client from the Client project choice box and click OK.

 

8.

When you are returned to the Web Service Client click Finish.

 

9.

Eclipse now parses the WSDL and generates the web service proxy classes, which you can inspect in the Package Explorer.

 

Back to Topic List

Adding the Sample IRM Client Applications

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 Eclipse 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 your Eclipse project folder,
e.g. <Eclipse folder>\IRM-ws-client.

 

2.

In the Package Explorer right click on the IRM-ws-client node and select Refresh (F5). The added sample Java files should appear in the Package Explorer under a (default package) node.

 

3.

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.

 

4.

Assuming that Eclipse is configured to build automatically (in the main Project menu) you should see successful compilation messages. The generated proxy code generates many warnings about unreferenced local variables, which you can ignore.

 

Back to Topic List

Running the First Sample

There are many ways of running and debugging Java applications within Eclipse, 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 Package Explorer, with the ListContextsExample.java node selected, click on the Run… menu item from the Run As pulldown menu.

 

2.

In the Run dialog box select the Arguments tab.

 

3.

On the Arguments tab of the Run dialog 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.

- my!wordpass - this is the associated password of the "Sample Admin" user. This argument is case-sensitive.

Click Run.

 

4.

If all goes well the ListContextsExample.java sample should execute and direct console output (such as shown below) to an Eclipse console window.

 

5.

To run the ListContextsExample.java sample again you just need to select the ListContextsExample item from the Run As pulldown menu.

 

6.

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.

 

Back to Topic List

Running the Remaining Samples

To run the remaining samples simply follow the instructions from the previous section, creating appropriately named run configurations 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"
Sample Admin: ContextAPI.GetContext server-level admin right; RoleAPI.ListRightsByOwner admin right in contexts "Acquisition Alpha" and "Project X"
Sample User: Contributor roles in "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
Sample User: Contributor roles in "Acquisition Alpha" and "Project X"


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"
Sample Admin: SealingServices.GetSealableTypeFromExtension server-level admin right and SealingServices.SealContent admin right in "Acquisition Alpha" context
Sample User: Contributor role in "Acquisition Alpha" (to open and edit the sealed file)


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"
Sample Admin: SealingServices.GetSealableTypeFromExtension server-level admin right and SealingServices.SealContent admin right in the target "Project X" context.
Sample User: Contributor role in "Acquisition Alpha", with copy constraints enabling resealing to "Project X", and Contributor role in "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"
Sample Admin: SealingServices.SealFileToFile admin right in "Acquisition Alpha" context.


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


Back to Topic List

Summary

In this tutorial, you learned how to:

 Take a set of simple Java classes illustrating the use of the Oracle IRM web services and imported them into Eclipse.
 Generated a set of Java web proxy classes from the WSDL contract published by the Oracle IRM Server.
 'Connected' the 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.

Back to Topic List

Related Information

To learn more about Oracle Information Rights Management (IRM) and web services in general, refer to:

- Oracle Information Rights Management on OTN
- Service-Oriented Architecture Technology Center on OTN

Back to Topic List

 Place the cursor over this icon to hide all screenshots.