Application Packaging

Overview and Goals

This chapter provides a high level overview of how application suites and LIBlets (or shared libraries) are packaged; that is, the logical packaging formats, the required and optional files, and the resources, content, and attributes that all application suites and LIBlets must support as a requirement of application packaging. Adherence to these requirements and definitions will ensure content interoperability among implementations, and will also provide guidance to content developers and tools providers.

Functional Requirements

A compliant device MUST be capable of:

Application Suites and LIBlets

An application suite is the fundamental device application packaging component. It contains one or more applications to be executed.

The elements of an application suite are:

Each device is presumed to implement the functions required to select, and run applications, with a MEEP implementation that supports provisioning also to install and delete applications. The term Application Management Software (AMS) is used to refer collectively to these device specific functions. The AMS provides an environment in which the application is installed (if supported), started, stopped, and deleted (if supported). It is responsible for handling errors during the installation (if supported), execution, and removal (if supported) of application suites. It provides to the application(s) the Java runtime environment required by the specification.

A LIBlet is a shareable software component that one or more applications MAY use at runtime. Support for multiple applications to share a common component enables great flexibility and scalability to a platform. LIBlets save static footprint size by enabling multiple application suites to share the same common code without packaging them redundantly. LIBlets effectively reduce download times for applications that declare dependencies on shared components.

Whether LIBlets make sense or not depends on several circumstances - most of all whether an implementation allows the installation of more than one application suite or application suites with more than one application. The support for LIBlets is therefore optional in MEEP 8. All remarks about LIBlets throughout this specification apply if and only if LIBlets are supported of course.

LIBlets are inert code fragments that have no execution context of their own. Classes contained within a LIBlet MUST NOT execute outside the context of the application's execution environment. Each LIBlet exposes a set of classes and resources to applications for their use, just as if those classes and resources were originally packaged within the application JAR. The support for LIBlets is achieved by the presence of LIBlet specific attributes in the JAD and JAR. No runtime specific APIs exist to support LIBlets. For more information about binding LIBlets, see the Execution Environment section.

Packaging

A single JAR is used to package either an application suite or a LIBlet. It MUST NOT contain both, an application suite and a LIBlet. The contents of this JAR include:

The developer is responsible for creating and distributing the components of the JAR 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.

JAR Manifest

The JAR manifest provides information about the contents of the JAR and defines attributes that are used by the application management software to identify and install the application 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 list of attributes and their allowed values can be found in Application Attributes.

Information about the JAR format and the manifest syntax is available in the JDK documentation at the JavaTM Archive (JAR) File documentation. Implementations MUST handle continuation lines starting with a single SPACE, that have to be inserted in order to avoid that lines become longer than 72 bytes (not characters), as defined in the manifest specification.

Manifest attributes are passed to the application when requested using the MIDlet.getAppProperty method. An attribute MAY appear in both the manifest and in the application descriptor, but they MUST have identical values. There is no ambiguity in the value of attributes; each appears either in the manifest or in the application descriptor exclusively, or has exactly the same value in both.

Any attribute that is exactly duplicated within the manifest, irrespective of the attribute value, MUST be treated as an invalid packaging, and MUST result in a failed installation with an installation status report of Status Code 906 (Invalid Descriptor) in the status report.

The manifest for an application suite MUST contain the following attributes:

The manifest for a LIBlet MUST contain the following attributes:

The manifest or the application descriptor for an application suite MUST contain the following attributes:

The manifest or the application descriptor for an application suite or for a LIBlet MUST contain the following attributes:

The manifest for an application suite MAY contain the following:

The manifest for a LIBlet MAY contain the following:

For example, a manifest for a hypothetical application suite of communication applications would look like the following example: 

MIDlet-Name: CommSuite
MIDlet-Version: 1.2.3
MIDlet-Vendor: Communication Corp.
MIDlet-1: QuickMessage, , com.communicorp.suite.QuickMessage
MIDlet-2: ProfiProt, , com.communicorp.suite.ProfiProt
MicroEdition-Profile: MEEP-8.0
MicroEdition-Configuration: CLDC-1.8
Solitaire-Author: John Q. Messenger

Service Providers

A service is a well-known set of interfaces and (usually abstract) classes. A service provider is a specific implementation of a service. The java.util.ServiceLoader specification contains the definition of services, the API to access services and the mechanism to configure them. There may be zero or more providers that implement the service.

