|
Oracle® Discussions Application Developer's Guide
10g Release 1(10.1.2) B28208-02 |
|
 Previous |
 Next |
|
Oracle® Discussions Application Developer's Guide
10g Release 1(10.1.2) B28208-02 |
|
|
Previous |
Next |
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:
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.
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.
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.
The following is an example for invoking a Web Service. This example does the following operations:
Log in as td_superuser, by supplying username and password in plain text. (td_superuser and welcome1 are the user name and password considered in the Example 4-1).
Retrieve the cookie on successful login.
Set the retrieved cookie on the Category Service client stub.
Prepare the required input parameters and invoke a Web Service call on the category service.
Print the properties on the returned category (and invoke any other Web Services).
Log out the user.
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.
|
