What’s New In MIDP 3.0 ? Part 4: Inter-MIDlet Communication

1. Overview

Inter-MIDlet communication (IMC) is a connection based client/server mechanism accessed through the javax.microxedition.io Generic Connection framework (GCF).

2. The IMC Client/Server Model

A server has a name and a version.

Each version of the same server is backwards compatible with all preceeding versions.

A server may specify that only an authorized MIDlet can be a client.

A client connects to a server by specifying a name and a version.

A client may also specify that the required server must be implemented by a MIDlet in a given MIDlet suite.

A client may also specify that the required server must be implemented by an authorized MIDlet.

A MIDlet can implement one or more servers and/or be the client of one or more servers.

2.2 Connection URIs

Connection URIs are used in the GCF to specify a connection to open. IMC defines two different URI formats, one for opening a server connection, and one for opening a client connection to a server.

2.2.1 Server Connection URIs

An IMC server connection URI specifies the name, version, and authorization mode of a server, and is of the form

    "imc://:"<ServerName>":"<ServerVersion>";"[<AuthMode>]

The <ServerName> must be in the same format as a Java class name.

The <ServerVersion> must be in the same format as a MIDlet suite version.

The <AuthMode> must be in the form

    "authmode=("true"|"false")

If <AuthMode> is present and is authmode=true then only authorized MIDlets can be clients of the server.

2.2.2 Client Connection URIs

An IMC client connection URI specifies a server instance to connect to. Zero, one, or more server instances may match the specification.

A client connection URI is of the form

    "imc://"(<MIDletSuiteUID>|"*")":"<ServerName>":"<ServerVersion>";"[<AuthMode>]

A <MIDletSuiteUID> is of the form

    <MIDletSuite-Vendor>":"<MIDletSuite-Name>":"(<MIDletSuite-Version>|"*")

<MIDletSuite-Vendor> can be any legal MIDlet suite vendor id.

<MIDletSuite-Name> can be any legal MIDlet suite name.

<MIDletSuite-Version> can be any legal MIDlet suite version.

Note

In the specification <MIDletSuiteUID> is referred to as <MIDlet UID>. I would argue that this is a misnomer. The MIDlet suite vendor/name/version triple identifies a MIDlet suite not a MIDlet.

If <MIDletSuiteUID> is specified then a connection can only be made to a server instance implemented by a MIDlet in the specified MIDlet suite.

If the wildcard (*) is specified instead then a connection can be made to any eligible server instance. In this case, if there are multiple eligible server instances then it is implementation specific which one is connected to.

A <Server-Name> has the same format as a Java class name.

A <Server-Version> has the same format as a MIDlet suite version number.

<AuthMode> is of the form

    "authmode="("true"|"false")

If <AuthMode> is present and is authmode=true then a connection can only be made to a server instance implemented by an authorized MIDlet.

2.2.2.1 Client Connection URI Examples

2.2.2.1.1

any version 1.0 compatible instance of the server example.Server.

    imc://*:example.Server:1.0;

2.2.2.1.2

any version 1.0 compatible instance of the server example.Server implemented by an authorized MIDlet.

    imc://*:example.Server:1.0;authmode=true

2.2.2.1.3

the version 1.0 compatible instance of the server example.Server implemented by a MIDlet in version 1.5 of the ExampleMIDletsRUs vendor’s ExampleIMCMIDlets suite.

    imc://ExampleMIDletsRUs:ExampleIMCMIDlets:1.5:example.Server:1.0;

2.2.2.1.4

the version 1.0 compatible instance of the server example.Server implemented by an authorized MIDlet in version 1.5 of the ExampleMIDletsRUs vendor’s ExampleIMCMIDlets suite.

    imc://ExampleMIDletsRUs:ExampleIMCMIDlets:1.5:example.Server:1.0;authmode=true

2.2.2.1.5

the version 1.0 compatible instance of the server example.Server implemented by a MIDlet in any version of the ExampleMIDletsRUs vendor’s ExampleIMCMIDlets suite.

    imc://ExampleMIDletsRUs:ExampleIMCMIDlets:*:example.Server:1.0;

2.2.2.1.6

the version 1.0 compatible instance of the server example.Server implemented by an authorized MIDlet in any version of the ExampleMIDletsRUs vendor’s ExampleIMCMIDlets suite.

    imc://ExampleMIDletsRUs:ExampleIMCMIDlets:*:example.Server:1.0;authmode=true

3. The IMC API

3.1 IMCServerConnection

The IMCServerConnection interface is defined in the javax.microedition.io package. It extends the existing StreamConnectionNotifier interface defined in the same package.

An instance of IMCServerConnection is returned from a call to Connector.open() when passed a server connection URI. This instance can then be used to accept connections from clients.

The interface defines the following methods.

3.1.2 getName()

This method returns the name of the server as specified in the URI used to open the connection.

3.1.3 getVersion()

This method returns a String representing version of the server as specified in the URI used to open the connection.

3.2 IMCConnection

The IMCConnection interface is defined in the javax.microedition.io package. It extends the existing StreamConnectionNotifier interface defined in the same package.

An instance of IMCConnection is returned from a call to Connector.open() when passed a client connection URI,
but also from a call to StreamConnectionNotifier.acceptAndOpen() on an instance of IMCServerConnection.

The interface defines the following methods.

3.2.2 getRemoteIdentity()

This method returns an instance of the class javax.microedition.midlet.MIDletIdentity which represents the MIDlet at the other end of this connection.

When invoked on the client side the result will represent the server MIDlet.

When invoked on the server side the result will represent the client MIDlet.

Note

The MIDletIdentity class is a new class defined in MIDP 3.0. I would suggest that it is wrongly named since an instance of MIDletIdentity actually identifies the MIDlet suite containing the MIDlet rather than the MIDlet itself.