The application or LIBlet provides a service by including a valid service provider configuration file in the JAR directory META-INF/services as defined by java.util.ServiceLoader. The application or LIBlet MUST include the service provider implementation classes and all necessary resources, etc. needed by the service. If the services configuration file is invalid or if the implementation classes listed in the configuration file are missing the service description is invalid and must not be used.

A service provider configured in the application JAR or LIBlet JARs that the application suite depends on is accessible to the application. If a service provider is explicitly exported by a LIBlet then it is available for potential use by other applications that depend on the LIBlet or the service. A service is exported by including the LIBlet-Services attribute in the JAD/Manifest of the LIBlet providing the service.

Service providers can be used within the application without further declaration. To use a service provider exported by a LIBlet an explicit dependency MUST be declared in the JAD/manifest of the client application using the MIDlet-Dependency-<n> and LIBlet-Dependency-<n> attributes.

Application Descriptor

Each JAR 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 application and is used by the application itself for configuration specific attributes. The descriptor allows the application management software on the device to verify that the application is suited to the device before loading the full JAR of the application suite. It also allows configuration-specific attributes (parameters) to be supplied to the application(s) without modifying the JAR.

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

A predefined set of attributes is specified to allow the application management software to identify, retrieve, and install the application(s). All attributes appearing in the application descriptor are made available to the application(s). The list of attributes and their allowed values can be found in Application Attributes.

Application developers and implementers MAY define attributes not beginning with MIDlet-, MicroEdition-, or LIBlet- for application-specific purposes. Vendor and application specific attributes SHOULD have a prefix that identifies the company or other entity. Attribute names are case-sensitive and MUST match exactly. An attribute MUST NOT appear more than once within the application descriptor. Any attribute that is exactly duplicated within the application descriptor, irrespective of the attribute value, MUST be treated as an invalid packaging, and MUST result in a failed installation with an installation status report of Status Code 906 (Invalid Descriptor) in the status report. The application can retrieve an attribute by name by calling the MIDlet.getAppProperty method.

The application descriptor for an application suite MUST contain the following attributes:

The application descriptor for a LIBlet MUST contain the following attributes:

In addition, the application descriptor of an application suite SHOULD contain the following attributes:

And the application descriptor of a LIBlet SHOULD contain the following attributes in addition:

The application descriptor for an application suite MAY additionally contain:

The application descriptor for a LIBlet MAY additionally contain:

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

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.

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

MIDlet-Name: CommSuite
MIDlet-Version: 1.2.3
MIDlet-Vendor: Communication Corp.
MIDlet-1: QuickMessage, , com.communicorp.suite.QuickMessage
MIDlet-2: ProfiProt, , com.communicorp.suite.ProfiProt
MicroEdition-Profile: MEEP-8.0
MicroEdition-Configuration: CLDC-1.8
MIDlet-Description: Really useful communication tools
MIDlet-Jar-URL: http://www.communicorp.com/commsuite/commsuite.jar
MIDlet-Jar-Size: 5612
MIDlet-Data-Size: 256

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 UTF-8 character encoding is the default character encoding for application descriptors, unless otherwise specified. Descriptors retrieved via HTTP, if that is supported, SHOULD use the standard HTTP content negotiation mechanisms, such as the Content-Encoding header and the charset parameter of the Content-Type header, to correctly convert the stream to Unicode.

Application descriptors, especially those with many localized versions of the attributes, may contain characters used in many different languages and writing systems. It is RECOMMENDED that UTF-8 be used as the character encoding of descriptors, and that the encoding is correctly indicated in the HTTP headers.

BNF for Parsing Application Descriptors 

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

Application Suite Packaging

An application suite is packaged as a single JAR which MUST contain one or more applications. The JAR contains class files, resources, service providers, and a manifest describing the JAR contents. An application suite MAY be accompanied by an associated JAD. All application and application attributes present in both the Application JAD and Manifest MUST match exactly.

The following attributes MUST NOT be present in the application Manifest, and MUST be present only in the application JAD :

LIBlet Packaging

A LIBlet is packaged in a JAR, in a similar way to an application suite. A LIBlet JAR contains class files, associated resources, service providers, and a Manifest describing the contents. A LIBlet JAR MUST contain exactly one LIBlet. A LIBlet MUST have an associated JAD. All LIBlet and user defined application attributes MUST be present in both the LIBlet JAD and LIBlet Manifest, and they MUST match exactly, with the following exceptions that MUST NOT be present in the LIBlet Manifest, and MUST be present only in the LIBlet JAD :

