Skip Headers
Oracle® Discussions Application Developer's Guide
10g Release 1(10.1.2)
B28208-02
  Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

4 Building Applications with Oracle Discussions Web Services

This chapter describes the requirements and the tasks for building applications with Oracle Discussions Web Services. For details about Web Services specification and activity, please refer to http://www.w3.org/2002/ws. This chapter consists of the following sections:

Requirements

This guide assumes that you are using Apache Axis as your Simple Object Access Protocol (SOAP) client. The version of Apache Axis should be at least 1.2.0. Invoking Oracle Discussions Web Services would be similar if any other Web Services client toolkit is used. For details on SOAP specification, refer to http://www.w3.org/TR/SOAP.

Accessing Deployed Web Services

Discussions Web services description and Web Service Description Language (WSDL) files will be available at the location http://<<hostname:port>>/discussions/ws on the instance of Oracle Collaboration Suite Applications tier.

WSDL describes Web Services in a structured way. WSDL describes the data types that the service uses, and the location of the service to the interface of the service. Axis supports WSDL generation using a Java2WSDL tool.

When a Web Service is deployed in an Axis engine, users may then access the URL of the service with a standard web browser and by appending ?WSDL at the end of the URL. An automatically generated WSDL document that describes the service is displayed on the browser screen.

For example, to access Oracle Discussions AuthenticationService, enter the following:

http://<<hostname>>:<<port>>/discussions/ws/AuthenticationService?wsdl

or

http://<<hostname>>:<<port>>/discussions/ws/axis/services/AuthenticationService

If the service URL is accessed in a browser, then a message indicating that the endpoint is an Axis service is displayed. If ?wsdl is appended at the end of the URL, then Axis will automatically generate a service description for the deployed service, and return it as XML in the browser. The resulting description may be saved or used as input to proxy generation. The WSDL-generated URL can be given to the online partners, and they will be able to use it to access the Web Services with toolkits like .NET, SOAP::Lite, or any other software which supports WSDL.

A WSDL document will contain the appropriate WSDL types, messages, portType, bindings, and service descriptions to support a SOAP RPC and encoding Web Service. If the methods of the Web Services interface reference other classes, then the Java2WSDL tool will generate the appropriate XML types to represent the classes and any nested or inherited types.

For details about the WSDL specification, please refer to the following URL: http://www.w3.org/TR/wsdl.

Generating Client-Side Stub Classes

To access Web Services, invoke a remote call on SOAP or HTTP. For this, the client must have the Web Service endpoint location and a handle to the Web Services interface. These remote interfaces, client side service locators, and stubs are generated by WSDL2Java tool that is provided by Axis.

Generating the Client Stubs

Download the axis related jar files from the location http://ws.apache.org/axis.

The downloaded axis jars are to be unzipped into /usr/axis (Change the directory accordingly). To set the classpath, follow the instructions below (it is assumed that you use bash shell).

set AXIS_HOME=/usr/axisset AXIS_LIB=$AXIS_HOME/libset AXISCLASSPATH=$AXIS_LIB/axis.jar:$AXIS_LIB/commons-discovery.jar  $AXIS_LIB/commons-logging.jar:$AXIS_LIB/jaxrpc.jar:$AXIS_LIB/saaj.jar  $AXIS_LIB/log4j-1.2.8.jar:$AXIS_LIB/xml-apis.jar:$AXIS_LIB/xercesImpl.jar

Along with these, include http_client.jar, mail.jar, activation.jar into the classpath (classpath of Axis).

Invoking WSDL2Java tool to generate client side stubs

Axis WSDL2Java tool can be found in org.apache.axis.wsdl.WSDL2Java. The basic invocation form looks like this:

%    $JAVA_HOME/bin/java -cp <<AXISCLASSPATH>>org.apache.axis.wsdl.WSDL2Java --output <<GEN_DIR >>--deployScope Session --NStoPkg  <<NAMESPACE-TO-PACKAGE-MAPPING>>  <<WSDL-FILE-URL>>

