The following sample code shows, how a store can be implemented on a filesystem. Every node that does not contain JUMPData is represented as a directory in the filesystem and every data node is represented in a single file say data.properties. Each line in the data.properties file contains the following information. data-name,data-type,data-value

  public class FileStoreImpl implements JUMPStore {

     public void createDataNode(String uri, JUMPData jumpData) {

        // get the full path of the file that holds the data for the
        // uri passed.
        File file = uriToDataFile(uri);
        // the data name is the last component of the URI.
        String dataName = getDataName(uri);
        String marshalledData = createMarshalledData(dataName, jumpData);
        OutputStream stream = createOutputStream(file);
        stream.writeString(marshalled);
      
        // The impl might create an instance of JUMPNode containing the jumpData
        // eagerly here, or delay until it is requested by getNode(String uri) 
        // call below.
     }

     public void createNode(String uri) {
        File file = uriToFile(uri);
        file.mkdirs();
     }                  

     public JUMPNode getNode(String uri) {
        // getNode(String) needs to return what the createDataNode() above store
        // if the uri parameter represents a data node.
   
        if (!isDataFile(uri)) {

            // This URI represents non-leaf node.
            // .... then do something to create a JUMPNode representing a List,
            // and return it.

        }  else {    
   
            File file = urlToDataFile(uri);
      
            String name = getDataName(uri);
            InputStream stream = createInputStream(file);
            String marshalledData = stream.readString();
      
            JUMPData data = createUnmarshalledData(marshalledData);
      
            JUMPNode node = createJUMPNode(uri, name, data);
      
            return node;
        }
     }

     public void deleteNode(String uri) {
        File file = uriToFile(uri);
        file.delete();
     }

     public void updateNode(String uri, JUMPData jumpData) {
        // check if the node represented by the uri exists and is data.
        if (!isDataFile(uri) || !exists(uri) ) {
           throw new java.io.IOException("Update failed"); 
        }
 
        // delete the old node and create a node with the new data.
        deleteNode(uri);
        createDataNode(uri, jumpData);
     }
   
     private String createMarshalledData(String dataname, JUMPData data) {
        // Create a representation of JUMPData's content to be written out to the file.
        // This method does not have to process anything in JUMPData data, but merely to
        // come up with a String representation of the JUMPData content that works the
        // opposite way of createUnmarshalledData.  The returned type, String, is also
        // just for the implementation example, and can also be in any other format.
     }

     private JUMPData createUnmarshalledData(String marshalledData) {
        // Creates a JUMPData out of the "marshalledData" representation.
        // This method should just do the opposite of createMarshalledData(JUMPData).
     }
  } 
  

  public class Application {
     
     public String getTitle() {
        return title;
     }
     
     public String getIconPath() {
        return iconPath;
     }
  }
  
  public class AppRepository extends JUMPContentStore {
      private static final String ROOT_URI = "./Apps";
      private Class storeClass = JUMPFileStore.class;
      
      
      protected JUMPStore getStore() {
         return JUMPExecutive.getInstance().getModule(this.storeClass);
      }
      
      public Application getApplication(String name) {
          Application app = new Application();
          // get access to the store in a read-only mode
          JUMPStoreHandle storeHandle = openStore(false);
          
          JUMPNode.Data appNode = (JUMPNode.Data)
            storeHandle.getNode(ROOT_URI+"/"+name+"/title");
          app.setTitle(appNode.getString());
          appNode = (JUMPNode.Data)
            storeHandle.getNode(ROOT_URI+"/"+name+"/iconPath");
          app.setIconPath(appNode.getString());
          
          // indicate that we do not need the store any more
          closeStore(storeHandle);
          return app;
      }
  }
  
  

All native events are transferred from an underlying platform by means of JavaCall events mechanism and the respective JavaCall API. Each event consists of the following fields:

• type - an integer representing number of the JSR that corresponds to this event;
• id - an integer that allows to distinguish event sub-types within one JSR;
• data - a byte array holding whatever additional data is needed to be passed with the event (data size is limited by the JavaCall implementation).

Each JSR that is interested in some type of platform events must have a class (probably, also an executive module) that implements JUMPEventHandler interface, and register it as a handler for a certain type of events. For instance, this is how JSR-75 module will register itself:

  public class FileSystemModuleImpl implements JUMPModule, JUMPEventHandler {
      public void load(Map config) {
          JUMPEventQueueModule eventQueue = JUMPEventQueueModuleFactory.getInstance().getModule();
          eventQueue.registerEventHandler(75, this);
          // more initialization here...
      }
  
      public void handleEvent(int id, byte[] data) {
          // event processing code here...
      }
  
      // more fields and methods...
  }
  

After a handler has been registered, all events of the respective type that appear in the queue will be passed to this handler for processing. The event handler itself may process events in a separate thread, if it is reasonable.

When a new native event arrives, the receiving thread wakes up, enqueues the event data and causes the processing thread to wake up. The processing thread gets the event from the queue and tries to find a registered handler for this type of events. If a handler is found, the corresponding event handler is executed.

The internal logic of event handlers is completely up to JSRs. However, their lengthy execution can affect the event system itself (by delaying the next event being retrieved from the queue), so potentially slow or blocking event handlers should use another thread for processing and return as soon as possible.

Porting information

Application Manager Example

The Application Manager component is an example user interface for managing existing applications. The component enables the user to perform various actions on installed MIDlet suites. It provides the ability to perform the following tasks:

• Show a list of installed applications
• Show information about an application
• Show the Sun copyright.
• Delete a MIDlet suite
• Invoke a selected MIDlet
• Modify a MIDlet suite's security permission level

Detailed Design

The example application manager is implemented as three MIDlets in the com.sun.midp.appmanager package. All of the MIDlets use the MIDletSuiteStorage class in the com.sun.midp.midletsuite package to access persistent application storage services.

The Manager class implements application selection. For maximum code reuse, the application information and security settings are implemented in the AppInfo and AppSettings classes. The Manager always has at least one application, the example Discovery Application. The figure below shows the dependencies between classes.

To highlight a newly-installed MIDlet suite on startup (a user-experience feature), the Manager checks the RMS record store of the internal suite, find any MIDlet suite identifiers (suiteIDs) written by the Graphical Installer MIDlet. If it finds a suiteID, the Manager highlights the corresponding MIDlet suite, then erases the suiteID from the record store.

@since CHAPI 1.0

Supported Signatures:

Supported Message Digests:

Supported Ciphers:

Adding a New Event Type to the MIDP Java Event System

1. First select the new event type ID to be next the highest one in midpEvents.h. Add the new event type ID to midpEvents.h
2. If the event is a native event and there a not enough fields in NativeEvent, add the required fields to both NativeEvent and MidpEvent midpEvents.h. Follow the generic naming scheme.
3. Implement an EventListener.

class MyListener implements EventListener {
    public boolean preprocess(Event event, Event waitingEvent) {
        // only one of these events should be in the queue at a time

        if (waitingEvent == null) {
            // let the event be put in the queue
            return true;
        }

        ... merge the new event into the waiting event ...

        // signal that this event should not be put in the queue
        return false;
    }

    public void process(Event genericEvent) {
        MyEvent myEvent = (MyEvent)genericEvent;

        ... process the event ...
    }
}

4. Add code to obtain a security token for the class that is going to register the event listenter or post an Java event. The code depends on if the class is optional or not. If the class to receive the security token is optional then the class must implement the ImplictlyTrustedClass interface and have a public no argument constructor and so an instance of the class can be loaded by name in the initializeInternalSecurity method of the MIDletSuiteLoader and be given a token. If the class normal part of MIDP it can just implement a static method that sets the classes security token if the token has not already been set and insert a call to this static method in initializeInternalSecurity.

Previous and Currently Implemented Thread Models

To speed up Java to Java events like repaints a Java level queue was introduced to avoid the any native method calls. Processing was in one thread and native methods were feed into the Java queue by another thread to avoid polling the native event queue. This boosted the repaint rate three fold.

To speed up native event response during continuous event activity, the thread switch that occurred to process a native event after it was read was eliminated. This was done by letting the Java queue processing thread read events in a non-blocking way after a it had processed the pending Java events. To avoid polling when the processing thread ran out of events to process the queue would sleep. Just before sleeping, the Java queue processing thread wakes up a separate thread that monitors the native event queue in a blocking fashion, wakes up the Java queue processing thread when a native event was available to be read and goes to sleep. This model is used by the real device implementation and will be used for Leap Frog.

Discovery Application Example

The Discovery Application component is an example of an application that finds MIDlet suites to download and install. The component is primarily a user interface, but also has some logic. It receives a URL from the user and displays a list of MIDlet suites at that URL. When the user selects a MIDlet suite, the component invokes the OTA Installer with the URL of the MIDlet suite.

The Discovery Application example supports HTTP URLs, but does not support HTTPS URLs because there is no error handling for certificate exceptions. Because HTTPS connections are also HTTP connections, the Discovery Application accepts them and attempts to use them.

Detailed Design

The Discovery Application example is implemented as a MIDlet called DiscoveryApp. It invokes the OTA Installer, which is a MIDlet called GraphicalInstaller. The Discovery Application is considered part of the internal MIDlet suite of ROMized applications. Java stack implementation grants the internal MIDlet suite the special permissions required to access classes restricted to externally installed suites. See "Classes Used by Internal MIDlets" in the porting guide for more information about the internal MIDlet suite's permissions.

The DiscoveryApp MIDlet is included for testing and demonstration purposes only, and must be replaced by a more robust application on the production quality device. For example, if a browser is already on the device, it can be configured to invoke the GraphicalInstaller MIDlet when a downloaded resource has a MIME type that corresponds to a JAD or JAR file, instead of building a custom Discovery Application.

The Discovery Application component reads HTML pages so that it can be replaced with standard web tools. So that the web pages that contain MIDlet suites can have other data and other links in addition to pointers to JAD and JAR files, the component only shows the links that end with .jad or .jar. All URLs must be absolute, and JAR file URLs must end with .jar.

Graphical Installer Example

The Graphical Installer component is an example that interacts with the user to install MIDlet suites. It uses the HTTP protocol, in accordance with the MIDP Specification.

Detailed Design

The Graphical Installer example consists of the GraphicalInstaller class and the SecureInstaller class. The GraphicalInstaller is considered part of the internal MIDlet suite of ROMized applications. Java stack implementation grants the internal MIDlet suite the special permissions required to access classes restricted to externally installed suites.

The GraphicalInstaller accepts the following three arguments as application properties:

• arg-0 ­ Either "U" if the application is being updated by the application manager or "I" if the user selected the URL from a discovery application
• arg-1 ­ An HTTP or HTTPS URL to a JAD or JAR file
• arg-2 ­ An optional application name to display in the title bar instead of "Application"

The GraphicalInstaller starts the SecureInstaller in its own thread. Then, based on callbacks from the SecureInstaller, it presents different forms (confirmation, password entry, or progress) to the user. It runs until the installer or the user ends the process.

Diagram showing the graphical installer class

The SecureInstaller performs the functions common to all installers written in the Java programming language, including HTTP handling, application verification, and storage. See "Installer Services" below for information.

After a successful installation, the Graphical Installer stores the new MIDlet suite's suiteID in a settings record store of the internal MIDlet suite. The diagram below shows the sequence of events that occur during a simple MIDlet download and installation.

Java Installer Services

Installer services are provided for Java platform and C-based installers. For the Java platform, the SecureInstaller provides a framework that handles the non-user-interface parts of MIDlet suite installation. This consists of getting the MIDlet suite from an HTTP server into MIDlet suite storage as specified by the MIDP Specification, including the optional public key infrastructure (PKI) authentication for MIDlet suites. For C, MIDP Optimized Implementation software provides a collection of primitive installer functions, but no HTTP or PKI authentication support.

SecureInstaller Detailed Design

The Installer class provides the following functionality:

