17.1 A Little History

When the MIDP v1.0 specification was released in 2000, it was a good compromise between the small footprint required by small devices at that time and features necessary to support simple mobile applications. Since then, capabilities of mobile devices and sophistication levels of mobile clients have increased drastically. MIDP v1.0 is showing its limitations. One such limitation is the lack of support to access structured data. To address this problem, a major design goal for the MIDP v2.0 specification was to add a set of XML and Web Services XML. However, during the development of MIDP v2.0, the expert group could not agree on the exact format, features, and footprint of the XML API. Considering that a large portion of MIDP v2.0 devices will be used for gaming applications and may never consume Web Services, the MIDP v2.0 expert group decided that the XML API should be offered as a standard Optional Package for both CLDC-based and CDC-based profiles. The specification development is delegated to a new expert group in Java Specification Request 172 (JSR 172, "J2ME Web Services Specification").

The JSR 172 expert group consists of 30 industry-leading corporations and individuals. It includes all the big handset manufacturers (e.g., Nokia, Motorola, Sony/Ericsson, LG, Siemens, Sharp, and RIM), system software vendors (e.g., Symbian, IBM, Borland, BEA, and Sun Microsystems) and several leading wireless carriers (e.g., NTT and Cingular). The specifications have been unanimously approved by the JCP J2ME executive committee. An implementation of the J2ME Web Services Optional Package is already available from IBM's Web Services Tool Kit for Mobile Devices. This toolkit integrates with the WebSphere Studio Device Developer IDE. Now, let's have a look at the APIs proposed by JSR 172.

17.2 The XML Processing API

The XML processing API of the J2ME Web Services Optional Package is a strict subset of JAXP v1.2. Implementations of the optional package must support the SAX v2.0 API (also see Section 15.3.1). They must support XML namespace and UTF-8 and UTF-16 encodings. DTD validation support is optional. However, if a nonvalidating parser encounters a DTD, it must throw an exception. JAXP features that are not supported include DOM and XSLT. The target runtime size for the API is about 25 KB.

17.2.1 The API

Table 17.1 lists the JAXP subset API supported by the J2ME Web Services Optional Package.


 

A simple example of the use of the JAXP SAX API is illustrated in Listing 17.1. The example program parses the XML file specified by the first line argument and prints out every start tag and attribute.

Listing 17.1. A JAXP SAX API example

import java.io.*;

import javax.xml.parsers.*;

import org.xml.sax.*;

import org.xml.sax.helpers.*;



// Parse the XML file specified by the first

// line argument and print out every start tag

// and attributes

public class SAXExample {



  public static void main(String[] args) {



    SAXParser parser;

    try {

     SAXParserFactory factory =

       SAXParserFactory.newInstance();

     parser = factory.newSAXParser();



     MyHandler handler = new MyHandler ();



     InputStream fis = new FileInputStream(args[0]);

     InputSource is = new InputSource (fis);

     parser.parse(is, handler);



   } catch (Exception e) {

     e.printStackTrace();

   }

  }

}

// Define a custom callback handler

class MyHandler extends DefaultHandler {



