Let’s build a simple service with GLUE to show you how it’s done. Later, we’ll build a client that can access this service also with GLUE. For our example, we’ll make a service that has two methods. The first will take a temperature sent to it in degrees F and return the equivalent temperature in degrees C. The second method will perform the opposite conversion. The code for our simple service can be seen in Listing 19.1.

public class TempConverter
{
    public double CtoF(double degreesC)
    {
      System.out.println("finding the F equivalent for "
         +degreesC+" degrees C");
      return (9.0/5.0)*degreesC+32.0;
    }

    public double FtoC(double degreesF)
    {
       System.out.println("finding the C equivalent for "
          +degreesF+" degrees F");
       return (degreesF-32.0)*(5.0/9.0);
    }
}

As you can see from the code, there is nothing specific to GLUE or Web services added to the code. It looks like any other Java class you might write to perform this function.

In order for GLUE to turn the TempConverter class into a Web service, it is necessary to write a small wrapper program. This wrapper program will register the class with the server and assign it a specific service name. The code for the wrapper can be found in Listing 19.2.

import electric.registry.Registry;
import electric.server.http.HTTP;

public class TempConverterService
{
   public static void main(String[] args) throws Exception
   {
     HTTP.startup("http://localhost:8888/glue");
     Registry.publish("urn:TempConverter"
        , new TempConverter());
   }
}

In this file, we first import a pair of support classes provided by GLUE: Registry and HTTP. We then create a Java class that contains a main() method, so we can run it as a program. That main method establishes an HTTP connection to the GLUE server, and then instructs the GLUE service registry to create a new entry for TempConverter and instantiates a copy of TempConverter for use.

If you downloaded the code from the Web site, you will find these two java files in the webservice24hoursch19glueservice directory. You can compile both of these files by typing the following command:

javac *.java

Provided everything is installed and configured correctly, you should receive no compile errors. Start the service up by typing:

java TempConverterService

You should see the following output:

[STARTUP] GLUE standard 4.0b2 © 2001-2003 The Mind Electric
[STARTUP] soap/http server started on http://thismachinesIPaddress>:8888/glue

That’s all there is to it. You now have a service running on GLUE ready to handle requests.

Now that you have a service running on GLUE, let’s access it with a client written using GLUE. As normal, the first part of writing a client is to access the service’s WSDL to determine the call structure. GLUE provides an excellent tool called wsdl2java that will take a WSDL and build the needed interface and helper classes for you.

If you downloaded the code from Sams’ Web site, you should find a directory named webservice24hoursch19glueclient. Open a new command-line window and CD to that directory. Then type the following command to generate the interface classes using wsdl2java:

wsdl2java http://localhost:8888/glue/urn:TempConverter.wsdl

You should get back the following output:

[STARTUP] GLUE standard 4.0b2 © 2001-2003 The Mind Electric
write file ITempConverter.java
write file TempConverterHelper.java

If you perform a DIR command, you will see that two new java files were created corresponding to the ones named in the output from the wsdl2java command you ran. Let’s briefly examine those files. ITempConverter.java can be seen in Listing 19.3 and TempConverterHelper.java is shown in Listing 19.4.

// generated by GLUE standard 4.0b2 (wsdl2java) on
// Sun Feb 02 15:35:44 EST 2003
public interface ITempConverter
  {
  double CtoF( double arg0 );
  double FtoC( double arg0 );
  }

// generated by GLUE standard 4.0b2 (wsdl2java)
//on Sun Feb 02 15:35:44 EST 2003
import electric.registry.Registry;
import electric.registry.RegistryException;

public class TempConverterHelper
{
  public static ITempConverter bind()
       throws RegistryException
  {
    return bind("http://localhost:8888/glue/urn:TempConverter.wsdl");
  }

  public static ITempConverter bind(String url)
       throws RegistryException
  {
    return (ITempConverter) Registry.bind(url,ITempConverter.class);
  }
}

As you can see from Listing 19.3, ITempConverter is a simple interface that lists the two methods found in our service. That’s all it does!