Application suites SHOULD NOT modify any attributes in nor add any attributes to the JAD or Manifest of LIBlets they depend on. Application suites SHOULD locate any additional application attributes in the application suite's manifest and JAD.

At installation time, when binding application suites together with independently developed LIBlets, there is potential for namespace conflicts if the application suite and LIBlets implement classes with the same name in the same packages. Implementations MUST ensure there are no namespace conflicts at install time. The application suite and the LIBlets it depends on MUST be packaged in non-overlapping namespaces, with package level granularity. Implementations MUST also ensure that resources with the same name do not exist in the application suite-LIBlet binding. It is RECOMMENDED that resources are placed in packages alongside the classes that use them to prevent resource level namespace collisions. Implementations MUST enumerate all the application suite JARs and LIBlet JARs to ensure that none of the described collisions exist. The values of attributes defined for a LIBlet MUST be retrieved with the LIBlet name and vendor; thus no namespace collision issue exists across LIBlets.

Application Attributes

This section describes the application attributes and their allowed values. Refer to Appendix A - Application Attributes for details on how application attributes can be included in the JAR manifest and the application descriptor.

Among other things, attributes allow the application management software to identify, retrieve, install, and invoke the application.

Any attribute that is exactly duplicated within the manifest, irrespective of the attribute value, MUST be treated as an invalid packaging, and MUST result in a failed installation with an installation status report of Status Code 906 (Invalid Descriptor) in the status report.

Applications must not add any attributes to the application suite JAR manifest or the Application Descriptor that begin with MIDlet- or MicroEdition- other than those defined in the relevant Configuration and Profile (e.g. CLDC-1.8 and MEEP-8.0) specifications. In addition, applications must not add any attributes that begin with LIBlet-. Unrecognized attributes that begin with MIDlet- or MicroEdition- and all attributes that begin with LIBlet- (except LIBlet-Name) MUST be ignored by the AMS, MUST be discarded, and their values MUST NOT be made available to a running application. An attribute LIBlet-Name though causes the installation to fail with an installation status report of Status Code 906 (Invalid Descriptor) in the status report.

LIBlets must not add any attributes to the LIBlet JAR manifest or the LIBlet JAD that begin with LIBlet- or MicroEdition- other than those defined in this specification. In addition, LIBlets must not add any attributes that begin with MIDlet-. Unrecognized attributes that begin with LIBlet- or MicroEdition- and all attributes that begin with MIDlet- (except MIDlet-Name) MUST be ignored by the AMS, MUST be discarded, and their values MUST NOT be made available to a running application. An attribute MIDlet-Name though causes the installation to fail with an installation status report of Status Code 906 (Invalid Descriptor) in the status report.

For ease of reference, the attributes are grouped by usage as follows:

In various attributes, <n> (and <m>) represent values of the integer sequence n = { 1, 2, ... }. The first non-consecutive value of n terminates the list, and any additional values MUST be ignored.

<locale> represents a valid value of the microedition.locale system property. See the Handling Localized Attribute Versions section for more information.

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 for each value.

Identification Attributes

Identification attributes are used by the AMS in various phases of the application lifecycle.

The following table defines the identification attributes used for application suites and individual applications.

Table 2-a : Application Identification Attributes

Attribute Name

Attribute Description

MIDlet-Name

The name of the application suite. This attribute identifies the applications, and that the JAD/JAR entity represents an application suite, not a LIBlet. If the JAD/Manifest contains both MIDlet-Name and LIBlet-Name, then the installation of such a JAD/JAR MUST fail.

MIDlet-Name-<locale>

Optional, localized version of the application suite name for <locale>. This attribute MUST NOT be used instead of the original MIDlet-Name for verification. It is only intended for display purposes.

MIDlet-Version

The version number of the application suite. Version numbers are formatted so that they can be used by the application management software for install and update purposes.

MIDlet-Vendor

The organization that provides the application suite.

MIDlet-Description

The description of the application suite.

MIDlet-Description-<locale>

Optional localized version of the application suite description for <locale>. If a description is not available for the current locale, the value of the MIDlet-Description attribute MUST be used.

MIDlet-<n>

<name>, <icon> ,<class>

