Developing Web Service on Weblogic 8.

1 Server
A Quick Guide
v1.0 By Lin Oon Kean

Copyright 2004 by Lin Oon Kean

Table of Contents
1.Terms and Conditions of Use...........................................................................................................3 2.Introduction...................................................................................................................................... 4 3.High Level Steps.............................................................................................................................. 4 4.Details...............................................................................................................................................5 5.References...................................................................................................................................... 10 6.Advanced Topic............................................................................................................................. 10

Copyright 2004 by Lin Oon Kean

1.Terms and Conditions of Use

The information here was written in the hope that it will be useful, but is provided AS IS , WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL I BE LIABLE TO ANY PARTY FOR ANY DIRECT, INDIRECT, SPECIAL OR OTHER CONSEQUENTIAL DAMAGES FOR ANY USE OF THIS MATERIAL, OR ON ANY OTHER HYPER LINKED MATERIAL, INCLUDING, WITHOUT LIMITATION, ANY LOST PROFITS, BUSINESS INTERRUPTION, LOSS OF PROGRAMS OR OTHER DATA ON YOUR INFORMATION HANDLING SYSTEM OR OTHERWISE, EVEN IF I AM EXPRESSLY ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. ALL INFORMATION IS PROVIDED BY ME ON AN "AS IS" BASIS ONLY. I PROVIDE NO REPRESENTATIONS AND WARRANTIES, EXPRESS OR IMPLIED, INCLUDING THE IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY AND NONINFRINGEMENT.

Copyright 2004 by Lin Oon Kean

2.Introduction
This article aims to be a quick start to get a Web Service up on Weblogic 8.1 Server. It highlights the things that needs to be done in order to expose an EJB as an RPC-Oriented Web Service. The BEA Weblogic Server e-docs provides comprehensive information on this issue. However , the plethora of documentation tends to bury the path on what needs to be done. It is the intention of this article to weed out much of the information to provide the bare minimum in getting things up and running. For further information , refer to the References section of this document for URL to the relevant documentation at BEA site. The web service example in this article is backed by a Stateless Session Bean. Familiarity with the following are assumed :

Developing and deploying a Stateless Session Bean in Weblogic 8.1 server Usage of ANT Concept of Web Service

3.High Level Steps

A quick overview of the steps that needs to be performed in creating a Web Service is as follows :
1. Create and compile the Java object that handles the Web Service

The logic that processes the web service request may be implemented as a Java class or an EJB. This article takes the latter approach in exposing an EJB as a web service. Note : Weblogic also provides a means to allow SOAP messages to be intercepted before and/or after the web service request is processed. This topic is not addressed in this document. More information can be found from the Advanced Topic section of this document. 2. Generate the Web Service deployment descriptor and WSDL for the Java object In order to expose the EJB as a Web Service , a web service deployment descriptor (web-services.xml) needs to be written , as well as the description of the Web Service in WSDL. Weblogic provides tools to generate these files. Weblogic also provide a corresponding ANT task for these tools. 3. Package the Web Service components into an EAR Web Services in Weblogic are packaged into EAR files before being deployed. The EAR file would contain an EJB JAR file (if the Java object handling the service is an EJB) and also a Web Appplication (WAR) that exposes the service (via the file web-services.xml) and serves the WSDL file.

Copyright 2004 by Lin Oon Kean

4. (Optional) Generate the client side proxy objects to interact with the EJB To allow a Java client to programatically communicate with the Web Service through an API , Weblogic provides a tool that can generate client side proxy classes that translates a method call to a Web Service request. Java clients may then interact via the API instead of forming SOAP packets. Since Web Services may also be invoked via SOAP directly , this step is only necessary if there is a need for generating client side stubs. 5. Deploy the EAR in Weblogic To get the Web Service humming along , the EAR is then deployed on Weblogic server.

4.Details
1. Create and compile the Java object that handles the Web Service