In Listing 19.4, you see the code for TempConverterHelper. This class is responsible for performing the actual binding of the method calls from our client to the service. You’ll notice that two versions of the bind method are given. The first takes no parameters and will create a binding to the exact service location that we provided during the wsdl2java tool invocation. The other is a more generic version that allows us to specify a different service URL. This can be helpful when you build both your client and service on one machine, and then deploy them on different machines because you can then specify their new addresses.

Now that we have the support classes created, let’s go ahead and build a client to call them. We have provided a simple client in the webservice24hoursch19glueclient directory called TempClient.java. The code for this file can be found in Listing 19.5.

import electric.registry.Registry;

public class TempClient
{
   public static void main(String[] args) throws Exception
   {
      if(args.length<2)
      {
         System.out.println("You must give temp and scale.");
         System.out.println("For instance: 21 F");
         System.exit(-1);
      }

      if(!(args[1].equals("C") || args[1].equals("F")))
      {
         System.out.println("Incorrect Temperature Scale.");
         System.out.println(" You must specify either 'F' or 'C'");
         System.exit(-1);
      }
      ITempConverter tempconverter = TempConverterHelper.bind();
      String temp_as_string = args[0];
      double starttemp = (new Double(temp_as_string)).doubleValue();
      double endtemp;
      if(args[1].equals("F"))
      {
         endtemp = tempconverter.FtoC(starttemp);
         System.out.println("The equivalent temperature is: "+endtemp
            +" degrees C");
      }
      else if(args[1].equals("C"))
      {
         endtemp = tempconverter.CtoF(starttemp);
         System.out.println("The equivalent temperature is: "+endtemp
            +" degrees F");
      }
   }
}

Only part of this program is any different than it would be if the TempConverter class was local—the line where we instantiate the class. Instead of creating an instance of the TempConverter, we create an ITempConverter reference and link it to an object that the TempConverterHelper class gives us after binding to the remote service. Then we call and use this reference as though it were a normal local object.

To run our client, first double-check that you have the service up and running in another window. Then, in this window, type the following:

java TempClient 100 C

You should get the following output:

The equivalent temperature is: 212.0 degrees F

In the service window, you should see output such as this:

Finding the F equivalent for 100.0 degrees C

That’s all there is to it. GLUE takes care of all the heavy lifting. This is one of the reasons that it has become so popular in the Java developer community. There is a lot more to GLUE than what we’ve shown here though. The Mind Electric provides excellent documentation on its product, and a number of good references are on the Web that can show you how to build more complex systems using GLUE. If you’re planning to do a Java-based Web services project, GLUE is an excellent choice and is highly recommended.

Because PocketSOAP is meant for client-side development only, we’ll build our example client to communicate with a service found on the www.xmethods.com Web services directory site. In this case, we’ll write a client to interface with the Weather-Temperature service found on the site. Weather-Temperature takes a U.S. ZIP Code and returns the current temperature to the client.

PocketSOAP allows the developer to write client code in a number of languages. In this case, we’ll use VBScript because it is built in and readily available on all Windows-based machines.

In order to write our client, we’ll need to first examine the methods that the Weather-Temperature service understands. To do this, open your browser and point it to http://www.xmethods.net. Scroll to the bottom of the page. Near the bottom is the link for Weather-Temperature. Clicking on the link opens up some initial details about the service. The first point of interest on this page is the endpoint value. We’ll need this for our code, so remember where you see it.

In the yellow block near the top of the screen is a link named Analyze WSDL. Click that link to get the WSDL analysis page provided by xmethods. This new page tells us the name of the service, the number of methods it supports, the call style, the transport protocol it uses, and the endpoint information again.

Click on the link that says 1 Operation. At this point, a new screen will appear listing the methods this service supports, the SOAP Action (in this case, none), the call style (in this case, RPC), and the input and output messages. If you click on the links for Input or Output message, you’ll see the list of parameters that this method expects, their types, and so on.

From the information in the screens we just viewed, we can conclude that a service with an endpoint at http://services.xmethods.net:80/soap/servlet/rpcrouter responds to a single method call named getTemp, which takes a single String parameter for the ZIP Code and returns a float for the temperature. You’ll note that we could also have gotten all this information by examining the WSDL file. (There’s a link for it on the main page for this service.) This method is just a bit easier for us humans.