The name, icon and class of the nth application in the JAR, separated by a comma.

  • <name> is used to identify this application. The name MUST be present and be non-null.
  • <icon> is the case-sensitive absolute path name of an image within the JAR for the icon of the n th application. The icon MAY be omitted, but in devices without any graphics support, it MUST be ignored. Otherwise, the image file MUST be in the PNG format.

    If an implementation is able to display application icons, the following requirements apply for bitmap image formats:

    • The application manager MUST always be able to display an icon of 16 by 16 pixels in the application list.
    • The application manager SHOULD always be able to display an icon of 24 by 24 pixels in the application list.
    • An icon larger than 24 by 24 MAY be displayed properly in full size in the application list.
  • <class> is the name of the class extending the javax.microedition.midlet.MIDlet class for the nth application. The classname MUST be non-null and contain only characters for Java class names. The class MUST have a public no-args constructor. The class name MUST be treated as case sensitive.

MIDlet-<n>-<locale>

Localized version of the MIDlet-<n> attribute. The values are the same as in the MIDlet-<n> attribute, except that all the parts of the value - name, icon and class are OPTIONAL. If some part is missing, the corresponding part of the MIDlet-<n> value MUST be used. If an implementation does not support graphics, the icon part, if present, MUST be ignored.

If there is no MIDlet-<n>-<locale> attribute present for the current locale, the value of the MIDlet-<n> attribute MUST be used.

The following table defines the identification attributes used for LIBlets.

Table 2-b : Identification Attributes for LIBlets

Attribute Name

Attribute Description

LIBlet-Name

The name of the LIBlet. This attribute identifies that the JAD/JAR entity represents a LIBlet, not an application. If the JAD/Manifest contains both LIBlet-Name and MIDlet-Name, then the installation of such a JAD/JAR MUST fail.

LIBlet-Version

The version number of the LIBlet. Version numbers are formatted so that they can be used by the application management software for install and update purposes.

LIBlet-Vendor

The vendor of the LIBlet.

LIBlet-Services

The services exported from the LIBlet. The attribute contains a list of one or more services. Multiple services are separated by a comma (Unicode U+002C). Leading and trailing whitespace (Unicode U+0020) and tabs (Unicode U+0009) are ignored.

LIBlet-Description Description of the LIBlet.
LIBlet-Description-<locale> Description of the LIBlet for <locale>.

Provisioning Attributes

Provisioning attributes are used by the AMS when discovering, installing, updating and deleting application suites and related LIBlets.

The following table lists the application suite attributes related to provisioning.

Table 2-c : Provisioning Attributes for Application Suites and Applications

Attribute Name

Attribute Description

MIDlet-Info-URL

A URL for information further describing the application suite. The syntax and meaning MUST conform to [RFC3986] and the RFCs that define each scheme.

MIDlet-Jar-URL

The URL from which the JAR can be loaded. The syntax and meaning MUST conform to [RFC3986] and RFCs that define each scheme. Both absolute and relative URLs MUST be supported. The context for a relative URL is the URL from which this application descriptor was loaded.

MIDlet-Update-URL

The absolute URL to use for automatic updates of the application suite. The syntax and meaning MUST conform to [RFC3986] and RFCs that define each scheme.

If the value contains a valid URL, the automatic update of the application suite MUST be requested from this URL. Note that this overrides the priority rules used to decide which URL is used in updating. In this case other URLs MUST NOT be used, and other rules related to the update MUST remain in effect.

MIDlet-Jar-Size

The number of bytes in the JAR.

MIDlet-Data-Size

The minimum number of bytes of persistent data required by the application. The device may provide additional storage according to its own policy. The default is zero.

MIDlet-Install-Notify

<url> [;ack]

<url> = The URL to which an HTTP POST request is sent to report the installation status (whether a new installation or application suite update) of this application suite. The device MUST use this URL unmodified. The URL MUST be no longer than 256 UTF-8 encoded characters. If the device receives a URL longer than 256 UTF-8 encoded characters, it MUST reject the installation and return Status Code 906 (Invalid Descriptor) in the status report.

ack = optional value to indicate that installation MUST NOT be considered successful and the application suite MUST NOT be made available for use if no acknowledgement is received after the installation status report has been sent.

MIDlet-Delete-Notify

The URL to which a POST request is sent to report the deletion of this application suite. The device MUST use this URL unmodified. The URL MUST be no longer than 256 UTF-8 encoded characters. If the device receives a URL longer than 256 UTF-8 encoded characters it MUST reject the installation and return Status Code 906 (Invalid Descriptor) in the status report.

MIDlet-Certificate-<n>-<m>

The Base64 encoding of a security certificate. Only useful if the mechanism as described in Authenticating an Application Suite or LIBlet section is used for authentication. Please consider that implementations are free to implement other mechanisms instead being out of scope of this specification.