The description of the preceding code is as follows:

  • JAVA_HOME is the location, where Java Development Kit (JDK) is installed.

  • GEN_DIR is the directory in which the client stubs are to be generated.

  • NAMESPACE-TO-PACKAGE-MAPPING is the mapping between the XML namespace to Java files. While converting the XML files (WSDL files are XML documents) to corresponding Java classes (client stubs), the XML namespace is converted into the provided package structure. For example, if the namespace to package mapping is provided as following:

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

    Then the generated client stubs are placed in the oracle/discussions/ws/ package structure.

  • WSDL-FILE-URL is the URL at which the WSDL files are available. For example, if Oracle Discussions Web Services are deployed on machine stacx01.us.oracle.com at port 8888, then Authentication Service WSDL-FILE-URL would be as follows:

    http://stacx01.us.oracle.com: 8888/discussions/ws/AuthenticationService?wsdl
    
    

Compiling the client stubs

The client stubs are to be compiled by invoking the following command:

Javac -classpath $AXISCLASSPATH -d <<DESTINATION-CLASSES-DIRECTORY>>  *java

The invocation is to be done in the directory in which the client stub source files are present.

DESTINATION-CLASSES-DIRECTORY is the directory in which the class files are to be placed.

Once the client stubs classes are generated, include the directory containing the stub classes into the classpath. Now you are ready to compile and run a web services java client, to access Oracle Discussions Web Services.

Invoking a Service

The following is an example for invoking a Web Service. This example does the following operations:

Example 4-1 Invoking a Web service

package oracle.discussions.ws;
 
import java.util.Date;
import java.io.*;
import java.util.*;
import javax.mail.*;
import javax.mail.internet.*;
 
import org.apache.axis.transport.http.HTTPConstants;
import oracle.discussions.ws.exceptions.TdWSException;
import oracle.discussions.ws.beans.*;
import oracle.discussions.ws.AuthenticationServiceServiceLocator;
import oracle.discussions.ws.AuthenticationServiceSoapBindingStub;
import oracle.discussions.ws.AuthenticationService;
import oracle.discussions.ws.CategoryServiceSoapBindingStub;
import oracle.discussions.ws.CategoryServiceServiceLocator;
import oracle.discussions.ws.CategoryService;
 
/*
 * This method invokes various web services methods, to retrieve the results and 
 * check if the results are fine.
 */
