Network-Based MIDlet Launch

17.2 Network-Based MIDlet Launch

Devices can use protocols from the Generic Connection Framework (GCF) for their push functionality. (For more information, refer to Chapter 15, "MIDP Networking and Serial Communications.") Launching a MIDlet when a network connection is received is an efficient mechanism to alert users to time-critical information.

Not all protocols are appropriate for use as push connections. Even if a device supports a protocol for inbound connections, the device is not required to use that protocol in its push mechanism. For example, a device might support server socket connections in a MIDlet, but might not support launching a MIDlet in response to receiving a server socket connection.

The three tasks that enable a MIDlet to be started to handle a push notification are registration, listening, and processing of the connection. During the registration phase, the system is given the expected network connection, the MIDlet to run, and a source-address filter. Listening is done by the Application Management Software (AMS). (See Section 19.2, "MIDP System Software," for more information.) The AMS listens for the registered connections associated with MIDlets that are not running. Processing occurs when a registered connection is made: the AMS will run the corresponding MIDlet, and the MIDlet then assumes control of its connections. The steps for registration, listening, and processing are described in more detail below.

MIDlets use the methods of the javax.microedition.io.PushRegistry class to find and open connections. It uses the normal GCF classes to read, write, and close the connection.

When the MIDlet suite is active it is responsible for handling incoming connections. When the MIDlet suite is destroyed, AMS resumes listening for registered connections.

1 Registering a MIDlet to Be Launched

MIDlet suites must register for push notifications. They can register either statically or dynamically. Static registration is done by adding attributes to the application descriptor, the JAR manifest, or both. It is called static registration because it uses information that is present at installation time. Static registrations remain valid until the MIDlet suite is removed from the device. Dynamic registration is done with the methods of the PushRegistry class. It is called dynamic registration because MIDlets can enable and disable push notifications as needed. They can also modify registrations as needed.

If a MIDlet requires a particular connection in order to function correctly and will not need to change that connection while the MIDlet is on the device, the application developer should use static registration. Two MIDlet suites on a device cannot use the same connection. If two MIDlet suites have a push connection in common, they cannot be on the device at the same time and still function correctly. The device checks for connection conflicts at installation. If all the static push declarations can be fulfilled, then installation proceeds. If not, the user is notified that there are conflicts, and the MIDlet suite is not installed. (Refer to Chapter 19, "MIDlet Deployment," for connection-conflict errors.) The end-user typically uninstalls one MIDlet in order to successfully install the other.

If a MIDlet can be flexible in its push connections, the application developer should use dynamic registration. That is, dynamic registration is for MIDlets that can use (but do not require) a connection, require a connection for only a short period of time, do not need a well-known endpoint, or might have to change the connection during their lifetime. For example, consider a MIDlet that exchanges data with a server application using a private protocol and can allow the device to allocate a port. The MIDlet could open a connection without specifying a port number, causing the device to allocate an available port. Using the information in the open connection (such as the allocated port), the MIDlet would dynamically register the connection. The MIDlet would also send the connection information to the server application. The MIDlet and server application can then use this connection until the MIDlet unregisters or changes it.

2 Mechanics of Static Push Registration

An application developer declares a static push registration with the MIDlet-Push-n attribute. The attribute can be in either the MIDlet suite's JAD file or JAR manifest. During installation, the device registers the MIDlet to accept those connections. Each push registration entry consists of a colon-separated attribute-value pair. The attribute is to the left of the colon (:); the value is the comma-separated list to the right:

MIDlet-Push-n: ConnectionURL, MIDletClassName, Filter

• MIDlet-Push-n: attribute name. Multiple push registrations can be provided in a MIDlet suite. The numeric value for n starts from 1 and must use consecutive ordinal numbers for additional entries. The first missing entry terminates the list. Any additional entries are ignored. (Note that the n value of this attribute does not correspond to the n value of the MIDlet-n attribute. MIDlet-Push-1 does not have to declare a push connection for the MIDlet-1.)

• ConnectionURL: connection string used in the Connector.open method.

