2 Building Applications with Oracle Workspaces Web Services

This chapter describes the following requirements and tasks involved in building applications with Oracle Workspaces Web Services:

Requirements for Compilation and Execution of Applications that Use Oracle Workspaces Web Services
Location of WSDL Files
General Procedure to Build Applications with Oracle Workspaces Web Services

Requirements for Compilation and Execution of Applications that Use Oracle Workspaces Web Services

You will need a SOAP engine that can generate client stub classes from WSDL files, such as Apache Axis, Oracle JDeveloper, or Oracle Application Server SOAP Management Utilities and Scripts.

This guide uses Apache Axis as its SOAP engine and Apache Xerces Java Parser. The version of Apache Axis should be at least 1.2.0.

Classpath of Oracle Workspaces Web Services

On the machine you wish to execute your Oracle Workspaces Web services client application, set the classpath to include the following libraries and files:

Library .jar files shipped with Apache Axis
Libraries that Apache Axis require. Apache Axis requires a JAXP-1.1 compliant XML parser such as Apache Xerces (the samples in this guide use Xerces).

Generating Client-Side Stub Classes

Before using any Oracle Workspaces Web Services, you must create client-side stub classes from WSDL files hosted on the Oracle Workspaces server .

Generate client-side stub classes of a particular Web service by using the Apache Axis WSDL2Java tool:

java -cp <AXISPATH> org.apache.axis.wsdl.WSDL2Java
  --deployScope Session
  --NStoPkg <package-to-namespace-mapping>
      <path-to-wsdl-file>

<AXISPATH> is the classpath that contains the Apache Axis library .jar files.

<package-to-namespace-mapping> is the package to namespace mapping. The following is an example of a mapping:

"http://xmlns.oracle.com/workspaces/ws"="oracle.workspaces.ws"

<path-to-wsdl-file> is the URL where the WSDL files are hosted. This path is in the following form:

http://<host>:<port>/ocw/services/<service-name>?wsdl

<host>:<port> is the host and port where the WSDL files are hosted.
<service-name> is the name of the Web service for which you wish to generate the client-side bindings

For example, if your WSDL files are hosted in your local OC4J instance at port 8888 on machine www.example.com and you wish to generate the stubs for AuthenticationService, the URL would be the following:

http://www.example.com:8888/ocw/ws/AuthenticationService?wsdl

Using Apache Ant to Build Client-Side Stub Classes

Alternatively, you may use Apache Ant and Axis Ant tasks to generate client-side stub classes. The following is an example of using the <axis-wsdl2java> task to generate the client-side stubs for AuthenticationService:

<axis-wsdl2java
      output="${GEN_HOME}/src"
      testcase="true"
      verbose="true"
      deployscope="Session"
      url="${WS_HOST}/ocw/services/AuthenticationService?wsdl">
      <mapping
        namespace="http://xmlns.oracle.com/workspaces/ws"
        package="oracle.workspaces.ws" />
    </axis-wsdl2java>

GEN_HOME is the directory in which the client-side stub .java files will be generated

WS_HOST is the URL where the WSDL files are hosted.

Compiling Generated Stub Classes

Compile the generated stub classes and package them into a .jar file. Ensure that you add this .jar file to the classpath of your Oracle Workspaces Web services client application.

Location of WSDL Files

A list of all available Oracle Workspaces Web services is available at the following URL:

http://<host>:<port>/ocw/ws

The WSDL file for a particular Web service is available at the following URL:

http://<host>:<port>/ocw/services/<name-of-Web-service>?wsdl

<name-of-Web-service> is the name of the Web service.

General Procedure to Build Applications with Oracle Workspaces Web Services

The following steps are a general outline you may follow to create Oracle Workspaces Web Services client applications:

Use Authentication Service or Service-to-Service Authentication Service to retrieve an authentication cookie. This authentication cookie is required to invoke any Oracle Workspaces Web service.
Most Oracle Workspaces Web service operations require a workspace. Use Home Service to create or retrieve a workspace.
Retrieve users of Oracle Workspaces (which are users of Oracle Collaboration Suite that have been registered in Oracle Internet Directory) with Users Service.
Make a user a member of a workspace with Workspaces Service. You may also add additional resources to a workspace with this service.
Work with workspace items with the following services:
Retrieve, create, store, and delete workspace templates with Template Service.
Grant or revoke administrative roles to users or configure Oracle Workspaces with Administration Service.