Now that we have the specifics we need to call the service, let’s write our client. We’ll make it take a single parameter at the command line that contains the ZIP Code of the area in the United States that we want to get the temperature of. It will then build up the SOAP call, make the communication with the service, and get back the results. The results will be displayed in a small pop-up dialog box on our screen. Listing 19.6 shows the code for our example client.

' get the command line parameter
dim objArgs
set objArgs = WScript.Arguments

' Create a new envelope object,
'this is the core part of any pocketSOAP usage.
dim env
set env = CreateObject("pocketSOAP.Envelope.2")

' set the methodName and methodname Namespace values
env.SetMethod "getTemp", "urn:xmethods-Temperature"

' create the parameter, pass along the zip code the user types
' at the command line.
env.Parameters.Create "zipcode", objArgs(0)

' now, we need to send the SOAP request to the
' endpoint, so we create a transport object
dim http
set http = CreateObject("pocketSOAP.HTTPTransport.2")

' we need to set the SOAPAction header
http.SOAPAction = ""
' now we send the request, the call to env.serialize,
' takes the envelope object we've been working with
' and serializes it out to the SOAP/XML format for sending.
strLoc = "http://services.xmethods.net:80/soap/servlet/rpcrouter"
http.Send strLoc, env.serialize

' now, we need to parse the SOAP message we get as a response
env.parse http

' and now, extract the return value
wscript.echo "Temp for "&objArgs(0)&"="&env.Parameters.Item(0).Value

Let’s examine the code of our client and see how the PocketSOAP system comes into play. In the first three lines, we do some setup to retrieve the ZIP Code as a command-line parameter to be passed in at runtime.

Next, we’ll set up the SOAP envelope object:

dim env
set env = CreateObject("pocketSOAP.Envelope.2")

Then, we’ll tell it what method we’re calling and from which service:

env.SetMethod "getTemp", "urn:xmethods-Temperature"

In this next step, we’ll pass in the parameters for the getTemp method. In this case, we’re going to pass in the "zipcode", which is stored in objArgs(0):

env.Parameters.Create "zipcode", objArgs(0)

Okay, now that the envelope for our request is all built, we’ll need to set up the transport object. We’ll do that with the next two lines of code:

Dim http
Set http = CreateObject("pocketSOAP.HTTPTransport.2")

No SOAP action is required for this method, so we’ll tell the transport not to use anything for it:

http.SOAPACtion = ""

At this point, all the setup work is finished. Now, we can make the actual call out to the service. We do that with these lines:

StrLoc = "http://services.xmethods.net:80/soap/servlet/rpcrouter"
http.Send strLoc, env.serialize

Next, we need to parse out the response. We can reuse the envelope object by using it to store the data returned by the http.Send command that we just executed. We’ll need to tell the envelope to parse the data that http returns to it. We do that here:

env.parse http

Now that we have the results, we report them back to the user:

Wscript.echo "Temp for "&objArgs(0)&"="&env.Parameters.Item(0).Value

As you can see, we requested the results of the service call by getting the first item’s value out of the envelope.

To run our new client, open a command prompt, navigate to the directory that you have the code in, and then type the following:

TemperatureClient.vbs 30096

You can replace the 30096 with any valid U.S. ZIP Code. The remote service will be called, and you should get back a prompt similar the one in Figure 19.1, but with a different temperature depending on current weather conditions.

Figure 19.1. Results of the TemperatureClient VBScript program, utilizing the Weather-Temperature service on xmethods.net.

As you can see, the process of using PocketSOAP is quite simple and easy to understand. Although we have demonstrated using only the PocketSOAP package to build your client and having to get the needed information manually, it is possible to automate some of this by making use of the WSDL Wizard and other tools found on the PocketSoap Web site. Regardless, the limited work involved in building Web service clients using PocketSOAP and its wide range of language support and features should make it quite useful to anyone looking to quickly prototype a Web service client.

In order to demonstrate the SOAP::Lite system, we’ll once again use our Temperature Conversion example. We’ll write a service using SOAP::Lite that will convert temperatures in degrees Celsius to degrees Fahrenheit and vice versa.

In Listing 19.7, you can see how easy it is to write the Perl SOAP::Lite-based service.

#!perl -w
use SOAP::Transport::HTTP;
SOAP::Transport::HTTP::CGI
  -> dispatch_to('TemperatureConverters')
  -> handle;
