Creating the Echo Web Service | Oracle Application Server 10g: J2EE Deployment and Administration

Creating web services with Oracle 10g AS is remarkably simple. In fact you'll find that building a web service is very much a case of implementing your logic and letting Oracle 10g AS worry about SOAP and all the other web-service plumbing. The web-service implementation class itself is very straightforward. It's just a normal Java class or session EJB with normal Java methods . Of course, since all communication will be traveling over SOAP and will be processed by JAX-RPC, you need to stick to parameter and return types allowed by those protocols. Essentially, you can use any of the primitive types along with their corresponding wrapper classes. On top of this you can use java.util.Date and java.util.Map , plus some of the XML classes. In addition you're able to use JavaBeans and single-dimension arrays of the types mentioned here. When using JavaBeans you must ensure that the properties of the class are of the types described here. For a fuller list of the appropriate types, check out the documentation at http://download-uk.oracle.com/ocs/cd/B10464_02/web.904/b10447/javaservices.htm#g1034081 .

In this section we'll demonstrate how to build two of the three kinds of web services: stateless and stateful. The web service you're going to implement is a simple echo service where the parameter passed to the service is echoed back to the client. In the stateful example you'll append a counter to the end of the message to see the state management in action.

Building the Web-Service Interface

To start with you need to build an interface for your web service. Oracle 10g AS uses the methods defined in the interface as the guide for which methods to expose as operations of your service. You can skip this stage and have Oracle 10g AS generate the service directly from your implementation class, which will result in all public methods of the implementation class being exposed as service operations.

Although not obligatory , in our experience it's always a better to use an interface to explicitly define the operations of your service, because it makes it simpler to modify the implementation class or even to change the class altogether. For the echo web service you just need to define a basic interface, as shown here:

 package com.apress.oracle10g.webservices; public interface EchoWebService {     public String echo(String message); }

As you can see, the interface for the echo service defined a single operation, echo , which accepts a single String parameter and returns a String value. Now let's move on to the stateless implementation.

Building the Stateless Implementation

The next step toward building your web service is to create the implementation of the stateless service. You won't be surprised to know that the implementation is trivial, as shown here:

 package com.apress.oracle10g.webservices; public class EchoWebServiceStatelessImpl implements EchoWebService {     public String echo(String message) {         return message;     } }

Not much to it! So far you've done nothing that's specifically related to a web service. I could use this class just as well in a web application, a Swing application and a command-line application. You're free to use almost any class as a web service, provided the method arguments and return types meet the type requirements stated earlier.

Building the Stateful Implementation

The final block of Java code required for the web service is the implementation of the stateful service, as shown here. Again this is very simple.

 package com.apress.oracle10g.webservices; public class EchoWebServiceStatefulImpl implements EchoWebService {     private int count = 0;     public String echo(String message) {         return message + count++;     } }

As you can see, the only difference is that this class has some state, which is reflected in the value returned from the echo() method. As far as implementation of the actual service logic goesthat is it. Again, nothing that you've created is specifically related to a web service, which is good because it means that you could use these classes elsewhere if you desired.

Configuring and Deploying the Web Service

Technically, there are two ways you can configure and deploy the web service. The first involves creating and configuring a web application for the web service, using the Oracle web-service Servlets to expose your classes as web services. The drawback of this approach is that the exact details of how a web service is actually configured and deployed are likely to change in the future, and thus you'll need to change your code. Also you'll find this method requires many different steps and is quite error prone. The second, and better, solution is to use the WebServices Assembler (WSA) tool, which takes a generically defined configuration file, creates a correctly configured web application for your services, and packages it up in an EAR file. If the details of how Oracle implements web services in the future change, then you simply run the newer version of WSA using your application's configuration file to create an up-to-date deployment package. You'll also find that the WSA configuration file is simple to understand and requires less work than creating the web application manually.

The configuration file for the echo web service, as shown here, isn't particularly complex, but it does introduce some tags you haven't seen before so we'll explain it piece by piece.

 <web-service>     <display-name>Echo Web Service</display-name>     <description>Oracle 10g Web Service Example</description>     <destination-path>./echows.ear</destination-path>     <context>/ws</context>     <option name="source-path">./bin</option>     <temporary-directory>./tmp</temporary-directory>

The configuration file starts with the <web-service> tag and directly under that are tags that control the overall behavior of the WSA:

The <destination-path> tag specifies the full path, including the filename, of the EAR file that the WSA will create.
The <context> tag specifies the context path for the web application. All web services defined will be accessible under this path.
The <option> tag shown in the example, with the name attribute set to source-path , is an important one. It specifies the location of the Java class files of the web service.
The <temporary-directory> specifies a directory that WSA can use for temporary resources. The documentation says this parameter is optional but we were unable to get WSA working without it.