The stateless EJB that will be exposed as Web Service has the following remote interface definition. package com.webvertices.webservice; import com.webvertices.webservice.objects.Message; import javax.ejb.EJBObject; import java.rmi.RemoteException; public interface WebserviceSession extends EJBObject { public String simpleEcho(String message) throws RemoteException; public Message echoMessage(Message message) throws RemoteException; }

The two methods which are published are WebserviceSession.simpleEcho() and WebserviceSession.echoMessage(). The former method's parameter takes in a simple java.lang.String object while the latter takes in a custom com.webvertices.webservice.objects.Message object. In Web Services , objects are passed from a caller to a Web Service via serialization to XML. Weblogic web service tool have default support for certain type of objects. These default supported objects are called Built-In Data Types. The String object is one of the built in types. The non-default supported objects are called Non-Built-In Data Types. The tool is also able to generate the XML representation of Non-Built-In Data Types , but it is bound to some restrictions. A more thorough discussion of this can be found in Weblogic's documentation Assembling WebLogic Web Services Using Ant Tasks (URL can be found in the References section). In this example , the object Message does not violate any restriction on Weblogic's generation tool. Copyright 2004 by Lin Oon Kean

Using ANT , the EJB above is compiled and packaged into a JAR file. This is a common step and no extra steps needs to be taken. Since we are deploying on Weblogic , the typical step of running the EJB through Weblogic's EJB compiler to generate the stubs is done. The ANT task for this step is called <wlappc>. Take note that weblogic.jar needs to be in the classpath of ANT when <wlappc> is executed. In the example below , weblogic.jar is also used to supply the javax.ejb.* classes for the compilation of the EJB. <target name="ejb"> <copy todir="classes/META-INF"> <fileset dir="META-INF"> <include name="ejb-jar.xml"/> </fileset> </copy> <javac srcdir="." includes="**/**" destdir="classes" > <classpath> <fileset dir="D:\bea\weblogic81\server\lib\"> <include name="weblogic.jar" /> </fileset> </classpath> </javac> <jar destfile="build/WeblogicWebserviceEJB.jar" basedir="classes" /> <wlappc debug="yes" source="build/WeblogicWebserviceEJB.jar" /> ....

After the execution of the above script , the EJB is packaged into a file named WeblogicWebserviceEJB.jar. The EJB JAR will also would have contain the stubs generated by Weblogic EJB compiler.

Copyright 2004 by Lin Oon Kean

2. Generate the Web Service deployment descriptor and WSDL for the Java object and package the Web Service components into an EAR

Generally speaking , the <servicegen> ant task of Weblogic generates the web service deployment descriptor and also the WSDL based on the EJB JAR file created in step 1. Each Web Service that is implemented with either a Stateless Session EJB or java class is described in the child tag <service>. <servicegen> also generates a WAR file that will publish the WSDL and services the Web Service request. The task then creates an EAR file that contains the EJB JAR and the WAR file. This bundle is the unit of deployment to expose the Web Service. For <servicegen> to execute , the library webservices.jar (which resides in the same directory as weblogic.jar) should be in the ANT classpath. Note : The document Web Service Ant Tasks and Command-Line Utilities contains the command line equivalent of the web service ant tasks provided by Weblogic. The ANT script below builds an EAR file called WeblogicWebserviceEAR.ear .

The web service deployment descriptor and WSDL will be generated from WeblogicWebserviceEJB.jar (via the child tag <service>) . The task then creates a WAR file called WeblogicWebserviceWAR.war and adds the web service deployment descriptor and WSDL into it. Lastly , both the WAR and the JAR file is added intoWeblogicWebserviceEAR.ear file.