• Bypass JAD processing for JAR only suites
• Stores and updates MIDlet suites in MIDlet suite storage
• Determines the initial permissions of a MIDlet suite (when updating, the previous user-level permissions are kept if they apply to the new suite)
• Notifies the servers listed in the MIDlet-Notify attribute of the installation's success or failure
• Posts any pending deletion notifications
• Registers static push connections
• Rejects incoming push notifications while installing a MIDlet suite
• Handles the following aspects of the HTTP and HTTPS protocols:
  • HTTP retries, but waits no more than 60 seconds
  • HTTP authentication fields
  • HTTP proxy-authentication fields
  • User-Agent field (microedition.profiles and microedition.configuration)
  • Accept field (*/* for HTML link, OTA MIME type for MIDlet-Jar-URL)
  • Accept-Language field (microedition.locale)
  • Accept-Charset field (UTF-8 and ISO-8859-1)
• Checks that the JAD file and manifest contain the required properties
• Ensures that the MIDlet suite can fit on the device
• Compares the old and new URLs when updating a MIDlet suite
• Checks for existing RMS data when updating a MIDlet suite, and removes it if required

The Installer class does not support the following:

• HTTP redirection response codes

The SecureInstaller class is a subclass of Installer and adds authentication of MIDlet suites that are signed with public keys. The figure below shows the SecureInstaller class and its dependencies with other Java stack implementation components.

AutoTester

The AutoTester is a MIDlet that installs and runs sequences of tests without user intervention. The TCK and the QA Test Suite use this component. This MIDlet must not be included with the code on production implementations.

In addition, the AutoTester includes the following functionality:

• Enables the tester to assign a permission domain to unsigned test suites at a given URL. This provides automated testing without the requirement to sign test suites.
• Removes the RMS record stores of the previous version of a MIDlet suite when it updates the suite.
• Removes the last version of the test suite after the last test is run. The last test is indicated by a return code of 404 on the next update.
• Waits and retries when an HTTP retry response code (505) is received from the test server.
• Ends the testing immediately upon receipt of a system shutdown.
• Tries to resume the testing by updating the test suite after an error, including a VM abort. The one exception is when the MIDlet suite cannot be found.
• Provides a batch mode. It checks the application properties for the URL and permission domain before showing the parameters form to support running the AutoTester MIDlet from the command line in batch mode.

Detailed Design

The AutoTester is implemented in the AutoTester class of the com.sun.midp.installer package. It is considered part of the internal MIDlet suite of ROMized applications, and is granted the special permissions required to access classes from which externally installed suites are restricted.

The AutoTester can run interactively or in batch mode. To run the AutoTester in batch mode, the test engineer must supply arg-0, and optionally can supply arg-1. If property arg-0 is present, the AutoTester uses it as the URL for the test suite. If arg-1 is present, the AutoTester uses it as the unsigned suite permission domain. In batch mode, the default permission domain is maximum. The maximum domain requires the least amount of tester interaction. If the user does not supply arg-0, the AutoTester runs interactively and queries the user for the two parameters.

Note that none of the security of the MIDP runtime environment is bypassed to automate runtime API testing. Security checks cannot be accidentally or intentionally bypassed on the end-user device. Test engineers must conduct authentication and authorization installation testing interactively with the Graphical Installer, not the Autotester.

AutoTester depends on the SecureInstaller and the MIDletSuiteStorage classes, as shown in the figure below. The AutoTest.startApp method starts the SecureInstaller in its own thread. If the installer does not return a result of "MIDlet suite not found", two calls are made in that thread to the MIDletSuiteStorage API. One call schedules the AutoTester to be the last MIDlet to be run (this how the MIDlet is looped). The other call schedules the installed suite to be the next suite run. At that point, the AutoTest MIDlet ends.

The SecureInstaller performs the installer functions common to all Java platform installers, including HTTP handling, application verification, and application storage. See "Installer Services" on page 166 for information. One part of the AutoTester that cannot be used in the Java layer is to retry when the VM aborts. To handle this, a loop was added to the native function that runs MIDlets.

Unlike the Graphical Installer that queries users for information requested by the SecureInstaller, the AutoTester does not query the user. Instead, the AutoTester automatically provides yes for download confirmations and no for security questions and considers HTTP password requests as fatal errors.

The figure below shows the sequence of actions taken by the AutoTester.

The native porting API for L2CAP protocol is collected in btL2CAPSocket.h file.
This API has GNU sockets style but could be used for other non-sockets underlying Bluetooth implementations too.
There are two entities in the API: client connection and server connection. Some functions can be applied only for dedicated entity but other functions are common.

Native connection handles stored in fields of the L2CAPConnectionImpl and L2CAPNotifierImpl Java classes are accessed only from native code to avoid race conditions.
All KNI-oriented code is located in these two files and the porting layer is used to call native platform-specific connection methods.
There are no global native variables except jfieldID variables that are set once by static initializers and can be safely used by multiple isolates.
Native finalizers are used to release all native resources used by connections.

The following environment variables are used by JSR 82 build system:

1. USE_JSR_82 turns on JSR 82 building process in phoneME project build system.
2. JSR_82_DIR specifies path to JSR 82 workspace.
3. USE_JSR_82_EMULATOR switchs between real mode and emulation mode.

For files with .jpp extension Java pre-processor is called to generate emulator or real mode specific code depending on the value of USE_JSR_82_EMULATOR environment variable.

The following romizer tunings in jsr82_rom.config are done:

1. Renaming is disabled for the fields accessed via KNI_GetFieldID.
2. Renaming is disabled for the classes that are instantiated via Class.forName().
3. Internal packages are made hidden. Non-romized code is prevented from accessing even public methods/fields of classes in these packages.
4. Public JSR API are restricted. Non-romized code cannot load new classes into them.

This stack has own technology to manipulate properties. It uses .xml configuration files for this purpose.
So the properties were moved to dedicated configurator files. Three configuration files were created: common, emul and linux.

Currently own trace system is used for debugging. Later it could be replaced using common logging system.
Current trace system is located in btMacros.h. The following macros are declared: PRINT_INFO, PRINT_ERROR and EXCEPTION_MSG.
It's possible independently to swith on/off each of them. For instance, it a good approach to switch on EXCEPTION_MSG macro during developing to cache problems easier but switch it off in release to reduce code footprint.

TCK and JDTS test frameworks could be used to test the implementation.
The following permissions need to be enabled in JDTS: Connector.comm, Connector.bluetooth.client, Connector.bluetooth.server.

This is the optimized implementation for WMA 2.0, which provides classes that allow Java applications to access CBS functionality on a mobile device.

CBS Implementation

The CBS has its own Protocol implementation that calls the native platform's CBS functionality.

• The CBS URL connection string does not support a designated host.
• The CBS Connector.open() will throw an IOException if an attempt is made to open for WRITE, since it is an inbound-only protocol.
• Attempts to call send will throw an IOException.

Sending Messages to a CBS Port

CBS support is only available for inbound messages. The rules for fragmenting large messages and the basic payload types for GSM 7-bit text, UCS-2 text, and binary messages are the same for CBS and SMS messages.

irdaobex protocol is implemented in two Java classes, IrNativeConnection and IrNativeNotifier. .Native. prefix is used to identify that these classes are mostly implemented in native code, and are intended to use with non-emulation build. No corresponding implementation is available for emulation build at the moment.

The porting interface is defined in IrConnection.h header file. Most of the functions declared there need to be implemented accordingly during the porting. In some cases, ir_connect_complete() is not required, when the connection establishment is known to be synchronous.

This is the optimized implementation for WMA 2.0, which provides classes that allow Java applications to access MMS functionality on a mobile device.

This implementation provides its own Protocol.java that makes native calls to access the platform provided MMS functions.

The classes in this package support the sending and receiving of MMS messages. The classes in this package, {@link com.sun.midp.io.j2me.mms.Protocol Protocol}, {@link com.sun.midp.io.j2me.mms.MMSAddress MMSAddress} and {@link com.sun.midp.io.j2me.mms.MultipartObject MultipartObject} define this implementation. MultipartObject extends MessageObject and implements a MMS message. MMSAddress provides MMS address parsing and validation.

Connection and Message Lifecycle

Connections can be made in server mode or in client mode. In server mode, messages can be sent or received. In client mode, messages can be sent only. Applications can treat sending and receiving independently.

To receive messages, the application can open the connection by passing a string containing an "application ID" to the Connector.open method. A MessageConnection object is returned, on which the message can be received. If there are no messages in the queue, the receive() method will block until one arrives. When a message has been received, methods are available in the MessageObject class for retrieving its address and data parts. Calling the close() method closes the connection.

To send messages, the application will either obtain an existing Message object or use the newMessage factory method to create one. If the application creates a Message object, methods are available in the MultipartObject class for setting its address and data parts. The application can open a connection by passing a string containing a fully-qualified MMS URL address to the Connector.open method. A MessageConnection object is returned, on which the message can be sent. Calling the close() method closes the connection.

For more information about the SIP protocol, consult the JCP JSR180 SIP for J2ME specification and the IETF RFC3261 specification.

For more information about the SIPS protocol, consult the JCP JSR180 SIP for J2ME specification and the IETF RFC3261 specification.

This is the optimized implementation for WMA 2.0, which provides classes that allow Java applications to access SMS functionality on a mobile device.

The classes in this package support the sending and receiving of SMS messages. The classes in this package, {@link com.sun.midp.io.j2me.sms.Protocol Protocol}, {@link com.sun.midp.io.j2me.sms.MessageObject MessageObject}, {@link com.sun.midp.io.j2me.sms.TextObject TextObject}, {@link com.sun.midp.io.j2me.sms.BinaryObject BinaryObject} and {@link com.sun.midp.io.j2me.sms.TextEncoder TextEncoder} define this implementation. MessageObject defines the implementation of the SMS message. TextObject and BinaryObject extend MessageObject and represent the two possible types of SMS messages. Text messages can be enocded as GSM 7-bit text or UCS2 characters. The TextEncoder class provides an encoder and decoder for these two types of encodings. Protocol defines the implementation of the SMS message connection. Protocol interfaces with the platform provided SMS services. It makes native calls to open, close and send messages. This connection is to a low-level transport mechanism which can be any of the following:

• a datagram short message peer-to-peer (SMPP) protocol to a service center to satisfy a network-based solution
• a comm connection to a mobile device that understands AT-commands
• a native SMS stack for proprietary implementations
• a loop back implementation; that is, anything that is sent will be automatically received. This implementation is provided for testing purposes.

Connection and Message Lifecycle

Connections can be made in server mode or in client mode. In server mode, messages can be sent or received. In client mode, messages can be sent only. Applications can treat sending and receiving independently.

To receive messages, the application can open the connection by passing a string containing a local port to the Connector.open method. A MessageConnection object is returned, on which the message can be received. If there are no messages in the queue, the receive() method will block until one arrives. When a message has been received, methods are available in the MessageObject class for retrieving its address and data parts. Calling the close() method closes the connection.

To send messages, the application will either obtain an existing Message object or use the newMessage factory method to create one. If the application creates a Message object, methods are available in the MessageObject class for setting its address and data parts. The application can open a connection by passing a string containing a fully-qualified SMS URL address (phone number and port number) to the Connector.open method. A MessageConnection object is returned, on which the message can be sent. Calling the close() method closes the connection.

Package Specification

The classes in this package need access to classes in the optional javax.microedition.io package, the CLDC implementation (com.sun.cldc.*), and the MIDP implementation (com.sun.midp.*).

This package is also dependent on javax.microedition.io for the definition of Connector.open (the CLDC-definition of the Generic Connection Framework).

Design Overview

This package contains classes which are to be subclassed or directly modified during porting to various native Bluetooth stack implementations. GenericBluetoothStack java class and CBlueZStack C++ class are provided as a reference implementation which was tested with the official Linux Bluetooth stack.

Central to the package is the abstract BluetoothStack class, which provides services for device inquiry, remote device name retrieval, access to local service discovery database (SDDB), authentication and encryption.

Device inquiry is asynchronous operations, meaning that the corresponding class method call is non-blocking, and notification is used to deliver data when it arrives. All other methods are blocking, including retrieval of a remote device name (which is actually processed asynchronously in a different thread).

It is assumed that the native stack implementation provides methods to poll for events such as inquiry result and remote name result, and returns such events in binary form (the format is stack-specific). This binary data is then transformed into Java event classes, which are processed accordingly.

Separate threads are used for event polling and event delivery. This allows to continue receiving and storing events in cases such as when processing of a certain event can only be ended with receiving another event (e.g. to simulate synchronous remote name retreival).

A generic implementation of the BluetoothStack is available, which relies on Bluetooth HCI interface for device inquiry and remote name retrieval. GenericBluetoothStack should generally be used as a base for the port, unless the native Bluetooth stack provides more convenient API for operations such as device inquiry, remote name retrieval, authentication and encryption.

JSR 82 porting layer is a set of native methods that invoke native and hardware functions in the real implementation. In the emulation mode the porting layer calls functionality implemented in this package.

JSR 82 Emulation consists of a number of emulation clients and an emulation server. At runtime it is assumed that server runs somewhere on the Internet in J2SE environment and provides server sockets for connections. A client runs under J2ME VM control and represents Bluetooth local or remote device, connection or anything else that requires Bluetooth ether communication. Server in turn represents Bluetooth ether.

This package contains clients implementations and related functionality.

Runtime Environment Components

Detailed Design

The top level (main) files and objects of the Runtime Environment component used to launch a MIDlet are listed in the table below.

The figure below shows the sequence of events that occur in the runtime environment when a MIDlet is launched from the Java Application Manager.

The figure below shows the sequence of events that occur in the runtime environment when a MIDlet is destroyed.

Provides a Java^tm API and a command line interface (ME Key Tool) to manage the public keys in the mobile equipment keystore.

The key tool imports keys from Java^tm Standard Edition keystores (J2SE). A J2SE^tm keystore "jse_test_keystore.bin" is provided, it has the public key of the most popular Internet certificate authority for test purposes. Its password is "password". For example to see what is in the keystore, use the J2SE^tm keytool as follows:

keytool -list -keystore j2se_test_keystore.bin -storepass password

For usage information on the MEKeyTool see:  MEKeyTool.main()

HTTPS and Certificates

If you are using the HTTPS prototype API, you may have to install the public key of a certificate authority (CA) into the mobile equipment public keystore. MIDP includes the public key needed to verify VeriSign E-Commerce certificates. However, to verify other certificates from VeriSign (such as their trial certificates) and certificates from other CA's, their public keys must be manually installed into the public keystore. To do so, follow these steps:

1. Import the certificate of the CA that issued the certificate you want verify into a Java^tm 2 Platform, Standard Edition (J2SE) keystore using the J2SE^tm keytool command. Assign the certificate an appropriate alias. (For testing without a CA, using a self signed server certificate, just use the server's certificate as a CA certificate.) For example:

   keytool -import -keystore keystore -storepass password -file ca_cert.txt -alias httpsca

2. Import the public key of the CA from the J2SE^tm keystore into the MIDP public keystore by using the MEKeyTool. For example:

   java -jar bin/MEKeyTool.jar -import -keystore keystore -alias httpsca -storepass password

   For usage information on the MEKeyTool, use the -help option.

3. (optional) Check the result by listing the keys in the public keystore. For example:

   java -jar bin/MEKeyTool.jar -list

For security purposes the MIDletStateHandler is the anchor of trust internally for the MIDP API, restricted methods obtain the MIDletStateHandler for a MIDlet suite in order to check the properties and actions of a suite. Because of this, there MUST only be one a MIDlet suite per MIDletStateHandler.

MIDlet State Handing

The MIDletStateHandler handles state transitions for a MIDlet. MIDP Optimized Implementation software has more states than those listed in the MIDP Specification (which are paused, active, and destroyed). The additional states are active pending, pause pending, and destroy pending. The state processing for a MIDlet is described in the table and illustrated in figure below.

Pausing a MIDlet

A MIDlet can be placed in paused state by either the system or itself, as indicated by the figure above. A MIDlet pauses itself by calling its pauseNotify method. However, as of MIDP 2.0 there is no longer any reason for this to happen for the following reasons:

• A MIDlet does not need to pause itself to give up resources like CPU time or the display. To give up the display a MIDlet should call the Display.setCurrent method with an null argument. To give up CPU time the MIDlet only has to end or block the threads it started. Another option is for the MIDlet to ask the system to start it in the future using the Alarm API. See the Push API in the MIDP Specification for information.
• MIDlets that use a Canvas object suspend and resume threads it created based on the Canvas or CustomItem class's hideNotify and showNotify methods. They must not depend on startApp and pauseApp because the hideNotify and showNotify methods also get called when a MIDlet is paused and activated.

MIDlet can be paused if desired by a device manufacture by using the MIDletProxy class or the native application manager API. The common reasons for customizing a system to pause MIDlets are:

• The system allows the user to launch more than one MIDlet but only has the resources to run one MIDlet. In this case, the system pauses the MIDlets that do not have the physical display until the current MIDlet gives up the display.
• The OS is about to suspend the CPU time for the VM process (as opposed to ending the process). In this case, the system pauses all of the MIDlets and activates them again when the OS resumes CPU time for the VM process.

MIDlet Suite Storage

The MIDlet Suite Storage component is responsible for the following:

• Persistently stores MIDlet suites
• Manages all the MIDlet suites' information
• Provides a way to load a MIDlet

Each MIDlet suite in persistent storage (each installed MIDlet suite) is uniquely identified by a storage name constructed from the combination of the values of the MIDlet-Name and MIDlet-Vendor attributes. The syntax and content of storage names are implementation dependent. Only packages installed or upgraded using this API appear in the list of known packages.

Managing a MIDlet suite's information means storing any data that is received or created during installation, and removing all the data when the MIDlet suite is removed. This component uses the native persistent storage services of the platform, and must be ported to different platforms.

Detailed Design

The MIDlet suite storage component has a C interface and a secure Java platform interface. The C interface is in the file suitestore_common.h. The Java platform interface is MIDletSuiteStorage.

The default implementation is in the file suitestore_intern.c, which use midpStorage.c and rms.c. The figure below shows the MIDlet suite storage component's dependencies.

The MIDlet Suite Storage component provides the following services to both Java platform and native components:

• Provides a suite's unique identifier, given the name and vendor of the suite
• Creates a unique identifier for a suite, given its name and vendor
• Provides the total amount of persistent storage used by a suite
• Provides the amount of storage available for a suite to be installed
• Adds a MIDlet suite to the MIDlet suite storage, or updates an existing MIDlet suite. This service is designed to handle system-specific installation actions
• Removes a MIDlet suite from the MIDlet suite storage. This service is designed to handle system-specific uninstall actions
• Provides the installation information for a MIDlet suite such as the URL of its JAD file
• Provides the application-specific properties of a MIDlet suite such as its name, vendor, and version
• Provides the current permissions for a suite
• Updates the current permissions for a suite
• Provides the Push interrupt setting for a suite
• Updates the Push interrupt setting for a suite
• Provides a list of the unique identifiers of all the installed MIDlet suites
• Provides a list of delete-notification URLs for OTA installers
• Adds a URL to the list of delete-notification URLs
• Removes a URL from the list of delete-notification URLs

To avoid creating a class for only a few runtime environment services, the MIDletSuiteStorage class provides the following functionality:

• Sets the next suite to run after the current suite ends
• Sets the last suite to run after there is no current suite to run
• Gets a MIDletSuite object for scheduling a suite to run

See the com.sun.midp.main package for more information.

Unique Suite IDs

MIDlet suites are identified globally by their name, vendor, and version. Because there can only be one version of a suite on a device at time, the name and vendor can be used to identify a MIDlet suite. However, it saves a lot of code if a MIDlet suite can be uniquely identified with only one value, a value that can be used in ASCII files. The MIDlet suite storage component gives each MIDlet suite a device-unique ASCII string of a arbitrary length that cannot be used for another suite, even after the suite is deleted.

An implementation of the MIDlet suite storage component MAY internally use the unique identifier as part of a file name, none of the other AMS components use the identifier to access MIDlet suite storage files directly.

File Storage

The MIDlet Suite Storage component assumes the file system is one large repository. It also assumes that file names can be of arbitrary length and can be made up of any printable ASCII characters. Using these assumptions, the component builds file names by appending the following three strings, without directory separators:

• Application database root ­ Enables the files in the MIDlet suite storage area to be distinguished from other files in the system. This string can be missing (zero characters long) if the feature is not needed. It can also be a directory name that ends with a directory separator.
• Unique suite root ­ Identifies the MIDlet suite. This string is found by using a function that takes the unique ID of a suite.
• File extension ­ Identifies the file's contents

The RecordStoreFile class provides a file interface to persistent storage for MIDlet suite records via the RecordStore API. Implements a unified random access file interface to storage utilizing the capabilities of the File and RandomAccessStream classes provided by the internal com.sun.midp.io.j2me.storage package.

An important capability of this class is to confine the scope of the storage name space visible to a MIDlet to be files created by applications in its MIDlet suite. This occurs because all RecordStore calls that access storage do so through RecordStoreFile, which converts maps the RecordStore's name into a unique identifier in storage, prefixed by a prefix unique to its MIDlet suite. Any call which modifies storage (e.g. deleteRecordStore) is confined in scope to storage allocated by a MIDlet or another MIDlet in the same suite.

All MIDP applications are "untrusted" unless otherwise setup to have some explicit trust, this is done by giving each MIDlet suite it's own resources and not allowing access to or "see" other suites resources.

However, while restricting access to resources MIDP must also:

1. Enable an internal class to perform a larger set of actions than the suite using it
2. Enable a "trusted" suite to perform a larger set of actions than "untrusted" suites

The first feature depends on the MIDletSuiteLoader class and SecurityToken class. MIDletSuiteLoader, being the first class running in the VM is implicitly trusted to create and issue SecurityToken objects to the internal classes that need them. Restricted internal methods take a SecurityToken as an extra argument, which they check before performing their task. A "untrusted" MIDlet cannot get a SecurityToken object on its own so it will be restricted.

The second feature is depends on the Scheduler class, MIDletSuite interface, and Installer class. The Scheduler is anchor of trust, from which a restricted public method can get the interface to scheduled suite and check to see if the suite is permitted perform the action. The Installer class determines if a suite is "trusted".

Provides a reference implementation of SSLv3.0 Library for MIDP. The code is modified version of KSSL from Sun Labs.

Supports abbreviated SSL handshakes.

Does not support SSL client authentication. This is because purpose of HTTPS for MIDP is to provide the wireless device with end-to-end confidentiality. The authentication must be done at the application level, which is what nearly all consumer applications do.

Only supports the SSL_RSA_WITH_RC4_128_SHA, SSL_RSA_WITH_RC4_128_MD5, and SSL_RSA_EXPORT_WITH_RC4_40_MD5 cipher suites. All known HTTPS servers support these suites.

Only Supports RSA X.509 certificates, these are the defacto standard. KSSL supports version 1, 2, and 3 X.509 certificates signed using RSA with either SHA-1, MD5 and MD2. For security reasons only version 3 certificates are allowed to be chained. While the key usage extension is supported, the name constraints extension is not.

Related Information

• KSSL: Experiments in Wireless Internet Security
• Introduction to SSL
• Introduction to Public Key Cryptography
• RFC 2246, The TLS Protocol Version 1.0
• SSL Protocol Version 3.0
• RFC 2459, Internet X.509 Public Key Infrastructure Certificate and CRL Profile
• RSA's PKCS (Public Key Cryptography Standards) document set.

• com.sun.midp.wma.WMACleanupMonitor

The function of this class is to call a native function, when a MIDletSuite terminates. The native function will perform any cleanup that is required, eg: delete any messages left unread by the MIDletSuite. This class implements the {@link com.sun.midp.main.MIDletProxyListListener} interface and is thus notified whenever a MIDletSuite is installed or removed. The methods here are called at appropriate times.

At startup init is called by {@link com.sun.midp.main.MIDletSuiteLoader} to initialize any necessary cleanup handling when the application exits.

When a MIDlet is about to created the midletAdded method is called, but it is a no-op here.

When a MIDlet state is updated the midletUpdated method is called, but it is a no-op here.

When an error occurs while starting a MIDlet the midletStartError method is called, but it is a no-op here.

When a MIDlet has been destroyed the midletRemoved method is called and it calls a native method to delete any unread messages in the inbox.

Contains all classes to build a Model tree (see the com.sun.perseus.model package) from an SVG document.

The Builder package uses the SAX 2 API to parse an SVG document and turn SVG elements into ModelNode instances.

The package classes are:

• BuildContext. This class contains contextual information about the build process, such as the current Locator into the SVG source (i.e., the current line number) or the constants to use for units conversion (which depend on context).
• BuilderErrors. Defines the error codes generated by the module.
• BuilerException. The type of exceptions thrown by the ModelFactory (and the classes it uses) when an error happens while building a Model tree from an SVG source
• BuilderUtil. This is where the nitty gritty details happen. BuilderUtil is used by all the ElementHandler implementations in an effort to factor code as much as possible.
• ElementHandler. This is the interface for all classes which can turn a XML Element and its attributes in a CompositeNode instance. It is possible to implement ElementHandler to make Perseus handle any type of XML markup. By default, Perseus comes with the ElementHandler implementations necessary to implement SVG Tiny content.
• FontElementHandler. Handles all SVG Tiny elements in the SVG Tiny Font module
• ModelBuilder. This is Perseus' interface with the SAX 2 engine. It extends the org.xml.sax.helpers.DefaultHandlers class. This is where SAX events are received and where building of ModelNode instances is delegated to ModelFactory.
• ModelFactory. This class handles all elements found in the input SVG source. If there is an ElementHandler for the element, then building a corresponding ModelNode is delegated to that element. Otherwise, a generic CompositeNode is built to represent the input content.
• ShapeElementHandler. Handles all SVG Tiny elements in the SVG Tiny Shape module
• StructureElementHandler. Handles all SVG Tiny elements in the SVG Tiny Basic Structure module
• SVGTinyModelFactory. This extension of ModelFactory is a utility class that registers (with itself) all the ElementHandlers necessary to handle SVG Tiny content.
• TextElementHandler. Handles all SVG Tiny elements in the SVG Tiny Basic Text module

The Perseus Model package (com.sun.perseus.model) contains interfaces and classes used to describe an SVG Tiny document as a tree of ModelNodes objects with properties. Note that this is different from the DOM (Document Object Model) in a number of ways (e.g, there are not Attr nodes). The Perseus model is not generic like the DOM is. Instead, the Perseus model is very specific to the needs of SVG Tiny and contains all that is needed for SVG Tiny and no more.

The key interfaces in the model package are:

• ModelNode. All classes that represent an SVG Tiny element implement that interface. It contains methods for child navigation and supports getting and setting of common XML attributes (such as the 'id' attribute.
• DecoratedNode. All nodes that have properties (e.g., graphical properties or text properties) implement this interface.
• GraphicsNode. All nodes that have graphical properties (such as 'fill', 'stroke' or 'stroke-width') implement that interface to allow getting and setting of the properties as well as management of their inheritance and relative value (e.g. for handling the 'currentColor' value on 'fill').
• TextNode. All nodes that have text properties (such as 'font-size', 'text-anchor' or 'font-weight) must implement that interface to allow getting and setting of the properties as well as management of their inheritance.
• Transformable. All nodes which have a an attribute mapping to an AffineTransform implement that interface.

The classes in the model package are:

• AbstractShapeNode. All nodes which represent shapes (basic or arbitrary shapes) are represented by descendants of this class.
• CompositeGraphicsNode. All nodes wich can have children and can have graphical properties are represented by descendant of this class.
• CompositeNode. All node that may have a children is represented by a descendant of this class. It provides methods for managing children.
• ConditionalProcessing. This is a helper class used to compute conditional processing on model nodes.
• Defs. Represents an SVG Tiny <defs> element.
• Ellipse. Represents an SVG Tiny <ellipse> element.
• Font. Represents an SVG Tiny <font> element.
• FontFace. Represents an SVG Tiny <font-face> element.
• Glyph. Represents an SVG Tiny <glyph> and <missing-glyph> elements.
• Group. Represents an SVG Tiny <g> element.
• ImageNode. Represents an SVG Tiny <image> element.
• Line. Represents an SVG Tiny <line> element.
• ModelNodeProxy. Used to model expanded content in Use and Glyph. A ModelNodeProxy manages the RenderContext but delegates rendering to the node it proxies.
• Rect. Represents an SVG Tiny <rect> element.
• ShapeNode. Represents an SVG Tiny <path>, <polygon> and <polylines> elements.
• StructureNode. Base class for all the nodes representing structure in SVG Tiny, such as images, defs, use or svg.
• SVG. Represents an SVG Tiny <svg> element.
• Switch. Represents an SVG Tiny <switch> element.
• Text. Represents an SVG Tiny <text> element.
• Use. Represents an SVG Tiny <use> element.
• Viewport. Represents an SVT Tiny's <svg> element's viewport.

The Perseus Parser package provides parsers used to handle complex attributes such as transforms or path data.

The main classes are:

• AbstractParser. This is the base class for all the Perseus parsers. It is a helper class to ease the development of parsers (e.g., it contains common methods for skipping separators).
• ColorParser. Parses CSS 2 color values
• NumberParser. Parses SVG numbers. It is also the base class for parsers that need to handle lists of numbers or parsers that need to parse numbers as part of their syntax (e.g., TransformListParser.
• PathParser. Parses SVG path data (e.g., the 'd' attribute on <path>
• TransformListParser. Parses transform list values (e.g., the 'transform' attribute)
• ViewBoxParser. Parses the view box values
• LengthParser. Parses SVG length values (e.g., the 'width' attribute on <svg>

The Perseus Utility package contains supporting classes and interfaces such as SVG constants definitions and a Base64 decoding utility.

The main classes are:

• SVGConstants. Contains the SVG constants (attributes, tag names) used in SVG Tiny. The interface defines constants for generic XML processing (e.g., the XML namespace value), CSS constants (e.g., property names and values) and SVG constants.
• Base64DecodeStream. This class is used to decode Strings that represent Base64 encoded data. In Perseus, this is used to decode xlink:href attributes (e.g., on the <image> element) that encode the referenced resource into the attribute value rather than really pointing to it.
• LocalizableSupport. This class is used to ease loading the appropriate resource bundle for a given locale. It is typically used by Messages classes, such as the one in the com.sun.perseus.builder package.

The RSAPublicKey class provides and implementation of the RSA key constructor. The TLV and Util classes provide DER byte stream parsing.

This proposal is made with the assumption that the minimal requirement for a WMA implementation is that the following functionality is available:

• The ability to send a Message to the network.
• The ability to receive a Message from the network.

In this situation, the only possible way for TCK to test for sending/receiving messages is to require that some J2SE-based framework API will provide the functionality of a "network-initiated send" and "network-side receive" to the implementation under test. "Round trip" tests in which the device sends/receives Messages to itself will not work for all expected WMA implementations.

This document contains a proposal for the framework API. The framework is intended to run on J2SE and would be exhibit functionality approximately the same as WMA.

The framework would be located in the package, com.sun.tck.wma package. The following APIs that were unnecessary for testing and that have been omitted are:

Connector.open*Stream
Connector.open(String, ...)  Methods with more than one parameter
MessageConnection.numberOfSegments
MessageConnection.setMessageListener
MessageListener
    

The proposal does not contain Javadoc comments, assuming that these will be copied from the WMA specification.

The API consists of a set of interfaces with the single entry point com.sun.tck.wma.Connector interface and its open(String) method. Licensees and the reference implementation should provide an implementation of these interfaces and should specify the name of the class that implements the com.sun.tck.wma.Connector interface to the TCK.

The TCK will use a distributed test framework which tests if the Message, sent from the device, can be received by the network (and vice versa).

Possible problems with this approach:

• There would be an extra requirement of this implementation to provide a J2SE implementation of WMA for TCK testing purposes. The J2SE WMA implementation would be dependent on this implementation's WMA implementation (Message transport and formatting.). The J2SE WMA implementation can be done by the TCK team, with support for any changes to this J2SE-WMA implementation.
• There would be an unreasonable requirement on the licensee to the support "round trip" tests in the WMA implementation. An API would be required to map WMA to the underlying protocol.

J2SE CBS Message Connection Implementation

Implementation classes for the CBS Message Connection layered on a DatagramPacket low level transport.

A single class is shared by the J2ME client and the J2SE service to allow formatted messages to be transmitted across platforms.

com.sun.midp.io.j2me.cbs.CBSPacket provides the interfaces to get/set fielded data packed into a binary datagram message.

Configuration File

Properties can be set in a configuration file called "connections.prop" in the current working directory to override the built-in default values. Such values include the phone number of the device and the input/output port numbers for receiving datagrams, respectively. A phone number may also configured in order to identify the address of the "device.".

These are the default CBS configurations in connections.prop:

#
# The datagram host is the name of the client or /target device. Messages are
# sent to and/or received from this client. The host can be an alias that maps
# in /etc/hosts (UNIX/Linux systems) to a a real client device name. The alias
# can also be mapped to the IP address of the device under test.
#
DatagramHost=wmadatagramhost
#
# The phone number starts with "+" and is followed by a number of digits
# (e.g.: +5551234). The phone number represents the number of a device that
# would contact the MIDP code under test. The phone number is the same across
# all protocols.
#
PhoneNumber=+5551234

#
# CBS properties -- These properties are used by CBSMessageConnector.
#
# The "out" port is used for broadcasting CBS messages. The CBS client can only
# receive the messages sent by the host. The port represents a physical
# transport-layer port number and may not match a port number of a CBS address.
#
CBSDatagramPortOut=22200
    

J2SE MMS Message Connection Implementation

Implementation classes for the MMS Message Connection layered on a DatagramPacket low-level transport.

A single class is shared by the J2ME client and the J2SE service to allow formatted messages to be transmitted across platforms.

com.sun.midp.io.j2me.mms.MMSPacket provides the interfaces to get/set fielded data packed into a binary datagram message.

Configuration File

Properties can be set in a configuration file called "connections.prop" in the current working directory to override the built-in default values. Such values include the phone number of the device and the input/output port numbers for receiving/sending datagrams, respectively. A phone number may also configured in order to identify the address of the sender.

These are the default MMS configurations in connections.prop:

#
# The datagram host is the name of the client or /target device. Messages are
# sent to and/or received from this client. The host can be an alias that maps
# in /etc/hosts (UNIX/Linux systems) to a a real client device name. The alias
# can also be mapped to the IP address of the device under test.
#
DatagramHost=wmadatagramhost
#
# The phone number starts with "+" and is followed by a number of digits
# (e.g.: +5551234). The phone number represents the number of a device that
# would contact the MIDP code under test. The phone number is the same across
# all protocols.
#
PhoneNumber=+5551234

#
# MMS properties -- These properties are used by MMSMessageConnector.
#
# The port numbers represent the server-side datagram ports. These values
# will be opposite to the "in" and "out" ports in the XML properties file
# of the client (MIDP) code.
#
# The "reply-to" application ID is not real, but simply representative of
# a real-world application ID string. Normally, this would be the path to
# the application that would process the message data sent to the server
# (or, in this case, to the tool code.).
#
MMSDatagramPortOut=33300
MMSDatagramPortIn=33301
MMSReplyToAppID=com.sun.mms.MMSTest
    

J2SE SMS Message Connection Implementation

Implementation classes for the SMS Message Connection layered on a DatagramPacket low-level transport.

A single class is shared by the J2ME client and the J2SE service to allow formatted messages to be transmitted across platforms.

com.sun.midp.io.j2me.sms.SMSPacket provides the interfaces to get/set fielded data packed into a binary datagram message.

Configuration File

Properties can be set in a configuration file called "connections.prop" in the current working directory to override the built-in default values. Such values include the phone number of the device and the input/output port numbers for receiving/sending datagrams, respectively. A phone number may also configured in order to identify the address of the sender.

These are the default SMS configurations in connections.prop:

#
# The datagram host is the name of the client or /target device. Messages are
# sent to and/or received from this client. The host can be an alias that maps
# in /etc/hosts (UNIX/Linux systems) to a a real client device name. The alias
# can also be mapped to the IP address of the device under test.
#
DatagramHost=wmadatagramhost
#
# The phone number starts with "+" and is followed by a number of digits
# (e.g.: +5551234). The phone number represents the number of a device that
# would contact the MIDP code under test. The phone number is the same across
# all protocols.
#
PhoneNumber=+5551234

#
# SMS properties -- These properties are used by SMSMessageConnector.
#
# The "out" port is used for sending messages. The "in" port is used for
# receiving messages and acknowledgements. The ports represent physical
# transport-layer port numbers and may not match a port number in an SMS
# address.
#
SMSDatagramPortOut=11100
SMSDatagramPortIn=11101
    

Compatibility

Disposal of indirect buffers is handled in the normal way by the garbage collector. However, direct buffers involve allocation of memory on the native heap, which is outside the scope of the garbage collector. This memory may still be in use by native code even though the buffer is no longer referenced by application code. In this case, the garbage collector will collect the Java object representing the buffer, but the buffer contents will continue to occupy memory in the native heap. The implementation must ensure that this memory is properly deallocated when it is no longer referenced by native code. The implementation may create a cleanup thread for this purpose.

The central abstractions of the NIO APIs are:

• Buffers, which are containers for data;

• Charsets and their associated decoders and encoders,
  which translate between bytes and Unicode characters;

• Channels of various types, which represent connections
  to entities capable of performing I/O operations; and

• Selectors and selection keys, which together with
  selectable channels define a multiplexed, non-blocking
  I/O facility.

The java.nio package defines the buffer classes, which are used throughout the NIO APIs. The charset API is defined in the {@link java.nio.charset} package, and the channel and selector APIs are defined in the {@link java.nio.channels} package. Each of these subpackages has its own service-provider (SPI) subpackage, the contents of which can be used to extend the platform's default implementations or to construct alternative implementations.

Buffers	Description
{@link java.nio.Buffer}	Position, limit, and capacity; clear, flip, rewind, and mark/reset
{@link java.nio.ByteBuffer}	Get/put, compact, views; allocate, wrap
{@link java.nio.MappedByteBuffer}	A byte buffer mapped to a file
{@link java.nio.CharBuffer}	Get/put, compact; allocate, wrap
{@link java.nio.DoubleBuffer}	' '
{@link java.nio.FloatBuffer}	' '
{@link java.nio.IntBuffer}	' '
{@link java.nio.LongBuffer}	' '
{@link java.nio.ShortBuffer}	' '
{@link java.nio.ByteOrder}	Typesafe enumeration for byte orders

• A byte buffer can be allocated as a direct buffer, in which case the Java virtual machine will make a best effort to perform native I/O operations directly upon it.

• A byte buffer can be created by {@link java.nio.channels.FileChannel#map mapping} a region of a file directly into memory, in which case a few additional file-related operations defined in the {@link java.nio.MappedByteBuffer} class are available.

• A byte buffer provides access to its content as either a heterogenous or homogeneous sequence of binary data of any non-boolean primitive type, in either big-endian or little-endian byte order.

A subset of the java.rmi package in the Java 2 Standard Edition. The package includes the Remote interface and the RemoteException class. The Remote interface serves to identify interfaces whose methods may be invoked from a non-local virtual machine. A RemoteException is the common superclass for a number of communication-related exceptions that may occur during the execution of a remote method call.

SATSA Subset Description

Package Specification

• RFC 2459: X.509 Certificate and CRL Profile

Related Documentation

• http://www.ietf.org/rfc/rfc2459.txt
• Why should I care about X.509 certificates?

Note that these interfaces are intended only for key implementations whose key material is accessible and available. These interfaces are not intended for key implementations whose key material resides in inaccessible, protected storage (such as in a hardware device).

For more developer information on how to use these interfaces, including information on how to design Key classes for hardware devices, please refer to these cryptographic provider developer guides:

• How to Implement a Provider for the Java^TM Cryptography Architecture
• How to Implement a Provider for the Java^TM Cryptography Extension

Package Specification

• PKCS #1: RSA Encryption Standard, Version 1.5, November 1993
• Federal Information Processing Standards Publication (FIPS PUB) 186: Digital Signature Standard (DSS)

A key specification is a transparent representation of the key material that constitutes a key. A key may be specified in an algorithm-specific way, or in an algorithm-independent encoding format (such as ASN.1).

Package Specification

• PKCS #1: RSA Encryption Standard, Version 1.5, November 1993
• Federal Information Processing Standards Publication (FIPS PUB) 186: Digital Signature Standard (DSS)

Related Documentation

• Java Cryptography Architecture API Specification and Reference

SATSA Subset Description

These classes are capable of formatting dates, numbers, and messages, parsing; searching and sorting strings; and iterating over characters, words, sentences, and line breaks. This package contains three main groups of classes and interfaces:

• Classes for iteration over text
• Classes for formatting and parsing
• Classes for string collation

Package Specification

• Info-ZIP file format - The JAR format is based on the Info-ZIP file format. See java.util.zip package description.

• Manifest and Signature Specification - The manifest format specification.

Package Specification

• Info-ZIP Application Note 970311 - a detailed description of the Info-ZIP format upon which the java.util.zip classes are based.

• ZLIB Compressed Data Format Specification version 3.3   (PostScript) (RFC 1950)

• DEFLATE Compressed Data Format Specification version 1.3   (PostScript) (RFC 1951)

• GZIP file format specification version 4.3   (PostScript) (RFC 1952)

• CRC-32 checksum is described in RFC 1952 (above)

• Adler-32 checksum is described in RFC 1950 (above)

SATSA Subset Description

A key specification is a transparent representation of the key material that constitutes a key. A key may be specified in an algorithm-specific way, or in an algorithm-independent encoding format (such as ASN.1).

An algorithm parameter specification is a transparent representation of the sets of parameters used with an algorithm.

Package Specification

• Federal Information Processing Standards Publication (FIPS PUB) 46-2: Data Encryption Standard (DES)

SATSA Subset Description

@since CHAPI 1.0

MID Profile includes networking support based on the Generic Connection framework from the Connected, Limited Device Configuration.

HTTP Networking

In addition to the javax.microedition.io classes specified in the Connected Limited Device Configuration the Mobile Information Device Profile includes the following interface for the HTTP access. An HttpConnection is returned from Connector.open() when an "http://" connection string is accessed.

• javax.microedition.io.HttpConnection

The MIDP extends the connectivity support provided by the Connected, Limited Device Configuration (CLDC) with specific functionality for the GenericConnection framework. The MIDP supports a subset of the HTTP protocol, which can be implemented using both IP protocols such as TCP/IP and non-IP protocols such as WAP and i-Mode, utilizing a gateway to provide access to HTTP servers on the Internet.

The GenericConnection framework is used to support client-server and datagram networks. Using only the protocols specified by the MIDP will allow the application to be portable to all MIDs. MIDP implementations MUST provide support for accessing HTTP 1.1 servers and services.

There are wide variations in wireless networks. It is the joint responsibility of the device and the wireless network to provide the application service. It may require a gateway that can bridge between the wireless transports specific to the network and the wired Internet. The client application and the Internet server MUST NOT need to be required to know either that non-IP networks are being used or the characteristics of those networks. While the client and server MAY both take advantage of such knowledge to optimize their transmissions, they MUST NOT be required to do so.

For example, a MID MAY have no in-device support for the Internet Protocol (IP). In this case, it would utilize a gateway to access the Internet, and the gateway would be responsible for some services, such as DNS name resolution for Internet URLs. The device and network may define and implement security and network access policies that restrict access.

HTTP Network Connection

The GenericConnection framework from the CLDC provides the base stream and content interfaces. The interface HttpConnection provides the additional functionality needed to set request headers, parse response headers, and perform other HTTP specific functions.

The interface MUST support:

HTTP 1.1

Each device implementing the MIDP MUST support opening connections using the following URL schemes (RFC2396 Uniform Resource Identifiers (URI): Generic Syntax)

"http" as defined by RFC2616 Hypertext Transfer Protocol -- HTTP/1.1

Each device implementing the MIDP MUST support the full specification of RFC2616
HEAD, GET and POST requests. The implementation MUST also support the absolute forms of URIs.

The implementation MUST pass all request headers supplied by the application and response headers as supplied by the network server. The ordering of request and response headers MAY be changed. While the headers may be transformed in transit, they MUST be reconstructed as equivalent headers on the device and server. Any transformations MUST be transparent to the application and origin server. The HTTP implementation does not automatically include any headers. The application itself is responsible for setting any request headers that it needs.

Connections may be implemented with any suitable protocol providing the ability to reliably transport the HTTP headers and data.(RFC2616 takes great care to not to mandate TCP streams as the only required transport mechanism.)

HTTP Request Headers

The HTTP 1.1 specification provides a rich set of request and response headers that allow the application to negotiate the form, format, language, and other attributes of the content retrieved. In the MIDP, the application is responsible for selection and processing of request and response headers. Only the User-Agent header is described in detail. Any other header that is mutually agreed upon with the server may be used.

User-Agent and Accept-Language Request Headers

For the MIDP, a simple User-Agent field may be used to identify the current device. As specified by RFC2616, the field contains blank separated features where the feature contains a name and optional version number.

The application is responsible for formatting and requesting that the User-Agent field be included in HTTP requests via the setRequestProperty method in the interface javax.microedition.io.HttpConnection. It can supply any application-specific features that are appropriate, in addition to any of the profile-specific request header values listed below.

Applications are not required to be loaded onto the device using HTTP. But if they are, then the User-Agent request header should be included in requests to load an application descriptor or application JAR file onto the device. This will allow the server to provide the most appropriate application for the device.

The user-agent and accept-language fields SHOULD contain the following features as defined by system properties using java.lang.System.getProperty. If multiple values are present they will need to be reformatted into individual fields in the request header.

System Properties Used for User-Agent and Accept-Language Request Headers

HTTP Request Header Example

User-Agent: Profile/MIDP-2.1 Configuration/CLDC-1.0
Accept-Language: en-US

StreamConnection Behavior

All MIDP StreamConnections have one underlying InputStream and one OutputStream. Opening a DataInputStream counts as opening an InputStream and opening a DataOutputStream counts as opening an OutputStream. Trying to open another InputStream or another OutputStream from a StreamConnections causes an IOException. Trying to open InputStream or OutputStream after they have been closed causes an IOException.

After calling the close method, regardless of open streams, further method calls to connection will result in IOExceptions for those methods that are declared to throw IOExceptions. For the methods that do not throw exceptions, unknown results may be returned.

The methods of StreamConnections are not synchronized. The only stream method that can be called safely in another thread is close. When close is invoked on a stream that is executing in another thread, any pending I/O method MUST throw an InterruptedIOException. In the above case implementations SHOULD try to throw the exception in a timely manner. When all open streams have been closed, and when the StreamConnections is closed, any pending I/O operations MUST be interrupted in a timely manner.

Secure Networking

Since the MIDP release additional interfaces are available for secure communication with WWW network services. Secure interfaces are provided by HTTPS and SSL/TLS protocol access over the IP network. Refer to the package documentation of javax.microedition.pki for the details of certificate profile that applies to secure connections. An HttpsConnection is returned from Connector.open() when an "https://" connection string is accessed. A SecureConnection is returned from Connector.open() when an "ssl://" connection string is accessed.

• javax.microedition.io.HttpsConnection
• javax.microedition.io.SecureConnection
• javax.microedition.io.SecurityInfo
• javax.microedition.pki.Certificate
• javax.microedition.pki.CertificateException

Low Level IP Networking

Since the MIDP release, the MIDP specification also includes optional networking support for TCP/IP sockets and UDP/IP datagrams. For each of the following schemes, a host is specified for an outbound connection and the host is omitted for an inbound connection. The host can be a host name, a literal IPv4 address or a literal IPv6 address (according to RFC2732 square bracket characters '[' ']' may be used to designate an IPv6 address in URL strings). Implementations MUST be able to parse the URL string and recognize the address format used, but are not required to support all address formats and associated protocols.

When the host and port number are both omitted from the socket or datagram connection, the system will allocate an available port. The host and port numbers allocated in this fashion can be discovered using the getLocalAddress and getLocalPort methods. The colon (:) may be omitted when the connection string does not include the port parameter.

A SocketConnection is returned from Connector.open() when a "socket://host:port" connection string is accessed. A ServerSocketConnection is returned from Connector.open() when a "socket://:port" connection string is accessed. A UDPDatagramConnection is returned from Connector.open() when a "datagram://host:port" connection string is accessed.

• javax.microedition.io.SocketConnection
• javax.microedition.io.ServerSocketConnection
• javax.microedition.io.DatagramConnection
• javax.microedition.io.Datagram
• javax.microedition.io.UDPDatagramConnection

Push Applications

A PushRegistry is available in the MIDP release which provides a MIDlet with a means of registering for network connection events, which may be delivered when the application is not currently running.

• javax.microedition.io.PushRegistry

Serial Port Communications

A CommConnection is available in the MIDP release which provides a MIDlet with a means of registering for network accessing a local serial port as a stream connection.

• javax.microedition.io.CommConnection

Security of Networking Functions

The security model is found in the package javax.microedition.midlet and provides a framework that allows APIs and functions to be restricted to MIDlet suites that have been granted permissions either by signing or explicitly by the user. (See Security for MIDlet suites for details about granting specific permissions to a MIDlet suite.)

The risks associated with a MIDlet suite's use of the network are related the potential for network abuse and to costs to the device owner since network use may result in charges. MIDP provides a security framework in which network functions can be protected and allowed only to those applications that have requested and been granted appropriate permissions.

Each protocol is accessed by invoking javax.microedition.io.Connector.open with a URI including the protocol and arguments. The permissions below allow access to be granted individually to protocols. The functionality of the protocols is specified by subclasses of Connection interface that defines the syntax of the URI and any protocol specific methods. Devices are NOT REQUIRED to implement every protocol. If a protocol is implemented, the security framework specifies the naming of permissions according to the package and class name of the APIs used to access the protocol extended with the protocol name. The API providing access is javax.microedition.io.Connector.open. The table below defines the corresponding permissions for the protocols defined within this specification.

Security of PushRegistry

The PushRegistry is protected using the security framework and permissions. The MIDlet suite must have the javax.microedition.io.PushRegistry permission to register an alarm based launch, to register dynamically using the PushRegistry, to make a static registration in the application descriptor and to determine if the user needs to be prompted prior to invoking MIDlet suite in response to a Push connection event or alarm. The protection domain defines the general behavior for user permissions with the interaction modes of "oneshot", "session", and "blanket". For the PushRegistry and the AMS, launching behavior is specialized:

• Oneshot: The user is prompted before the MIDlet suite is invoked to handle a push event or alarm and for each PushRegistry request; for example to register an alarm or a connection.
• Session: The user is prompted before the MIDlet suite is invoked to handle a push event or alarm, or before the first PushRegistry request; for example to register an alarm or a connection. Subsequently, when a MIDlet uses the PushRegistry the user is not prompted.
• Blanket: The user is prompted only once during installation, before the first time the MIDlet suite is invoked to handle a push event or alarm, or uses the PushRegistry.

The push mechanism uses protocols in which the device is acting as the server and connections can be accepted from other elements of the network. To use the push mechanisms the MIDlet suite will need the permission to use the server connection. For example, to register a chat program that can be started via push might use the following attributes in the manifest:

MIDlet-Push-1: socket://:79, com.sun.example.SampleChat, *
MIDlet-Permissions: javax.microedition.io.PushRegistry, javax.microedition.io.Connector.serversocket
     

The JavaCardRMIConnection interface defines the Java Card RMI connection which can be used by J2ME applications to communicate with applications on a smart card using Java Card RMI protocol.

A J2ME application uses stubs for communicating with remote objects on a smart card. A stub is a proxy for a remote object. When passing a remote object as a return value in a remote method call, the stub for that remote object is passed instead. The J2ME application invokes a method on the local stub which is responsible for carrying out the method call on the remote object.

The RemoteStub class is the common superclass for stubs of remote objects.

The interface RemoteRef represents the handle for a remote object. Each stub contains an instance of RemoteRef. RemoteRef contains the concrete representation of a reference. This reference is used to carry out remote calls on the remote object for which it is a reference.

The RemoteStub class and RemoteRef interface are transparent to J2ME applications. They are used by the stubs generated by the Java Card RMI stub compiler. @since SATSA1.0

A package containing the Khronos EGL interfaces. Although this specification incorporates portions of the EGL documentation, the documentation available at the Khronos Web site should always be considered definitive.

This specification defines exception behavior that is intended to enhance platform security by preventing invalid memory accesses from occuring in the underlying EGL implementation. The TCK for this specification will test for proper generation of exceptions.

See the documentation for the EGL10 interface for a description of the integration between EGL and platform drawing APIs such as MIDP and Personal Basis Profile.

A package containing the Khronos OpenGL(R) ES interfaces. Although this specification incorporates portions of the OpenGL ES documentation, the documentation available at the Khronos Web site should always be considered definitive.

An implementation of this specification must utilize an underlying OpenGL ES engine that has been certified as conformant. The TCK for this specification will not address the conformance of the underlying engine.

The object of an implementation of this specification is to pass the OpenGL ES command stream generated by the application to the underlying OpenGL ES engine without any semantic alterations. An implementation may rewrite the command stream provided that the resulting command stream is guaranteed by the rules of OpenGL ES to produce identical results. For example, a duplicate state setting may be removed from the command stream.

Because some implementations may need to reformat the image data generated by the OpenGL ES engine in order to convert it to a format that matches those used elsewhere in the Java platform implementation, color values are allowed to be modified as long as no pixel is observed to differ from the value that would be produced by an equivalent native OpenGL ES program by more than +- 16.

This specification defines exception behavior that is intended to enhance platform security by preventing invalid memory accesses from occuring in the underlying OpenGL ES implementation. The TCK for this specification will test for proper generation of exceptions.

User Interface

The main criteria for the MIDP have been drafted with mobile information devices in mind (i.e., mobile phones and pagers). These devices differ from desktop systems in many ways, especially how the user interacts with them. The following UI-related requirements are important when designing the user interface API:

• The devices and applications should be useful to users who are not necessarily experts in using computers.
• The devices and applications should be useful in situations where the user cannot pay full attention to the application. For example, many phone-type devices will be operated with one hand.
• The form factors and UI concepts of the device differ between devices, especially from desktop systems. For example, the display sizes are smaller, and the input devices do not always include pointing devices.
• The applications run on MIDs should have UIs that are compatible to the native applications so that the user finds them easy to use.

Given the capabilities of devices that will implement the MIDP and the above requirements, the MIDPEG decided not to simply subset the existing Java UI, which is the Abstract Windowing Toolkit (AWT). Reasons for this decision include:

• Although AWT was designed for desktop computers and optimized to these devices, it also suffers from assumptions based on this heritage.
• When a user interacts with AWT, event objects are created dynamically. These objects are short-lived and exist only until each associated event is processed by the system. At this point, the event object becomes garbage and must be reclaimed by the system's garbage collector. The limited CPU and memory subsystems of a MID typically cannot handle this behavior.
• AWT has a rich but desktop-based feature set. This feature set includes support for features not found on MIDs. For example, AWT has extensive support for window management (e.g., overlapping windows, window resize, etc.). MIDs have small displays which are not large enough to display multiple overlapping windows. The limited display size also makes resizing a window impractical. As such, the windowing and layout manager support within AWT is not required for MIDs.
• AWT assumes certain user interaction models. The component set of AWT was designed to work with a pointer device (e.g., a mouse or pen input). As mentioned earlier, this assumption is valid for only a small subset of MIDs since many of these devices have only a keypad for user input.

Structure of the MIDP UI API

The MIDP UI is logically composed of two APIs: the high-level and the low-level.

The high-level API is designed for business applications whose client parts run on MIDs. For these applications, portability across devices is important. To achieve this portability, the high-level API employs a high level of abstraction and provides very little control over look and feel. This abstraction is further manifested in the following ways:

• The actual drawing to the MID's display is performed by the implementation. Applications do not define the visual appearance (e.g., shape, color, font, etc.) of the components.
• Navigation, scrolling, and other primitive interaction is encapsulated by the implementation, and the application is not aware of these interactions.
• Applications cannot access concrete input devices like specific individual keys.

In other words, when using the high-level API, it is assumed that the underlying implementation will do the necessary adaptation to the device's hardware and native UI style. The classes that provide the high-level API are the subclasses of {@link javax.microedition.lcdui.Screen}.

The low-level API, on the other hand, provides very little abstraction. This API is designed for applications that need precise placement and control of graphic elements, as well as access to low-level input events. Some applications also need to access special, device-specific features. A typical example of such an application would be a game.

Using the low-level API, an application can:

• Have full control of what is drawn on the display.
• Listen for primitive events like key presses and releases.
• Access concrete keys and other input devices.

The classes that provide the low-level API are {@link javax.microedition.lcdui.Canvas} and {@link javax.microedition.lcdui.Graphics}.

Applications that program to the low-level API are not guaranteed to be portable, since the low-level API provides the means to access details that are specific to a particular device. If the application does not use these features, it will be portable. It is recommended that applications use only the platform-independent part of the low-level API whenever possible. This means that the applications should not directly assume the existence of any keys other than those defined in the Canvas class, and they should not depend on a specific screen size. Rather, the application game-key event mapping mechanism should be used instead of concrete keys, and the application should inquire about the size of the display and adjust itself accordingly.

Class Hierarchy

The central abstraction of the MIDP's UI is a Displayable object, which encapsulates device-specific graphics rendering with user input. Only one Displayable may be visible at a time, and and the user can see and interact with only contents of that Displayable.

The Screen class is a subclass of Displayable that takes care of all user interaction with high-level user interface component. The Screen subclasses handle rendering, interaction, traversal, and scrolling, with only higher-level events being passed on to the application.

The rationale behind this design is based on the different display and input solutions found in MIDP devices. These differences imply that the component layout, scrolling, and focus traversal will be implemented differently on different devices. If an application were required to be aware of these issues, portability would be compromised. Simple screenfuls also organize the user interface into manageable pieces, resulting in user interfaces that are easy to use and learn.

There are three categories of Displayable objects:

• Screens that encapsulate a complex user interface component (e.g., classes List or TextBox). The structure of these screens is predefined, and the application cannot add other components to these screens.
• Generic screens (instances of the Form class) that can contain Item objects to represent user interface components. The application can populate Form objects with an arbitrary number of text, image, and other components; however, it is recommended that Form objects be kept simple and that they should be used to contain only a few, closely-related user interface components.
• Screens that are used in context of the low-level API (i.e., subclasses of class Canvas).

Each Displayable can have a title, a Ticker and a set of Commands attached to it.

The class Display acts as the display manager that is instantiated for each active MIDlet and provides methods to retrieve information about the device's display capabilities. A Displayable is made visible by calling the setCurrent() method of Display. When a Displayable is made current, it replaces the previous Displayable.

Class Overview

It is anticipated that most applications will utilize screens with predefined structures like List , TextBox , and Alert . These classes are used in the following ways:

• List is used when the user should select from a predefined set of choices.
• TextBox is used when asking textual input.
• Alert is used to display temporary messages containing text and images.

A special class Form is defined for cases where screens with a predefined structure are not sufficient. For example, an application may have two TextFields, or a TextField and a simple ChoiceGroup . Although this class (Form ) allows creation of arbitrary combinations of components, developers should keep the limited display size in mind and create only simple Forms .

Form is designed to contain a small number of closely related UI elements. These elements are the subclasses of Item: ImageItem, StringItem, TextField, ChoiceGroup, Gauge, and CustomItem. The classes ImageItem and StringItem are convenience classes that make certain operations with Form and Alert easier. By subclassing CustomItem application developers can introduce Items with a new visual representation and interactive elements. If the components do not all fit on the screen, the implementation may either make the form scrollable or implement some components so that they can either popup in a new screen or expand when the user edits the element.

Interplay with Application Manager

The user interface, like any other resource in the API, is to be controlled according to the principle of MIDP application management. The UI expects the following conditions from the application management software:

• getDisplay() is callable starting from MIDlet's constructor until destroyApp() has returned.
• The Display object is the same until destroyApp() is called.
• The Displayable object set by setCurrent() is not changed by the application manager.

The application manager assumes that the application behaves as follows with respect to the MIDlet events:

• startApp - The application may call setCurrent() for the first screen. The application manager makes Displayable really visible when startApp() returns. Note that startApp() can be called several times if pauseApp() is called in between. This means that initialization should not take place, and the application should not accidentally switch to another screen with setCurrent() .
• pauseApp - The application should release as many threads as possible. Also, if starting with another screen when the application is re-activated, the new screen should be set with setCurrent() .
• destroyApp - The application may delete created objects.

Event Handling

User interaction causes events, and the implementation notifies the application of the events by making corresponding callbacks. There are four kinds of UI callbacks:

• Abstract commands that are part of the high-level API
• Low-level events that represent single key presses and releases (and pointer events, if a pointer is available)
• Calls to the paint() method of a Canvas class
• Calls to a Runnable object's run() method requested by a call to callSerially() of class Display

All UI callbacks are serialized, so they will never occur in parallel. That is, the implementation will never call an callback before a prior call to any other callback has returned. This property enables applications to be assured that processing of a previous user event will have completed before the next event is delivered. If multiple UI callbacks are pending, the next is called as soon as possible after the previous UI callback returns. The implementation also guarantees that the call to run() requested by a call to callSerially() is made after any pending repaint requests have been satisfied.

There is one exception to the callback serialization rule, which occurs when the {@link javax.microedition.lcdui.Canvas#serviceRepaints Canvas.serviceRepaints} method is called. This method causes the the Canvas.paint method to be called and waits for it to complete. This occurs even if the caller of serviceRepaints is itself within an active callback. There is further discussion of this issue below.

The following callbacks are all serialized with respect to each other:

• {@link javax.microedition.lcdui.Canvas#hideNotify Canvas.hideNotify}
• {@link javax.microedition.lcdui.Canvas#keyPressed Canvas.keyPressed}
• {@link javax.microedition.lcdui.Canvas#keyRepeated Canvas.keyRepeated}
• {@link javax.microedition.lcdui.Canvas#keyReleased Canvas.keyReleased}
• {@link javax.microedition.lcdui.Canvas#paint Canvas.paint}
• {@link javax.microedition.lcdui.Canvas#pointerDragged Canvas.pointerDragged}
• {@link javax.microedition.lcdui.Canvas#pointerPressed Canvas.pointerPressed}
• {@link javax.microedition.lcdui.Canvas#pointerReleased Canvas.pointerReleased}
• {@link javax.microedition.lcdui.Canvas#showNotify Canvas.showNotify}
• {@link javax.microedition.lcdui.Canvas#sizeChanged Canvas.sizeChanged}
• {@link javax.microedition.lcdui.CommandListener#commandAction CommandListener.commandAction}
• {@link javax.microedition.lcdui.CustomItem#getMinContentHeight CustomItem.getMinContentHeight}
• {@link javax.microedition.lcdui.CustomItem#getMinContentWidth CustomItem.getMinContentWidth}
• {@link javax.microedition.lcdui.CustomItem#getPrefContentHeight CustomItem.getPrefContentHeight}
• {@link javax.microedition.lcdui.CustomItem#getPrefContentWidth CustomItem.getPrefContentWidth}
• {@link javax.microedition.lcdui.CustomItem#hideNotify CustomItem.hideNotify}
• {@link javax.microedition.lcdui.CustomItem#keyPressed CustomItem.keyPressed}
• {@link javax.microedition.lcdui.CustomItem#keyRepeated CustomItem.keyRepeated}
• {@link javax.microedition.lcdui.CustomItem#keyReleased CustomItem.keyReleased}
• {@link javax.microedition.lcdui.CustomItem#paint CustomItem.paint}
• {@link javax.microedition.lcdui.CustomItem#pointerDragged CustomItem.pointerDragged}
• {@link javax.microedition.lcdui.CustomItem#pointerPressed CustomItem.pointerPressed}
• {@link javax.microedition.lcdui.CustomItem#pointerReleased CustomItem.pointerReleased}
• {@link javax.microedition.lcdui.CustomItem#showNotify CustomItem.showNotify}
• {@link javax.microedition.lcdui.CustomItem#sizeChanged CustomItem.sizeChanged}
• {@link javax.microedition.lcdui.CustomItem#traverse CustomItem.traverse}
• {@link javax.microedition.lcdui.CustomItem#traverseOut CustomItem.traverseOut}
• {@link javax.microedition.lcdui.Displayable#sizeChanged Displayable.sizeChanged}
• {@link javax.microedition.lcdui.ItemCommandListener#commandAction ItemCommandListener.commandAction}
• {@link javax.microedition.lcdui.ItemStateListener#itemStateChanged ItemStateListener.itemStateChanged}
• Runnable.run resulting from a call to {@link javax.microedition.lcdui.Display#callSerially Display.callSerially}

Note that {@link java.util.Timer Timer} events are not considered UI events. Timer callbacks may run concurrently with UI event callbacks, although {@link java.util.TimerTask TimerTask} callbacks scheduled on the same Timer are serialized with each other. Applications that use timers must guard their data structures against concurrent access from timer threads and UI event callbacks. Alternatively, applications may have their timer callbacks use {@link javax.microedition.lcdui.Display#callSerially Display.callSerially} so that work triggered by timer events can be serialized with the UI event callbacks.

Abstract Commands

Since MIDP UI is highly abstract, it does not dictate any concrete user interaction technique like soft buttons or menus. Also, low-level user interactions such as traversal or scrolling are not visible to the application. MIDP applications define Commands , and the implementation may manifest these via either soft buttons, menus, or whatever mechanisms are appropriate for that device.

Commands are installed to a Displayable (Canvas or Screen ) with a method addCommand of class Displayable .

The native style of the device may assume that certain types of commands are placed on standard places. For example, the "go-back" operation may always be mapped to the right soft button. The Command class allows the application to communicate such a semantic meaning to the implementation so that these standard mappings can be effected.

The implementation does not actually implement any of the semantics of the Command. The attributes of a Command are used only for mapping it onto the user interface. The actual semantics of a Command are always implemented by the application in a CommandListener.

Command objects have attributes:

• Label: Shown to the user as a hint. A single Command can have two versions of labels: short and long. The implementation decides whether the short or long version is appropriate for a given situation. For example, an implementation can choose to use a short version of a given Command near a soft button and the long version of the Command in a menu.
• Type: The purpose of a command. The implementation will use the command type for placing the command appropriately within the device's user interface. Commands with similar types may, for example, be found near each other in certain dedicated place in the user interface. Often, devices will have policy for placement and presentation of certain operations. For example, a "backward navigation" command might be always placed on the right soft key on a particular device, but it might be placed on the left soft key on a different device. The Command class provides fixed set of command types that provide MIDlet the capability to tell the device implementation the intent of a Command. The application can use the BACK command type for commands that perform backward navigation. On the devices mentioned above, this type information would be used to assign the command to the appropriate soft key.
• Priority: Defines the relative importance between Commands of the same type. A command with a lower priority value is more important than a command of the same type but with a higher priority value. If possible, a more important command is presented before, or is more easily accessible, than a less important one.

Device-Provided Operations

In many high-level UI classes there are also some additional operations available in the user interface. The additional operations are not visible to applications, only to the end-user. The set of operations available depends totally on the user interface design of the specific device. For example, an operation that allows the user to change the mode for text input between alphabetic and numeric is needed in devices that have only an ITU-T keypad. More complex input systems will require additional operations. Some of operations available are presented in the user interface in the same way the application-defined commands are. End-users need not understand which operations are provided by the application and which provided by the system. Not all operations are available in every implementation. For example, a system that has a word-lookup-based text input scheme will generally provide additional operations within the TextBox class. A system that lacks such an input scheme will also lack the corresponding operations.

Some operations are available on all devices, but the way the operation is implemented may differ greatly from device to device. Examples of this kind of operation are: the mechanism used to navigate between List elements and Form items, the selection of List elements, moving an insertion position within a text editor, and so forth. Some devices do not allow the direct editing of the value of an Item, but instead require the user to switch to an off-screen editor. In such devices, there must be a dedicated selection operation that can be used to invoke the off-screen editor. The selection of a List elements could be, for example, implemented with a dedicated "Go" or "Select" or some other similar key. Some devices have no dedicated selection key and must select elements using some other means.

On devices where the selection operation is performed using a dedicated select key, this key will often not have a label displayed for it. It is appropriate for the implementation to use this key in situations where its meaning is obvious. For example, if the user is presented with a set of mutually exclusive options, the selection key will obviously select one of those options. However, in a device that doesn't have a dedicated select key, it is likely that the selection operation will be performed using a soft key that requires a label. The ability to set the select-command for a List of type IMPLICIT and the ability to set the default command for an Item are provided so that the application can set the label for this operation and so it can receive notification when this operation occurs.

High-Level API for Events

The handling of events in the high-level API is based on a listener model. Screens and Canvases may have listeners for commands. An object willing to be a listener should implement an interface CommandListener that has one method:

void commandAction(Command c, Displayable d);

The application gets these events if the Screen or Canvas has attached Commands and if there is a registered listener. A unicast-version of the listener model is adopted, so the Screen or Canvas can have one listener at a time.

There is also a listener interface for state changes of the Items in a Form . The method

void itemStateChanged(Item item);

defined in interface ItemStateListener is called when the value of an interactive Gauge , ChoiceGroup , or TextField changes. It is not expected that the listener will be called after every change. However, if the value of an Item has been changed, the listener will be called for the change sometime before it is called for another item or before a command is delivered to the Form's CommandListener. It is suggested that the change listener is called at least after focus (or equivalent) is lost from field. The listener should only be called if the field's value has actually changed.

Low-Level API for Events

Low-level graphics and events have the following methods to handle low-level key events:

public void keyPressed(int keyCode); public void keyReleased(int keyCode); public void keyRepeated(int keyCode);

The last call, keyRepeated , is not necessarily available in all devices. The applications can check the availability of repeat actions by calling the following method of the Canvas :

public static boolean hasRepeatEvents();

The API requires that there be standard key codes for the ITU-T keypad (0-9, *, #), but no keypad layout is required by the API. Although an implementation may provide additional keys, applications relying on these keys are not portable.

In addition, the class Canvas has methods for handling abstract game events. An implementation maps all these key events to suitable keys on the device. For example, a device with four-way navigation and a select key in the middle could use those keys, but a simpler device may use certain keys on the numeric keypad (e.g., 2, 4, 5, 6, 8). These game events allow development of portable applications that use the low-level events. The API defines a set of abstract key-events: UP, DOWN, LEFT, RIGHT, FIRE, GAME_A, GAME_B, GAME_C, and GAME_D.

An application can get the mapping of the key events to abstract key events by calling:

public static int getGameAction(int keyCode);

If the logic of the application is based on the values returned by this method, the application is portable and run regardless of the keypad design.

It is also possible to map an abstract event to a key with:

public static int getKeyCode(int gameAction);

where gameAction is UP,DOWN, LEFT, RIGHT, FIRE, etc. On some devices, more than one key is mapped to the same game action, in which case the getKeyCode method will return just one of them. Properly-written applications should map the key code to an abstract key event and make decisions based on the result.

The mapping between keys and abstract events does not change during the execution of the game.

The following is an example of how an application can use game actions to interpret keystrokes.

class MovingBlocksCanvas extends Canvas { public void keyPressed(int keyCode) { int action = getGameAction(keyCode); switch (action) { case LEFT: moveBlockLeft(); break; case RIGHT: ... } } }

The low-level API also has support for pointer events, but since the following input mechanisms may not be present in all devices, the following callback methods may never be called in some devices:

public void pointerPressed(int x, int y); public void pointerReleased(int x, int y); public void pointerDragged(int x, int y);

The application may check whether the pointer is available by calling the following methods of class Canvas :

public static boolean hasPointerEvents(); public static boolean hasPointerMotionEvents();

Interplay of High-Level Commands and the Low-Level API

The class Canvas , which is used for low-level events and drawing, is a subclass of Displayable , and applications can attach Commands to it. This is useful for jumping to an options setup Screen in the middle of a game. Another example could be a map-based navigation application where keys are used for moving in the map but commands are used for higher-level actions.

Some devices may not have the means to invoke commands when Canvas and the low-level event mechanism are in use. In that case, the implementation may provide a means to switch to a command mode and back. This command mode might pop up a menu over the contents of the Canvas. In this case, the Canvas methods hideNotify() and showNotify() will be called to indicate when the Canvas has been obscured and unobscured, respectively.

The Canvas may have a title and a Ticker like the Screen objects. However, Canvas also has a full-screen mode where the title and the Ticker are not displayed. Setting this mode indicates that the application wishes for the Canvas to occupy as much of the physical display as is possible. In this mode, the title may be reused by the implementation as the title for pop-up menus. In normal (not full-screen) mode, the appearance of the Canvas should be similar to that of Screen classes, so that visual continuity is retained when the application switches between low-level Canvas objects and high-level Screen objects.

Graphics and Text in Low-Level API

The Redrawing Scheme

Repainting is done automatically for all Screens , but not for Canvas ; therefore, developers utilizing the low-level API must ; understand its repainting scheme.

In the low-level API, repainting of Canvas is done asynchronously so that several repaint requests may be implemented within a single call as an optimization. This means that the application requests the repainting by calling the method repaint() of class Canvas . The actual drawing is done in the method paint() -- which is provided by the subclass Canvas -- and does not necessarily happen synchronously to repaint() . It may happen later, and several repaint requests may cause one single call to paint() . The application can flush the repaint requests by calling serviceRepaints() .

As an example, assume that an application moves a box of width wid and height ht from coordinates (x1,y1 ) to coordinates (x2,y2 ), where x2>x1 and y2>y1 :

// move coordinates of box box.x = x2; box.y = y2; // ensure old region repainted (with background) canvas.repaint(x1,y1, wid, ht); // make new region repainted canvas.repaint(x2,y2, wid, ht); // make everything really repainted canvas.serviceRepaints();

The last call causes the repaint thread to be scheduled. The repaint thread finds the two requests from the event queue and repaints the region that is a union of the repaint area:

graphics.clipRect(x1,y1, (x2-x1+wid), (y2-y1+ht)); canvas.paint(graphics);

In this imaginary part of an implementation, the call canvas.paint() causes the application-defined paint() method to be called.

Drawing Model

The primary drawing operation is pixel replacement, which is used for geometric rendering operations such as lines and rectangles. With offscreen images, support for full transparency is required, and support for partial transparency (alpha blending) is optional.

A 24-bit color model is provided with 8 bits each for the red, green, and blue components of a color. Not all devices support 24-bit color, so they will map colors requested by the application into colors available on the device. Facilities are provided in the Display class for obtaining device characteristics, such as whether color is available and how many distinct gray levels are available. This enables applications to adapt their behavior to a device without compromising device independence.

Graphics may be rendered either directly to the display or to an off-screen image buffer. The destination of rendered graphics depends on the origin of the graphics object. A graphics object for rendering to the display is passed to the Canvas object's paint() method. This is the only way to obtain a graphics object whose destination is the display. Furthermore, applications may draw by using this graphics object only for the duration of the paint() method.

A graphics object for rendering to an off-screen image buffer may be obtained by calling the getGraphics() method on the desired image. These graphics objects may be held indefinitely by the application, and requests may be issued on these graphics objects at any time.

The Graphics class has a current color that is set with the setColor() method. All geometric rendering, including lines, rectangles, and arcs, uses the current color. The pixel representing the current color replaces the destination pixel in these operations. There is no background color. Painting of any background be performed explicitly by the application using the setColor() and rendering calls.

Support for full transparency is required, and support for partial transparency (alpha blending) is optional. Transparency (both full and partial) exists only in off-screen images loaded from PNG files or from arrays of ARGB data. Images created in such a fashion are immutable in that the application is precluded from making any changes to the pixel data contained within the image. Rendering is defined in such a way that the destination of any rendering operation always consists entirely of fully opaque pixels.

Coordinate System

The origin (0,0) of the available drawing area and images is in the upper-left corner of the display. The numeric values of the x-coordinates monotonically increase from left to right, and the numeric values of the y-coordinates monotonically increase from top to bottom. Applications may assume that horizontal and vertical distances in the coordinate system represent equal distances on the actual device display. If the shape of the pixels of the device is significantly different from square, the implementation of the UI will do the required coordinate transformation. A facility is provided for translating the origin of the coordinate system. All coordinates are specified as integers.

The coordinate system represents locations between pixels, not the pixels themselves. Therefore, the first pixel in the upper left corner of the display lies in the square bounded by coordinates (0,0), (1,0), (0,1), (1,1).

An application may inquire about the available drawing area by calling the following methods of Canvas :

public static final int getWidth(); public static final int getHeight();

Font Support

An application may request one of the font attributes specified below. However, the underlying implementation may use a subset of what is specified. So it is up to the implementation to return a font that most closely resembles the requested font.

Each font in the system is implemented individually. A programmer will call the static getFont() method instead of instantiating new Font objects. This paradigm eliminates the garbage creation normally associated with the use of fonts.

The Font class provides calls that access font metrics. The following attributes may be used to request a font (from the Font class):

• Size: SMALL, MEDIUM, LARGE.
• Face: PROPORTIONAL, MONOSPACE, SYSTEM.
• Style: PLAIN, BOLD, ITALIC, UNDERLINED.

Concurrency

The UI API has been designed to be thread-safe. The methods may be called from callbacks, TimerTasks, or other threads created by the application. Also, the implementation generally does not hold any locks on objects visible to the application. This means that the applications' threads can synchronize with themselves and with the event callbacks by locking any object according to a synchronization policy defined by the application. One exception to this rule occurs with the {@link javax.microedition.lcdui.Canvas#serviceRepaints Canvas.serviceRepaints} method. This method calls and awaits completion of the paint method. Strictly speaking, serviceRepaints might not call paint directly, but instead it might cause another thread to call paint. In either case, serviceRepaints blocks until paint has returned. This is a significant point because of the following case. Suppose the caller of serviceRepaints holds a lock that is also needed by the paint method. Since paint might be called from another thread, that thread will block trying to acquire the lock. However, this lock is held by the caller of serviceRepaints, which is blocked waiting for paint to return. The result is deadlock. In order to avoid deadlock, the caller of serviceRepaints must not hold any locks needed by the paint method.

The UI API includes also a mechanism similar to other UI toolkits for serializing actions with the event stream. The method {@link javax.microedition.lcdui.Display#callSerially Display.callSerially} requests that the run method of a Runnable object be called, serialized with the event stream. Code that uses serviceRepaints() can usually be rewritten to use callSerially(). The following code illustrates this technique:

class MyCanvas extends Canvas { void doStuff() { // <code fragment 1> serviceRepaints(); // <code fragment 2> } }

The following code is an alternative way of implementing the same functionality:

class MyClass extends Canvas implements Runnable { void doStuff() { // <code fragment 1> callSerially(this); } // called only after all pending repaints served public void run() { // <code fragment 2>; } }

Implementation Notes

The implementation of a List or ChoiceGroup may include keyboard shortcuts for focusing and selecting the choice elements, but the use of these shortcuts is not visible to the application program.

In some implementations the UI components -- Screens and Items -- will be based on native components. It is up to the implementation to free the used resources when the Java objects are not needed anymore. One possible implementation scenario is a hook in the garbage collector of KVM.

Wireless devices have minimal processing power, so much of the API is intended to improve performance by minimizing the amount of work done in Java; this approach also has the added benefit of reducing application size.  The API's are structured to provide considerable freedom when implementing them, thereby permitting the extensive use of native code, hardware acceleration and device-specific image data formats as needed.

The API uses the standard low-level graphics classes from MIDP (Graphics, Image, etc.) so that the high-level Game API classes can be used in conjunction with graphics primitives.  For example, it would be possible to render a complex background using the Game API and then render something on top of it using graphics primitives such as drawLine, etc.

Methods that modify the state of Layer, LayerManager, Sprite, and TiledLayer objects generally do not have any immediately visible side effects. Instead, this state is merely stored within the object and is used during subsequent calls to the paint() method. This approach is suitable for gaming applications where there is a game cycle within which objects' states are updated, and where the entire screen is redrawn at the end of every game cycle.

API Overview

GameCanvas

Layer

LayerManager

Sprite

TiledLayer

Applications

The MIDP defines an application model to allow the limited resources of the device to be shared by multiple MIDP applications, or MIDlets. It defines what a MIDlet is, how it is packaged, what runtime environment is available to the MIDlet, and how it should be behave so that the device can manage its resources. The application model defines how multiple MIDlets forming a suite can be packaged together and share resources within the context of a single Java Virtual Machine. Sharing is feasible with the limited resources and security framework of the device since they are required to share class files and to be subject to a single set of policies and controls.

MIDP MIDlet Suite

A MIDP application MUST use only functionality specified by the MIDP specification as it is developed, tested, deployed, and run.

The elements of a MIDlet suite are:

• Runtime execution environment
• MIDlet suite packaging
• Application descriptor
• Application lifecycle

Each device is presumed to implement the functions required by its users to install, select, run, and remove MIDlets. The term application management software is used to refer collectively to these device specific functions. The application management software provides an environment in which the MIDlet is installed, started, stopped, and uninstalled. It is responsible for handling errors during the installation, execution, and removal of MIDlet suites and interacting with the user as needed. It provides to the MIDlet(s) the Java runtime environment required by the MIDP Specification.

One or more MIDlets MAY be packaged in a single JAR file. Each MIDlet consists of a class that extends the MIDlet class and other classes as may be needed by the MIDlet. The manifest in the JAR file contains attributes that are used during installation and execution of MIDlets. The MIDlet is the entity that is launched by the application management software. When a MIDlet suite is invoked, a Java Virtual Machine is needed on which the classes can be executed. A new instance of the MIDlet is created by the application management software and used to direct the MIDlet to start, pause, and destroy itself.

Sharing of data and other information between MIDlets is controlled by the individual APIs and their implementations. For example, the Record Management System API specifies the methods that are used when the record stores associated with a MIDlet suite are shared among MIDlets.

MIDlet Suite Security

The MIDP 1.0 specification constrained each MIDlet suite to operate in a sandbox wherein all of the APIs available to the MIDlets would prevent access to sensitive functions of the device. That sandbox concept is used in this specification and all untrusted MIDlet suites are subject to its limitations. Every implementation of this specification MUST support running untrusted MIDlet suites.

MIDP introduces the concept of trusted applications that may be permitted to use APIs that are considered sensitive and are restricted. If and when a device determines that a MIDlet suite can be trusted the device allows access as indicated by the policy. Security for MIDP Applications section describes the concepts and capabilities of untrusted and trusted applications.

MIDP Execution Environment

The MIDP defines the execution environment provided to MIDlets. The execution environment is shared by all MIDlets within a MIDlet suite, and any MIDlet can interact with other MIDlets packaged together. The application management software initiates the applications and makes the following available to the MIDlet:

• Classes and native code that implement the CLDC, including a Java Virtual Machine
• Classes and native code that implement the MIDP runtime
• All classes from a single JAR file for execution
• Non-class files from a single JAR file as resources
• Contents of the descriptor file, when it is present
• Any other APIs available on the device such as implementations of additional JSRs, Licensee Open Classes, Optional Packages, etc.

The CLDC and Java Virtual Machine provide multi-threading, locking and synchronization, the execution of byte codes, dispatching of methods, etc. A single VM is the scope of all policy, naming, and resource management. If a device supports multiple VMs, each may have its own scope, naming, and resource management policies. MIDlet Suites MUST NOT contain classes that are in packages defined by the CLDC or MIDP.

The MIDP provides the classes that implement the MIDP APIs. The implementation MUST ensure that the application programmer cannot override, modify, or add any classes to these protected system packages.

A single JAR file contains all of the MIDlet's classes. The MIDlet may load and invoke methods from any class in the JAR file, in the MIDP, or in the CLDC. All of the classes within these three scopes are shared in the execution environment of the MIDlets from the JAR file. All states accessible via those classes are available to any Java class running on behalf of the MIDlet. There is a single space containing the objects of all MIDlets, MIDP, and CLDC in use by the MIDlet suite. The usual Java locking and synchronization primitives SHOULD be used when necessary to avoid concurrency problems. Each library will specify how it handles concurrency and how the MIDlet should use it to run safely in a multi-threaded environment.

The class files of the MIDlet are only available for execution and can neither be read as resources nor extracted for re-use. The implementation of the CLDC may store and interpret the contents of the JAR file in any manner suitable.

The files from the JAR file that are not Java class files are made available using java.lang.Class.getResourceAsStream. For example, the manifest would be available in this manner.

The contents of the MIDlet descriptor file, when it is present, are made available via the javax.microedition.midlet.MIDlet.getAppProperty method.

MIDlet Suite Packaging

One or more MIDlets are packaged in a single JAR file that includes:

• A manifest describing the contents
• Java classes for the MIDlet(s) and classes shared by the MIDlets
• Resource files used by the MIDlet(s)

The developer is responsible for creating and distributing the components of the JAR file as appropriate for the target user, device, network, locale, and jurisdiction. For example, for a particular locale, the resource files would be tailored to contain the strings and images needed for that locale.

The JAR manifest defines attributes that are used by the application management software to identify and install the MIDlet suite and as defaults for attributes not found in the application descriptor. The attributes are defined for use in both the manifest and the optional application descriptor.

The predefined attributes listed below allow the application management software to identify, retrieve, install, and invoke the MIDlet.

MIDlet Attributes

Some attributes use multiple values, for those attributes the values are separated by a comma (Unicode U+002C) except where noted. Leading and trailing whitespace (Unicode U+0020) and tab (Unicode U+0009) are ignored on each value.

Version Numbering

Version numbers have the format Major.Minor[.Micro] (X.X[.X]), where the .Micro portion MAY be omitted. (If the .Micro portion is not omitted, then it defaults to zero). In addition, each portion of the version number is allowed a maximum of two decimal digits (i.e., 0-99). Version numbers are described in the the Java(TM) Product Versioning Specification http://java.sun.com/products/jdk/1.2/docs/guide/versioning/spec/VersioningSpecification.html.

For example, 1.0.0 can be used to specify the first version of a MIDlet suite. For each portion of the version number, leading zeros are not significant. For example, 08 is equivalent to 8. Also, 1.0 is equivalent to 1.0.0. However, 1.1 is equivalent to 1.1.0, and not 1.0.1.

A missing MIDlet-Version tag is assumed to be 0.0.0, which means that any non-zero version number is considered as a newer version of the MIDlet suite.

JAR Manifest

The manifest provides information about the contents of the JAR file. JAR file formats and specifications are available at http://java.sun.com/products/jdk/1.2/docs/guide/jar/index.html. Refer to the JDK JAR and manifest documentation for the syntax and related details. MIDP implementations MUST implement handling of lines longer than 72 bytes as defined in the manifest specification. An attribute MUST not appear more than once within the manifest. If an attribute is duplicated the effect is unspecified. Manifest attributes are passed to the MIDlet when requested using the MIDlet.getAppProperty method, unless the attribute is duplicated in the application descriptor, for handling of duplicate attributes see the "Application Descriptor" section.

The manifest MUST contain the following attributes:

• MIDlet-Name
• MIDlet-Version
• MIDlet-Vendor

The manifest or the application descriptor MUST contain the following attributes:

• MIDlet-<n> for each MIDlet
• MicroEdition-Profile
• MicroEdition-Configuration

The manifest MAY contain the following:

• MIDlet-Description
• MIDlet-Icon
• MIDlet-Info-URL
• MIDlet-Data-Size
• MIDlet-Permissions
• MIDlet-Permissions-Opt
• MIDlet-Push-<n>
• MIDlet-Install-Notify
• MIDlet-Delete-Notify
• MIDlet-Delete-Confirm
• Any application-specific attributes that do not begin with MIDlet- or MicroEdition-

For example, a manifest for a hypothetical suite of card games would look like the following example:

  MIDlet-Name: CardGames    
  MIDlet-Version: 1.1.9    
  MIDlet-Vendor: CardsRUS    
  MIDlet-1: Solitaire, /Solitare.png, org.cardsrus.games.Solitare     
  MIDlet-2: JacksWild, /JacksWild.png, org.cardsrus.games.JacksWild     
  MicroEdition-Profile: MIDP-2.1
  MicroEdition-Configuration: CLDC-1.0     
  Solitaire-Author: John Q. Public      

MIDlet Classes

All Java classes needed by the MIDlet are be placed in the JAR file using the standard structure, based on mapping the fully qualified class names to directory and file names. Each period is converted to a forward slash ( / ) and the .class extension is appended. For example, a class com.sun.microedition.Test would be placed in the JAR file with the name com/sun/microedition/Test.class .

Application Descriptor

Each JAR file MAY be accompanied by an application descriptor. The application descriptor is used in conjunction with the JAR manifest by the application management software to manage the MIDlet and is used by the MIDlet itself for configuration specific attributes. The descriptor allows the application management software on the device to verify that the MIDlet is suited to the device before loading the full JAR file of the MIDlet suite. It also allows configuration-specific attributes (parameters) to be supplied to the MIDlet(s) without modifying the JAR file.

To allow devices to dispatch an application descriptor to the MIDP application management software, a file extension and MIME type are registered with the IANA:

• The file extension of an application descriptor file is jad
• The MIME type of an application descriptor file is
  text/vnd.sun.j2me.app-descriptor.

A predefined set of attributes is specified to allow the application management software to identify, retrieve, and install the MIDlet(s). All attributes appearing in the descriptor file are made available to the MIDlet(s). The developer may use attributes not beginning with MIDlet- or MicroEdition- for application-specific purposes. Attribute names are case-sensitive and MUST match exactly. An attribute MUST NOT appear more than once within the manifest. If an attribute is duplicated the effect is unspecified. The MIDlet retrieves attributes by name by calling the MIDlet.getAppProperty method.

The application descriptor MUST contain the following attributes:

• MIDlet-Name
• MIDlet-Version
• MIDlet-Vendor
• MIDlet-Jar-URL
• MIDlet-Jar-Size

The application descriptor MAY contain:

• MIDlet-<n> for each MIDlet
• MicroEdition-Profile
• MicroEdition-Configuration
• MIDlet-Description
• MIDlet-Icon
• MIDlet-Info-URL
• MIDlet-Data-Size
• MIDlet-Permissions
• MIDlet-Permissions-Opt
• MIDlet-Push-<n>
• MIDlet-Install-Notify
• MIDlet-Delete-Notify
• MIDlet-Delete-Confirm
• Any application-specific attributes that do not begin with MIDlet- or MicroEdition-

The mandatory attributes MIDlet-Name, MIDlet-Version, and MIDlet-Vendor MUST be duplicated in the descriptor and manifest files since they uniquely identify the application. If they are not identical (not from the same application), then the JAR MUST NOT be installed.

Duplication of other manifest attributes in the application descriptor is not required and their values MAY differ even though both the manifest and descriptor files contain the same attribute for untrusted MIDlet suites. If the MIDlet suite is not trusted the value from the descriptor file will override the value from the manifest file. If the MIDlet suite is trusted then the values in the application descriptor MUST be identical to the corresponding attribute values in the Manifest.

MIDlets MUST NOT add any attributes to the manifest or the Application Descriptor that start with MIDlet- or MicroEdition- other than those defined in the relevant Configuration and Profiles (e.g. CLDC and MIDP) specifications. Unrecognized attributes MUST be ignored by the AMS.

Generally speaking, the format of the application descriptor is a sequence of lines consisting of an attribute name followed by a colon, the value of the attribute, and a carriage return. White space is ignored before and after the value. The order of the attributes is arbitrary.

The application descriptor MAY be encoded for transport or storage and MUST be converted to Unicode before parsing, using the rules below. For example, an ISO-8859-1 encoded file would need to be read through the equivalent of java.io.InputStreamReader with the appropriate encoding. The default character encoding for transporting a descriptor is UTF-8. Descriptors retrieved via HTTP, if that is supported, SHOULD use the standard HTTP content negotiation mechanisms, such as the Content-Encoding header and the Content-Type charset parameter to convert the stream to UCS-2.

 appldesc:  *attrline    
 attrline:  attrname ":" [WSP] attrvalue [WSP] newlines
 attrname:  1*<any Unicode char except 
                 CTLs or separators>    
 attrvalue: *valuechar | valuechar *(valuechar | WSP) valuechar    
 valuechar: <any valid Unicode character, 
            excluding CTLS and WSP>    
 newlines = 1*newline  ; allow blank lines to be ignored
 newline:   CR LF | LF 
   
 CR  = <Unicode carriage return (U+000D)>     
 LF  = <Unicode linefeed (U+000A)>     
 
 WSP:  1*( SP | HT )
 SP  = <Unicode space (U+0020)>
 HT  = <Unicode horizontal-tab (U+0009)>
 CTL = <Unicode characters 
           U+0000 - U+001F and U+007F>
 separators: "(" | ")" | "<" |    
             ">" | "@" |   
             "," | ";" | ":" |    
             "'" | <">|    
             "/" | "[" | "]" |    
             "?" | "=" |        
             "{" | "}" | SP | HT            

For example, an application descriptor for a hypothetical suite of card games would look look like the following example:

 MIDlet-Name: CardGames    
 MIDlet-Version: 1.1.9    
 MIDlet-Vendor: CardsRUS    
 MIDlet-1: Solitaire, /Solitare.png, com.cardsrus.org.Solitare     
 MIDlet-2: JacksWild, /JacksWild.png, com.cardsrus.org.JacksWild     
 MicroEdition-Profile: MIDP-2.1    
 MicroEdition-Configuration: CLDC-1.0    
 MIDlet-Description: Really cool card games    
 MIDlet-Jar-URL: http://www.cardsrus.com/games/cardgames.jar    
 MIDlet-Jar-Size: 7378    
 MIDlet-Data-Size: 256     

Application Lifecycle

Each MIDlet MUST extend the MIDlet class. The MIDlet class allows for the orderly starting, stopping, and cleanup of the MIDlet. The MIDlet can request the arguments from the application descriptor to communicate with the application management software. A MIDlet suite MUST NOT have a public static void main() method. If it exists, it MUST be ignored by the application management software. The application management software provides the initial class needed by the CLDC to start a MIDlet.

When a MIDlet suite is installed on a device, its classes, resource files, arguments, and persistent storage are kept on the device and ready for use. The MIDlet(s) are available to the user via the device's application management software.

When the MIDlet is run, an instance of the MIDlet's primary class is created using its public no-argument constructor, and the methods of the MIDlet are called to sequence the MIDlet through its various states. The MIDlet can either request changes in state or notify the application management software of state changes via the MIDlet methods. When the MIDlet is finished or terminated by the application management software, it is destroyed, and the resources it used can be reclaimed, including any objects it created and its classes. The MIDlet MUST NOT call System.exit , which will throw a SecurityException when called by a MIDlet.

The normal states of Java classes are not affected by these classes as they are loaded. Referring to any class will cause it to be loaded, and the normal static initialization will occur.

MIDlet lifecycle

The MIDlet lifecycle defines the protocol between a MIDlet and its environment through the following:

• A simple well-defined state machine

• A concise definition of the MIDlet's states

• APIs to signal changes between the states

MIDlet Lifecycle Definitions

The following definitions are used in the MIDlet lifecycle:

• application management software - a part of the device's software operating environment that manages MIDlets. It maintains the MIDlet state and directs the MIDlet through state changes.

• MIDlet - a MIDP application on the device. The MIDlet can signal the application management software about whether is it wants to run or has completed. A MIDlet has no knowledge of other MIDlets through the MIDlet API.

• MIDlet States - the states a MIDlet can have are defined by the transitions allowable through the MIDlet interface. More specific application states are known only to the application.

MIDlet States

The MIDlet state machine is designed to ensure that the behavior of an application is consistent and as close as possible to what device manufactures and users expect, specifically:

• The perceived startup latency of an application SHOULD be very short.

• It SHOULD be possible to put an application into a state where it is not active.

• It SHOULD be possible to destroy an application at any time.

The valid states for MIDlets are:

The states and transitions for a MIDlet are:

MIDlet Lifecycle Model

A typical sequence of MIDlet execution is:

MIDlet Interface

• pauseApp - the MIDlet SHOULD release any temporary resources and become passive

• startApp - the MIDlet SHOULD acquire any resources it needs and resume

• destroyApp - the MIDlet SHOULD save any state and release all resources

• notifyDestroyed - the MIDlet notifies the application management software that it has cleaned up and is done

• notifyPaused - the MIDlet notifies the application management software that it has paused

• resumeRequest - the MIDlet asks application management software to be started again

• getAppProperty - gets a named property from the MIDlet

Application Implementation Notes

The application SHOULD take measures to avoid race conditions in the execution of the MIDlet methods. Each method may need to synchronize itself with the other methods avoid concurrency problems during state changes.

Example MIDlet Application

The example uses the MIDlet lifecycle to do a simple measurement of the speed of the Java Virtual Machine.

import javax.microedition.midlet.*;      
      
/**      
 * An example MIDlet runs a simple timing test      
 * When it is started by the application management software it will      
 * create a separate thread to do the test.      
 * When it finishes it will notify the application management software      
 * it is done.      
 * Refer to the startApp, pauseApp, and destroyApp      
 * methods so see how it handles each requested transition.      
 */      
public class MethodTimes extends MIDlet implements Runnable {      
    // The state for the timing thread.      
    Thread thread;      
      
    /**      
     * Start creates the thread to do the timing.      
     * It should return immediately to keep the dispatcher      
     * from hanging.      
     */      
    public void startApp() {      
        thread = new Thread(this);      
        thread.start();      
    }      
      
    /**      
     * Pause signals the thread to stop by clearing the thread field.      
     * If stopped before done with the iterations it will      
     * be restarted from scratch later.      
     */      
    public void pauseApp() {      
        thread = null;      
    }      
      
    /**      
     * Destroy must cleanup everything.  The thread is signaled      
     * to stop and no result is produced.      
     */      
    public void destroyApp(boolean unconditional) {      
        thread = null;      
    }      
      
   /**      
     * Run the timing test, measure how long it takes to      
     * call a empty method 1000 times.      
     * Terminate early if the current thread is no longer      
     * the thread from the      
     */      
    public void run() {      
        Thread curr = Thread.currentThread();  // Remember which thread is current      
        long start = System.currentTimeMillis();      
        for (int i = 0; i < 1000000 && thread == curr; i++) {      
            empty();      
        }      
        long end = System.currentTimeMillis();      
      
        // Check if timing was aborted, if so just exit      
        // The rest of the application has already become quiescent.      
        if (thread != curr) {      
            return;      
        }      
        long millis = end - start;      
        // Reporting the elapsed time is outside the scope of this example.      
      
        // All done cleanup and quit      
        destroyApp(true);      
        notifyDestroyed();      
    }      
      
    /**      
     * An Empty method.      
     */      
    void empty() {      
    }      
}     

This package provides the payment application programming interface. This application programming interface has been designed to allow for an asynchronous handling of payment transactions. This is achieved by an emit/notify mechanism, respectively represented by the TransactionModule class and TransactionListener interface.

Design

The MIDP X.509 Certificate Profile below defines the format and usage of certificates. X.509 Certificates MUST be supported. Other certificate formats MAY be supported. The implementation MAY store only the essential information from certificates. Internally, the fields of the certificate MAY be stored in any format that is suitable for the implementation.

References

MIDP devices are expected to operate using standard Internet and wireless protocols and techniques for transport and security. The current mechanisms for securing Internet content is based on existing Internet standards for public key cryptography:

• [RFC2437] - PKCS #1 RSA Encryption Version 2.0
• [RFC2459] - Internet X.509 Public Key Infrastructure
• [WAPCERT] - WAP-211-WAPCert-20010522-a - WAP Certificate Profile Specification

MIDP X.509 Certificate Profile

WAP-211-WAPCert-20010522-a [WAPCert] which is based on RFC2459 Internet X.509 Public Key Infrastructure Certificate and CRL Profile [RFC2459].

Devices MUST conform to all mandatory requirements in [WAPCert] and SHOULD conform to all optional requirements in [WAPCert] except those requirements in excluded sections listed below. Mandatory and optional requirements are listed in Appendix C of [WAPCert]. Additional requirements, ON TOP of those listed in [WAPCert] are given below.

• Excluding [WAPCert] Section 6.2, User Certificates for Authentication
• Excluding [WAPCert] Section 6.3, User Certificates for Digital Signatures

RFC2459 contains sections which are not relevant to implementations of this specification. The WAP Certificate Profile does not mention these functions. The sections to be excluded are:

• Exclude the requirements from Paragraphs 4 of Section 4.2 - Standard Certificate Extensions. A conforming implementation of this specification does not need to recognize extensions that must or may be critical including certificate policies, name constraints, and policy constraints.
• Exclude RFC2459 Section 6.2 Extending Path Validation. Support for Policy Certificate Authority or policy attributes is not required.

Certificate Extensions

A version 1 X.509 certificate MUST be considered equivalent to a version 3 certificate with no extensions. At a minimum, a device conforming to this profile MUST recognize key usage (see RFC2459 sec. 4.2.1.3), basic constraints (see RFC2459 sec. 4.2.1.10).

Although a conforming device may not recognize the authority and subject key identifier (see RFC2459 sec. 4.2.1.1 and 4.2.1.2) extensions it MUST support certificate authorities that sign certificates using the same distinguished name but using multiple public keys.

Implementations MUST be able to process certificates with unknown distinguished name attributes.

Implementations MUST be able to process certificates with unknown, non-critical certificate extensions.

The serialNumber attribute defined by [WAPCert] must be recognized in distinguished names for Issuer and Subject.

Certificate Size

Devices must be able to process certificates that are not self-signed root CA certificates of size up to at least 1500 bytes.

Algorithm Support

A device MUST support the RSA signature algorithm with the SHA-1 hash function sha1WithRSAEncryption as defined by PKCS #1 [RFC2437]. Devices that support these algorithms MUST be capable of verifying signatures made with RSA keys of length up to and including 2048 bits.

Devices SHOULD support signature algorithms md2WithRSAEncryption and md5WithRSAEncryption as defined in [RFC2437]. Devices that support these algorithms MUST be capable of verifying signatures made with RSA keys of length up to and including 2048 bits.

Certificate Processing for HTTPS

Devices MUST recognize the extended key usage extension defined of RFC2818 if it is present and is marked critical and when present MUST verify that the extension contains the id-kp-serverAuth object identifier (see RFC2459 sec. 4.2.1.13).

SSL and TLS allow the web server to include the redundant root certificate in the server certificate message. In practice this certificate may not have the basic constraint extension (it is most likely a version 1 certificate), a device MUST ignore the redundant certificate in this case. Web servers SHOULD NOT include a self-signed root CA in a certificate chain.

This package defines an API which allows applications to send and receive wireless messages. The API is generic and independent of the underlying messaging protocol. The underlying protocol can be, for example, GSM Short Message Service, CDMA SMS, and so on.

Overview

This package is designed to work with Message objects that may contain different elements depending on the underlying messaging protocol. This is different from Datagrams that are assumed always to be blocks of binary data.

An adapter specification for a given messaging protocol may define further interfaces derived from the Message interfaces included in this generic specification.

Unlike network layer datagrams, the wireless messaging protocols that are accessed by using this API are typically of store-and-forward nature. Messages will usually reach the recipient, even if the recipient is not connected at the time of sending. This may happen significantly later if the recipient is disconnected for a long period of time. Sending and possibly also receiving these wireless messages typically involves a financial cost to the end user that cannot be neglected. Therefore, applications should not send unnecessary messages.

The MessageConnection and Message Interfaces

The MessageConnection interface represents a Connection that can be used for sending and receiving messages. The application opens a MessageConnection with the Generic Connection Framework by providing a URL connection string.

The MessageConnection can be opened either in "server" or in "client" mode. A "server" mode connection is opened by providing a URL that specifies an identifier for an application on the local device for incoming messages. A port number is an example of an identifier. Messages received with this identifier will then be delivered to the application by using this connection. A "server" mode connection can be used both for sending and for receiving messages.

A "client" mode connection is opened by providing a URL that points to another device. A "client" mode connection can only be used for sending messages.

The messages are represented by the Message interface and interfaces derived from it. The Message interface has the very basic functions that are common to all messages. Derived interfaces represent messages of different types and provide methods for accessing type-specific features. The kinds of derived interfaces that are supported depends on the underlying messaging protocol. If necessary, interfaces derived from Message can be defined in the adapter definitions for mapping the API to an underlying protocol.

The mechanism to derive new interfaces from the Message is intended as an extensibility mechanism allowing new protocols to be supported in platforms. Applications are not expected to create their own classes that implement the Message interface. The only correct way for applications to create object instances implementing the Message interface is to use the MessageConnection.newMessage factory method.

BinaryMessage and TextMessage are subinterfaces of Message representing binary and text messages. They have methods to get and set the binary/text data payloads. To create instances of these classes, use the MessageConnection.newMessage factory method, using MessageConnection.BINARY_MESSAGE or MessageConnection.TEXT_MESSAGE for the message type.

The MessageListener interface provides a mechanism for the application to be notified of incoming messages. The listener mechanism allows applications to receive incoming messages without needing to have a thread blocked in the receive() method call.

This package, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.