SOCKET Quick and Simple

This document describes how to quickly and easily produce a simple Web service and to create consumer software for it using the Saturn web application, a SOCKET development tool. Once the three required SOCKET applications have been loaded into a servlet container, all that is required is a Java source file that contains one or more public methods. These public methods will be converted into Web service operations. An example is given below.

2. Requirements

2.1 Platform

SOCKET Saturn has been tested on Windows XP, Fedora Linux (Kernel 2.6.10) and Red Hat Enterprise 3 and 4

2.2 Java

2.3 Application Server

SOCKET has been tested on Tomcat 5.5 and the Sun Java System Application Server 8.1 (Platform Edition) and 9 (Glassfish).

2.4 Browser

SOCKET consumer web applications have been tested on the following browsers/platforms.

2.4.1. Internet Explorer 6.5 on Windows XP Professional.

2.4.2 Mozilla Firefox 1.0.7 on Windows XP Professional.

2.4.3. Opera 7.23 on Windows XP Professional.

(Straight out of the box, however, XML files are not displayed, so that the contents of the WSDL file are not rendered in Section 7 below.)

2.4.4. Safari on Mac OSX 10.4.7.

2.5 SOCKET software

2.5.1 SOCKET engine.

This holds the consumer factory, the module that produces the consumer software.

2.5.2 SOCKET Saturn

A Web application client for the SOCKET engine that converts a WSDL document to Web service consumer software.

2.5.3 SOCKET Samples application

This contains the Axis Web services toolkit, and over 30 simple test Web services whose requests and responses are composed solely of simple datatypes and arrays thereof.

3. How to Obtain the Software

3.1 Tomcat

It is assumed that you already have the Tomcat server installed and running on your system.

3.2 SOCKET engine

3.3 SOCKET Saturn

3.4 Samples application

4. How to install the software

The following assumes that the autodeploy function is enabled on Tomcat, ie a Web application placed into the webapp directory will deploy automatically. This is the default behaviour.

Drop the socket-engine.war into the webapps directory of a running Tomcat server. Alternatively, use the management application to deploy the WAR.

Drop the socket-saturn.war file into the webapps directory of a running Tomcat installation. Alternatively, use the management application to load the application.

There is one configuration task required. Go to the WEB-INF directory of the socket-saturn application where you will find the saturn.properties file. This contains one line:

org.socketelf.saturn.engine-location=http://socket.leeds.ac.uk/socket-engine/engine/http

All that is required here is to change the hostname to that on which you have installed the SOCKET engine. For example:

org.socketelf.saturn.engine-location=http://www.myserver.ac.uk/socket-engine/engine/http

Drop the samples.war file into the webapps directory of a running Tomcat installation.

http://www.myserver.ac.uk/socket-saturn/

5. Create a Java class to convert to service

Using this simple method, every public method of a Java class will be converted to an operation of a Web service.

2. For 1.0-Beta, only simple Java types should be used for input parameters: this includes any Java primitive type or wrapped primitive, Strings, QNames or Calendar objects.

Here is an example of a Java class that will produce a service with two operations. One will echo back an entered String and the other will echo a byte.

Create a file SocketService.jws (NOTE: the jws extension, not java) with the following content:

public class SocketService
{
    public byte echoByte(byte b)
    {
        return b;
    }

    public String echoString(String s) 
    {
        return s;
    }
}

6. Create the Web service

To create the Web service that the SOCKET consumer software will talk to, drop the SocketService.jws file into the following directory on the server running the samples WAR.

http://www.myserver.ac.uk/samples/ws/

7. Obtain the WSDL document

To obtain the WSDL document associated with the service that you have just created, navigate to the following URL:

http://www.myserver.ac.uk/samples/ws/SocketService.jws?wsdl

The WSDL document should now appear in your browser. Ignore it. What you need is the URL: select it, right-click and copy it.

8. Use Saturn to obtain consumer.war

http://www.myserver.ac.uk/socket-saturn/

If the socketization process is successful you should be presented with a download link for the consumer.war.

Depending on your browser settings, you may be offered the download of a file consumer.zip. Change the name of this to consumer.war either before or on completion of the download.

9. Run consumer application

Now drop the consumer.war file into the webapps directory of a running Tomcat server. This does not have to be the same server on which the samples or socket-engine application is loaded.

http://www.myserver.ac.uk/consumer/

where www.myserver.ac.uk is the domain name of the server on which the consumer war has been loaded.

(This is assuming the default behaviour that the context name has been set as the name of the WAR file. If you have loaded the application with a different context name then swap this for consumer in the URL above.)

You should now see a web page with hyperlinks to a data input page for each of the public methods in the Java source file. SOCKET refers to these as operations.

10. Troubleshooting

Here are some hints for troubleshooting when you are unable to use the SOCKET software to act as a client for the Web service.

Java error

If you see the following error message when trying to access the WSDL document for your service then your class has generated a compiler error. Check the Java syntax.

AXIS error
  Sorry, something seems to have gone wrong... here are the details:
  Fault - Error while compiling: /root/socket/dev-servers/apache-tomcat-5.5.16/webapps/
  samples/WEB-INF/jwsClasses/ws/SocketService.java
  AxisFault
  faultCode: {http://xml.apache.org/axis/}Server.compileError
  faultSubcode:
  faultString: Error while compiling: /root/socket/dev-servers/apache-tomcat-5.5.16/webapps/
  samples/WEB-INF/jwsClasses/ws/SocketService.java
  faultActor:
  faultNode:
  faultDetail:
  {}Errors:Error compiling /root/socket/dev-servers/apache-tomcat-5.5.16/webapps/samples/
  WEB-INF/jwsClasses/ws/SocketService.java:
  Line 3, column 7: 'class' or 'interface' expected
  Line 0, column 0:
  1 error

Service not found

If you get a message while looking for your WSDL file to the effect that your Web service cannot be found, check that you have not included a package name in the SocketService.jws file

SocketProjectException

SOCKET uses the URL of the WSDL to form a unique qualified name for the Web service. The Beta-1 version of the engine failed when the URL contained dashes or an IP address. This was fixed in Beta-2.

Another reason for a SOCKET project exception is that the stub classes produced by Axis cannot be processed because they have data types that are too complex.

Quick & SImple Consumers with Saturn

1. Introduction