<n> = a number equal to 1 for first certificate chain in the descriptor or 1 greater than the previous number for additional certificate chains. This defines the sequence in which the certificates are tested to see if the corresponding Root Certificate can be found. See the Authenticating an Application Suite or LIBlet section for details.

<m> = a number equal to 1 for the signer's certificate in a certificate chain or 1 greater than the previous number for any subsequent intermediate certificates.

MIDlet-Jar-RSA-SHA1-<n>

The Base64 encoding of the JAR signature

<n> = a number equal to 1 for the first signature or greater than one for each consecutive signature. The number corresponds to number <n> in the MIDlet-Certificate-<n>-<m> attribute.

MIDlet-<n>-Category

The attribute value is a comma separated list of different categories that implementations may use when choosing how to make the application available. Implementations may ignore some or all of the values, or may combine them to make an application available in several ways. Supported values are platform specific.

MIDlet-Profile-Request

Possible values: true, false.

The attribute value specifies true to indicate that application descriptor MUST be downloaded by providing the client profile using UAProf for Device Identification.

This attribute is only useful if OTA has been chosen as the Provisioning algorithm for this implementation!

The following table lists the LIBlet attributes related to provisioning.

Table 2-d : Provisioning Attributes for LIBlets

Attribute Name

Attribute Description

LIBlet-Jar-URL

 The URL from which the LIBlet JAR can be downloaded.

LIBlet-Jar-Size

The size of the JAR.

LIBlet-Install-Notify

The URL to which a POST request is sent to confirm successful installation of this LIBlet.

LIBlet-Delete-Notify

The URL to which a POST request is sent to report deletion of this LIBlet.

LIBlet-Certificate-<n>-<m>

The Base64 encoding of a security certificate. Only useful if the mechanism as described in Authenticating an Application Suite or LIBlet section is used for authentication. Please consider that implementations are free to implement other mechanisms instead being out of scope of this specification.

<n> = a number equal to 1 for first certificate chain in the descriptor or 1 greater than the previous number for additional certificate chains. This defines the sequence in which the certificates are tested to see if the corresponding Root Certificate can be found. See the Authenticating an Application Suite or LIBlet section for details.

<m> = a number equal to 1 for the signer's certificate in a certificate chain or 1 greater than the previous number for any subsequent intermediate certificates.

LIBlet-Jar-RSA-SHA1-<n>

The Base64 encoding of the JAR signature

<n> = a number equal to 1 for the first signature or greater than one for each consecutive signature. The number corresponds to number <n> in the LIBlet-Certificate-<n>-<m> attribute.

Operational Attributes

Operational attributes affect the invocation and runtime behavior of applications.

The following tables list the operational attributes for application suites, individual applications, and LIBlets that bind to these.

Table 2-e : Operational Attributes for Application Suites and Applications

Attribute Name

Attribute Description

MicroEdition-Profile

The Java ME profiles required, using the same format and value as the system property microedition.profiles (for example "MEEP-8.0"). For each of the profiles listed, the device MUST implement a profile that is able to install (if provisioning is supported) an application declaring itself as of the listed profile and is also able to launch the class referenced by the MIDlet-1 attribute value. E.g. for Microedition-Profile: IMP-NG it would be enough if the device implements MEEP-8, as MEEP-8 is able to install and run IMP-NG applications as legacy applications. If this condition is not fulfilled for any of the profiles listed, the installation MUST fail.

Multiple profiles are separated with a blank (Unicode U+0020). The value of this attribute MUST NOT contain different versions of the same profile. An application suite should declare the single lowest profile version it needs to run.

This attribute MUST be used by LIBlets and application.

MicroEdition-Configuration

The Java ME Configuration required, using the same format and value as the system property microedition.configuration (for example "CLDC-1.8"). As for the value, there are exceptions for legacy applications.

This attribute MUST be used by LIBlets and application.

MIDlet-Permission-<n>

A fully qualified permission class, with optional resource name and actions, that are critical to the function of the application suite. Besides, MEEP 8 also allows named permissions (see the Legacy compatibility chapter for details), although being deprecated.

MIDlet-Permission-Opt-<n>

A fully qualified permission class, with optional resource name and actions, that are not-critical to the function of the application suite. Besides, MEEP 8 also allows named permissions (see the Legacy compatibility chapter for details), although being deprecated.

MIDlet-Push-<n>

Register an application to handle inbound connections. Refer to PushRegistry for details.

MIDlet-Event-Launch-<n>

