Chapter 9 .
Creating Web Services :
Web services promises to be the next generation of software development. In essence, a web service is a means of interfacing to web or enterprise applications that allows you to integrate these with other enterprise applications, including those from different vendors and different platforms, using XML as the means of exchanging data.
There is a great deal of hype about web services. In the past there have been a number of initiatives to provide such vendor-and-platform agnostic integration technology, but none of these has been totally succesful. A good example is that of getting an enterprise applicaction running on Windows to communicate with an enterprise application running on Unix. Sure, it's been possible by various means but typically with a mechanism which is not equally well supported by both environments. That has changed with the advent of web services SOAP and XML provide an integration glue that everyone can finally agree on.
The basic mechanism of Web services is to use XML to transport its across different applications using the standard Web HTTP protocol (Hyper Text Transfer Protocol ). Specifically SOAP (Simple Object Access Protocol) is used, which is a lightweight XML based RPC (Remote Procedure Call) over HTTP. The protocol has three parts :
An envelope (SOAP envelope) that defines a framework for describing what is in a message and how to process it.
A set of encoding rules for expressing instances of application defined-dataypes.
A set of rules for representing remote procedure calls and responses.
Web Services Standards :
Now lets go through some evolving standards used in in Web Services, which are SOAP, WSDL (Web Services Description Language), UDDI (Universal Description Discovery and Integration), ebXML which is promoted by OASIS (Organization for the Advancement of Structured Information Standards) and UN/CEFACT (United Nations Centre for Trade Facilitation and Electronic Business). We will cover only SOAP and WSDL in this tutorial.
WSDL (Web Services Description Language) describes the interface of a network service similar to IDL (Interface Definition Language) in CORBA (Common Object Request Broker Architecture), specifying what messages an endpoint (i.e. a service instance which processes client requests and returns responses) will receive and send. WSDL is itself an XML metadata format. (In the terms of similar mechanisms like RMI or CORBA, a service is the interface or set of methods that a client will invoke across the wire).
SOAP (Simple Object Access Protocol) as discussed earlier describes the format of the data that is transmitted over the wire.
Both these standards are still evolving under the eye of the W3C, but these standards are regarded as the building block of the next revolution in distributed computing and the IT industry in general. Web services promise to do for machine-to-machine communication what the Web has done for human-to-human and machine-to-human communication.
However, due to the evolving nature of the web services standards together with the various related tools and platforms, the full impact is still far from being realized.
Web Services In Java :
As discussed earlier, Web Services standards are still evolving and their support in Java is still evolving. Even though Web Services were initially promoted by Microsoft and IBM, with the release of J2EE 1.4 Sun has provided full support for Web Services.
In the J2EE environment Web services are built on JAX-RPC (Java API for XML-based RPC). This is an API for building Web services and clients that use remote procedure calls (RPC) and XML.
In JAX-RPC, a remote procedure call is represented by an XML-based protocol such as SOAP. The SOAP specification defines the envelope structure, encoding rules, and convention for representing remote procedure calls and responses. These calls and responses are transmitted as SOAP messages (XML files) over HTTP. Even though the SOAP messages are a bit complex, but this complexity is transparent to the developer. When developing client and server side implementations, developers don't have to generate SOAP messages these are generated by the JAX-RPC API calls.
On the server side, the developer specifies the remote procedures by defining methods in an interface written in the Java programming language. The developer also codes one or more classes that implement those methods. Client programs are also easy to code. A client creates a proxy, a local object representing the service, and then simply invokes methods on the proxy. With JAX-RPC, the developer does not generate or parse SOAP messages. It is the JAX-RPC runtime system that converts the API calls and responses to and from SOAP messages.
For this tutorial, we will use the Apache Axis library, which is an open source initiative of the Apache Software Foundation (ASF). Axis is a JAX-RPC compliant SOAP engine. It can be integrated with web containers like Tomcat/Jetty, which allows it to use the features of such web containers like security, resource pooling, multi-threading, etc.
Note: JAX-RPC is based on JSR-101, which took the first step in defining a standard set of Java APIs and a programming model for developing and deploying Web services on the Java platform. Apache Axis is JAX-RPC compliant.
Now another specification which is evolving is JSR-109. This builds upon JAX-RPC. It defines a standard mechanism for deploying a Web service in the J2EE environment, more specifically, in the area of Enterprise JavaBean (EJB) technology and servlet containers.
Both of these specifications will be integrated into the J2EE 1.4 specification. Together they serve as the basis of Web services for J2EE.
Jboss.3.2.x comes with integrated support for Web-services provided by Jboss.Net. Jboss.NET has Apache AXIS as a plugin service for the Jboss-Microkernel. Jboss.Net uses the built-in JBoss deployment system that understands the WSR packaging. [Web Service aRchive (WSR- or .wsr-) files are ordinary .jar files that contain, besides necessary byte code for plugging into the Axis machinery, a slightly extended Axis deployment descriptor in their "META-INF/web-service.xml" entry]. Currently, there are not that many application servers available which support WSR deployment, which can result in portability issues.
Therefore for this tutorial we will use Apache-AXIS 1.1 for creating and deploying web services.
Installing AXIS :
Download the Apache-Axis binary from http://ws.apache.org/axis/.
Ex : Version 1.1 Binary - tar.gz
First create a dir named axis under /opt and then save this file under /opt/axis/.
- [vishal@vishal axis]$ pwd
- /opt/axis
- [vishal@vishal axis]$ ls
- axis-1_1.tar.gz
Now unzip the file. A new directory will be created with the name axis-1_1.
- [vishal@vishal axis]$ tar -xvzf axis-1_1.tar.gz
- axis-1_1/
- axis-1_1/docs/
- axis-1_1/docs/ant/
- axis-1_1/docs/ant/ant.html
- axis-1_1/docs/ant/axis-admin.html
- -----------------------------------------------------
- ----------------------------------------------------
- ------------------------------------------------------
- axis-1_1/xmls/
- axis-1_1/xmls/checkstyle.xml
- axis-1_1/xmls/deploy_catalina_local.xml
- axis-1_1/xmls/path_refs.xml
- axis-1_1/xmls/properties.xml
- axis-1_1/xmls/targets.xml
- axis-1_1/xmls/taskdefs.xml
- axis-1_1/xmls/taskdefs_post_compile.xml.
- [vishal@vishal axis]$ ls
- axis-1_1 axis-1_1.tar.gz
- [vishal@vishal axis]$
The directory structure will be as shown below.
- [vishal@vishal axis]$ pwd
- /opt/axis
- [vishal@vishal axis]$ ls
- axis-1_1 axis-1_1.tar.gz
- [vishal@vishal axis]$ cd axis-1_1
- [vishal@vishal axis-1_1]$ ls
- docs lib LICENSE README release-notes.html samples webapps xmls
- [vishal@vishal axis-1_1]$ pwd
- /opt/axis/axis-1_1
- [vishal@vishal axis-1_1]$ cd lib/
- [vishal@vishal lib]$ ls
- axis-ant.jar commons-discovery.jar jaxrpc.jar saaj.jar
- axis.jar commons-logging.jar log4j-1.2.8.jar wsdl4j.jar
- [vishal@vishal lib]$
Now the axis binary is installed, let's configure it for use with our application server Jboss-3.2.1.
Configuring AXIS with JBOSS :
In order to configure Jboss with Axis, first go to $JBOSS_HOME/server/all/deploy/all/ as shown below.
- [vishal@vishal deploy]$ pwd
- /opt/jboss/jboss-3.2.1/server/all/deploy
- [vishal@vishal deploy]$
Create a dir named webapps under this directory as shown below.
- [vishal@vishal deploy]$ ls
- cache-invalidation-service.xml jbossweb-jetty.sar MyStoreMgr.jar
- cluster-service.xml jboss-xa-jdbc.rar OnlineStore.war
- farm-service.xml jms properties-service.xml
- hsqldb-ds.xml jmx-console.war schedule-manager-service.xml
- http-invoker.sar jmx-ejb-connector-server.sar scheduler-service.xml
- iiop-service.xml jmx-invoker-adaptor-server.sar sqlexception-service.xml
- jbossha-httpsession.sar jmx-rmi-adaptor.sar transaction-service.xml
- jboss-jca.sar mail-service.xml user-service.xml
- jboss-local-jdbc.rar management uuid-key-generator.sar
- jboss-net.sar MyFirstBean.jar
- jbossweb-ejb.jar MySecondBean.jar
- [vishal@vishal deploy]$ mkdir webapps
- [vishal@vishal deploy]$ ls
- cache-invalidation-service.xml jbossweb-jetty.sar MyStoreMgr.jar
- cluster-service.xml jboss-xa-jdbc.rar OnlineStore.war
- farm-service.xml jms properties-service.xml
- hsqldb-ds.xml jmx-console.war schedule-manager-service.xml
- http-invoker.sar jmx-ejb-connector-server.sar scheduler-service.xml
- iiop-service.xml jmx-invoker-adaptor-server.sar sqlexception-service.xml
- jbossha-httpsession.sar jmx-rmi-adaptor.sar transaction-service.xml
- jboss-jca.sar mail-service.xml user-service.xml
- jboss-local-jdbc.rar management uuid-key-generator.sar
- jboss-net.sar MyFirstBean.jar webapps
- jbossweb-ejb.jar MySecondBean.jar
- [vishal@vishal deploy]$
Now go to /opt/axis/axis-1_1/webapps dir. Copy the axis dir to $JBOSS_HOME/server/all/deploy/all/webapps/ as shown below.
Note : Here JBOSS_HOME is /opt/jboss/jboss-3.2.1
- [vishal@vishal webapps]$ pwd
- /opt/axis/axis-1_1/webapps
- [vishal@vishal webapps]$ ls
- axis
- [vishal@vishal webapps]$ cp -r axis /opt/jboss/jboss-3.2.1/server/all/deploy/webapps/.
- [vishal@vishal webapps]$
Now go back to the $JBOSS_HOME/server/all/deploy/webapps/ dir and rename the axis directory to axis.war.
- [vishal@vishal webapps]$ pwd
- /opt/jboss/jboss-3.2.1/server/all/deploy/webapps
- [vishal@vishal webapps]$ ls
- axis
- [vishal@vishal webapps]$ mv axis axis.war
- [vishal@vishal webapps]$ ls
- axis.war
- [vishal@vishal webapps]$
Note : As shown above, the directory axis has been renamed to axis.war so that JBOSS can recognize this as a web application and hence the web container can deploy it at run-time.
Now from within Eclipse start your Application server (JBOSS) , if it isn't already running. If it is already running then don't restart it as it will hot-deploy the the axis.war.
Also make sure all the libraries which come with AXIS are on the classpath ($CLASSPATH or $AXISCLASSPATH) as shown below.
- [vishal@vishal lib]$ pwd
- /opt/jboss/jboss-3.2.1/server/all/deploy/webapps/axis.war/WEB-INF/lib
- [vishal@vishal lib]$ ls
- axis-ant.jar commons-discovery.jar jaxrpc.jar saaj.jar
- axis.jar commons-logging.jar log4j-1.2.8.jar wsdl4j.jar
- [vishal@vishal lib]$ echo $AXISCLASSPATH
- /opt/axis/axis-1_1/lib/axis.jar:/opt/axis/axis-1_1/lib/jaxrpc.jar:/opt/axis/axis-1_1/lib/saaj.jar:/opt/axis/axis-1_1/lib/wsdl4j.jar:/opt/axis/axis-1_1/lib/commons-discovery.jar:/opt/axis/axis-1_1/lib/commons-logging.jar:.
- [vishal@vishal lib]$
Now to test your configuration go to http://127.0.0.1:8080/axis/.
Note : The port no. will be different if you have customized it from its default settings.
You should now be able to see an Apache-Axis start page as shown below. If you do not, then either the webapp is not actually installed properly, or the appserver is not running.
Now Validate the local installation's configuration by clicking on the link 'Validate the local installation's configuration'.
This will bring you to happyaxis.jsp, a test page that verifies whether required and optional libraries are present. The URL for this will be something like http://localhost:8080/axis/happyaxis.jsp as shown below in figure.
If any of the needed libraries are missing, Axis will not work.
Note : Make sure that all the needed libraries are found, and this validation page is happy.
Optional components are indeed optional; install them as you require. If you see nothing but an internal server error and an exception trace, then you probably have multiple XML parsers on the CLASSPATH (or AXISCLASSPATH), and this is causing version confusion.
Now go back to your Apache AXIS start page and select the list of already deployed Web services. By clicking on 'View the list of deployed Web services'.
Note : There are a few web services which come with Apache-AXIS bundle to assist us with our learning curve.
In order to make sure that your Web Service is up and running, click on each WSDL (Web Service Description Language) as shown above in figure. Example : If we click on AdminService (WSDL) then the following screen will be available as shown below.
Before we write our first Web Service, let's test one of the working example services which is already deployed as part of the Apache bundle.
Note : For more information look at the documentation for Apache-AXIS under 'Installing and deploying web applications using xml-axis' at http://ws.apache.org/axis/.
Now, SOAP 1.1 uses HTTP POST to submit an XML request to the endpoint, but Axis also supports a HTTP GET access mechanism, which is very useful for useful for testing. So to test the service, let's retrieve the version of Axis from the version endpoint, by calling the getVersion method:
http://localhost:8080/axis/services/Version?method=getVersion
This will result in the screen shown below.
After successfully testing the Web Service, let's write our own first Web Service by extending our tutorial application MyStore.
We will create a web service named MyStoreLoginService, which will allow the user to login to MyStore using a Java Client, but using Web service (HTTP) rather then RMI, which is normally the case when we use servlets/JSP or a Java Client. StoreAccessBean will be acting as our endpoint.
Note : Lomboz-2.1_02 witth Eclipse 2.1 and Lomboz 2.1.1 with Eclipse 2.1.1 doesn't have a wizard to create a webservice (that is Web Service Deployment Descriptor [WSDD]) and deploy it. So we will have to do it by hand. Both versions of Lomboz do provide a wizard for creating a SOAP Client.
Create the Web Service :
In order to create a Web Service we need to create an endpoint. In this case, our Stateless Bean StoreAccessBean will be acting as an endpoint. Method loginUser will be invoked from the client side using this Web Service, so we have to create a Web Service Deployment Descriptor (WSDD) file describing the signature of the loginUser method along with some other required information.
Note : Currently, only a Stateless Bean can be used as an endpoint for a Web Service as specified in JSR-109.
WSDD is an AXIS specific file, used to create a skeleton for JAX-RPC. This is transparent to the developer, and once this skeleton is created and deployed, AXIS generates WSDL and publishes the Web-Service.
For more information : http://ws.apache.org/axis/.
Now, under Eclipse, go to Package Explorer > Expand Mystore (project) node > select src, right click and a menu will pop up.
On the pop up menu > New > Select Package > Add name of package as 'au.com.tusc.WebService' .
Press Finish.
This will create a new package named au.com.tusc.WebService under 'src'.
Go to src/au.com.tusc.WebService > Select New > File as shown below.
Now create a file named deploy.wsdd under the package au.com.tusc.WebService as shown below.
Add the following XML tags as shown below in the deploy.wsdd file, and then we will examine the contents of the file..
Lets analyze these deployment descriptors.
<service name="MyStoreLoginService" provider="java:EJB"> | 