3.2.3 getRequestedServerVersion()

This method returns a String representing the server version specified in the client connection URI associated with this connection.

When invoked on the client side the associated client connection URI is the one used to open the connection.

When invoked on the server side the associated client connection URI is the one used to open the corresponding client connection.

Using this method a MIDlet implementing a server can determine which version of the server functionality the client is expecting.

3.2.4 getServerName()

This method returns the server name specified in the client connection URI associated with this connection.

When invoked on the client side the associated client connection URI is the one used to open the connection.

When invoked on the server side the associated client connection URI is the one used to open the corresponding client connection.

3. Opening A Client Connection To A Server

A client can open a connection to a server by invoking the Connector.open() method with a client connection URI.

If the call succeeds then an instance of IMCConnection will be returned.

The call can fail if no server with the specified name exists, if a server with the specified name exists but it does not support the specified version, or if a server with the specified name and supporting the specified version exists, but it is not implemented by a MIDlet in the specified MIDlet suite.

In each of these cases a ConnectionNotFundException will be thrown.

The call can fail if a server exists but it specifies that a client must be authorized and the caller is not. In this case a SecurityException will be thrown.

The call can fail if a server exists but the client specifies that it must be implemented by an authorized MIDlet and it is not. In this case a SecurityException will be thrown.

Code Fragment

import javax.micredition.io.Connector;
import javax.micredition.io.IMCConnection;

...

    IMCConnection imcc = (IMCConnection)Connector.open("imc://*:ExampleServer:1.0;");

...

4. Opening A Server Connection

A server connection can be opened by invoking the method Connector.open() with a server connection URI.

Note

It is not clear from the specification under what circumstances a call to Connector.open() with a server connection URI can fail. It is obviously (?) an error if a MIDlet attempts to open a server connection twice using the same server connection URI, and it is presumably an error if different MIDlets in the same MIDlet suite attempt to open a server connection using the same server connection URI. It is also presumably an error if a MIDlet attempts to open a server connection twice using a server connection URI which differs only in the specified authorization mode. However, is it an error if the same MIDlet or different MIDlets in the same MIDlet suite attempt to open server connections using server connection URIs which differ only in the specified version ?

Code Fragment

import javax.micredition.io.Connector;
import javax.micredition.io.IMCConnection;
import javax.micredition.io.IMCServerConnection;

...

    IMCServerConnection imcsc = null;
	
    imcsc = (IMCServerConnection)Connector.open("imc://:ExampleServer:1.0;");

...

5. Accepting Connections From Clients

Once a server connection has been opened, connections from clients can be accepted by calling the acceptAndOpen() method of the returned IMCServerConnection instance.

Once a client connection has been accepted the server can determine the server version expected by the client using the getRequestedServerVersion() method of the returned IMCConnection instance.

Code Fragment

import javax.micredition.io.Connector;
import javax.micredition.io.IMCConnection;
import javax.micredition.io.IMCServerConnection;

...

    IMCServerConnection imcsc = null;
	
    imcsc = (IMCServerConnection)Connector.open("imc://:ExampleServer:1.0;");

    while (true)
    {
        IMCConnection imcc    = (IMCConnection)imcsc.acceptAndOpen();
        String        version = imcc.getRequestedServerVersion();
		
        ...

    }

...

6. Push Connections

An IMC server connection can be registered as a push connection either statically at installation time, or dynamically using the PushRegistry.registerConnection() method, using a standard IMC server connection URI.

The <AllowedSender> element of the value of the MIDlet-Push-<n> attribute used for static registration, or the corresponding filter argument of the code>PushRegistry.registerConnection() method can be either a <MIDletSuiteUID> or the wildcard (*).

Note

As in the definition of a client connection URI the specification actually refers to <MIDlet UID>.

6.2 Static Registration Examples

6.2.1

MIDlet-Push-1: imc://:ExampleServer:1.0;,IMCExampleServerMIDlet,*

Register version 1.0 of the ExampleServer server. Connections will be accepted from any MIDlet.

6.2.2

MIDlet-Push-1: imc://:ExampleServer:1.0;authmode=true,IMCExampleServerMIDlet,*

Register version 1.0 of the ExampleServer server. Connections will be only be accepted from authorized MIDlets.

6.2.3

MIDlet-Push-1: imc://:ExampleServer:1.0;,IMCExampleServerMIDlet,MIDletsRUs:Examples:1.0

Register version 1.0 of the ExampleServer server. Connections will be only be accepted from MIDlets in version 1.0 of the MIDletsRUs Examples MIDlet suite.

6.3 Dynamic Registration Examples

6.3.1

import javax.microedition.io.PushRegistry;

...

    PushRegistry.registerConnection(
                     "imc://:ExampleServer:1.0;"
                     "IMCExampleServerMIDlet",
                     "*");
					 
...

Register version 1.0 of the ExampleServer server. Connections will be accepted from any MIDlet.

6.3.2

import javax.microedition.io.PushRegistry;

...

    PushRegistry.registerConnection(
                     "imc://:ExampleServer:1.0;authmode=true"
                     "IMCExampleServerMIDlet",
                     "*");
					 
...

Register version 1.0 of the ExampleServer server. Connections will be only be accepted from authorized MIDlets.

6.3.3

import javax.microedition.io.PushRegistry;

...

    PushRegistry.registerConnection(
                     "imc://:ExampleServer:1.0;authmode=true"
                     "IMCExampleServerMIDlet",
                     "MIDletsRUs:Examples:1.0");
					 
...

Register version 1.0 of the ExampleServer server. Connections will be only be accepted from MIDlets in version 1.0 of the MIDletsRUs Examples MIDlet suite.

---

Copyright (c) 2009 By Simon Lewis. All Rights Reserved.