  public void startElement(String uri,

      String localName, String qName,

      Attributes attributes) throws SAXException {



    System.out.println(qName);

    for (int i=0; i

 

17.3 The JAX-RPC API
The J2ME Web Services Optional Package also defines a strict subset of the JAX-RPC v1.0 API that runs on both CLDC and CDC devices. JAX-RPC allows Java developers to use their familiar RMI-like APIs to invoke remote SOAP services without caring about the underlying transport or marshaling mechanisms. This is a Java-centric approach in which the developer never sees SOAP messages. All remote procedure calls are simply mapped to local calls to stub objects. Figure 17.1 illustrates the architecture of the JAX-RPC package for J2ME.

17.3.1 Features
The J2ME Web Services Optional Package is required to implement the following JAX-RPC v1.0 features.
Support for SOAP v1.2.
HTTP Basic Authentication and session support in the underlying message transport. HTTPS support is optional.
Simple SOAP type mappings. XML structs and complex composite types are supported. This allows passing simple JavaBean objects as RPC parameters and return values. However, extensible type mapping is not supported.
Mapping SOAP (or WSDL) Fault messages to the appropriate Java exceptions on the client side.
Both document and literal styles of SOAP messages.
Generating J2ME client stubs for remote services from their WSDL documents.
Serverside APIs and SOAP attachments are not supported.

17.3.2 The API
Table 17.3 lists user APIs defined in the J2ME Web Services Optional Package. All of them are J2SE/J2EE (especially JAX-RPC) classes that are added back to J2ME. The RMI classes are also available from the CDC RMI Optional Package.

17.3.3 A User Scenario
To build a Web Services client using the Optional Package, we need to go through several steps.

 Fetch the WSDL document from the service provider and generate a javax.xml.rpc.Stub class for each service. The stub class generator is a desktop utility. For example, we can generate a GoogleSearchStub class using the WSDL file fetched from the Google Web site (see Section 16.2.2 for more details).
Put the generated class into the project class path and instantiate an instance of the Stub when necessary in the application code.
GoogleSearchStub stub = new GoogleSearchStub ();

stub._setProperty(

    Stub.ENDPOINT_ADDRESS_PROPERTY,

    "http://api.google.com/search/beta2");

// Set more properties if authentication is needed




Use the Stub object to invoke remote services and get the return value as a Java object.
String key = "Google license key";

String query = "badspell";

String suggestion = stub.doSpellingSuggestion(key, query);

// Go on and make use of the suggested word




When the development work is done, we need to bundle the generated Stub classes with the application before deploying them to devices.



Now, we have seen how to use J2ME Web Services Optional Package from the user point of view. The generated Stub class shields the underlying complexity from us. Since the Stub interface is standardized, we can change the Optional Package vendors without changing the application code. JSR 172 does not stop here. It made further efforts to standardize the operation of the Stub by defining standard Service Provider Interfaces (SPIs).
17.4 The SPI for Implementers
The SPI specifies the interface to pass data between the generated Stub classes and the underlying implementation. The SPI benefits both application developers and the JSR 172 specification implementers.

    
Application developers can reuse the generated Stub classes when switching implementation providers. This makes the application more portable.
    
Multiple implementation providers can share the same Stub generator and focus on their core business—implementing the communication and marshaling logic.

The SPI classes are defined in package javax.microedition.xml.rpc . Those classes correspond to elements in the programming model defined in the WSDL document. The JSR 172 specification implementers must implement them.
For more up-to-date documentation and usage examples of the SPI, please refer to the specification documents released by JSR 172.
17.4.1 Support for Gateway-Based Clients
The SPI is just a set of interfaces. There are many innovative ways to implement it. For example, a vendor can implement most of the SOAP 

parsing methods on a gateway. The SPI implementation on the client device could communicate with the gateway using optimized proprietary protocols (Figure 17.2. This way, we can reduce the device hardware and bandwidth requirements of mobile Web Services clients. Oracle's J2ME Web Services gateway application server is a step toward this direction.

17.5 Compare with kXML and kSOAP

The J2ME Web Services Optional Package does not make kXML and kSOAP obsolete. The kXML and kSOAP libraries work at a lower level and target developers who want more flexibility. In fact, kXML and kSOAP can be used to implement the Optional Package. The major differences between the Optional Package and kXML/kSOAP are as follows:
 
Support for XML processing models: The Optional Package supports only SAX, while kXML supports SAX, XMLPull, and kDOM.
Java-centric versus XML-centric: A big feature of the Optional Package is its Java-centric design that treats SOAP RPC calls the same way as Java native RMI RPC calls. However, the trade-off is that we do not have any direct control over the underlying SOAP messages. In contrast, kSOAP allows us to peek into the XML structure, add custom headers/attributes, and manipulate arbitrary nodes. The difference between the Optional Package and kSOAP is analogous to the difference between JAX-RPC and Apache Axis.
Custom type mapping: Extensible data marshaling that requires access to the underlying SOAP structure is available only in kSOAP.
Support for flexible architecture: The support for Web Services gateways via the SPI is a big plus for the Optional Package.
Availability: kXML and kSOAP packages are available in production quality now on almost all MIDP-based and CDC-based devices. Commercial implementation of the Optional Package is still several months away. In fact, the kXML and kSOAP libraries can be used to implement the Optional Package.