1 Connecting to Oracle Content Services

The Oracle Content Services Web Services Development Kit

This guide should be used in conjunction with the Oracle Content Services Web Services Development Kit. The Development Kit can be downloaded from:

http://www.oracle.com/technology

Inside you will find the necessary JAR files with which to run the Web Services client. The examples in this guide are available in full within the Development Kit, along with additional documentation, the bulk tools, more samples, and the Java API Reference (Javadoc).

The following JARs from the /lib directory of the Development Kit must be in your CLASSPATH to run the examples:

• activation

• axis

• commons-discovery-0.2

• commons-logging-1.0.3

• content-ws-client

• http_client

• jaxrpc

• mail

• saaj

• wsdl4j-1.5.1

• xmlpaserv2

The examples in this guide are available in the Development Kit in the sample_code/sample_webservices/src/oracle/ifs/examples/ws directory. The Development Kit also provides documentation and a number of examples for creating, configuring, and using custom Business Process Execution Language (BPEL) workflows with Oracle Content Services. The custom workflow document provides information about how to get started with custom BPEL workflows.

The Development Kit also contains documentation for the command-line tools, which provide a way to easily load and modify a large number of Libraries or Groups.

Connecting to an Oracle Content Services Instance

The first step for a client is to authenticate with the Oracle Content Services instance. The instance is accessed at a fixed URL such as http://servername.com/content/ws. To connect to an instance, you will need a URL and port, as well as a valid username and password. Authentication uses the RemoteLoginManager class to pass the username and password to the running instance.

Note: For the example below, we will assume that your Oracle Content Services instance can accept authentication requests over an insecure connection. By default, Oracle Content Services only allows cleartext authentication over HTTPS. To change this setting, the CleartextAuthenticationRequiresHttps property of the Oracle Collaboration Suite domain must be set to false. See Chapter 6 of the Oracle Content Services Administrator's Guide for more information.

The RemoteLoginManager object must be retrieved from the server using its ServiceLocator.

RemoteLoginManagerServiceLocator rlmsl =
        new RemoteLoginManagerServiceLocator();
    rlmsl.setMaintainSession(true);
    
    // initialize the RemoteLoginManager
    s_RLM = rlmsl.getRemoteLoginManager(new URL(serverUrl +
                                        "/RemoteLoginManager"));
    

The RemoteLoginManager.login method returns a set of properties about the login session (namely, the login user, session timeout, and transaction timeout). These properties are stored in an array of NamedValue pairs, and can be used as needed.

// establish a session
    NamedValue[] properties = s_RLM.login(username, password, null, null);

After logging in, get the value of the HEADER_COOKIE property from the RemoteLoginManager. This cookie will be used to register the session with other Manager instances. In order to properly store session state, the client must support HTTP cookies.

// get the cookies
    s_Cookie =
        (String) ((Stub) s_RLM)._getCall().getMessageContext().getProperty(
            HTTPConstants.HEADER_COOKIE);

The examples in this book use the WsConnection utility class to connect to an instance and retrieve Manager objects.

Note: Oracle Content Services imposes a limit on the number of concurrent sessions a user can maintain. This limit protects against Denial of Service attacks. Because HTTP is a connection-less protocol, the server has no way of knowing if a client disconnects unless explicitly alerted to by the client by way of a request (such as calling a logout method). Many servers, including Oracle Content Services, impose a session inactivity timeout, whereby if the user has not made a request in a certain period of time, the server frees (and disconnects) the client's inactive session. Should the client not explicitly log out, it would be possible to flood the server with new connections (and thus new user sessions) at a higher rate than the server can dispose of the inactive sessions. Thus, always invoke the RemoteLoginManager logout operation when appropriate.

Initializing Manager Classes

Manager classes must be retrieved and initialized individually before a user can perform actions with them. Each Manager is located at the base URL of the Web Services instance with /ManagerName appended. To retrieve an object for a Manager, you will use the corresponding Locator class.

DomainManagerServiceLocator dmsl = new DomainManagerServiceLocator();

dmsl.setMaintainSession(true);

The setMaintainSession method sets a flag to allow the Manager instance to be used across a persistent user session. This session must be registered with each Manager individually by passing the session cookie. Registering the session prevents having to authenticate and register with each Manager every time you want to perform an operation.

The Manager instance is returned from the Locator class.

DomainManager s_DM = dmsl.getDomainManager(new URL(serverUrl + "/DomainManager"));

Register the session cookie with a Manager instance by setting its HEADER_COOKIE property (Stub is a JAX-RPC class used to set properties on the Manager instance.).

((Stub) s_DM)._setProperty(HTTPConstants.HEADER_COOKIE, s_Cookie);