9 Using Remote Intradoc Client (RIDC)

9.1 Introduction to RIDC

The RIDC communication API removes data abstractions to Oracle Content Server while still providing a wrapper to handle connection pooling, security, and protocol specifics. If you want to use a native Java API, then RIDC is recommended.

RIDC has these key features:

• Support is provided for Intradoc socket-based communication and the HTTP and JAX-WS protocols.

• Client configuration parameters include setting the socket time outs, connection pool size, and so forth.

• All calls to RIDC require some user identity for authentication. For Intradoc URLs, no credentials are required because the request is trusted between Oracle Content Server and the client. For HTTP URLs, the context requires credentials.

• To invoke a service, you can use the ServiceRequest object, which can be obtained from the client.

• The RIDC client pools connections, which requires that the caller of the code close resources when done with a response.

• Streams are sent to Oracle Content Server through the TransferStream interface.

• The RIDC objects follow the standard Java Collection paradigms, which makes them extremely easy to consume from a JSP/JSPX page.

• Binders can be reused among multiple requests.

• RIDC allows Secure Socket Layer (SSL) communication with Oracle Content Server.

http://hc.apache.org/httpclient-3.x

// build a secure IDC client as cast to specific type
IntradocClient idcClient = (IntradocClient
   manager.createClient("idcs://localhost:54444");

// set the SSL socket options
config.setKeystoreFile("ketstore/client_keystore");  //location of keystore file
config.setKeystorePassword ("password");      // keystore password
config.setKeystoreAlias("SecureClient");  //keystore alias
config.setKeystoreAliasPassword("password");  //password for keystore alias

import oracle.stellent.ridc.convenience.adf.mbeans.IdcMBeanManager;
...
//connection name is the connection in the ADFContext you want to manage
IdcMBeanManager mbeanManager = IdcMBeanManager.getInstance(connectionName);
mbeanManager.register();

9.2 Initializing RIDC

To initialize RIDC, you will need the ECM Client libraries, which are shipped with the RIDC distribution, in your class path.

For the JAX-WS protocol, you also need to configure Oracle WebLogic Server security for the Oracle UCM web services. The security configuration includes these tasks:

• Setting up the policy for the login service

• Creating a new keystore file (or adding credentials to your existing keystore), which will be used by both the server and the client

• Setting up an Oracle wallet by adding the credentials

The client requires the following items:

• The JPS configuration file

• The keystore

• The Oracle wallet from the server

For information about configuring the server and client for web services, see the Oracle Fusion Middleware Services Reference Guide for Oracle Universal Content Management.

The following table shows the URL formats that are supported.

This example code initializes RIDC for an Intradoc connection:

// create the manager
IdcClientManager manager = new IdcClientManager();

// build a client that will communicate using the intradoc protocol
IdcClient idcClient = manager.createClient("idc://localhost:4444");

This example code initializes an HTTP connection (the only difference from an Intradoc connection is the URL):

// create the manager
IdcClientManager manager = new IdcClientManager();

// build a client that will communicate using the HTTP protocol
IdcClient idcClient = manager.createClient("http://localhost/idc/idcplg");

This example code initializes a JAX-WS client. These two web services are exposed by Oracle Content Server: the login service and the request service. You will need the web context root that these web services use. By default, this is idcnativews.

// create the manager
IdcClientManager manager = new IdcClientManager();

// build a client that will communicate using the JAXWS protocol
IdcClient idcClient = manager.createClient("http://wlsserver:7044/idcnativews");

9.3 Configuring Clients

Configuration of the clients can be done after they are created. Configuration parameters include setting the socket time outs, connection pool size, and so on. The configuration is specific to the protocol; if you cast the IdcClient object to the specific type, then you can retrieve the protocol configuration object for that type.

This example code sets the socket time out and wait time for Intradoc connections:

// build a client as cast to specific type
IntradocClient idcClient = (IntradocClient)manager.createClient
   ("http://host/cs/idcplg");

// get the config object and set properties
idcClient.getConfig ().setSocketTimeout (30000); // 30 seconds
idcClient.getConfig ().setConnectionSize (20);   // 20 connections

These JAX-WS specific configurations can be set after you have created the client:

// build a client as a cast for jaxws type
JaxWSClient jaxwsClient = (JaxWSClient) manager.createClient(
   ("http://wlsserver:7044/idcnativews");
JaxWSClientConfig jaxwsConfig = jaxwsClient.getConfig();

You can set the name of the Oracle Content Server instance that you want to connect to. By default, this is /cs/, which is the default web context for an Oracle UCM installation. If the server web context is different than the default, then you can set the the web context by editing a property. This example code sets your web context root:

// set the property
jaxwsConfig.setServerInstanceName("/mywebcontext/");

A JPS configuration file is required for most policies, such SAML or Message Token. This example code sets the location of the JPS configuration file:

jaxwsConfig.setJpsConfigFile("/my/path/to/the/jps-config.xml");

This example code sets the security policy:

jaxwsConfig.setClientSecurityPolicy
   ("policy:oracle/wss11_username_token_with_message_protection_client_policy");

RIDC uses the default values for the installed web services. If, for some reason, the web services have been modified and do not conform to the default URIs or URLs, you may need to modify the default values. This example code changes the login and request service URLs:

// login port wsdl url
jaxwsConfig.setLoginServiceWSDLUrl(new URL
   ("http://server:7044/webservices/loginPort?WSDL"));

//request port wsdl url
jaxwsConfig.setRequestServiceWSDLUrl(new URL
   ("http://server:7044/anotherservice/myrequestport?WSDL"));

The default streaming chunk size is set to 8192. This example code changes the streaming chunk size:

jaxwsConfig.setStreamingChunkSize(8190);

9.4 Authenticating Users

All calls to RIDC require some user identity. Optionally, this identity can be accompanied by credentials as required by the protocol. The user identity is represented by the IdcContext object; once created, it can be reused for all subsequent calls. To create an identity, you pass in the user name and, optionally, some credentials:

//create a simple identity with no password (for idc:// urls)
IdcContext userContext = new IdcContext("sysadmin");

// create an identity with a password
IdcContext userPasswordContext = new IdcContext("sysadmin", "idc");

For Intradoc URLs, you do not need any credentials because the request is trusted between Oracle Content Server and the client.

For HTTP and JAX-WS URLs, the context needs credentials.

For HTTP URLs, the credentials can be a simple password or anything that the HttpClient package supports.

For JAX-WS URLs, the requirement for credentials will be dependent on the service policy that the web service is configured to use by the server.

9.5 Using Services

To invoke a service, use the ServiceRequest object, which you can obtain from the client. Creating a new request will also create a new binder and set the service name in the binder, along with any other default parameters. From that point, you can populate the binder as needed for the request.

This example code executes a service request and gets back a DataBinder object with the results:

// get the binder
DataBinder binder = idcClient.createBinder();

// populate the binder with the parameters
binder.putLocal ("IdcService", "GET_SEARCH_RESULTS");
binder.putLocal ("QueryText", "");
binder.putLocal ("ResultCount", "20");

// execute the request
ServiceResponse response = idcClient.sendRequest (userContext, binder);

// get the binder
DataBinder serverBinder = response.getResponseAsBinder ();

The ServiceResponse object contains the response from Oracle Content Server. From the response, you can access the stream from Oracle Content Server directly, or you can parse it into a DataBinder object and query the results.

This example code takes a ServiceResponse and gets the search results, printing out the title and author values:

// get the binder
DataBinder binder = response.getResponseAsBinder ();
DataResultSet resultSet = binder.getResultSet ("SearchResults");

// loop over the results
for (DataObject dataObject : resultSet.getRows ()) {
    System.out.println ("Title is: " + dataObject.get ("dDocTitle"));
    System.out.println ("Author is: " + dataObject.get ("dDocAuthor"));
}

9.6 Handling Connections

The RIDC client pools connections, meaning that the caller of the code must close resources when it is done with a response. This is done by calling getResponseAsBinder, which closes resources automatically, or by calling close on the stream returned from a call to getResponseStream. If you do not want to examine the results, close must still be called, either by getting the stream and closing it directly or by calling close on the ServiceResponse object.

// execute the request
ServiceResponse response = idcClient.sendRequest (userContext, binder);

// get a binder closes the response automatically
response.getResponseAsBinder ();

// execute the request
ServiceResponse response = idcClient.sendRequest (userContext, binder);

// get the result stream and read it
InputStream stream = response.getResponseStream ();
int read = 0;
while ((read = stream.read ()) != -1)
{
}

//close the stream
stream.close ();

// execute the request
ServiceResponse response = idcClient.sendRequest (userContext, binder);

// close the response (which closes the stream directly)
response.close ();

9.7 Sending and Receiving Streams

Streams are sent to Oracle Content Server through the TransferStream interface. This interface wraps the actual stream with metadata about the stream (length, name, and so on).

This example code performs a check-in to Oracle Content Server:

// create request
DataBinder binder = idcClient.createBinder();
binder.putLocal ("IdcService", "CHECKIN_UNIVERSAL");

// get the binder
binder.putLocal ("dDocTitle", "Test File");
binder.putLocal ("dDocName", "test-checkin-6");
binder.putLocal ("dDocType", "ADACCT");
binder.putLocal ("dSecurityGroup", "Public");

// add a file
binder.addFile ("primaryFile", new TransferFile ("test.doc"));

// check in the file
idcClient.sendRequest (userContext, binder);

You can receive a stream from Oracle Content Server through the ServiceResponse object; the response is not converted into a DataBinder object unless you specifically request it. If you just want the raw HDA data, you can get that directly, along with converting the response to a String or DataBinder object:

// create request
DataBinder binder = idcClient.createBinder ();

// execute the service
ServiceResponse response = idcClient.sendRequest (userContext, binder);

// get the response stream
InputStream stream = response.getResponseStream ();

// get the response as a string
String responseString = response.getResponseAsString ();

// parse into data binder
DataBinder dataBinder = response.getResponseAsBinder ();

9.8 Using RIDC Objects in JSP and JSPX Pages

The RIDC objects all follow the standard Java Collection paradigms, which makes them extremely easy to consume from a JSP or JSPX page. Assume the ServerResponse object (used in the previous example) was available in the HttpServletRequest object in an attribute called idcResponse. This example JSPX code will iterate over the response and create a small table of data:

<table>
  <tr>
    <th>Title</th>
    <th>Author</th>
    <th>Release Date</th>
  </tr>
<c:forEach var="row" items="${idcResponse.dataBinder.SearchResults.rows}">
  <tr>
    <td>${row.dDocTitle}</td>
    <td>${row.dDocAuthor}</td>
    <td>${row.dInDate}</td>
   </tr>
</c:forEach>
</table>

9.9 Reusing Binders for Multiple Requests

The binders can be reused among multiple requests. A binder from one request can be sent in to another request. For example, this example code pages the search results by reusing the same binder for multiple calls to Oracle Content Server:

// create the user context
IdcContext idcContext = new IdcContext ("sysadmin", "idc");

// build the search request binder
DataBinder binder = idcClient.createBinder();
binder.putLocal("IdcService", "GET_SEARCH_RESULTS");
binder.putLocal("QueryText", "");
binder.putLocal("ResultCount", "20");

// send the initial request
ServiceResponse response = idcClient.sendRequest (binder, idcContext);
DataBinder responseBinder = response.getResponseAsBinder();

// get the next page
binder.putLocal("StartRow", "21");
response = idcConnection.executeRequest(idcContext, binder);
responseBinder = response.getResponseAsBinder();

// get the next page
binder.putLocal("StartRow", "41");
response = idcConnection.executeRequest(binder, idcContext);
responseBinder = response.getResponseAsBinder();

9.10 Providing User Security

Oracle UCM has several security models that are controlled by settings in Oracle Content Server. To resolve if a particular user has access to a document, three things are needed: the user's permission controls, the document's permission controls, and the Oracle Content Server security environment settings.

It is assumed that the application program calling the UserSecurity module will fetch documents and the DOC_INFO metadata (in the document's binder, typically the result of a search) as some superuser and cache this information. When the application needs to know if a particular user has access to the document, a call is made to Oracle Content Server as that user to fetch that user's permissions. Once the user's permission controls are known, then they can be matched to the information in the document's metadata to resolve the access level for that user. The available access levels follow:

• READ

• READ/WRITE

• READ/WRITE/DELETE

• READ/WRITE/DELETE/ADMIN

It is preferable to reduce the number of calls to Oracle Content Server (using a cache) and to provide a default implementation for matching the user's permissions information with the document's permission information. One limitation is that Oracle Content Server controls which types of security are used in some server environment properties: UseAccounts=true and UseCollaboration=true.

The user security convenience is accessed through the IUserSecurityCache interface. Three concrete classes implement the optional Oracle Content Server security:

• The UserSecurityGroupsCache class simply keeps a cache of user permissions and will match documents considering only Security Group information.

• The UserSGAccountsCache class adds a resolver to also consider Account information if Oracle Content Server has the UseAccounts=true setting.

• The UserSGAcctAclCache class adds a resolver to also consider ACL permissions if UseCollaboration=true.

The IAccessResolver interface allows the addition of classes that can participate in the resolution of the access levels for a document.

This example code uses the three classes for implementing security:

IdcClientManager m_clientManager = new IdcClientManager ();
IdcClient m_client = m_clientManager.createClient
   ("http://localhost/scs/idcplg");

//RIDC superuser context
IdcContext m_superuser = new IdcContext("sysadmin", "idc");

//Examples of the three concrete cache classes
IUserSecurityCache m_SGCache = new UserSecurityGroupsCache 
   (m_client, 20, 1000);
IUserSecurityCache m_SGAcctCache = new UserSGAccountsCache 
   (m_client, 20, 1000, 20000);
IUserSecurityCache m_SGAcctAclCache = new UserSGAcctAclCache 
   (m_client, 20, 1000, 20000, m_superuser);

//Example test
testDocPermission () {
   DataBinder m_doc1 = getDataBinder ("TEST");

   //Get the document information (typically in the first row of DOC_INFO)
   DataObject docInfo = m_doc1.getResultSet ("DOC_INFO").getRows ().get (0);

   //Get the cache id for this user
      //Important: this makes a live call to Oracle Content Server
      //to get the user ID for "Acme1")
      //CacheId acme1 = m_SGAcctAclCache.getCacheIdForUser 
                                      //   (new IdcContext("Acme1", "idc"));
      //You may want to include this:

   IdcContext context = new IdcContext("Acme1", "idc");
   CacheId acme1 = new CacheId (context.getUser (), context);

   //Get the access level for this document by this user
int access = m_SGAcctAclCache.getAccessLevelForDocument (acme1, docInfo);
   }

//Example code to get a Document's DOC_INFO databinder
DataBinder getDataBinder (String dDocName) throws IdcClientException {
   DataBinder dataBinder = m_client.createBinder ();
   dataBinder.putLocal ("IdcService", "DOC_INFO_BY_NAME");
   dataBinder.putLocal ("dDocName", dDocName); 

   ServiceResponse response = m_client.sendRequest 
      (m_superuser, dataBinder);
   return response.getResponseAsBinder ();
}

//Example code to create a DataObject
DataObject dataObject = m_client.getDataFactory ().createDataObject ();
dataObject.put ("dSecurityGroup", "public");
dataObject.put ("dDocAccount", "Eng/Acme");

Internally, these fields from the document are examined during getAccessLevelForDocument() processing:

• For the AccessResolverSecurityGroups class: dSecurityGroup

• For the AccessResolverAccounts class: dDocAccount

• For the AccessResolverSecurityGroups class: xClbraUserList and xClbraAliasList

The preceding IAccessResolver classes determine if they should participate based on cached information from Oracle Content Server. If they do participate, the access levels are put together with the AND operator.

9.11 Configuring SSL Communication with Oracle Content Server

RIDC allows Secure Socket Layer (SSL) communication with Oracle Content Server. This section provides basic information about SSL communication, including how to set up a sample implementation for testing purposes.

For SSL communication, you must install and enable the SecurityProviders component, configure Oracle Content Server with a new incoming provider, and specify the truststore or keystore information. You must have a valid keystore or trust manager with signed, trusted certificates on both the client and Oracle Content Server.

The sample implementation uses a JDK utility to create a self-signed key pair and certificates. Oracle does not provide signed certificates. For most implementations, you will want a certificate signed by a universally recognized Certificate Authority.

The following subsections describe how to configure SSL communication with Oracle Content Server:

• Section 9.11.1, "Installing and Enabling the SecurityProviders Component"

• Section 9.11.2, "Configuring an Incoming Provider for SSL Communication"

• Section 9.11.3, "Creating Self-Signed Key Pairs and Certificates"

# keytool -genkey -alias SecureClient -keyalg RSA -keystore client_keystore -dname "cn=SecureClient" -keypass idcidc -storepass idcidc

# keytool -genkey -alias SecureClient -keyalg RSA -keystore client_keystore -dname "cn=SecureClient" -keypass idcidc -storepass idcidc

# keytool -genkey -alias SecureServer -keyalg RSA -keystore server_keystore -dname "cn=SecureServer" -keypass idcidc -storepass idcidc

# keytool -selfcert -alias SecureClient -keystore client_keystore -keypass idcidc -storepass idcidc

# keytool -selfcert -alias SecureServer -keystore server_keystore -keypass idcidc -storepass idcidc

# keytool -export -alias SecureClient -file client_cert -keystore client_keystore -storepass idcidc

# keytool -export -alias SecureServer -file server_cert -keystore server_keystore -storepass idcidc

# keytool -import -alias SecureClient -file client_cert -keystore server_keystore -storepass idcidc

Owner: CN=SecureClient
Issuer: CN=SecureClient
Serial number: 3c42e605
Valid from: Mon Jan 14 08:07:01 CST 2002 until: Sun Apr 14 09:07:01 CDT 2002
Certificate fingerprints:
  MD5: 17:51:83:84:36:D2:23:A2:8D:91:B7:14:84:93:3C:FF
  SHA1: 61:8F:00:E6:E7:4B:64:53:B4:6B:95:F3:B7:DF:56:D3:4A:09:A8:FF
Trust this certificate? [no]: y
Certificate was added to keystore

# keytool -import -alias SecureServer -file server_cert -keystore client_keystore -storepass idcidc

Owner: CN=SecureServer
Issuer: CN=SecureServer
Serial number: 3c42e61e
Valid from: Mon Jan 14 08:07:26 CST 2002 until: Sun Apr 14 09:07:26 CDT 2002
Certificate fingerprints:
  MD5: 43:2F:7D:B6:A7:D3:AE:A7:2E:21:7C:C4:52:49:42:B1
  SHA1: ED:B3:BB:62:2E:4F:D3:78:B9:62:3B:52:08:15:8E:B3:5A:31:23:6C
Trust this certificate? [no]: y
Certificate was added to keystore

9.12 Using Tables for Content Items, the Search Index, and the File Store

The following subsections describe how to search tables for information about content items:

• Section 9.12.1, "Finding Information for Each Content Item"

• Section 9.12.2, "Using a Search Index"

• Section 9.12.3, "Using the File Store Provider"