Seminar Enterprise Computing Winter Term 2004/05 University of Applied Sciences, Aargau Faculty of Engineering and Technology Author: Siarhei Sirotkin Scientic Adviser: Prof. Dr. Dominik Gruntz Windisch, 24th January 2005
Abstract There is great interest and activity in the Java community in the use of Web Services standards and infrastructures to provide the programming model for the next generation of enterprise services. There is also considerable interest in the developer community in extending enterprise services out to Java 2 Micro Edition clients. To provide standard access from Java 2 Micro Edition to Web Services in order to be able to build wireless applications using XML and SOAP, the JSR 172 specication was dened. J2ME Web Services (JSR 172) is poised to propel a new generation of networked data services for mobile devices. This latest addition to the J2ME platform is WS-I interoperable, compliant and allows mobile devices to access Web Services using XML technology and SOAP protocol. The introduction of J2ME Web Services greatly expands and simplies the current usage of mobile data services in the areas of networked applications for both the consumer and enterprise markets. This seminar paper discusses how Web Services can be accessed and XML documents parsed on devices which do support the JSR 172 standard, as well as on devices which do not. 2 University of Applied Sciences, Aargau
CONTENTS Contents 1 What Is JSR 172 4 1.1 Specication Description...................................... 4 1.2 JSR 172 Goals........................................... 5 2 Java API for XML Parsing (JAXP) Subset 6 2.1 Requirements............................................ 6 2.2 JAXP Subset APIs......................................... 6 3 Java API for XML-Based RPC (JAX-RPC) Subset 8 3.1 JAX-RPC Subset Functionality Overview............................ 8 3.2 Requirements............................................ 8 3.3 JAX-RPC Subset Core APIs................................... 9 3.4 J2ME-based Service Client Programming Model........................ 10 4 WSDL/XML to Java Mapping 11 4.1 XML to Java Type Mapping................................... 11 4.2 WSDL to Java Mapping...................................... 11 5 Runtime Service Provider Interface (SPI) 13 6 J2ME Web Services Practical Approach 14 6.1 JSR 172 Based Web Services Architecture............................ 14 6.2 Understanding JSR 172...................................... 15 6.3 Using the JAX-RPC Subset in Applications........................... 16 6.3.1 Stub Generation...................................... 16 6.3.2 Stub Instantiation..................................... 17 6.3.3 Remote Methods Invocation................................ 17 6.3.4 Packaging.......................................... 18 6.4 Using the JAXP Subset in Applications............................. 18 6.4.1 Dening Event Handler.................................. 20 6.4.2 Creating SAX Parser.................................... 22 6.4.3 Parsing an XML Document................................ 23 7 Web Services Without JSR 172 24 7.1 Client and Server Applications.................................. 24 7.2 Network, Protocols, and Services................................. 26 8 Conclusion 27 A Glossary 28 B Demo Source Code 29 [ia02] Sergey Sirotkin 3
1 What Is JSR 172 There is great interest and activity in the Java community in the use of Web Services standards and infrastructures to provide the programming model for the next generation of enterprise services. There is also considerable interest in the community of developers in extending enterprise services out to J2ME clients. Structured data sent from existing applications to mobile devices is represented, as a rule, in the form of XML since this standard is reliable, transparent, universal and established. In order to avoid implementing code to process such data in each application over and over again, an optional package (two, in fact) has been dened that is (are) included with the platform of a mobile device. Since J2ME contains only low level programming and communication APIs to support Web Services, it appears to be rather dicult for developers to take advantage of this technology. Although JSR 63 (JAXP) and JSR 101 (JAX-RPC) dene Java APIs and conventions for XML processing and XML-based Remote Procedure Call communication targeted at the Java 2 Standard Edition (J2SE) and Enterprise Edition (J2EE) platforms, they do not provide such facilities for Java 2 Micro Edition (J2ME) developers. The following sections briey describe the most signicant issues of the JSR 172. For more detailed information please refer to the specication itself. 1.1 Specication Description JSR 172 specication is developed to help implement the aforementioned infrastructure as two optional packages for Java 2 Micro Edition in order to: provide basic XML processing capabilities; enable reuse of Web Services concepts when designing J2ME clients; provide APIs and conventions for programming J2ME clients of enterprise services; adhere to Web Services standards and conventions around which the Web Services and Java developer community is consolidating; enable interoperability of J2ME clients with Web Services; provide a programming model for J2ME client communication with Web Services, consistent with that for other Java clients such as Java 2 Standard Edition. JSR 172 does not change in any way existing network protocols, data formats or interface denition languages, but merely provides convenient Java platform support in J2ME for the specications dened by the appropriate network standards organizations, such as World Wide Web Consortium (W3C) or Organization for the Advancement of Structured Information Standards (OASIS). Neither of any existing specications is in need of revision as a result of JSR 172 introduction. The specication is targeted for the J2ME platform including the CLDC- and CDC-based proles, does not have any specic dependencies and provides optional packages suitable for J2ME devices. The aim of the specication is subsetting the APIs and conventions dened by Java API for XML Parsing (JAXP) and Java API for XML-Based RPC (JAX-RPC). The following technologies are addressed: APIs for basic manipulation of structured XML data, also known as parsing (these APIs are based upon a suitable strict subset of the APIs already dened by JAXP); APIs and conventions for enabling XML-based Remote Procedure Call (RPC) communication from J2ME, including: 4 University of Applied Sciences, Aargau
1 WHAT IS JSR 172 denition of a strict subset of the Web Services Description Language (WSDL) to Java mappings dened by JSR 101 (JAX-RPC), suitable for J2ME; denition of stub APIs based on the mapping above for XML-based RPC communication, which focuses on subsetting the mapping and conventions produced by JSR 101; denition of runtime APIs to support stubs generated according to this mapping supporting XML as a transport and encoding component; investigation of a suitable and compact encoding mechanism for XML-based RPC messages. 1.2 JSR 172 Goals The main goal to be achieved by introducing JSR 172 is to provide two new capabilities to the Java 2 Micro Edition platform: access to remote SOAP/XML-based Web Services; parsing XML data. This is to be realized in the form of two new, independent, optional packages: An optional package providing XML Parsing support on the platform level which: is a subset of JSR 63 (JAXP 1.2) functionality; meets platform size requirements, i.e. ensures that the API ts within the footprint requirements of the target devices; meets platform performance requirements, i.e. ensures that the API can be implemented within the runtime memory and processing requirements for the target devices. An optional package to facilitate access to XML-based Web Services from CDC- and CLDC-based proles which: is a subset of JSR 101 (JAX-RPC 1.1) functionality; is a separate deliverable from XML Parsing optional package; provides access to Web Services from J2ME (without dening web service endpoints for the target devices); meets platform size requirements, i.e. ensures that the API ts within the footprint requirements of the target devices; meets platform performance requirements, i.e. ensures that the API can be implemented within the runtime memory and processing requirements for the target devices. [ia02] Sergey Sirotkin 5
2 Java API for XML Parsing (JAXP) Subset XML is becoming a standard means for clients and servers to interact with each other. With its platform neutrality and strong industry support, XML is being widely used by developers to link network-enabled clients with remote backend servers, their databases and services. A permanently increasing number of such clients are based on the J2ME platform: mobile phones, PDAs, and other portable devices. As these mobile devices are utilized more and more to access remote enterprise data, XML support on the Java 2 Micro Edition platform is becoming a crucial issue. 2.1 Requirements In order to provide implementations that are useful on the widest possible range of congurations and proles, the JSR 172 specication is treating the Connected Limited Device Conguration (CLDC) 1.0 as the lowest acceptable standard. The target size for a complete implementation, including interfaces, is only 35 kilobytes. This size is calculated as the sum of the uncompressed Java class les required for both the interface denitions and their implementations. The API of the package is a strict subset of the JAXP 1.2 specication. The modications applied to the functionality dene that an implementation must support the Simple API for XML Parsing (SAX) 2.0 subset, XML namespaces, and both UTF-8 and UTF-16 encodings. Such features as support for SAX 1.0, Document Object Model (DOM), and XSL Transformations (XSLT) are not supported. DTD-validation of XML documents is optional: it may be supported by an implementation, however, developers should always keep in mind that XML validation is an expensive process in terms of processing power and memory usage and hence is not supported on most J2ME devices. 2.2 JAXP Subset APIs When inspecting the API set, one will quickly notice that much of what exists in the J2SE JAXP API set is missing from the J2ME JAXP API set. However, although many of the classes are gone, much of the functionality remains. There are three packages which comprise the JAXP API subset: The javax.xml.parsers package contains the classes to obtain and reference a platform's given parser implementation. The package contains four classes: SAXParser (simple SAX-based parser); SAXParserFactory (a factory to obtain and congure a SAX-based parser); FactoryConfigurationError (thrown to indicate a conguration error); ParserConfigurationException (thrown to indicate a problem with the parser factories). The org.xml.sax package contains a subset of the SAX 2.0 API classes and interfaces. The interfaces included in this package are: Attributes (an interface that provides access to a list of attributes by attribute index, namespacequalied name, or prexed name); Locator (an interface for associating a SAX event with a document location). The classes included in this package are: InputSource (provides methods to get or set the byte stream, the character set, the encoding, and the public and system identiers); 6 University of Applied Sciences, Aargau
SAXException (general SAX exception class); SAXNotRecognizedException (subclass of SAXException); SAXNotSupportedException (subclass of SAXException); SAXParseException (subclass of SAXException). 2 JAVA API FOR XML PARSING (JAXP) SUBSET The org.xml.sax.helpers package contains a class for applications to extend to receive parse events: DefaultHandler (provides default implementations of event-handling behavior for applications to extend). [ia02] Sergey Sirotkin 7
3 Java API for XML-Based RPC (JAX-RPC) Subset JAX-RPC is a Java API for interacting with SOAP-based Web Services. JSR 172 denes a subset of the JAX-RPC 1.1 specication which meets the requirements of the J2ME platform and conforms to the WS-I Basic Prole. The functionality provided in the subset reects both the limitations of the platform (memory size and processing power), as well as the limitations of the deployment environment (low bandwidth and high latency). The specication does not depend on either the Java API for XML Messaging (JAXM) 1.0 specication or the SOAP with Attachments API for Java (SAAJ) dened by JAXM 1.1. 3.1 JAX-RPC Subset Functionality Overview The RPC invocation in the subset is stub-based (Stub interface is provided). There is no support for dynamic proxies or dynamic invocation interface (DII). The generated stubs use the document style and literal use. This does restrict the Web Services that can be interacted with but greatly simplies implementation on a target device. JSR 172-compatible platforms support WSDL documents referencing the most common primitive (boolean, byte, short, int, long, float, double), String, and complex data types, as well as arrays of primitive and complex types. A SOAP fault is mapped to a service specic Java exception or a RemoteException. The SOAPFaultException is not included into the API subset (see 4.2). There is no support for the service endpoint model. The subset only provides support for clients to access web service endpoints. Support for extensible type mapping is not provided either. The following classes and interfaces are additionally included into the J2ME Web Services Optional Package to satisfy dependencies of JAX-RPC on the CLDC-based platforms: java.rmi.remote, java.rmi. RemoteException, java.rmi.marshalexception, and java.rmi.serverexception. An RMI Optional Package is available for CDC-based platforms. As for the rest of the features (e.g. HTTP Basic Authentication and Session Management), the behavior of the JAX-RPC subset runtime is identical to that described in the JAX-RPC 1.1 specication. 3.2 Requirements The JAX-RPC subset runtime system, which forms the core of the implementation, is a client-side library that provides a set of services required for the JAX-RPC subset runtime mechanisms. A client must be based on either the J2ME platform Connected Limited Device Conguration 1.0 (CLDC 1.0), or CLDC 1.1, or Connected Device Conguration 1.0 (CDC 1.0). J2ME server side requirements are not dened. The minimum resources requirements for an implementation of the JAX-RPC subset dened by JSR 172 are 50 KB of RAM and 25 KB of ROM in addition to those dened for the base platform. In order to provide interoperability with the existing Web Services infrastructure, the communication of clients with server endpoints use SOAP 1.1 encoded messages. Due to limitations of the wireless environment the JAX-RPC subset runtime on the client device does not necessarily support an XML encoding. However, if it does, this must be transparent to the web service, which means all outgoing XML encoded messages have to be transformed into SOAP 1.1, so they can be understood by the server. Requests or responses in the SOAP body can be either encoded or may represent a concrete schema denition (literal representation). As a consequence, the subset implementations must support the literal representation of an RPC call or response (a WSDL operation using the Document/Literal messaging mode), while the encoded representation is not supported. As the transport for SOAP messages, HTTP 1.1 protocol is typically used, which does not mean that this is the only transport that can be supported by a JAX-RPC runtime system implementation, since JAX- 8 University of Applied Sciences, Aargau
3 JAVA API FOR XML-BASED RPC (JAX-RPC) SUBSET RPC core APIs are designed to be transport-neutral. Any protocol that supports the ability to deliver SOAP messages may be used. Security features of such protocols are outside the scope of the JAX-RPC specication. The implementations of the JAX-RPC subset specication must support the following mode of interaction between the client and service endpoint: the client invokes a remote method on the service endpoint and receives a return value or an exception in case of failure. The invocation thread on the client side blocks while the remote method is preparing the result. Eventually, the client receives a return value (void is also possible) or, again, an exception. This mode is called Synchronous Request-response Mode (Fig. 1). Figure 1: Synchronous Request-response Mode. The JAX-RPC specication does not dene how a runtime system implements support for this mode in terms of the underlying protocol and transport. The JAX-RPC subset APIs and service client programming model support Synchronous Request-response Mode through the stub-based model. It is required that client code is portable across multiple JAX-RPC runtime system implementations. This is achieved by dening a Service Provider Interface (SPI) via which the generated stub interacts with the runtime (see section 5). Non-supported by JAX-RPC runtime system features are Extensible Type Mapping, use of SOAP messages with attachments as an underlying protocol, SOAP message handlers, and a number of other features listed in JSR 172 specication. 3.3 JAX-RPC Subset Core APIs The JAX-RPC subset APIs that support the JAX-RPC runtime mechanisms are packaged in javax.xml. rpc package: javax.xml.rpc.stub interface; javax.xml.rpc.jaxrpcexception class; javax.xml.rpc.namespaceconstants class. Besides, there are several other packages that have to be included in the JSR 172 JAX-RPC subset: javax.microedition.xml.rpc (denes used by stubs Type enumeration, ComplexType representing WSDL xsd:complextype denitions, Element, Operation, interface FaultDetailHandler, and a FaultDetailException class), javax.xml.namespace (denes a qualied name QName class), and a subset of the standard java.rmi package included to satisfy JAX-RPC dependencies (denes only the Remote interface and three exception classes: MarshalException, RemoteException, ServerException). All generated by a WSDL to Java mapping tool stub classes are required to implement the javax.xml.rpc. Stub interface in order to represent stub instances for the target service endpoint. Besides, a stub class should be bound to a Service Provider Interface (see section 5 for details). It must only use the SPI to interact with the runtime. [ia02] Sergey Sirotkin 9
3.4 J2ME-based Service Client Programming Model To create a JSR 172 JAX-RPC client that is able to access a remote service, the following steps are required: 1. Generate a stub from the WSDL XML-description of the remote service (at development time). 2. Create an instance of the stub in the code of the application (as a proxy for the remote service from which it was created). 3. Invoke methods on the generated stub corresponding to the service endpoints' wsdl:operation implementation. 4. Package the stub with the J2ME client application into its deployment bundle. These steps are discussed later in this paper. 10 University of Applied Sciences, Aargau
4 WSDL/XML TO JAVA MAPPING 4 WSDL/XML to Java Mapping This section briey describes the specied JSR 172 standards of WSDL and XML to Java mapping, which includes mapping of XML data types to the Java types, mapping of abstract denitions of port type, operations and messages to Java interfaces and classes, Java representation of a wsdl:port address specication, and Java representation of a wsdl:service denition. 4.1 XML to Java Type Mapping The following table species the Java mapping for the built-in simple XML data types. These XML data types are as dened in the XML schema specication. Simple Type Java Type xsd:string java.lang.string xsd:int int or java.lang.integer 2 xsd:long long or java.lang.long 2 xsd:short short or java.lang.short 2 xsd:boolean boolean or java.lang.boolean 2 xsd:byte byte or java.lang.byte 2 xsd:float java.lang.string 3 or float or java.lang.float 2 xsd:double java.lang.string 3 or double or java.lang.double 2 xsd:qname javax.xml.namespace.qname xsd:base64binary 1 byte[] xsd:hexbinary 1 byte[] Table 1. Java Mapping for the built-in simple XML data types. Notes: 1. Support for xsd:base64binary and xsd:hexbinary is only required at the level of SOAP messages as encoding for arrays of bytes. 2. In several cases a built-in simple XML data type must be mapped to the corresponding Java wrapper class for the Java primitive type. These cases are described in detail in the JSR 172 specication. 3. The CLDC 1.0 does not provide the float and double native types, that is why in this conguration additional code has to be generated to map these types to java.lang.string (this is also the default mapping). 4. The standard mapping for the xsd:anytype is not dened. An XML array, derived from any element where the maxoccurs attribute is a nonnegative integer greater than 1 or unbounded, is mapped to a Java array with the operator [ ]. The type of Java array element is determined based on the schema for the XML array. An XML struct (xsd:complextype with sequences of simple type and complex types) maps to a JavaBeans class which provides getter and setter methods for each property mapped from the member elements of the XML struct. The instances of the mapped JavaBeans class must be capable of marshaling to and from the corresponding XML struct representation. XML enumerations, deriving simple types by restriction, and deriving simple types using xsd:list are not supported by the JAX-RPC subset. 4.2 WSDL to Java Mapping A WSDL document is mapped to a Java package, its application specic name being congured during the mapping. [ia02] Sergey Sirotkin 11
A WSDL port type (named set of abstract operations and messages involved) is mapped to a Java interface (called a Service Endpoint Interface) which extends the java.rmi.remote interface. Its name is mapped from the name attribute of the wsdl:porttype element. Since WSDL does not support inheritance of the port types, the inheritance of the mapped Java interfaces is not dened. Each method of the mapped Java interface declares java.rmi.remoteexception (common superclass for exceptions related to a remote method invocation) in its throws clause. A wsdl:operation dened in a wsdl:porttype maps to a Java method on the service endpoint interface, and its name maps to the name of the corresponding method. Overloading is not allowed; consequently, wsdl:operation names must be unique within a wsdl:porttype. The message parts in the wsdl:input and wsdl:output elements are mapped to parameters on the corresponding Java method signature. The optional wsdl:fault element in a wsdl:operation maps to either a java.rmi.remoteexception (or its subclass), or a service specic Java exception, which extends the class java.lang.exception directly or indirectly. 12 University of Applied Sciences, Aargau
5 RUNTIME SERVICE PROVIDER INTERFACE (SPI) 5 Runtime Service Provider Interface (SPI) The Service Provider Interface (SPI) is the only way of communication between the generated stubs and the JAX-RPC subset runtime. The JAX-RPC subset runtime SPI is used by generated stubs to execute RPC calls, it is not intended to be directly used by application developers. The SPI only supports the functionality described in the JAX-RPC subset. A stub uses the SPI to perform the following steps: Figure 2: JAX-RPC Subset Runtime SPI classes. 1. Set properties needed to invoke an RPC, such as target service endpoint address, password and username for authentication etc. An IllegalArgumentException is thrown by the runtime if a supplied property is not supported. 2. Create an object graph describing the input parameters (Type, Element and ComplexType classes are used). 3. Create an object graph describing the return parameters (Type, Element and ComplexType classes are used). 4. Create an Operation object representing an invocation of an RPC. 5. Encode the input parameter values. The input parameter values are passed to the runtime encoded in an array of Object. Each element in the array is either a corresponding Java object wrapper for a primitive type (Integer, Boolean etc.), or an array of Object, representing the elds of a complex type. 6. Invoke the RPC service endpoint (using the invoke method). 7. Decode return values from the RPC invocation. The return values are in an Object array, encoded in the same way as input parameters. In the case of a SOAP fault that maps to java.rmi.remoteexception (or a subclass), a JAXRPCException is thrown by the Operation's method invoke. The getlinkedcause method of JAXRPCException is used by the stub to retrieve the generated exception. The stub then re-throws the linked exception (the cause) to the application. [ia02] Sergey Sirotkin 13
6 J2ME Web Services Practical Approach The implementation of the JSR 172 specication extends the Java 2 Micro Edition Platform to support Web Services and is termed Web Services API (WSA). However, as we could have seen from the previous sections, the JSR 172 also uses other core specications and application-level protocols that are promoted by the Web Services Interoperability Organization (WS-I), and standardized by W3C and OASIS. Creation, deployment, lookup, and use of Web Services depend on four core standards tangentially mentioned before: Simple Object Access Protocol (SOAP) 1.1 (species transport and data encoding); Web Services Denition Language (WSDL) 1.1 (species remote services description); Universal Description, Discovery, and Integration (UDDI) 2.0 (species remote services discovery; this API is not specied in JSR 172); Extensible Markup Language (XML) 1.0. Since these basic specications are very broad and subject to be dierently interpreted in certain situations, it is rather dicult for developers to achieve full interoperability without additional guideline assistance. To resolve these diculties, WS-I has developed a set of conformance rules called the WS-I Basic Prole that provides recommendations and clarications for many specications referenced by JSR 172. JSR 172 is conformant to the Basic Prole version 1.0 where its recommendations overlap the functionality dened by this specication. 6.1 JSR 172 Based Web Services Architecture If we take a closer look at the high level of the typical Web Services architecture (Fig. 3), we will easily identify its three main elements: web service consumer, web service producer, and network infrastructure in between. Figure 3: J2ME Web Services in a typical web service architecture. A web service consumer may be any J2ME-enabled, WSA-supporting mobile device with a network-aware application installed. This application uses a generated JSR 172 stub that communicates with the network via the JAX-RPC subset runtime. Note that currently clients are only able to consume Web Services, not produce them. No creation or deployment of service endpoints is supported by JSR 172. The wireless network and the Internet serve the communication between clients and servers and use corresponding communication and data-encoding binary and ASCII-based protocols, HTTP and SOAP/XML among them. 14 University of Applied Sciences, Aargau
6 J2ME WEB SERVICES PRACTICAL APPROACH A service producer (typically a web server behind a rewall and/or a proxy gateway) either provides a direct access to Web Services installed and running on this machine, or forwards clients' requests to back-end applications and servers on a local network. 6.2 Understanding JSR 172 In additional to the summarized specication description given in sections 2, 3 and 5, it would be helpful to look at how a typical JSR 172-based application is organized (Fig. 4). Figure 4: Typical JSR 172-based application. The application represents a smart client typically based on the Mobile Information Device Prole (MIDP) and has its business-specic logic, user interface and application-state management. XML documents are handled by the application by means of the JAXP subset API. To consume Web Services, the JAX-RPC subset API is used. The latter employs JSR 172 stubs and the runtime. In most of the mobile devices (cell phones, PDAs etc.) the application including the stub reside in the device's memory, whilst all the rest of JSR 172 core elements, along with the underlying prole and con- guration, are embedded in the device's platform itself. The JAX-RPC runtime is the main module of JSR 172 operations, with its Service Provider Interface (SPI), which enables the stubs to perform all the tasks associated with invoking an RPC service endpoint (these tasks are described in section 5). Figure 5 depicts the relationships between the client application, the stub, and the runtime. Such complexities as, for instance, connection management and data encoding, are hidden for developers inside the runtime, and owing to SPI the stubs are independent from the runtime implementation, allowing high level of portability. The client application does not interact with the runtime and SPI directly; it uses stubs instead. Although the runtime and SPI implementations must conform with the JSR 172 specication and other standards addressed by it, this issue remains the responsibility of third-party vendors who intend to develop JSR 172-compatible platforms. [ia02] Sergey Sirotkin 15
Figure 5: The JSR 172 runtime and SPI. 6.3 Using the JAX-RPC Subset in Applications The typical steps for creating a JSR 172 JAX-RPC client are described in section 3. The following four subsections explain these steps in detail. 6.3.1 Stub Generation As mentioned before, the network-aware application installed on a client wireless device interacts with the remote service through stubs and the device's JSR 172 runtime which hides the low-level complexities related to connection and data management. The stubs are generated by a stub generator (WSDL-to-Java mapping tool), which converts a remote service interface denition in the form of a WSDL document into the stub classes for the future use with the JAX-RPC subset API and runtime SPI (Fig. 6). Figure 6: Typical steps for generating a JSR 172 stub. Generation of a JSR 172 JAX-RPC stub is very similar to that of creating an RMI-based application 16 University of Applied Sciences, Aargau
6 J2ME WEB SERVICES PRACTICAL APPROACH where an RMI compiler (rmic) generates a stub from a remote interface denition. When creating a WSA application, a WSDL-to-Java mapping tool generates a stub, as well as remote interface Java le and supporting classes. After that the stub is compiled into a Java class and packaged with the application. The resulting stub class implements the Stub interface and the service's Remote interface, and uses supporting classes (Fig. 7). Figure 7: The resulting stub class. 6.3.2 Stub Instantiation As soon as the stub is generated, it can be instantiated within the application. After specifying the package name, importing MIDP-specic (e.g. javax.microedition.midlet.midlet) and JAX-RPC-specic (e.g. java.rmi.remoteexception) classes, and initializing variables, a stub can be instantiated in a usual Java way: MyService_Stub service = new MyService_Stub(); Before invoking a remote method, stub instance's properties have to be set. The supported properties are listed in the table 2. Property Name Description Stub.ENDPOINT_ADDRESS_PROPERTY Target service endpoint address. Stub.PASSWORD_PROPERTY Password for authentication. Stub.USERNAME_PROPERTY Username for authentication. Stub.SESSION_MAINTAIN_PROPERTY Indicates whether or not a client wants to participate in a session with a service endpoint. Operation.SOAPACTION_URI_PROPERTY URI to use for HTTP SOAPAction header. Table 2. Required property names. The properties can be set by calling the _setproperty() method and supplying a property name along with a value, for instance: service._setproperty(stub.endpoint_address_property, serviceurl); service._setproperty(stub.session_maintain_property, new Boolean(true)); 6.3.3 Remote Methods Invocation Using stubs makes remote service invocation very simple. A MyService_Stub has been instantiated and initialized, and now any of its methods can be invoked in a usual way that is, locally. How the method and its arguments are encoded, serialized, and sent to the remote server, and how the response is received, decoded, and de-serialized, is absolutely transparent to the application, since it all is handled by the JSR 172 runtime. A source code snippet below demonstrates an example of such remote method invocation: [ia02] Sergey Sirotkin 17
try { MyResult result = service.getmesomething("a parameter"); // create a javax.microedition.lcdui.form to display the result Form form = new Form(result.getTitle()); form.append(wrap(result.getsubtitle())); form.append(wrap(result.getinfo())); // etc. // use javax.microedition.lcdui.display to display the form display.setcurrent(form); catch (RemoteException e) { // handle RMI exception catch (Exception e) { // handle exception Note that invoking MyService_Stub.getMeSomething() is a blocking call, so in an actual application it has to be dispatched in a separate thread in order to avoid general system halt. As described in section 3, in JSR 172 WSA methods are invoked according to the Synchronous Request-response Model of client-server interaction: rst the client makes a request to the server, and then waits for a response (Fig. 8). Figure 8: Synchronous Request-response Mode in detail. 6.3.4 Packaging A J2ME client application that makes use of a stub to invoke operations on a service endpoint must include the generated stub, along with any other generated artifacts, in its deployment bundle. 6.4 Using the JAXP Subset in Applications Another optional JSR 172 API, the JAXP subset, which can exist independently of JAX-RPC (and vice versa), provides the necessary core XML parsing functionality. Figure 9 depicts the typical elements of a JAXP for J2ME application. MyApplication is the actual J2ME application which is to be developed. It includes a custom MyEventHandler class (extending org.xml.sax.defaulthandler) responsible for application-specic event handling. The 18 University of Applied Sciences, Aargau
6 J2ME WEB SERVICES PRACTICAL APPROACH Figure 9: Typical JAXP for J2ME application. SAXParserFactory class is used to get an instance of the SAXParser, which, in turn, does the work: parses the XML documents read from a network connection or from local storage. Input documents are represented as a java.io.inputstream or, preferably, as an org.xml.sax.inputsource. Note that real applications may have signicantly more elements than the ones illustrated in Figure 9 e.g. screens, data models and controllers, command listeners to capture user interface input, and base classes such as MIDlet. To hide the details from the application and just for developer's convenience, it is recommended to put all the application-specic XML logic, i.e. all the JAXP objects, initializing, invoking the parser, and processing the input XML documents, into a single class. Using the JAXP includes three main steps: 1. Implementation of the application-specic event handler. 2. Creation of a SAXParser instance using SAXParserFactory. The SAX parser invokes the event handler's event-processing callbacks as dierent parts of the XML document are processed. 3. Parsing the input XML document by invoking the SAXParser.parse() method. The sequence diagram in Figure 10 shows the interactions between the dierent application objects over time. Notes on Fig. 10: 1. MyApplication instantiates MyEventHandler. 2. MyApplication instantiates the XML InputSource. 3. MyApplication gets an instance of the SAXParserFactory. 4. MyApplication gets an instance of the SAXParser. 5. SAXParserFactory instantiates a SAXParser. [ia02] Sergey Sirotkin 19
Figure 10: JAXP API sequence diagram. 6. MyApplication calls the SAXParser to initiate the parsing of the XML document. 7. SAXParser invokes the event handler's callback startdocument() at the start of the document parsing. 8. SAXParser invokes the event handler's callback startelement() when a new element is encountered. This call also includes the element's attributes, if any. 9. SAXParser invokes the event handler's callback characters() when an element's characters are encountered. 10. SAXParser invokes the event handler's callback endelement() when a closing element is encountered. 11. SAXParser invokes the event handler's callback enddocument() at the end of the document parsing. Now we will discuss the three main steps of JAXP API usage in more detail. These steps can be performed either in the main application logic (for example, the MIDlet) or, as previously mentioned, it is recommended that this XML-specic logic is encapsulated into its own class or set of classes, hiding these details from the application. As an example we will use the following sample XML document: <?xml version="1.0"?> <dogs owner="l.a.p.d."> <name>ace</name> <name>harley</name> <name>ushki</name> </dogs> 6.4.1 Dening Event Handler The rst step is to write an application-specic event handler, a class that extends org.xml.sax.helpers. DefaultHandler and overrides the methods startelement(), endelement(), and characters() in order to be able to process the specic elements and attributes in an XML document. Methods startdocument() and enddocument() can also be overridden. A simple example of a JAXP event handler MyEventHandler listed in the code snippet below parses our dogs sample XML document. MyEventHandler shows how to parse elements dogs, its attribute owner, and sub-element name, while maintaining a list of name values. class MyEventHandler extends DefaultHandler { // private members private boolean parsing; // keep track of parsing 20 University of Applied Sciences, Aargau
6 J2ME WEB SERVICES PRACTICAL APPROACH private Stack qnamestack = new Stack(); // keep track of QName private Vector names = new Vector(); // keep track of names // XML tags private static final String DOGS = "dogs"; private static final String NAME = "name"; private static final String OWNER = "owner"; // start document processing public void startdocument() throws SAXException { parsing = true; qnamestack.removeallelements(); names.removeallelements(); // end document processing public void enddocument() throws SAXException { // end of document reached parsing = false; // postprocessing, e.g.: for (int i = 0; i < names.size(); i++) { Name name = (Name)names.elementAt(i); name.dump(); // process new element // uri - namespace URI or empty string // localname - local name (no prefix) or empty string // qname - qualified name (with prefix) or empty string // attributes - attributes or empty Attributes object public void startelement(string uri, String localname, String qname, Attributes attributes) throws SAXException { if (DOGS.equals(qName)) { String owner = attributes.getvalue(owner); // process attribute //... else { if (NAME.equals(qName)) { // keep track of names Name name = new Name(); names.addelement(name); // keep track of QNames qnamestack.push(qname); // process character data // ch - element's characters // start - start position in the character array // length - number of characters to use public void characters(char[] ch, int start, int length) throws SAXException { String qname; [ia02] Sergey Sirotkin 21
String chars = new String(ch, start, length); qname = (String)qNameStack.peek(); if (DOGS.equals(qName)) { // nothing to process else if (NAME.equals(qName)) { // keep track of names if (names.size() > 0) { Name name = (Name)names.lastElement(); name.setvalue(chars); // process end element tag // uri - namespace URI or empty string // localname - local name (no prefix) or empty string // qname - qualified name (with prefix)or empty string public void endelement(string uri, String localname, String qname) throws SAXException { qnamestack.pop(); if (DOGS.equals(qName)) { // encountered end of DOGS //... else { if (NAME.equals(qName)) { // encountered end of NAME //... Using Stack to keep track of the current qualied name simplies handling signicantly. The top of the Stack is the current XML element tag being processed. Using Vector to keep track of element values is also a good practice. These values are typically wrapped by a custom class as shown in the code snippet below. class Name { private String value; public Name() { public void setvalue(string s) { this.value = s; public void dump() { System.out.println("Value: " + value); 6.4.2 Creating SAX Parser This step is trivial. First an instance of the of the SAX parser factory has to be created: 22 University of Applied Sciences, Aargau
6 J2ME WEB SERVICES PRACTICAL APPROACH SAXParserFactory factory = SAXParserFactory.newInstance(); Then, by calling the factory's newsaxparser() method, the SAX parser is instantiated: SAXParser saxparser = factory.newsaxparser(); These statements must be enclosed within a try/catch block since they might throw a SAXException, a FactoryConfigurationError, or a ParserConfigurationException. 6.4.3 Parsing an XML Document Now, everything is ready to start parsing. To do so, the SaxParser.parse() method is called. It takes as arguments the XML document to parse (represented as an org.xml.sax.inputsource or as a java.io.inputstream), and the event handler created in the rst step. As mentioned previously, the preferred way to represent the XML document is InputSource as it provides a number of auxiliary methods such as setting and getting the input source's character encoding and the system identier. An InputSource can be created from a java.io.inputstream or a java.io.reader. In the code snippet below a java.io.inputstream created from a network connection is used. Once the input source is created, the SAXParser.parse() method is called to initiate parsing. // initialize URI and InputStream String uri = "http://www.project.org/dogs.xml"; InputStream inputstream = getxmldoc(uri); // create InputSource from InputStream InputSource inputsource = new InputSource(inputStream); // parse the input XML document MyEventHandler = new MyEventHandler(); saxparser.parse(inputsource, myeventhandler); Parsing operation may take a long time, that is why the parse() method must be called in its own thread to avoid freezing of the user interface. Besides, the parse() method must be enclosed within a try/catch block since it might throw an IOException or SAXException. [ia02] Sergey Sirotkin 23
7 Web Services Without JSR 172 Until recently, mobile devices such as cell phones, PDAs etc. did not support JSR 172 technology due to the fact that is simply did not exist in the form of an approved document. Until the end of 2003 the JSR 172 specications had a status of draft, which obviously did not inspire the developers to start working on any implementations based upon such a specication. And even at present, when the nal release of JSR 172 has been published by Java Community Process (on March 3, 2004), many vendors choose not to support these standards, for whatever reason. As mentioned previously, the two optional packages, JAXP and JAX-RPC, included with the J2ME platform, make the development of client applications dealing with Web Services easier and more transparent both for the platform and for developers. If these packages are not included with the platform, the developers face the need to write sophisticated software spanning all the aspects of wireless devices, wireless networks and communication routines, XML parsing, the Internet, and back-end systems residing on enterprise platforms. This task can be cumbrous and must be repeated for each new application. To avoid such repetition, a library of helper classes may be created, but this can turn complex, ineective, and always remains application-specic. Creating networked wireless applications for mobile devices requires a broad set of skills, and detailed knowledge of client technologies like the Mobile Information Device Prole (MIDP), of Java 2 Micro Edition (J2ME), of server technologies like servlets and web containers, and of the mechanisms they use to communicate with each other (Fig. 11; on the left-hand side is a wireless device, or service consumer, on the right-hand side is a server, or service provider). Figure 11: Components of a networked wireless application. 7.1 Client and Server Applications The wireless device (client) has a network-aware application installed, which is usually based on the J2ME platform's MIDP. In the Figure 12 the typical application structure is depicted. It may consist of: application logic (responsible for the user interface and general application behavior); remote service invocation and network layer (encoding requests and decoding responses). 24 University of Applied Sciences, Aargau
7 WEB SERVICES WITHOUT JSR 172 Figure 12: A wireless client application. Implementing network logic is not an easy task. It requires the detailed knowledge of how the HTTP protocol works, which services and where are available, and how to encode requests and decode responses. Remote services invocation on a server is neither trivial. Some developers introduce their own applicationspecic network protocols or XML dialects, while other developers use XML-RPC and SOAP. At the other end of the networked wireless communication are the server and back-end systems, which are typically based on the Java 2 Enterprise Edition (J2EE). The server acts as a web service provider. As shown in Figure 13, the server side application consists of a web server running servlets or Java Server Pages (JSP) engine, supporting application classes, and back-end resources such as Enterprise Java Beans components and databases. Figure 13: A wireless web server application. [ia02] Sergey Sirotkin 25
Creating the server side can also be an elaborate and cumbersome process that requires a broad set of skills, but this topic is outside scope of this paper. 7.2 Network, Protocols, and Services On MIDP devices, the transport protocol of choice is HTTP due to its exibility, availability, and integrability. This protocol is also used for popular web-services mechanisms such as XML-RPC and SOAP. The network communication via HTTP is based on a client-server model, with a client making requests to and receives responses from a server (Fig. 14). Figure 14: Communication based on a Request-response Model. A standard protocol is the only simplication for wireless application development. What varies the most is the way the data is encoded and packaged. Developers typically either rely on their own solutions, or use third-party solutions such as kxml-rpc and ksoap. Since XML-RPC, SOAP, and almost all their alternatives are XML-based, a wireless application requires to have an XML parser embedded in both the client and the server. This is another task developers have to full; again, there is a choice between an own or a third-party solution (e.g. kxml, NanoXML, TinyXML etc.). Embedding an RPC mechanism and an XML parser in each application is not only cumbrous, but also expensive, taking into consideration the platform limitations of MIDP-enabled devices. 26 University of Applied Sciences, Aargau
8 CONCLUSION 8 Conclusion This paper has introduced the JSR 172 Web Services APIs for the Java 2 Micro Edition platform, covering the essential aspects of: remote service invocation by means of Java API for XML-Based RPC (JAX-RPC); XML parsing using Java API for XML Parsing (JAXP) for J2ME. Peculiarities of Web Services support on devices that do not conform to JSR 172 are also briey discussed. The J2ME Web Services Specication (JSR 172) standardizes programming interfaces for web services and XML parsing in the J2ME platform. With the advent of the JAX-RPC subset API, developers can use the Java programming language and familiar JAX-RPC APIs to create applications that consume XML-based remote services, without having to deal with the low-level details of HTTP, SOAP, and data marshaling. And with the introduction of the JAXP subset API, XML parsing is now part of the J2ME platform itself. The J2ME Web Services API eliminates the need for developers to include code for remote invocation and XML parsing in each application. Developers dispose of more memory space and time to concentrate on their applications. As we could see, designing an end-to-end networked wireless application on a platform that does not support JSR 172 is a dicult task, which requires a broad set of skills. This is one of the reasons the Java Community Process introduced the Web Services for J2ME APIs which dene a standard approach to remote invocation and XML parsing for J2ME. [ia02] Sergey Sirotkin 27
A Glossary API Application Programming Interface CDC Connected Device Conguration CLDC Connected Limited Device Conguration DOM Document Object Model DII Dynamic Invocation Interface DTD Document Type Denition J2ME Java 2 Micro Edition J2SE Java 2 Standard Edition J2EE Java 2 Enterprise Edition JAX-RPC Java API for XML-Based RPC JAXB Java API for XML Binding JAXM Java API for XML Messaging JAXP Java API for XML Parsing JCP Java Community Process JSP Java Server Pages JSR Java Specication Request MIDP Mobile Information Device Prole OASIS Organization for the Advancement of Structured Information Standards PBP Personal Basis Prole RAM Random Access Memory RMI Remote Method Invocation ROM Read Only Memory RPC Remote Procedure Call RSS Really Simple Syndication SAAJ SOAP with Attachments API for Java SOAP Simple Object Access Protocol SPI Service Provider Interface URI Universal Resource Identier URL Universal Resource Locator UTF Unicode Transformation Format W3C World Wide Web Consortium WSDL Web Services Description Language WS-I Web Services Interoperability Organisation WS-I BP WS-I Basic Prole 28 University of Applied Sciences, Aargau
B DEMO SOURCE CODE WSA Web Services API XML Extensible Markup Language XSL extensible Stylesheet Language XSLT XSL Transformations B Demo Source Code Follows after the presentation. [ia02] Sergey Sirotkin 29