<servicegen destEar="build/WeblogicWebserviceEAR.ear" warName="WeblogicWebserviceWAR.war"> <service ejbJar="build/WeblogicWebserviceEJB.jar" targetNamespace="http://mynamespace" serviceName="WeblogicWebservice" serviceURI="/WeblogicWebservice" generateTypes="True" expandMethods="True"> <client packageName="com.webvertices.webservice.client" clientJarName="WeblogicWebserviceClient.jar" /> </service> </servicegen> The Web Service name is set to WeblogicWebservice as indicated by the attribute serviceName in the <service> tag. Because the WAR file servicing the web service is called WeblogicWebserviceWAR , this would also be the default context in which the Web Service falls under.

Copyright 2004 by Lin Oon Kean

Hence , to access the Web Service when it is deployed on a local machine, the URL would be : http://localhost:7001/WeblogicWebserviceWAR/WeblogicWebservice To get the WSDL , append ?WSDL to the URL : http://localhost:7001/WeblogicWebserviceWAR/WeblogicWebservice?WSDL The optional <client> tag allows the generation of the client side proxy JAR to be created and packed into the WAR file. This allows the client JAR to be downloadable from the server. The client JAR will then be available from http://localhost:7001/WeblogicWebserviceWAR/WeblogicWebserviceClient.jar 3. Generate the client side proxy objects to interact with the EJB The ANT task <clientgen> generates the client side proxy object from the Web Service EAR file. This task generates the client JAR from the web service EAR file (pointed to by the attribute ear). It looks into the given EAR file for the WAR that contains the Web Service(s). The name of the WAR file is defined using the attribute warName .

<clientgen ear="build/WeblogicWebserviceEAR.ear" warName="WeblogicWebserviceWAR.war" keepGenerated="True" packageName="com.webvertices.webservice.client" clientJar="build/WeblogicWebserviceClient.jar" />

The package name of the client side proxies can be specified via the attribute packageName and the resulting client JAR file containing the proxies by the attribute clientJar. The typical keepGenerated attribute when set to True would cause the generated source file of the proxies to be packaged into the client JAR file as well. 4. Deploy the EAR in Weblogic Server The EAR file is not ready for deployment in Weblogic Server 5. Client Side Web Service Request On the client side , in order to invoke the Web Service through the client proxy , the following files need to be present in the classpath (both JAR files resides in the same directory as weblogic.jar)

webserviceclient.jar wsclient81.jar

Copyright 2004 by Lin Oon Kean

On the client side , to invoke the Web Service through the client proxy , the client needs to set the system properties javax.xml.soap.MessageFactory and javax.xml.rpc.ServiceFactory to Weblogic's implementation

// Setup the global JAXM message factory System.setProperty("javax.xml.soap.MessageFactory", "weblogic.webservice.core.soap.MessageFactoryImpl"); // Setup the global JAX-RPC service factory System.setProperty( "javax.xml.rpc.ServiceFactory", "weblogic.webservice.core.rpc.ServiceFactoryImpl");

Next , the client needs to instantiate a new proxy implementation of the Web Service (typically the class name starts with the Web Service name and ends the post fix _Impl ). From the proxy implementation , a Web Service Port object is obtained. All the Web Services are invoked through this Port object. WeblogicWebservice_Impl service = new WeblogicWebservice_Impl(); WeblogicWebservicePort port = service.getWeblogicWebservicePort(); String result = port.simpleEcho("From Client"); Message message = new Message(); message.setMessage(Some Message); Message returnMessage = port.echoMessage(message);

Copyright 2004 by Lin Oon Kean

5.References
1. Implementing WebLogic Web Services http://e-docs.bea.com/wls/docs81/webserv/implement.html 2. Assembling WebLogic Web Services Using Ant Tasks http://e-docs.bea.com/wls/docs81/webserv/assemble.html 3. Web Service Ant Tasks and Command-Line Utilities http://e-docs.bea.com/wls/docs81/webserv/anttasks.html

6.Advanced Topic
1. Creating SOAP Message Handlers To Intercept SOAP Message http://e-docs.bea.com/wls/docs81/webserv/interceptors.html

Copyright 2004 by Lin Oon Kean