Understanding the Web Services Subset API for Java ME

This article introduces you to the JAX-RPC web services APIs for the Java Platform, Micro Edition (Java ME). I'll show you how this API differs from its superset, JAX-RPC 1.1, and how these differences affect you.

These subsets were created for Java ME because the original JSR 63 and JSR 101 specifications targeted only the Standard and Enterprise Editions of the Java platform (Java SE and Java EE).

In general terms, a web service is a software component or service that has been published on the World Wide Web in one of several particular ways. You can expose a web service using a technology like XML-RPC, Representational State Transfer (REST), or the Simple Object Access Protocol (SOAP) - or even using your own message encoding, as long as it complies with the Hypertext Transport Protocol (HTTP).

The industry tends to use the term web services more specifically, to describe services that are exposed using SOAP, an XML-based message encoding that is typically transported using HTTP. The current version of SOAP is 1.2, but SOAP 1.1 is more widely adopted, and JAX-RPC for Java ME is based on SOAP 1.1.

Through the use of service descriptors and well-defined interfaces, web services promote independence of programming language, operating system, and hardware, loose coupling between service consumers and providers, and clean separation between exposed interfaces and their implementations. These characteristics result in services that are interoperable, easier to interface with, and easier to aggregate than binary interfaces such as CORBA.

Many people equate web services with Service-Oriented Architectures (SOA), but web services are just one element of SOA - they're about service invocation. SOA's scope is broader than just invocation. It's a complete software component architectural model, a way to organize, manage, deploy, discover, and expose software components, and to consume these over the Internet. From the software life-cycle perspective, in addition to the typical software development phases of design, development, and deployment, SOA defines web services-specific phases that include service publishing, discovery, binding and consumption, and management. For more information on SOA read the article Service-Oriented Architecture and Web Services: Concepts, Technologies, and Tools

Before we focus on the Java ME subset of JAX-RPC, let's review the general concepts and elements of a typical JAX-RPC application:

When examining a JAX-RPC application, in our case an application based on Java ME, we should focus on three main areas of interest: the service consumer, the service provider, and the network.

The Service Consumer consists of the application, the JAX-RPC stubs for the service of interest, and the JAX-RPC runtime. On Java ME the JAX-RPC stubs and runtime are based on the JSR 172 subset. The JAX-RPC stubs are proxies created from a web service descriptor that represent the remote service and that hide the complexity of data marshalling and interfacing with the JAX-RPC runtime. The JAX-RPC runtime is responsible for managing the remote invocations and the network operations.

The Service Provider consists of the service classes that are accessible through a web server and a SOAP engine. There also is the Web Services Descriptor Language (WSDL) description, an XML document that describes the web service itself, the method signatures, and the binding information. The web server, for example the Apache HTTP Server, provides the web transport, and the SOAP engine, for example Apache's Axis, provides the JAX-RPC SOAP runtime for service invocation. The service ties are proxies for the actual service classes, and are responsible for handling details such as data marshalling. The service classes provide the actual service implementation.

The Network represents the Web, the transport (typically HTTP), and the SOAP-encoded messages.

JAX-RPC 1.1 is a well-documented specification, API, and runtime. JAX-RPC for Java ME is a subset of JAX-RPC 1.1 designed to work on top of any of Java ME's configurations: version 1.0 or 1.1 of the Connected, Limited Device Configuration (CLDC 1.0 or CLDC 1.1), or the Connected Device Configuration (CDC).

JAX-RPC for Java ME is a client API for the consumption of web services. Applications that use JAX-RPC for Java ME rely on the same concepts and follow the same steps as in the full JAX-RPC 1.1 implementation, as explained in the article Introduction to J2ME Web Services. Because JAX-RPC for Java ME is a subset, you must consider its differences from JAX-RPC 1.1. A client application written to the JAX-RPC 1.1 APIs won't be portable to Java ME without tweaking. In this context, "tweaking" refers to analyzing the WSDL description, handling workarounds, generating stubs, compilation, and testing:

Let's enumerate the main areas of differences between JAX-RPC 1.1 and the Java ME subset:

