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 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.
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,
click No.
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 JDeveloper 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 - 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.
- ComponentObject_InterfaceSOAPSerializer.java - in the patch
folder within the ZIP archive. This file is required for patching the
JDeveloper-generated proxy classes (see later).
- 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.
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.
Adding the Sample IRM Web Service 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 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:
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\
samples\proxy\types\com\sealedmedia\ls\common\schema\runtime.
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:
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.
- my!wordpass - this is the associated password of the "Sample
Admin" user. This argument is case-sensitive.
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"
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
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.
Bookmark
