This document describes how to quickly and easily produce a simple Web service and to create consumer software for it using the Pluto command line resource, a SOCKET development tool. Once Pluto has been configured and the two required SOCKET Web 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.
Pluto 1.0 Beta-1 works only on a Linux/Unix platform. It has been tested on Fedora Linux. The full 1.0 release will contain a bat file for Windows operation. Note that the Saturn Web application offers identical functionality to that of Pluto, the only difference being the use of an HTML input form instead of the command line.
Java SDK 1.5.
The SOCKET Web applications have been tested on Tomcat 5.5 and the Sun Java System Application Server 8.1 (Platform Edition) and 9 (Glassfish).
SOCKET consumer web applications have been tested on the following browsers/platforms.
(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.)
This holds the consumer factory, the module that produces the consumer software bundled in a WAR file.
A command line client for the SOCKET engine.
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.
It is assumed that you already have the Tomcat server installed and running on your system.
socket-engine.war can be downloaded as a zip file from the SourceForge code repository (http://sourceforge.net/projects/socket) or from the downloads page on the SOCKET web site.
The Pluto executable and dependencies can be downloaded as a zip file from the SourceForge code repository (http://sourceforge.net/projects/socket) or from the downloads page on the SOCKET web site.
samples.war can be downloaded as a zip file from the downloads page on the SOCKET web site.
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.
Expand the socket-pluto zip file. You will see a pluto directory containing two sub-directories bin and lib.
There is one configuration task required. Go to the pluto.properties file in the bin directory. This contains the following line:
org.socketelf.pluto.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.pluto.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.
Using this simple method, every public method of a Java class will be converted to an operation of a Web service.
There are two important things to remember here.
1. There should be no package name in the Java file.
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.
SOCKET should ignore methods that have complex Java types.
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;
}
}
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/
The service is automatically created for you.
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.
The usage is as follows:
for example:
If the socketization process is successful you should be presented with a URL for the consumer.war.
Enter this URL in a browser location box. 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.
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.
To run the consumer software, browse to the following URL:
http://www.myserver.ac.uk/consumer/
The actual page being called is:
http://www.myserver.ac.uk/consumer/consumer/operation_list.html
(Note that one consumer in the path refers to the Web application context while the second is the name of the servlet.)
where www.myserver.ac.uk is the domain name of the server on which the consumer war has been loaded. Using autodeploy, you can change the name of the context by changing the name of the WAR file. Deployment using the administration console of the Sun Java System Application Server provides the option of specifying the context name.
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.
Here are some hints for troubleshooting when you are unable to use the SOCKET software to act as a client for the Web service.
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
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
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.
SOCKET, A JISC ELF Toolkit Project
b.p.clark@leeds.ac.uk, August 2006
Document last modified 23 September 2006