package TemperatureConverters;
sub c2f
{
    my ($class, $degreesc) = @_;
    return 32+($degreesc*9/5);
}
sub f2c
{
    my ($class, $degreesf) = @_;
    return (5/9)*($degreesf-32);
}

This Perl code looks very similar to virtually any other Perl model except for the first couple of lines. Just to be sure that we understand what’s happening, let’s walk through the code line by line.

#!perl -w

This line tells the computer what to do with this code. Here, we’re indicating that this is Perl code and to use the Perl runtime interpreter to execute it.

use SOAP::Transport::HTTP;

Here, we’re indicating what transport mechanism to use for the SOAP communications. In this case, we’re indicating HTTP. We could have chosen Jabber or any number of others supported by SOAP::Lite.

SOAP::Transport::HTTP::CGI
    ->dispatch_to('TemperatureConverters')
    ->handle;

Here is where we set up the linkage between the Web server’s CGI engine and the SOAP::Lite engine. We’re telling SOAP::Lite to accept calls to the CGI via HTTP and route them to the TemperatureConverters package. It will be the one responsible for returning the results.

package TemperatureConverters;

Here we’re declaring the package that our functions will be referenced by.

The rest of the code simply builds the two conversion functions—one for converting Celsius to Fahrenheit and the other to go in the opposite direction.

To deploy this service, simply place the file into the IIS default Web server’s cgi-bin subdirectory with the name TempConverterService.pl.

Much as you saw that building services using SOAP::Lite was easy, so to is it relatively simple to write clients using the SOAP::Lite tools. Here we’ll examine how to write a client to use our new SOAP::Lite service. The code for our client can be seen in Listing 19.8.

#!perl -w
use SOAP::Lite;

my $soap = SOAP::Lite
  -> uri('http://127.0.0.1/TemperatureConverters')
  -> proxy('http://127.0.0.1/cgi-bin/TempConverterService.pl'),
print "Enter the temperature you wish to convert";
print "
";
print "for example: 100.0";
print "
";
$temp = <STDIN>;
print "
Enter the scale to convert FROM (either C or F)
";
$scale = <STDIN>;

if($scale =~"C")
{
   print $soap
     -> c2f($temp)
     -> result;
   print " degrees F";
}
elsif($scale =~ "F")
{
   print $soap
     -> f2c($temp)
     -> result;
   print" degrees C";
}
else
{
   print "You must enter a valid scale. Either C or F";
}

Let’s examine this code as we did with the service. First, we start out with the usual declaration telling the system what to do with the file:

#!perl -w

We then tell the Perl runtime engine that we want to make use of the SOAP::Lite service module and that we want to link this code to the TemperatureConvertors module found in the TempConvertorService.pl file. This sets up the call binding for us to make use of the functions found in the service:

use SOAP::Lite;

my $soap = SOAP::Lite
  -> uri('http://127.0.0.1/TemperatureConverters')
  -> proxy('http://127.0.0.1/cgi-bin/TempConverterService.pl'),

In the remaining code, we request some input from the user, both the temperature and then the scale that the users are converting from. Depending on which scale the user tells us he is converting from, we pick the correct function of the service and call it. We take the results and display them back out to the user.

Now that we have the code for our client, let’s try it out. Type the following command:

perl TempConverterClient.pl

You should see the following prompt:

Enter the temperature you wish to convert
for example: 100.0

Enter a value, say 212 (the boiling point of water in degrees F) and press the Enter key. You’ll next be prompted to enter the scale you’re converting from as seen here:

Enter the scale to convert FROM (either C or F)

In this case, type in the letter F and press Enter. You should get back the following results:

100 degrees C

That’s all there is to it. Try the program a few more times, entering different values for the temperature and the scale, and see what happens.

As you can see, there isn’t much involved in terms of creating the binding to the remote service. This really is the only difference between calling the remote functions and what would be needed for calling local ones. That’s why SOAP::Lite has the word lite in its name!

Note

Although the view of SOAP::Lite that we have shown is very basic, it should be enough to get you started. Much like the other tools we’ve examined in this hour, a good support group can be found on the Yahoo! Groups system at http://groups.yahoo.com/group/soaplite/.