Using Oracle IRM web services with Eclipse WTP 1.5.4
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.
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.
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.
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.
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]
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.
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.
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.
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.
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.
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.
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"
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)
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".
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
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.
Bookmark