public class WSClient
{
  public static void main(String args[]) 
  {
     try
     { 
        //STEP - 1: User Login
        //Create the service locator for authentication service. The locator
        //contains information about the webservices endpoint.
         AuthenticationServiceServiceLocator assl = new
                  AuthenticationServiceServiceLocator();
        
        //Get the handle to the actual Web Services interface
         AuthenticationService as = assl.getAuthenticationService();
        //Indicate to the server that the client is interested in maintaining
        //session.
        //HTTP is stateless and the user state is maintained in the session.
        //Unless the user is willing to participate in a session, user state
        //cannot be preserved.
         ((AuthenticationServiceSoapBindingStub)as).setMaintainSession(true);

        //Invoke the actual login Web Services call
         as.login("td_superuser","welcome1");
        //Retrieve the cookie. The cookie is set on successful authentication.
         String cookie = (String)((AuthenticationServiceSoapBindingStub)as).
                  _getCall().getMessageContext()
                  .getProperty(HTTPConstants.HEADER_ COOKIE);
         System.out.println("Cookie : " + cookie);
 
        //STEP - 2: Category Creation
        //Create an instance of the category service locator.
         CategoryServiceServiceLocator catssl = new
                  CategoryServiceServiceLocator();
        //Get the handle to the category service interface.
         CategoryService cats = catssl.getCategoryService();
        //Indicate to the server that the user is willing to participate in the
        // session.
         ((CategoryServiceSoapBindingStub)cats).setMaintainSession(true);
        //Set the cookie retrieved in the call to login webservice.
        //The cookie asserts user's identity to the server.
         ((javax.xml.rpc.Stub)cats)._setProperty(HTTPConstants.HEADER_
                 COOKIE,cookie);
  
        //Define a category definition bean. The bean defines the category
        //properties.
         CategoryDefinition cd = new CategoryDefinition();
         cd.setName("Test Category");
         cd.setDisplayName("Test Category");
         cd.setDescription("Category created for testing ws java client");
         cd.setWithAnnouncementBoard(true);
        //Invoke the webservices call on the web services interface.
         Category category = cats.create(-1,cd);

        //If the category creation is successful, a category bean is returned, 
        //depicting the category object created in the TD repository.
         if(category != null)
         {
             System.out.println("Creation Date :" +
                   category.getCreationDate().getTime());
             System.out.println("Creator :" + category.getCreator());
             System.out.println("Description :" + category.getDescription());
             System.out.println("Display Path :" + category.getDisplayPath());
             System.out.println("Display Name :" + category.getDisplayName());
             LastPost lp = category.getLastPost();
             if(lp != null)
                    {
                        System.out.println("Author :" + lp.getLastpostAuthor());
                        System.out.println("Date :" + lp.getLastpostDate());
                        System.out.println("Forum ID :" +
                                  lp.getLastpostForumId());
                        System.out.println("Topic id :" +
                                  lp.getLastpostTopicId());
                        System.out.println("Message Id :" +
                                  lp.getLastpostMessageId());
                    }
 
                    System.out.println("Is Favorite :" + category.isFavorite());
                    System.out.println("Is New :" + category.isNewFolder());
                    System.out.println("Is New Since Last Visit :" +
                            category.isNewSinceLastVisit());
                    System.out.println("Is New Since Session :" +
                            category.isNewSinceSession());
                    System.out.println("Name :" + category.getName());
                    System.out.println("Id :" + category.getId());
                    System.out.println("is category type :" +
                            category.isCategoryType());
                    System.out.println("Web ui URL :" + category.getWebuiURL());
                    System.out.println("Rss URL :" + category.getRssURL());
                    System.out.println("Has ann forum :" +
                            category.isAnnouncementsBoardPresent());
                    System.out.println("Parent id :" + category.getParentId());
              }
 
              //Invoke as many web service operations as you want..
              //...........................
              //...........................
 
              //STEP - 2: User Logout
               System.out.println("User logout.");
              //Once all the webservices operations are done, invoke logout 
              //operation.
              //On logout, user state is destroyed and the cookie is
              //invalidated.
               as.logout();
               System.out.println("Done"); 
           }
           catch(TdWSException ex)
           {
                 System.out.println("Error Code :" + ex.getErrorCode());
                 System.out.println("Error Message :" + ex.getErrorMessage());
                 String[] trace = ex.getServerStackTrace();
                 if(trace != null)
                 {
                    for(int i = 0 ; i < trace.length ; i++)
                    System.out.println("trace[" + i + "]" + trace[i]);
                 }
           }
    catch(Exception ex)
    {
       System.out.println("Never went into tdex :" + ex.getMessage());  
       ex.printStackTrace();
    }
  }
}

Compile the Web Services Java program by invoking the following command:

Javac -classpath $AXISCLASSPATH  WSClient.java

WSClient .java is the name of the program in Example 4-1. Append the directory that contains the compiled class file to the AXISCLASSPATH.

The compiled Java program is run by using the following command:

Java -cp $AXISCLASSPATH  WSClient

The sample output of the program code above is given below

Cookie : JSESSIONID=8c57046a22b882c3e6c4ee72400ebbcfd8eeb777becfCreation Date :Thu Feb 23 23:50:46 PST 2006Creator :td_superuserDescription :Category created for testing ws java clientDisplay Path :/WS CategoryDisplay Name : WS CategoryIs Favorite :falseIs New :falseIs New Since Last Visit :falseIs New Since Session :falseName : WS CategoryId :85764is category type :trueWeb ui URL :http://stacx01:8888/discussions/app/mainAction.do?fid=85764Rss URL :http://stacx01:8888/discussions/rss/facility?fid=85764
Has ann forum :trueParent id :-1User logout.Done


Note:

Please ensure that the users mentioned in the sample program above are created and are granted relevant roles (td_superuser is granted a system administrator role in the provisioning console). Also please ensure that the category name or the display name are not same as in an already existing category in the same container in which the current category is being created. Please verify the user password before executing the program.