Register an application to launch on an event. Refer to EventManager for details.

MIDlet-Required-IP-Version

Possible values: ipv4, ipv6, any. Specifies which IP version the applications in a suite MUST use. If the device cannot support the requested version, the installation of the application suite MUST fail. If the required version is not available at runtime, a java.io.IOException MUST be thrown.

MIDlet-<n>-Type

Possible value: autostart. The attribute value is a comma separated list of different types for which the application implements the required behaviors. It is possible for a application to implement the behaviors of several types, if any. Here <n> corresponds to the nth application in the suite identified using the MIDlet-<n> attribute.
autostart: the application implements the Auto Start Application behavior.

MIDlet-Dependency-<n>

Dependency on an implementation of a standard optional API, an optional MEEP package, a service, a proprietary API, or a LIBlet. For the format of the value see here.

MIDlet-Dependency-JAD-URL-<n>

URL to download the dependency LIBlet from.

Table 2-f : Operational Attributes for LIBlets

Attribute Name

Attribute Description
LIBlet-Permission-<n>

A fully qualified permission class, with optional resource name and actions, that are critical to the function of the LIBlet. Besides, MEEP 8 also allows named permissions (see the Legacy compatibility chapter for details), although being deprecated.

LIBlet-Permission-Opt-<n>

A fully qualified permission class, with optional resource name and actions, that are not-critical to the function of the LIBlet. Besides, MEEP 8 also allows named permissions (see the Legacy compatibility chapter for details), although being deprecated.

LIBlet-Permissions

MEEP 8 allows named permissions (see the Legacy compatibility chapter for details), although being deprecated. This attribute is used to require critical named permissions for LIBlets.

LIBlet-Permission-Opt

MEEP 8 allows named permissions (see the Legacy compatibility chapter for details), although being deprecated. This attribute is used to require non-critical named permissions for LIBlets.

LIBlet-Dependency-<n>

Dependency on an implementation of a standard optional API, an optional MEEP package, a service, a proprietary API, or a LIBlet. For the format of the value see here.

LIBlet-Dependency-JAD-URL-<n>

URL to download the dependency LIBlet from.

Handling Localized Attribute Versions

In the above, all locale identifiers in attribute names (represented by <locale>) MUST be interpreted as valid values of the microedition.locale system property. Attributes that pertain to user interface languages not currently present in the device MAY be discarded at installation time to save storage space. Usually one or more localized attribute versions end up being retained, but in the most degenerate case (and depending on how the device is configured) the application installer could end up retaining only the original default attributes and none of the localized versions. Developers are encouraged to include localized attribute versions for at least those user interface languages they anticipate to be present in their target device configuration (often referred to as a "language pack").

The AMS SHOULD use the retained localized attribute versions to show information about the installed applications to the user. First the AMS SHOULD look for a locale-specific attribute where the <locale> part matches the current microedition.locale system property value. If such an attribute version is not found, the AMS SHOULD proceed by successively removing the variant, country, and language part from <locale>, until a match is found or <locale> is exhausted. In the case of a match the localized value MUST be used. If there is no match, the default attribute value MUST be used.

Example scenario: the microedition.locale system property has the value de-DE and the application descriptor (or manifest) contains the MIDlet-Name-de attribute. In this case the AMS first looks for a MIDlet-Name-de-DE attribute, but it is not found, so the country part is removed and a new search is made. This time the MIDlet-Name-de attribute is found, and the AMS uses its value. If the MIDlet-Name-de attribute had not been present either, the AMS would have used the original MIDlet-Name attribute.

Dependency Expression

Both application suites and LIBlets MUST declare dependencies for any LIBlet, or service, that the application suite or LIBlet directly depends on. Dependencies on standard APIs (other JSRs), optional MEEP packages, or proprietary APIs are not mandatory to be declared, but it is recommended to do so in order to avoid the installation of applications that cannot run on this platform due to missing components.

An application suite and each of its dependencies forms a distinct binding. Any declared dependencies that cannot be satisfied by an implementation MUST be treated as an invalid packaging, and the installation MUST fail with Status Code 915 (Missing Dependencies).

Dependency Attributes

The MIDlet-Dependency-<n> and LIBlet-Dependency-<n> attributes allow an application or a LIBlet to specify a dependency on an implementation of a standard optional API, an optional MEEP package, a service, a proprietary API, or a LIBlet. The format of the value is:

<type>;<level>;<name>; <vendor>;<version>

The components of the value are:

