MIRAE

User's Guide

Contents

Introduction to MIRAE
Basics of Accessing Web Services
Building stubs and Associate classes
Intergrating the Mobile appliication with MIRAE

Introduction to MIRAE

Mirae is a Web services sub-project to implement JSR 172.

JSR 172 provides support for accessing Web services on the J2ME platform. It will deliver two new features to the J2ME platform:

1) Accessing SOAP based remote Web services from the J2ME platform.

2) Giving XML parsing support to the J2ME platform.

ABOUT THE NAME: "Mirae" (pronounced 'mee re' (as in 'red')) means future in Korean. Also the Japanese word for future is "Mirai" .. which is nearly the same.

Here the Mobile application developer may able to use the XML parser for j2me platform independent of other modules. In addition to that they can use the web services api for developing mobile applications which contain the logics of invoking remote web services.

MIRAE provides WSDL2WS_J2ME tool to generate the required stub classes to invoke the web services.

Basics of Accessing WEB Services

Before running the samples, the user need to make sure that his CLASSPATH includes the following jar files.

wsdl2ws_j2me.jar

axis.jar

commons-discovery.jar

commons-logging.jar

jaxrpc.jar

log4j.jar

Saaj.jar

Wsdl4j.jar

Now let's travel through the MIRAE. First of all let's take a look at an example rpc Web Service client stub that will call the addPoint method on the remote web server.

public PointStub() throws Exception{
this.enduri="http://localhost:8080/axis/services/Point";
this.SOAPAction = new javax.xml.namespace.QName("PointService");
}
public ws_mobile_point.Point addPoint(ws_mobile_point.Point 
  param0,ws_mobile_point.Point param1) throws Exception{
javax.xml.namespace.QName methodName = new javax.xml.namespace.QName("urn:ws_mobile_point","addPoint");
j2me.xml.rpc.Call call = new j2me.xml.rpc.Call();
call.setStyle(j2me.util.Constants.STYLE_RPC); 
call.setOperationName(methodName);
call.setPortTypeName(SOAPAction);
call.addParameter(param0,"param0", new javax.xml.namespace.QName("urn:ws_mobile_point","Point"));
call.addParameter(param1,"param1", new javax.xml.namespace.QName("urn:ws_mobile_point","Point"));
call.setTargetEndpointAddress(this.enduri);
call.setReturnCategory(j2me.util.Constants.TYPE_COMPLEX);
call.setReturnType( new ws_mobile_point.Point());
ws_mobile_point.Point res = (ws_mobile_point.Point)call.invoke();
return res;
}

The target end point URI and the SOAPAction(web service name) are specified in the default constructor.
Here we define the operation (method) name of the Web Service.
Call object is used to store metadata about the service to invoke.
Input parameters to invoke the remote method are added
Finally the service is invoked and the result is received.

(Since it is a jax-rpc subset it will be easier for a developer to develop)

Building Stubs and Associate classes for RPC

WSDL2WS_J2ME tool accepts wsdl file and generates client side stubs which provides

the mean for accesing a specific web service defined by the wsdl file.

You'll find the WSDL2WS_J2ME tool in "org.apache.mirae.wsdl2ws.WSDL2Ws". The basic

invocation form looks like this:

% java org.apache.mirae.wsdl2ws.WSDL2Ws (WSDL-file-URL)

This will generate those bindings necessary for the client. Here it follows the JAX-RPC

specification when generating Java client bindings from WSDL. For this discussion,

assume that we use Point.wsdl and we executed the following:

% java org.apache.mirae.wsdl2ws.WSDL2Ws Point.wsdl

The generated files will reside in the directory "ws_mobile_point" which is in the genstub

directory which is in the current directory. They are put here because that is the target

namespace from the WSDL and namespaces map to Java packages.

If we specify the output directory as follows the generated files will reside in the

directory "ws_mobile_point" in the specified directory.

% java org.apache.mirae.wsdl2ws.WSDL2Ws Point.wsdl -o /samples/point

There is an Ant Task to integrate this action with an Ant based build process.

This will generate the following files

Point.java: New interface file that contains the appropriate remote usage.

PointStub.java: Client side stub.

(Array types): Java files will be produced for all of the other array types. There are no additional files for the Point web service.

Now you have all of the necessary files to build your client side code and access the web service!

Intergrating the Mobile Application with the MIRAE

Let us consider the folloing Mobile application for accessing web services.

public class PointClientMIDLet extends MIDlet implements CommandListener, Runnable{

//.........
public void commandAction(Command command, Displayable displayable) {
if(command==sendCommand){
Thread thread =new Thread(this);
thread .start(); 
}
public void run(){
try{
Point p1 = new Point(20,4);
Point p2 = new Point(10,3); 
PointStub stub =new PointStub(); 
Point p=stub.addPoint(p1,p2); 
int x=p.getX();
int y=p.getY();
}catch(Exception e){}
}
}

This mobile application is a class extended from abstract MIDLet class ant it implements CommandListener and Runnable interfaces.

The very important thing is that the operations defined in the generated stub class should be accessed by a different thread other than the main thread. If it is called by the main thread it will cause deadlock. So that the operations of the stub class is accessed within the run() method.

Here the user should specify the input parameters in correct format as the service needs when the method is invoked.

The received result may be further processed according to the need.