Puakma Web Services: Getting started

Web services is an emerging technology which enables services on a remote computer to be accessed by a client. In the past this has been achieved through DCOM, CORBA and RMI (to name the most popular technologies). In the last couple of years, with the advent of XML, XML and HTTP have been used together to perform this function, in a new technology called SOAP (Simple Object Access Protocol). The main advantage of SOAP is that it is platform neutral, HTTP is a common transport system used for requesting and posting pieces of data across the Internet. When combined with XML, that adds a platform neutral way of representing the objects and requests. SOAP may also work with SMTP mail, or any transport method for that matter. Puakma currently supports only HTTP.

Puakma web services require no knowledge of SOAP. This may well be the easiest SOAP implementation on the planet.

Puakma web services require two tasks to be loaded on the server. WIDGIE and HTTP. All connections are made to the HTTP server and the request data is passed by the internal message passing interface to the Business Widget Server (WIDGIE). WIDGIE then completes the request and passes the data back to the HTTP server to be streamed to the client. Download a simple widget here.

To set up the web service, two components need to be constructed, the client and the service. Creating both is very easy and all can be set up in seconds.

Writing your first web service is a snap. If you have written a Puakma action before, then a web service is just as easy. All you need is a simple class that extends the BusinessWidget class, then all methods you make public are automatically exposed as methods within your web service.

import puakma.system.*;
import puakma.addin.widgie.*;
import puakma.addin.http.action.*;
import java.util.*;

/**
* A simple web service
* */

public class SimpleWidget extends BusinessWidget
{

protected boolean init()
{
//any specific init routines
//called when the widget is initially started
m_pSystem.doInformation( "Initialised", this);
return true;
}

protected boolean requestQuit()
{
//called when this widget is requested to stop
return true;
}

public String helloWorld()
{
return "Hello World";
}

}

Compile the above code and save it under the "Business Widget" section of your application (using the Puakma web design application). In a few seconds you should see the class automatically loaded by WIDGIE, making it available for access by clients. Really, that’s it, no more to do on the server side!

There are a few URLs which are useful for accessing the web services:

http://your.server/your/app.pma?WidgetList

This command will list all the services available in this application. If you wish to return a list of all services available on the server, you can easily write your own Action code to perform this task.

http://your.server/your/app.pma/BusinessWidgetName?WidgetWSDL

This allows non-Puakma client to see the WSDL required to create a client web service for accessing the named service. Note, programmers may look at this to see the Java method declarations, which often make much more sense to humans than the reams of XML code.

http://your.server/your/app.pma/BusinessWidgetName?WidgetExecute

This is the URL you need to POST to, to execute the web service. Puakma does not support "GETs" for accessing web services, because a HTTP GET does not pass enough information to allow the full use of these services. You may, however, write some Action code which calls the service internally.

On the client side, life has never been easier. You can call the web service in two lines of code. You may also use the Puakma SOAP client software to access services on other non-Puakma servers. To access the above Business Widget service:

SOAPClient sc = new SOAPClient("http://your.server/your/app.pma/SimpleWidget?WidgetExecute", "helloWorld");

try
{
String sReturn = (String)sc.execute();
System.out.println("SOAP REPLY: " + sReturn);
}
catch(Exception e)
{
System.out.println("SOAP ERROR: " + e.toString());
}

The execute method returns the same object that the remote method returned, so can be easily cast as that type, for example:

byte[] buf = (byte[])sc.execute();

Puakma supports all the major primitive data types and multidimensional arrays of those types.

Puakma does not support complex types (eg: a "person" object). After careful investigation, it was decided that complex objects should not be represented by SOAP. To mimic this functionality, pass an XML string parameter to your methods, and have the methods reply with another XML string.

The use of Puakma web services in a production setting requires the purchase of a Puakma Enterprise license.

Recent Comments

Got something to say? Add comment