The Web Services Interoperability Organization's WS-I Basic Profile Version 1.0 defines a number of clarifications and recommendations to help guarantee interoperability among many web services implementations. JAX-RPC for Java ME conforms to these clarifications and recommendations, overriding JAX-RPC 1.1 whenever appropriate.

The effect on you: The WS-I Basic Profile maximizes interoperability by standardizing the technologies used for web services: SOAP 1.1, XML 1.0 and XML Schema, WSDL 1.1, and UDDI 2.0. Broad adherence to the Profile increases your confidence that your own Profile-compliant applications will be able to use a very broad variety of services. Today "web services" and "WS-I Basic Profile" are all but synonymous. You may encounter problems whenever you consume JAX-RPC 1.1 web services that don't implement the WS-I Basic Profile.

As I noted earlier, JAX-RPC for Java ME uses SOAP 1.1 between service providers and consumers. SOAP 1.2 introduces a number of changes such as InfoSets and new Faults, and clarifications to address a number of ambiguity issues.

The effect on you: At this writing, these innovations are nothing to worry about. SOAP 1.2 is not as common as SOAP 1.1, and won't become common until it is part of the WS-I Basic Profile.

Because XML is very verbose, it's not the ideal choice for communication with resource-constrained handsets. In wireless environments, latency and cost considerations oblige you to manage bandwidth use thoughtfully. For this reason, JAX-RPC for Java ME implementations are free to use binary message encoding during message exchange, as long as this use is transparent to applications.

The effect on you: None, because the encoding is transparent. From the application's perspective only valid SOAP XML messages are being exchanged.

JAX-RPC 1.1 supports three types of stubs and invocations: static stub, dynamic proxy, and Dynamic Invocation Interface (DII).

The Java ME subset supports only static stubs. The developer is responsible for generating the stubs using a WSDL-to-Java mapping tool such as wscompile:

The Sun Java Wireless Toolkit includes a special version of wscompile that takes into consideration the JAX-RPC subset restrictions. The toolkit also includes a graphical stub generator, but I recommend using the command-line utility wscompile for two reasons: It provides better feedback on error conditions, and you can include it in an Ant build task. To learn how to use the wscompile command, please refer to the toolkit's User's Guide, particularly the section Using the Stub Generator. The guide can be found in the toolkit's documentation directory.

What do a generated stub, the application, and related classes look like? Take a look at this class diagram:

The generated stub implements javax.xml.rpc.Stub as well as the remote service interface. The stub uses javax.xml.rpc.* classes such as Operation and Element, and javax.xml.namespace.QName for qualified names, as well as any vendor-specific XML RPC classes the application needs. From the developer's perspective most of the above complexity is hidden by the stub generator: Once you create the static stub, the application uses it and its associated service interface for service invocation. Other classes of concern are the application-specific classes such as the MIDP classes, and the RemoteException that is invoked if an error arises during service invocation.

The effect on you: Lack of support for dynamic proxy or DII has no real negative impact on Java ME applications. Static stubs work just fine. Their only downside is that you have to create them ahead of time.

JAX-RPC 1.1 supports a client model for the service consumer, and a service endpoint model for the service producer.

The JAX-RPC for Java ME subset doesn't support the service endpoint model, only the client service consumer model.

The effect on you: Because the current version of JAX-RPC for Java ME doesn't support exposing web services, only consuming them, you can't use the subset to create a service endpoint.

The effect on you: Having no support for asynchronous RPC or one-way RPC has no real impact on Java ME applications. Synchronous two-way RPC, the most prevalent type of RPC interaction mode, is sufficient. You do have to remember that the client blocks until a response is received or an exception is thrown. You should dispatch an RPC invocation on its own thread of execution so the main system thread isn't blocked.

Registering and discovering web services lies outside the scope of JAX-RPC 1.1. Universal Description Discovery and Integration (UDDI) has become the global de facto standard service registry, where producers can register WSDL descriptions of services, and consumers can discover them. UDDI.org publishes specifications, best practices, and technical notes.

There are no capabilities for standard service registration and discovery or UDDI Java APIs in Java ME as yet.

