MobileRPC Documentation

What is MobileRPC

MobileRPC is a tool which generates all necessary files to enable Remote Procedure Calls between J2ME client application and Java servlet server. Three types of files are generated:

Files for structures. Structure is a JavaBean class with methods for serializing properties. Each structure class has readObject(java.io.DataInput) and writeObject(java.io.DataOutput) methods. MobileRPC supports inheritance of structures.
Files for exceptions. You can define any number of exceptionds which will be thrown by interface methods. Each exception has message. MobileRPC supports inheritance of exceptions. By default an exceptions is inherited from the java.lang.Exception.
Files for structures and exceptions are the same for a J2ME application and server part of an application.
Files for interfaces. For every defined interface MobileRPC generates one file for J2ME part of an application and one file for server part.
J2ME file is a stub. Each method of a stub has code to establish connection with a server, serialize method parameters, deserialize mothod result, process exceptions etc. In addition to user defined exceptions each method throws java.io.IOException to indicate any communication problem. Stub has one costructor with String parameters. This parameter is a URL of this interface servant.
Server file is an abstract servlet. This servlet has an abstract method for every method defined in an interface definition. All you need is create a subclass of this abstract servlet with method implementation and register your implementation in web application's web.xml file.

MobileRPC Tool Usage

Use java -jar MobilePRC.jar <config file> <server dir> <j2me dir> to generate files. <config file> is a file with interface definition. <server dir> is a root of your server's source tree, MobileRPC will put server files to appropriate subdirectories of the <server dir>. <j2me dir> is a root of your j2me client source tree, MobileRPC will put client files to appropriate subdirectories of the <j2me dir>.

MobileRPC Interface Definition Format

MobileRPC configuration file is an XML file. It's root element must have mobileRPC name and has three attributes. commonPackage attribute specifies java package where MobileRPC will put common files for J2ME and server parts. These files are structures and exceptions. serverPackage attribute specifies package for server files. Server files are abstract servlets. j2mePackage specifies java package for J2ME interface stubs files.
Example:

    <mobileRPC commonPackage="example.common" serverPackage="example.server" j2mePackage="example.j2me">
        ...
    </mobileRPC>

Inside the mobileRPC there are three possible children elements: struct, exception and interface.

struct element defines structs. struct element has name attribute which defines name of the struct and optional extends attribute which defines superclass of the structure.
Inside the struct element there can be constant and attribute elements.
constant element defines structure's constants. It will become public static final field of the java class. constant element has name, type, optional arrayand value attributes which define field's name, type and value respectively. attribute is any java code to initialize attribute. If array attribute has true value it means that the constant has array type.
attribute element defines structure's attribute. MobileRPC will generate getter and setter method for every attribute and a constructor to initialize all structure attributes. Default constructor will be also generated. attribute element has name, type and optional array attributes. name and type define attribute name and type. If array attribute has true value it means that the attribute has array type.
Example:

    <struct name="Document" extends="IdNameObject">
        <constant name="TEXT_TYPE" type="int" value="0"/>
        <constant name="IMAGE_TYPE" type="int" value="1"/>
        <attribute name="type" type="int"/>
        <attribute name="modificationDate" type="java.util.Date"/>
    </struct>

exception element defines exceptions. exception element has name and optional extends attributes. name attribute is exception class name, extends attribute is exception superclass name. If extends attribute is missed java.lang.Exception is used as superclass.
Example:

    <exception name="SecurityException"/>
    <exception name="NoPermissionException" extends="SecurityException"/>

interface element defines interfaces. interface element has name attribute which defines an interface name.
interface element can have zero or more constant element just like structure element.
interface element has one or more method elements. method element has name and optional returnType, array and throws attributes. name attribute defines method name. If returnType exists it defines method return type otherwise method is void. If array attribute has true value it means that the method return type is array type. throws attribute is a comma separated list of exceptions thrown by the method.
method element has zero or more parameter elements which define mehtod parameters. Attributes of the parameter element are the same as attributes of the attribute element.
Example:

    <interface name="TreeInterface">
        <method name="getTree" returnType="Node" throws="DatabaseException, NoPermissionException"/>
        <method name="getDocuments" returnType="Document" array="true" throws="DatabaseException, NoPermissionException">
            <parameter name="nodeId" type="long"/>
        </method>
    </interface>

Supported Types

The following types are supported by MobileRPC:
boolean
byte
short
int
long
char
String
Boolean
Byte
Short
Integer
Long
Character
java.util.Date
Also every structure is available as type after declaration.

Artem Rudoy