Reviews : Java Books : Java and SOAP :

Now let's write a client application that accesses the service. This application is similar to some of the examples from the previous chapter; it differs only in that the parameter we're passing is an array of String instances, rather than a single object. Here is the code:

package javasoap.book.ch5;
import java.net.*;
import java.util.*;
import org.apache.soap.*;
import org.apache.soap.rpc.*;
public class VolumeClient {
   public static void main(String[] args) throws Exception {
      
      URL url = new URL("http://georgetown:8080/soap/servlet/rpcrouter");
    
      Call call = new Call(  );
      call.setTargetObjectURI("urn:BasicTradingService");
      
      call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC);
      String[] stocks = { "MINDSTRM", "MSFT", "SUN" };
      Vector params = new Vector(  );
      params.addElement(new Parameter("stocks", 
                            String[].class, stocks, null));
      call.setParams(params);
      
      try {
         call.setMethodName("getTotalVolume");
         Response resp = call.invoke(url, "");
         Parameter ret = resp.getReturnValue(  );
         Object value = ret.getValue(  );
         System.out.println("Total Volume is " + value);
      }
      catch (SOAPException e) {
         System.err.println("Caught SOAPException (" +
                         e.getFaultCode(  ) + "): " +
                         e.getMessage(  ));
      }
   }
}

We passed String[].class as the second parameter of the Parameter constructor. That identifies the stocks variable as an array of strings. That's it. Nothing else is required. If you run this example, the output should be:

Total Volume is 345000

Let's take a look at the SOAP envelope that was passed to the server for the invocation of the getTotalVolume service method:

<SOAP-ENV:Envelope 
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"   
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 
  <SOAP-ENV:Body>
    <ns1:getTotalVolume xmlns:ns1="urn:BasicTradingService" 
      SOAP-ENV:encodingStyle=
           "http://schemas.xmlsoap.org/soap/encoding/">
       <stocks  
         xmlns:ns2="http://schemas.xmlsoap.org/soap/encoding/"  
         xsi:type="ns2:Array" 
         ns2:arrayType="xsd:string[3]">
            <item xsi:type="xsd:string">MINDSTRM</item>
            <item xsi:type="xsd:string">MSFT</item>
            <item xsi:type="xsd:string">SUN</item>
       </stocks>
    </ns1:getTotalVolume>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The stocks element represents the string array parameter that we passed to the service method. It is typed as an array by setting the xsi:type attribute to ns2:Array. The ns2 namespace identifier was defined on the previous line. Next, the ns2:arrayType attribute is assigned a value of xsd:string[3]. This means that this is an array of size 3, and that each element of the array is an xsd:string. There are three child elements of stocks, each one named item. Remember that the name used for the array elements doesn't matter, and that different SOAP implementations use different schemes for naming these elements. Each element is explicitly typed by setting the xsi:type attribute to the value xsd:string.

This example uses a homogeneous array, i.e., all of the elements of the array are instances of the same type. You may have occasion to use heterogeneous arrays as well, so let's look at that possibility. In Java, arrays are often used as parameters to methods that, in other languages, would have a variable-length parameter list. For instance, the printf( ) function in the C language doesn't have a fixed number of parameters. Even though Java doesn't support this capability, you can simulate it by passing your parameter values in an array. An array can be of any size, and the array elements aren't required to have the same type.

Let's add a method to the urn:BasicTradingService that takes a single heterogeneous array as a parameter. The method is called executeTrade. Its parameter is an array containing the stock symbol, the number of shares to trade, and a flag indicating whether it's a buy or sell order (true means buy). The return value is a string that describes the trade.[1] Here is the modified BasicTradingService class:

package javasoap.book.ch5;
public class BasicTradingService {
   
   public BasicTradingService(  ) {
   }
   public int getTotalVolume(String[] stocks) {
      
      // get the volumes for each stock from some
      // data feed and return the total
      
      int total = 345000; 
      return total;
   }
   public String executeTrade(Object[] params) {
      String result;
      try {
         String stock = (String)params[0];
         Integer numShares = (Integer)params[1];
         Boolean buy = (Boolean)params[2];
         String orderType = "Buy";
         if (false == buy.booleanValue(  )) {
            orderType = "Sell";
         }
         result = (orderType + " " + numShares + " of " + stock);
      }
      catch (ClassCastException e) {
         result = "Bad Parameter Type Encountered";
      }
      return result;
   }
}

1. There are certainly other ways to design the interface to a method like this, and this is not the design I'd choose. This situation probably calls for using a custom class or Java bean. However, the approach I've used in this example demonstrates the use of heterogeneous arrays.

How to Add Java Applets to Your Site

New on the Java Boutique:

New Review:

Time Management Made Easy with the Quartz Enterprise Job Scheduler
Why not just use the Java timer API? This open source scheduling API boasts simplicity, ease-of-integration, a well-rounded feature set, and it's free!

New Applet:

Reverse Complement
Reverse Complement is a simple applet that converts DNA or RNA sequences into three useful formats.

Elsewhere on internet.com:

WebDeveloper Java
Lots of Java information on webdeveloper.com

WDVL Java
Thorough Java resource at the Web Developer's Virtual Library.

ScriptSearch Java
Hundreds of free Java code files to download.

jGuru: Your View of the Java Universe
Customizable portal with online training, FAQs, regular news updates, and tutorials.