Editor's Note: This is the first in a series of excerpts from "Chapter 5: Working with Complex Data Types" of Java and SOAP. This excerpt covers passing arrays as parameters.

In the previous chapter, we created RPC-style services in Java. Those services dealt only with simple data types. Simple data types may suffice in many situations, but you'll eventually need to use more complex data types, like those you're familiar with in your day-to-day Java programming. In this chapter we'll look at creating services with method parameters and return values that are arrays and Java beans. We'll hold off on custom data types until the next chapter, since it's possible that any custom types you create would use the complex data types we'll be discussing here.

Passing Arrays as Parameters

Let's face it--arrays are probably the most common complex data type in programming. They're everywhere, so their use in SOAP is critical. We covered the details of SOAP arrays back in Chapter 3, so you should be aware of how arrays are encoded. So let's get right into writing some Java code for services that use arrays.

In this Series

We've been working with stock market examples, so let's stick with that theme. It might be useful to have a service that returns information about a collection of stock symbols. It might provide the total volume of shares traded for the day, the average trading price of those stocks, the number of stocks trading higher for the day, etc. There are lots of possibilities. Let's start out with a service that returns the total number of shares traded for the day. The service is called urn:BasicTradingService, and it has a method called getTotalVolume. Here is the Java class that implements the service:

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;
}
}

The BasicTradingService class contains the method getTotalVolume( ), which returns the total number of shares traded. Since we're not going to access a data feed, we'll just return a made-up value. The method returns an integer and takes a single parameter called stocks that is an array of String values. The strings in the array are the stock symbols; in a real application, we'd retrieve the volume for each stock from our data feed and return the total for all the stocks in the array.

Apache SOAP has built-in support for arrays, so you don't need to do anything special on the service side. This also means that there's nothing new in the deployment descriptor; it's built just like it was in the previous chapter. Here is the deployment descriptor for the urn:BasicTradingService service:

You can deploy the service using this deployment descriptor, or you can use the Apache SOAP Admin tool from your browser.

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:

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:

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.

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.

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 (see sidebar). Here is the modified BasicTradingService class:

There is only one parameter for the executeTrade( ) method, an Object[] called params. The objects in this array must be cast to their corresponding types: a String, an Integer, and a Boolean. I like to put class casts inside a try/catch block in case the caller makes a mistake. That way I can do something useful if the method is called incorrectly, even if that means simply returning a description of the error. In Chapter 7, we'll look at generating SOAP faults for situations like this. The information passed in the array is used to generate a string that describes the parameters, and that string is stored in the result variable that is returned to the caller.