The next part of the file is the <stateless-java-service> , which declares the stateless echo service as shown here:

 <stateless-java-service>    <class-name>       com.apress.oracle10g.webservices.EchoWebServiceStatelessImpl    </class-name>    <interface-name>       com.apress.oracle10g.webservices.EchoWebService    </interface-name>    <uri>/echoStateless</uri> </stateless-java-service>

The tags here should be fairly self-explanatory. The important part to note is that the <uri> tag declares the URI of the service relative to the context path specified earlier.

The final part of the config file, as shown here, is the <stateful-java-service> for the stateful echo service:

 <stateful-java-service>      <class-name>           com.apress.oracle10g.webservices.EchoWebServiceStatefulImpl       </class-name>       <interface-name>          com.apress.oracle10g.webservices.EchoWebService       </interface-name>       <uri>/echoStateful</uri>    </stateful-java-service> </web-service>

As you can see, the configuration for both services is very similar. In fact, you'll find that both <stateless-java-service> and <stateful-java-service> share mostly the same set of configuration parameters, with stateful services having a few additional parameters. We won't cover all of the remaining configuration options here as they're covered in greater detail in the documentation. However, we do want to discuss two parameters that you can use to control the behavior of stateful services: <session-timeout> and <scope> . Using the <session-timeout> tag, you can specify how long (in seconds) that the client state should be kept active. By default this option is set to 60 seconds, but you may wish to increase or decrease this as appropriate. The <scope> tag allows you to specify where state is kept. By default <scope> is set to a value of session the state information is user specific, and stored using the HTTP session capabilities of the Servlet container. Setting <scope> to a value of application will mean that state is stored globally, thereby making the same state available to all clients .

Using Stateless Session Beans

Many times you'll just want to expose functionality that has already been implemented in a stateless session EJB. In this case, you just implement the EJB as usual, and make sure that all of the methods you want to expose are included in the remote interface.

Tip	If the remote interface has more methods than you want to make available, then just create a second, more limited one and deploy the EJB a second time with the same home and implementation classes.

We won't build an EJB example here because there are plenty of EJB examples in Chapter 11. There are no special requirements for EJBs used in web services other than that they should be stateless session beans. Deploying an EJB-based web service requires you to add a <stateless-session-ejb-service> tag to your WSA configuration file, as follows :

 <stateless-session-ejb-service>    <uri>/HelloService</uri>    <ejb-name>HelloService</ejb-name> </stateless-session-ejb-service>

You should also ensure that the <option name="source-path"> tag points to the EJB JAR file.

Using WebServices Assembler

You can find the WebServicesAssembler.jar file in $ORACLE_HOME/webservices/lib . The basic syntax for running the WSA is

 java jar WebServicesAssembler.jar config /path/to/config

However, it's tiresome to have to keep running that command over and over, so we prefer to integrate the generation of the web service EAR file into the build process, using Ant. A simple Ant build script allows you to compile your Java code, create the web service EAR file, and deploy it to OC4J with a single command, as shown here:

 <project name="OC4J Services" default="deploy">     <property name="dir.java.src" value="src/java"/>     <property name="dir.web.src" value="src/web"/>     <property name="dir.app.src" value="src/app"/>     <property name="dir.build" value="bin"/>     <property name="dir.lib" value="lib"/>     <property name="j2ee.home" value="/opt/oc4j_extended/j2ee/home"/>     <property name="oc4j.home" value="/opt/oc4j_extended/"/>     <path id="project.classpath">         <fileset dir="${j2ee.home}/lib" includes="*.jar"/>         <fileset dir="${j2ee.home}" includes="*.jar"/>         <fileset dir="${dir.lib}" includes="*.jar"/>     </path>     <target name="clean">         <delete dir="${dir.build}"/>         <mkdir dir="${dir.build}"/>     </target>     <target name="compile" depends="clean">         <javac srcdir="${dir.java.src}" destdir="${dir.build}"             includes="**/*.java" classpathref="project.classpath"/>     </target>     <target name="ws" depends="compile">         <exec executable="java">             <arg line="-jar ${oc4j.home}/webservices/lib/WebServicesAssembler.jar   -config ${dir.web.src}/config.xml"/>         </exec>     </target>     <target name="deploy" depends="ws">         <echo message="Deploying..."/>         <!-- Deploy -->         <exec executable="java">             <arg line="-jar ${j2ee.home}/admin.jar ormi:// admin welcome   -deploy -file echows.ear -deploymentName echows"/>         </exec>         <echo message="Binding Web App..."/>         <!-- Bind Web App -->         <exec executable="java">             <arg line="-jar ${j2ee.home}/admin.jar ormi:// admin welcome   -bindWebApp echows echows_web http-web-site /ws/"/>         </exec>     </target> </project>

Now all you need to do is run ant deploy and the code will be compiled, the web service will be created, and the application will be deployed. Whichever way you choose to invoke WSA you'll end up with an EAR file containing your web-service application. Deploying this EAR file within Oracle 10g AS will make your web service available. Before moving on you should deploy the web service to your local Oracle 10g AS instance.