The effect on you: In Java ME, service discovery is a manual step done ahead of time. You could develop your own UDDI client API, but it wouldn't be useful because you'd still have to generate static stubs manually.

JAX-RPC specifies the mapping between SOAP and Java types shown in Table 1. Due to platform restrictions, JAX-RPC for Java ME doesn't support all of the JAX-RPC 1.1 basic types. For example, there is no support for types such as java.math.BigInteger, and mapping of floating-point types depends on the Java ME configuration you use.

Simple Type	Java Type	JAX-RPC 1.1	Recommended Location for Java ME

`xsd:string`	`java.lang.String`	X	X
`xsd:integer`	`java.math.BigInteger`	X	Not supported
`xsd:int`	`int`	X	X
`xsd:long`	`long`	X	X
`xsd:short`	`short`	X	X
`xsd:decimal`	`java.math.BigDecimal`	X	Not supported
`xsd:float`	`float`	X	X String or float or Float¹
`xsd:double`	`double`	X	X String or double or Double²
`xsd:boolean`	`boolean`	X	X
`xsd:byte`	`byte`	X	X
`xsd:unsignedInt`	`long`	X	Not supported
`xsd:unsignedShort`	`int`	X	Not supported
`xsd:unsignedByte`	`short`	X	Not supported
`xsd:QName`	`javax.xml.namespace.QName`	X	X
`xsd:dateTime`	`java.util.Calendar`	X	Not supported
`xsd:date`	`java.util.Calendar`	X	Not supported
`xsd:time`	`java.util.Calendar`	X	Not supported
`xsd:anyURI`	`java.net.URI` (J2SE 1.4 only), `java.lang.String`	X	Not supported
`xsd:base64Binary`	`byte[]`	X	X
`xsd:hexBinary`	`byte[]`	X	X
`xsd:anySimpleType`	`java.lang.String`	X	Not supported
`xsd:complexType`	Sequence of primitive and class types	X	X

¹ Depending on the Java ME configuration: String if CLDC 1.0; float or Float if CLDC 1.1 or CDC.

² Depending on the Java ME configuration: String if CLDC 1.0; double or Double if CLDC 1.1 or CDC.

Type mapping restrictions are probably what will give you the most trouble. You'll need to work around the lack of support for some commonly used data types, including dateTime, date, and time. You may need to create special versions of WSDL files for Java ME clients. Remember to specify CLDC 1.1 when you're building for that configuration, as it supports floating-point numeric types. If you try to create a static stub from a WSDL description that specifies unsupported types, stub generation or compilation will fail.

Note: A future maintenance release of the Web Services for Java ME specification will remove some of the type limitations by adding support for xsd:date, xsd:time, and xsd:dateTime, all mapped to java.util.Calendar.

JAX-RPC 1.1 specifies support for arrays derived from soapenc:Array by restriction, and the wsdl:arrayType attribute.

JAX-RPC for Java ME doesn't support soapenc:Array or wsdl:arrayType. Instead, it derives arrays from any element whose maxOccurs attribute is greater than 1 or unbounded, as the WS-I Profile recommends. In addition, the JAX-RPC subset doesn't support simple types derived by restriction.

In both JAX-RPC 1.1 and the subset for Java ME, the type of Java array element is based on the schema for the XML array.

The effect on you: Without API support for soapenc:Array and wsdl:arrayType, your Java ME application won't be able to consume services that describe arrays using these two types. The good news is that the WS-I Profile is discouraging the use of soapenc:Array and wsdl:arrayType, because interpretation problems have arisen. If you try to create a static stub from a WSDL description that specifies unsupported types, stub generation or compilation will fail.

The effect on you: Your Java ME application won't be able to consume services with complex types that are described using the unsupported methods or attributes I've just described. If you try to create a static stub from a WSDL description that specifies unsupported types, stub generation or compilation will fail.

JAX-RPC 1.1 specifies support for enumerations, and for simple types derived by restriction or by using xsd:list. Deriving by restriction makes it possible to derive a simple type from an existing pre-defined simple type, referred to as a base type. Deriving by using xsd:list enables you to define arrays.