When the LIBlet dependency is resolved, the matching algorithm to be used depends on the type of the dependency.

If the type is liblet, the match is based solely on the name, vendor, and version. If the type is standard or proprietary, the implementation MUST look for a match based on the name, vendor and version fields of the dependency expression.

If LIBlets are not supported by this implementation, the existence of this attribute with <type> = liblet | service and <level> = required means that the application suite MUST NOT be installed. If the type is liblet | service but <level> = optional, those attributes are ignored in this case.

The LIBlet JAD Download URL Attribute

The MIDlet-Dependency-JAD-URL-<n> and LIBlet-Dependency-JAD-URL-<n> attributes indicate the URL to download the dependency LIBlet from. This URL is used to retrieve the LIBlet if it is not already available on the device. For each MIDlet-Dependency-<n> or LIBlet-Dependency-<n> attribute in a JAD or manifest that refers to a LIBlet, there MUST also be a corresponding MIDlet-Dependency-JAD-URL-<n> or LIBlet-Dependency-JAD-URL-<n> attribute in the same JAD or manifest.

If LIBlets are not supported by this implementation, this attribute is ignored. Please be aware that the existence of the MIDlet-Dependency-<n> attribute with <type> = liblet | service and <level> = required means that the application suite MUST NOT be installed though.

Dependency Declaration Chain

A LIBlet is uniquely identified by the triplet of name, vendor, and version. For a given dependency declaration chain, the same LIBlet MAY appear multiple times. However, LIBlets with the same name and vendor but different version MUST NOT exist within a single application's dependency declaration chain. Also, an application suite name and vendor pair MUST NOT match a LIBlet name and vendor pair within the application suite's dependency chain. These situations form an invalid package.

Since LIBlets can in turn depend on other LIBlets, it is possible for application suites to specify circular dependencies; such dependencies exist whenever an application suite dependency declaration chain contains a loop. The level of a dependency (optional or required) does not factor into circular dependency checking; implementations MUST enforce circular dependency checking on all dependencies found in the application suite dependency declaration chain, regardless of the specified level of any dependency in the chain; circular dependencies MUST be treated as an invalid packaging and MUST fail installation. Circular dependencies can be avoided by:

For a single application suite dependency declaration chain, implementations MUST allow a minimum of 16 LIBlet dependencies. As well, implementations SHOULD impose an upper limit on the number of LIBlet dependencies allowed for a single application suite. If an implementation imposes such an upper limit, and if an application suite exceeds that limit, then the implementation MUST fail installation.

If an application suite exceeds the number of LIBlet dependencies allowed by an implementation, it is recommended that the application developers reduce the number of LIBlet dependencies by combining multiple LIBlets into a single LIBlet.

Dependency Expression Example

As an example, consider a navigation application that depends on JSR 179 and a Maps LIBlet developed by a map vendor. The Maps LIBlet in turn has dependencies on the crypto package of JSR 177 (microedition.satsa.crypto) and a LIBlet that provides location based services (LBS) developed by another vendor. The LBS LIBlet then has an optional dependency on the javax.bluetooth package of JSR 82 and a proprietary location API.

Figure 2-1 : Navigation Application Dependencies

Navigation Application Dependencies

The JAD of the navigation application contains : 


    MIDlet-1: Maps-Navi, , MapsNavi
    MIDlet-Name: Maps On The Go
    MIDlet-Version: 1.0.0
    MIDlet-Vendor: CoolNaviApps
    MIDlet-Jar-Size: 12123
    MIDlet-Dependency-1: liblet; required; MapsForAll; MapsGalore, Inc.; 1.1.2
    MIDlet-Dependency-2: standard; required; microedition.location; JCP; 1.0+
    MIDlet-Dependency-JAD-URL-1: http://www.mapsgalore.com/liblets/mapsforall.jad

The JAD of the Maps LIBlet contains : 


    LIBlet-Name: MapsForAll
    LIBlet-Vendor: MapsGalore, Inc.
    LIBlet-Version: 1.1.2
    LIBlet-Jar-Size: 21544
    LIBlet-Jar-URL: http://www.mapsgalore.com/liblets/mapsforall.jar
    LIBlet-Dependency-1: standard; required; microedition.satsa.crypto; JCP; 1.0+
    LIBlet-Dependency-2: liblet; required; LocSvcs; LocationForAll Inc.; 1.0.3
    LIBlet-Dependency-JAD-URL-2: http://www.locsvcs.com/liblets/locsvcs.jad

