Retrieving MIDlet Attributes

Attributes in the Mobile Information Device Profile (MIDP) are similar in concept to the properties seen in the java.util.Properties package in the Java 2 Platform, Standard Edition (J2SE). Attributes are name-value pairs of strings that are bound into a MIDlet suite. You can use them to set initial default values or to control the behavior of your MIDlet in a way that's far more convenient than hard-coding values into the MIDlet suite. A common example in a network-aware MIDlet is a server URL. If you implement the URL as an attribute retrieved at runtime, you don't need to rebuild the MIDlet suite's Java Archive (JAR) file entirely each time you change the attribute's value. Using attributes this way increases the flexibility of the MIDlet, and reduces both build and test time.

The Pieces

As distributed, a MIDlet suite consists of a JAR file and a Java Descriptor (JAD) file. The JAD file contains the attributes the application management software (AMS) will use to manage the MIDlet's life-cycle, as well as the application-specific attributes the MIDlet suite itself will use. The JAR file contains a manifest, /META-INF/MANIFEST.MF, a special file that contains metainformation about the files in the JAR file, as well as other information, such as attributes for both AMS and MIDlet. Because you can specify attributes in both the descriptor and the manifest, there must be a policy for locating attributes, and for resolving any differences between values in the two locations.

Reserved Names

The MIDP 2.0 specification defines the rules for using attributes. Attribute names that begin with "MIDlet-" or "MicroEdition-", including the hyphen, are reserved and used by the AMS. The specification defines 18 reserved attribute names that can be categorized as follows: installation-required, installation-optional, runtime-required, and runtime-optional. The following table shows you where each attribute name may or must appear.

MIDP 2.0 Reserved Attribute Names

1. Must occur in manifest or descriptor; that is, it may appear in either, but is not optional.
2. Same as the System property microedition.profiles.
3. Same as the System property microedition.configuration.
4. <m> is an integer, starting at 1 and incremented by 1 for each MIDlet.
5. <n> is an integer, starting at 1 and incremented by 1 for each Push Registry entry.

Retrieving MIDlet Attributes

To retrieve an attribute's value, you call the method MIDlet.getAppProperty(), passing the attribute's name as a string. This method's behavior depends on whether the MIDlet suite is trusted or untrusted:

• If the MIDlet suite's JAR file is signed, the AMS checks the digital signature. If the signature is invalid, the AMS simply refuses to install the suite. If the signature is valid, the AMS considers the MIDlet suite to be trusted. It then searches the manifest file and the JAD file – the manifest first because it's in the JAR file, whose integrity the AMS has just verified. If the attribute is found in both the manifest and the descriptor, the values must match. If they don't, installation of the MIDlet suite will fail.
  
  
• If a MIDlet suite is unsigned, the AMS cannot verify the integrity of its JAR file, and considers it to be untrusted. The AMS searches the JAD file first, and only if it doesn't find the attribute does it consult the manifest file. If the attribute appears in both locations, it uses the value in the JAD and never sees the value in the manifest.
  
  

For more information about signing and verifying MIDlet suite JAR files, see " Understanding MIDP 2.0's Security Architecture."

Here's how the logic of MIDlet.getAppProperty() looks in pseudocode:

        given   : String key    // attribute name
        return  : String value
        throws  : NullPointerException if key is null

        if trusted
                String  v0      = lookup key in manifest
                String  v1      = lookup key in descriptor

                if ( v0 != null && v1 != null )
                        // found in both; must be the same value
                        assert( v0.compareTo( v1 ) == 0 );

                value   = ( v1 != null )? v1 : v0;
        else // untrusted
                value   = lookup key in descriptor

                if value == null
                        value   = lookup key in manifest

        return value

In addition to this algorithm, you should keep in mind the following characteristics of attributes:

• Names are case-sensitive.
  
  
• There is no iteration or enumeration of the attribute space.
  
  
• Attribute names should appear only once in a single location; if an attribute appears more than once in either the manifest or the descriptor, the behavior is unspecified.
  
  
• The attribute namespace is read-only; there is no MIDlet.setAppProperty() method.
  
  
• The MIDlet suite cannot discover the source location of a value.
  
  

An Example

In the following example, a MIDlet suite uses an attribute to store a URL associated with a hypothetical servlet. The attribute name is present in both the descriptor and the manifest, but the values differ.

        MIDlet.jad
                mycontacts.url : https://www.SomeURL.com/mycontacts/login.jsp

        /META-INF/MANIFEST.MF
                mycontacts.url : https://www.SomeOtherURL.com/mycontacts/login.jsp

        MIDlet.java
                ...
                String  siteurl = getAppProperty( "mycontacts.url" );
                String  userid  = Dictionary.getValue( siteurl + "userid" );
                String  url     = siteurl + "?" + userid;
                ...

If the MIDlet suite is trusted, this code will cause installation to fail, because the attribute "mycontacts.url" appears in both locations but the values don't match. If it's untrusted, the MIDlet suite will be installed, and getAppProperty() will return the value "https://www.SomeURL.com/mycontacts/login.jsp" for the name "mycontacts.url" because the method finds the JAD file's value first, and doesn't go on to find the value in the manifest.

Summary

MIDlet suite attributes enable you to create a flexible dictionary of configuration data. Using them can reduce MIDlet build and test time, by separating configuration data from the .java source code into an external file that doesn't require compilation after each change. Attributes can be used securely in trusted MIDlet suites because the manifest, which is in the signed JAR file, is the primary source of attribute values.

For more information on MIDlet attributes, see the MIDP 2.0 specification (JSR 118).

Acknowledgments

Thanks to Enrique Ortiz for reviewing this technical tip.