JAX-RPC for Java ME doesn't support enumerations, or simple types derived by restriction or using xsd:list.

The effect on you: Your Java ME application won't be able to consume services that are described using the unsupported methods I just described. If you try to create a static stub from a WSDL description that specifies unsupported types, stub generation or compilation will fail.

JAX-RPC 1.1 specifies support for extensible type mapping and serialization between Java types and XML data types. Pluggable serializers and deserializers provided by you or by a third party allow custom serialization and deserialization of Java-based objects to and from XML types, thus enabling developers to create their own extended types.

JAX-RPC for Java ME doesn't support extensible type mapping. It does support most of the simple types I've identified, including complex types and arrays of simple types.

The effect on you: The lack of support for extensible mapping means that you won't be able to define your own custom Java-to-XML serialization. Because extensible type mapping is defined loosely, and its implementation is very much vendor-specific, you should stay away from it anyway. Most web services stick to basic types.

JAX-RPC 1.1 specifies that a wsdl:operation defined in a wsdl:portType maps to a Java method on the mapped Java service endpoint interface. JAX-RPC 1.1 supports the overloading of operation names within wsdl:portType.

Following the WS-I Basic Profile, JAX-RPC for Java ME does not. Names of wsdl:operations within a wsdl:portType must be unique.

The effect on you: Your Java ME application won't be able to consume services that overload operation names within a wsdl:portType. If you try to create a static stub from a WSDL description that specifies unsupported types, stub generation or compilation will fail.

JAX-RPC 1.1 specifies that the parameterOrder attribute must reflect the order of the parameters in the RPC method signature.

JAX-RPC for Java ME follows the WS-I Basic Profile, which specifies that the order of the parts in a message, not the parameterOrder attribute, identifies the order of the parameters.

The effect on you: As adherence to the WS-I Basic Profile has become prevalent, parameter-order problems should not arise; but be aware of the possibility.

JAX-RPC 1.1 defines support for SOAP message handlers, which you can use to implement additional SOAP message processing, such as encryption or caching.

The effect on you: You can't implement advanced features during SOAP message processing. That's a shame, because message handlers could have provided a way to work around the lack of support for some data types.

JAX-RPC 1.1 defines support for SOAP messages with attachments based on MIME multi-part message types. The idea is to support MIME-encoded parameters or return values, such as images or XML documents.

The effect on you: Your Java ME application won't be able to send complex parameters or return values such as images or XML documents.

JAX-RPC 1.1 supports rpc- and document-oriented operation styles, and encoded and literal SOAP message encoding.

The Java ME subset supports only the document/literal combination of operation style and encoding.

The effect on you: Because JAX-RPC subset applications have no support for the rpc operation style and the encoded representation, they won't be able to interoperate with web services that rely on the rpc and encoded modes. Note, though, that web services are moving away from these modes and towards document/literal.

In JAX-RPC 1.1, a SOAP fault - a soap:fault element in the WSDL description - is mapped to javax.xml.rpc.soap.SOAPFaultException, to a service-specific exception class, or to RemoteException.

JAX-RPC for Java ME doesn't support SOAPFaultException; SOAP faults are mapped to a service-specific Java exception or RemoteException.

The effect on you: When invoking a web service, use RemoteExceptions in your catch blocks.

This article introduced the JAX-RPC for Java ME subset, identified its differences from the JAX-RPC 1.1 API available to applications based on Java SE and Java EE, and described how these differences affect development of Java ME applications that consume web services. There are a number of differences that will prevent applications that rely on the JAX-RPC for Java ME subset from working with JAX-RPC 1.1 web services without appropriate tweaking or workarounds.

Many thanks to Michael Krivoruchko of Sun Microsystems and Brian Christeson for helping improve this article.

C. Enrique Ortiz is a software architect and developer, and a mobility technologist, writer, and blogger. He has been author or co-author of many publications, and is an active participant in the Java mobility community. Enrique holds a B.S. in Computer Science from the University of Puerto Rico and has more than 16 years of software engineering, product development, and management experience.