• MIDletClassName: MIDlet responsible for the connection. The MIDlet class name must correspond to a MIDlet class name in a MIDlet-n attribute. If the named MIDlet appears more than once in the suite, the first matching entry is used. The device uses this information when it displays messages to the user regarding the applications. For example, it displays messages when it has detected push connections or when the user has granted or revoked permissions.

• Filter: restriction on which senders are valid for launching the requested MIDlet. The syntax and semantics of the Filter field depend on the addressing format used for the protocol. However, every filter can use the wildcard characters "*" and "?". The semantics of those wildcard characters are:

  • *: matches any string, including an empty string. When the Filter value is only this character, connections will be accepted from any sender.

  • ?: matches any single character.

  The MIDP Specification version 2.0 defines the syntax for datagram and socket inbound connections. The Filter for these push attributes must contain a numeric IP address in the same IPv4 and IPv6 formats as their respective URLs. (An IPv6 address includes the square brackets, as in the URL.) It is possible to use wild cards in the IP addresses. For example, 129.70.40.* allows subnet resolution. The port number is not part of the filter.

  When other specifications define push semantics for additional connection types, they must define the expected format for the connection URL string and the expected syntax for the filter field.

The following example shows two entries. One would reserve a stream socket at port 79 and the other a datagram connection at port 50000. (Port numbers are maintained by IANA and cover well-known, user-registered, and dynamic port numbers. See IANA Port Number Registry.)

MIDlet-Push-1: socket://:79, com.sun.example.SampleChat, *
MIDlet-Push-2: datagram://:50000, com.sun.example.SampleChat, *

Static push registrations can cause errors during installation. Conditions that cause installation failure are syntax errors in the push attributes, declaring a connection endpoint that another MIDlet has already reserved, declaring a protocol that the device does not support for push, and referencing a MIDlet class name that is not listed in the MIDlet-n attributes of the MIDlet suite.

A conflict-free installation reserves the requested connections for the exclusive use of the MIDlets in the MIDlet suite. If another application tries to open one of the connections, the attempt will fail with an IOException. In contrast, if a MIDlet in the suite tries to open one of the connections, the call will succeed unless the suite already has the connection open.

3 Mechanics of Dynamic Push Registration

The PushRegistry.registerConnection method registers a dynamic connection with Application Management Software (AMS). Once registered, the dynamic connection acts just like a statically registered connection. The arguments for the dynamic connection registration are the same as the Push-MIDlet-n attribute used for static registrations: the MIDlet must provide the connection string, the MIDlet to launch, and the filter string. The connection string includes the scheme, host, and port number as appropriate. The connection string can also include optional parameters, separated with semicolons. The MIDlet to launch must be listed in one of the MIDlet suite's MIDlet-n attributes. The filter argument indicates which senders' addresses are allowed to launch the MIDlet. See Section 17.2.2, "Mechanics of Static Push Registration," for more information.

Several kinds of errors can occur during dynamic registration. The device throws an IllegalArgumentException if the connection or filter arguments are null, a ClassNotFoundException if the MIDlet argument is null or names a class that cannot be found in the MIDlet suite, a ConnectionNotFoundException if the runtime system does not support push notification for the requested connection protocol, and an IOException if the connection is already registered or if there are insufficient resources to handle the registration request. The device throws a SecurityException if the MIDlet does not have permission to register a push connection. See Section 17.5, "Security of the Push Registry," for more detail.

The listConnections method gets a MIDlet suite's registered connections; it returns an array of strings, one for each connection. If the method is called with an argument true, the array contains only the connections that have input available; if the argument is false, the array contains all of the MIDlet suite's connections. Each connection string can be used with the getMIDlet and getFilter methods to return the other fields from the push registration. The getMIDlet and getFilter methods return null if the connection was not registered by the current MIDlet suite or if the connection argument was null.

The unregisterConnection method removes dynamic registrations. An application developer calls the method with the same connection string used for the registration. The unregisterConnection method returns true if the removal was successful and false if the connection was not registered or if the connection argument was null. It throws a SecurityException if the connection was registered by another MIDlet suite. If the user deletes the application from the device, its dynamically registered push connections are unregistered automatically.