The JAD of the LBS LIBlet contains : 


    LIBlet-Name: LocationServicesLIBlet
    LIBlet-Version: 1.0.3
    LIBlet-Vendor: LocationForAll Inc.
    LIBlet-Jar-Size: 23165
    LIBlet-Jar-URL: http://www.locationforall.com/liblets/locforall.jar
    LIBlet-Dependency-1: standard; optional; bluetooth.api; JCP; 1.0
    LIBlet-Dependency-2: proprietary; required; SuperDuper Location API;
                  Mega Software Services Co.; 1.0

Dependency Names For Standard APIs

Application suites and LIBlets that express dependencies on packages defined in standard APIs (JSRs) will do so via the MIDlet-Dependency-<n> or LIBlet-Dependency-<n> application attribute.

Each JSR generally defines system properties so that applications can retrieve API version information. JSR standard dependency names used in the dependency expression are based on the JSR package names used in the system properties for API version retrieval. Table 2-3 defines standard dependency names for JSRs that MAY be needed and required by MEEP 8 applications. For JSRs that specify a system property for version retrieval, the format of the version string used when expressing a dependency MUST conform to [JPVS]; any other format for version string in this case MUST be treated as an invalid packaging, and MUST result in a failed installation with an installation status report of Status Code 906 (Invalid Descriptor) in the status report. For JSRs that do not specify a system property for version retrieval, the format of the version string used when expressing a dependency is undefined.

Future JSRs that are intend to be used by MEEP 8 applications will have to define their respective dependency names in order to enable MEEP 8 applications then do claim their dependencies from those JSRs.

Table 2-3 : Dependency Names For Standard APIs

Dependency Name

Specification Defined In

Version Format
microedition.io.file.FileConnection [JSR75], PDA Optional Packages for the J2ME™ Platform [JPVS]
microedition.pim [JSR75], PDA Optional Packages for the J2ME™ Platform [JPVS]
bluetooth.api [JSR82], Java™ APIs for Bluetooth [JPVS]
obex.api [JSR82], Java™ APIs for Bluetooth [JPVS]
speech.api [JSR113], Java™ Speech API 2.0 Undefined
media.api [JSR135], Mobile Media API Undefined
xml.jaxp.subset [JSR172], J2ME™ Web Services Specification Undefined
xml.rpc.subset [JSR172], J2ME™ Web Services Specification [JPVS]
microedition.satsa.apdu [JSR177], Security and Trust Services API for J2ME™ Undefined
microedition.satsa.crypto [JSR177], Security and Trust Services API for J2ME™ Undefined
microedition.satsa.jcrmi [JSR177], Security and Trust Services API for J2ME™ [JPVS]
microedition.satsa.pki [JSR177], Security and Trust Services API for J2ME™ [JPVS]
microedition.location [JSR179], Location API for J2ME™ and [JSR293], Location API 2.0 [JPVS]
microedition.sip [JSR180], SIP API for J2ME™ [JPVS]
microedition.m3g [JSR184], Mobile 3D Graphics API for J2ME™ [JPVS]
wireless.messaging [JSR205], Wireless Messaging API 2.0 Undefined
microedition.chapi [JSR211], Content Handler API [JPVS]
microedition.global [JSR238], Mobile Internationalization API [JPVS]
microedition.telephony [JSR253], Mobile Telephony API (MTA) [JPVS]
microedition.telephony.charging [JSR253], Mobile Telephony API (MTA) [JPVS]
microedition.sensor [JSR256], Mobile Sensor API [JPVS]
microedition.contactless [JSR257], Contactless Communication API [JPVS]
microedition.broadcast [JSR272], Mobile Broadcast Service API for Handheld Terminals [JPVS]
microedition.xmlapi [JSR280], XML API for Java™ ME [JPVS]
fluid [JSR290], Java™ Language & XML User Interface Markup Integration [JPVS]

Please check here for additional Dependency Names.

When the dependency attribute contains a wildcard for the JSR version, an application can retrieve the exact version of the JSR that the application suite is bound to by calling System.getProperty(dependencyName + ".version"), where dependencyName is one of the dependency names found in Table 2-3 above or in the profile summary. The same applies to proprietary APIs, provided that they define a system property with a name like proprietaryAPIName + .version, where proprietaryAPIName is valid for the API as documented by its specification.

Dependency Names for Optional Packages

Optionality in MEEP 8 requires to give applications the possibility to declare which optional components of MEEP 8 they do expect in order to be able to run. Therefore the table above is amended by the entries defined here.

Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.