What’s New In MIDP 3.0 ? Part 5: LIBlets

1. Overview

It is clear, the name is a big clue, that conceptually at least, a LIBlet is the MIDP equivalent
of a library or DLL. That is, a collection of code which can be linked to by MIDP applications,
and then used at runtime as though it were part of the application itself.

One advantage of this is that it enables code to be shared which leads to reductions in the size
of individual applications. There are others which stem from the ability to re-use code, etc.

There are however, as has been demonstrated by other systems, also potential pit-falls, the most
infamous of which are probably those which arise from the proliferation of different
versions of the same DLL, and dependencies between DLLs themselves. This collection
of phenomena is often referred to as DLL hell.

The specification attempts to avoid these pit-falls, by, amongst other things, requiring explicit versioning,
forbidding circular dependencies, and supporting on demand installation. Given the nature
of Java, MIDP, and MIDlets, there are a large number of potential interactions,
and lots of behaviour to be defined. The result is that with respect to LIBlets at least,
the specification is fairly intricate and not always very clear, especially since the material
about LIBlets appears in a number of different places.

Below is what I have termed the LIBlet model which attempts to gather in one place, and make
explicit, what I think the specification says explicitly and implicitly about what LIBlets are and how
they work, as well as defining some terminology. This provides the context for everything that follows.

2. The LIBlet Model

A LIBlet is collection of classes which can be used by MIDlet Suites or other LIBlets.

A LIBlet may contain classes defined in one or more packages.

A LIBlet may define attributes which can be accessed by MIDlet Suites or other LIBlets.

A LIBlet may contain resources which can be accessed by MIDlet Suites or other LIBlets.

A LIBlet may create RecordStores which can be shared between MIDlet Suites.

LIBlet A can be dependent upon LIBlet B directly or indirectly.

LIBlet A is directly dependent upon LIBlet B if it declares a dependency on LIBlet B.

LIBlet A is indirectly dependent upon LIBlet B if it declares a depdendency on a LIBlet which is dependent on LIBlet B.

A LIBlet may not be dependent upon itself.

A MIDlet Suite can be dependent upon a LIBlet directly or indirectly.

A MIDlet Suite is directly dependent on a LIBlet if it declares a dependency on that LIBlet.

A MIlet Suite is indirectly dependent on LIBlet A if it declares a dependency upon a LIBlet which is dependent on LIBlet A.

A MIDlet Suite cannot be dependent on two versions of the same LIBlet, that is, it cannot dependent upon two LIBlets which have the
same vendor and name but different versions.

A MIDlet Suite cannot be dependent on two LIBlets which define classes in the same package.

A LIBlet is installed automatically during the installation of a MIDlet Suite which is dependent upon it, if it has
not already been installed.

Code defined in a LIBlet is only ever executed in the context of a MIDlet contained in a MIDlet Suite which is dependent upon that LIBlet.

Code defined in a LIBlet executing in the context of a MIDlet contained in a MIDlet Suite which is dependent upon that LIBlet is granted
only those permissions granted to the MIDlet suite.

3. Packaging

A LIBlet is packaged as a JAD and a Jar in the same way as a MIDlet Suite. The JAD and manifest of the Jar
contain attributes which specify information about the LIBlet.

3.1 Attributes

The specification defines a number of attributes that must or may be specified when packaging a LIBlet.

Custom attributes may also be used in addition to those defined in the specification.

All specification defined attributes and all custom attributes used in packaging a LIBlet must be defined in both
the JAD and the manifest of the LIBlet JAR, with the exception the following

• LIBlet-Jar-URL
• LIBlet-Jar-Size
• LIBlet-Jar-SHA1
• LIBlet-Dependency-JAD-URL-<n>

which must only be defined in the LIBlet JAD.

The values of those attributes in both the JAD and the manifest of the LIBlet Jar must be identical.

The specification categorizes the attributes defined for use in LIBlet packaging under five headings

• Identification
• Provisioning
• Operational
• Dependency
• Informatioanl

3.1.1 Identification Attributes

3.1.1.1 LIBlet-Name

This attribute specifies the name of the LIBlet.

3.1.1.2 LIBlet-Version

This attribute specifies the version of the LIBlet.

3.1.1.3 LIBlet-Vendor

This attribute specifies the vendor of the LIBlet.

3.1.1.4 LIBlet-Description

This attribute is a description of the LIBlet which
can be used by the device when interacting with a user.

3.1.1.5 LIBlet-Description-<locale>

This attribute is a locale specific description of the LIBlet
which can be used by the device when interacting with a user.

3.1.1.6 LIBlet-Icon

This attribute specifies a file containing an icon which can be used
by the device to represent the LIBlet when interacting with the user.

3.1.2 Provisioning Attributes

3.1.2.1 LIBlet-Jar-URL

This attribute specifies the URL of the LIBlet JAR.

3.1.2.2 LIBlet-Jar-Size

This attribute specifies the size in bytes of the LIBlet JAR.

3.1.2.3 LIBlet-Jar-SHA1

This attribute specifies the SHA1 hash of the LIBlet JAR.

3.1.2.4 LIBlet-NonShared-Data-Size

This attribute specifies the size in bytes of storage for RecordStores required by this LIBlet.

3.1.2.5 LIBlet-Shared-Data-Size

This attribute specifies the size in bytes of storage for RecordStores required by this LIBlet for each MIDlet Suite that is dependent upon it.

3.1.2.6 LIBlet-Install-Notify

This attribute specifies the URL to notify when the LIBlet is installed.

3.1.2.7 LIBlet-Delete-Notify

This attribute specifies the URL to notify if the LIBlet is uninstalled.

3.1.2.8 LIBlet-Persistent-Data-URL-<n>

This attribute specifies the location of data in RMS Interchange File Format to use to
create a RecordStore at installation time, and optionally that the created RecordStore
be encrypted.

A value of this attribute is of the form

    <dataURL> [" " "encryptLocally"]

3.1.3 Operational Attributes

3.1.3.1 LIBlet-Font

This attribute specifies the names of font files contained in this LIBlet.
The value must be a comma separated list. The file names specified must be absolute, and
the files identified must contain OpenType or TrueType fonts.

3.1.3.2 MicroEdition-Configuration

This attribute specifies the JME configuration required by this LIBlet,

3.1.3.2 MicroEdition-Profile

This attribute specifies the JME profiles required by this LIBlet.

3.1.4 Dependency Attributes

3.1.4.1 LIBlet-Dependency-<n>

A value of this attribute specifies a dependency upon either

• a LIBlet,
• a standard API, or
• a proprietary API

See Specifying Dependencies for details.

3.1.4.2 LIBlet-Dependency-JAD-URL-<n>

A value of this attribute specifies the URL of the JAD of the LIBlet specified by the corresponding LIBlet-Dependency-<n> attribute,
as described here.

3.1.4.3 LIBlet-Dependency-Jar-SHA1-<n>

A value of this attribute specifies the SHA1 hash of the JAR of the LIBlet specified by the corresponding LIBlet-Dependency-<n> attribute,
as described here.

3.1.5 Informational Attributes

3.1.5.1 LIBlet-Permission-<n>

A value of this attribute specifies a permission. It is of the form

    <class> " " <name> [" " <actions>]

Without this permission code defined in this LIBlet cannot function.

3.1.5.2 LIBlet-Permission-Opt-<n>

A value of this attribute specifies a permission.

    <class> " " <name> [" " <actions>]

Without this permission the functionality of code in this LIBlet is reduced.

3.2 Attributes Summary

Name	Status	Location	Since
LIBlet-Name	Mandatory	JAD AND Manifest	3.0
LIBlet-Vendor	Mandatory	JAD AND Manifest	3.0
LIBlet-Version	Mandatory	JAD AND Manifest	3.0
LIBlet-Jar-URL	Mandatory	JAD ONLY	3.0
LIBlet-Jar-Size	Mandatory	JAD ONLY	3.0
LIBlet-Jar-SHA1	Mandatory	JAD ONLY	3.0
LIBlet-Description	Optional	JAD AND Manifest	3.0
LIBlet-Description-<locale>	Optional	JAD AND Manifest	3.0
LIBlet-Icon	Optional	JAD AND Manifest	3.0
LIBlet-NonShared-Data-Size	Optional	JAD AND Manifest	3.0
LIBlet-Shared-Data-Size	Optional	JAD AND Manifest	3.0
LIBlet-Install-Notify	Optional	JAD AND Manifest	3.0
LIBlet-Delete-Notify	Optional	JAD AND Manifest	3.0
LIBlet-Persistent-Data-URL-<n>	Optional	JAD AND Manifest	3.0
LIBlet-Dependency-JAD-URL-<n>	Optional	JAD ONLY	3.0
LIBlet-Dependency-Jar-SHA1-<n>	Optional	JAD AND Manifest	3.0
LIBlet-Font	Optional	JAD AND Manifest	3.0
LIBlet-Permission-<n>	Optional	JAD AND Manifest	3.0
LIBlet-Permission-Opt-<n>	Optional	JAD AND Manifest	3.0

Notes

The table above differs from the table in ‘Appendix A – Application Attributes’ of the specification,
generally by specifying permitted locations explictly, and specifically, as follows:

1. in Appendix A the attribute LIBlet-Jar-SHA1 is specified to be optional rather than mandatory. I believe this to be a mistake, since
   it contradicts the description of the use of the attribute elsewhere in the specification.

2. in Appendix A the attributes

   • LIBlet-Delete-Notify
   • LIBlet-Font
   • LIBlet-Icon

   are all specified to be optional, but not allowed in the JAD. I believe this to be a mistake. It is at odds with the statement made elsewhere
   in the specification that all LIBlet attributes must appear in both the JAD and the manifest of the LIBlet Jar, and it is difficult
   to think of a reason for it, other than that it mirrors the specification of the corresponding MIDlet Suite
   attributes, for which it is in turn difficult to think of a reason, other than that they do not actually need to be in the JAD.

3. in Appendix A the attributes

   • LIBlet-Permission-<n>, and
   • LIBlet-Permission-Opt-<n>

   are mistakenly named

   • LIBlet-Permission, and
   • LIBlet-Permission-Opt

   respectively.

4. Specifying Dependencies

Dependencies are declared statically using attributes in the JAD or in the JAD and manifest of a LIBlet or a MIDlet Suite, and are resolved at installation time.

A LIBlet or MIDlet Suite can specify dependencies on LIBlets and on APIs.

4.1 Dependency Levels

A dependency can be specified to be either required, or optional

If a dependency is specified as required then if it cannot be satisified then the installation of the dependant must fail.

Note

It is not clear from the specification what the semantics of an optional LIBlet dependency are. I
assume that if a LIBlet dependency is optional and the LIBlet specified is not already installed,
no attempt is made to install it automatically. If it is already installed then it is subject to
the normal validation at this point. If validation fails the installation fails despite the fact
that the dependency is only optional.

4.2 Specifying A Dependency Upon A LIBlet

A dependency upon a LIBlet is specified by a group of three attributes which identify the LIBlet, the URL of the LIBlet JAD, and the SHA1 hash of the LIBlet JAR.

A MIDlet Suite specifies each LIBlet it is directly dependent upon using the attributes

• MIDlet-Dependency-<n>
• MIDlet-Dependency-JAD-URL-<n>
• MIDlet-Dependency-Jar-SHA1-<n>

A LIBlet specifies each LIBlet it is directly dependent upon using the attributes

• LIBlet-Dependency-<n>
• LIBlet-Dependency-JAD-URL-<n>
• LIBlet-Dependency-Jar-SHA1-<n>

4.2.1 Specifying The LIBlet

The value of a LIBlet-Dependency-<n> or MIDlet-Dependency-<n> specifying a dependency upon a LIBlet is of the form

    liblet;<level>;<name>;<vendor>;<version>

The value of level is of the form

    required|optional

See Dependency Levels.

The value of name specifies the name of the LIBlet.

The value of vendor specifies the vendor of the LIBlet.

The value of version specifies the version of the LIBlet, and is of the form

    <major> ["." <minor> ["." <micro>]]

4.2.2 Specifying The LIBlet JAD URL

A LIBlet-Dependency-JAD-URL-<n> or MIDlet-Dependency-JAD-URL-<n> attribute specifies the
URL of the JAD of the LIBlet specified by the corresponding
LIBlet-Dependency-<n> or MIDlet-Dependency-<n> attribute.

It is an error if the value of a LIBlet-Dependency-<n> or MIDlet-Dependency-<n>
has the type liblet and there is not a corresponding LIBlet-Dependency-JAD-URL-<n> or
MIDlet-Dependency-JAD-URL-<n> attribute.

Note

The behaviour when the corresponding Dependency attribute is not present or does not specify a LIBlet is not defined.

4.2.3 Specifying The LIBlet Jar Hash

A LIBlet-Dependency-Jar-SHA1-<n> or MIDlet-Dependency-Jar-SHA1-<n> attribute specifies the
Base-64 encoded value of the expected SHA1 hash of the Jar of the LIBlet specified by the corresponding
LIBlet-Dependency-<n> or MIDlet-Dependency-<n> attribute.

It is an error if the value of a LIBlet-Dependency-<n> or MIDlet-Dependency-<n>
has the type liblet and there is not a corresponding code>LIBlet-Dependency-Jar-SHA1-<n> or
MIDlet-Dependency-Jar-SHA1-<n> attribute.

Note

The behaviour when the corresponding Dependency attribute is not present or does not specify a LIBlet is not defined.

4.2.3 LIBlet Dependency Examples

Example

A MIDlet Suite with a required dependency upon version 2 of the ExampleMIDletsRUs ReallyUsefulLIBlet LIBlet.

JAD

    MIDlet-Dependency-1:          liblet;required;ExampleMIDletsRUs;ReallyUsefulLIBlet;2.0
    MIDlet-Dependency-JAD-URL-1:  http://www.examplemidletsrus.com/liblets/reallyuseful.jad
    MIDlet-Dependency-JAR-SHA1-1: <Base-64 encoded SHA1 hash value>

Manifest

    MIDlet-Dependency-1:          liblet;required;ExampleMIDletsRUs;ReallyUsefulLIBlet;2.0
    MIDlet-Dependency-JAR-SHA1-1: <Base-64 encoded SHA1 hash value>

Example

A LIBlet with an optional dependency upon version 1 of the ExamplesRUs NotQuiteAsUsefulLIBlet LIblet.

JAD

    LIBlet-Dependency-1:          liblet;optional;ExampleMIDletsRUs;NotQuiteAsUsefulLIBlet;1.0
    LIBlet-Dependency-JAD-URL-1:  http://www.examplemidletsrus.com/liblets/notquiteasuseful.jad
    LIBlet-Dependency-JAR-SHA1-1: <Base-64 encoded SHA1 hash value>

Manifest

    LIBlet-Dependency-1:          liblet;optional;ExampleMIDletsRUs;NotQuiteAsUsefulLIBlet;1.0
    LIBlet-Dependency-JAR-SHA1-1: <Base-64 encoded SHA1 hash value>

4.3 Specifying A Dependency Upon An API

A LIBlet or a MIDlet Suite can specify a dependency upon a standard API, that is a standard defined by the JCP, i.e., a JSR, or other standards body,
or a proprietary API, which could be manufacturer, operator, or even device specific.

Note

The specification permits, but does not require, an implementation to limit the APIs accessible at runtime to a MIDlet
to those which its containing MIDlet Suite has explicit direct or indirect dependencies upon.

To ensure portability, therefore, a MIDlet Suite or LIBlet must explicitly specify all the APIs it is
dependent upon.

4.3.1 Specifying API Versions

The version of an API is defined to have the same form as a MIDlet Suite, that is

    <major> ["." <minor> ["." <micro>]]

An API dependency can specify a specific version, for example,

• 1
• 1.1
• 1.2.1

any version, or any sub-version of a specific version

• *
• 2.*
• 1.2.*

or any version greater than or equal to a specific version

• 2+
• 1.3+
• 3.1.2+

4.3.2 Specifying A Dependency Upon A Standard API

In this case the value of a LIBlet-Dependency-<n> or MIDlet-Dependency-<n> attribute is of the form

    standard;<level>;<name>;<vendor>;<version>

The value of level is of the form

    required|optional

See Dependency Levels

The value of <name> is the name of the API. The specification defines names for all the component JSRs of the Mobile Service Architecture (JSR248).

The value of <vendor> specifies the organization that defined the standard.

The value of <version> specifies the constraints on the version of the API as described above.

Example

A MIDlet Suite attribute specifying a required dependency on version 1.0 of the JME SVG API (JSR226)

    MIDlet-Dependency-1: standard;required;microedition.m2g;JCP;1.0

Example

A MIDlet Suite attribute specifying an optional dependency on version 1.0 or greater of the JME Location API (JSR179/293)

    MIDlet-Dependency-1: standard;optional;microedition.location;JCP;1+

4.3.3 Specifying A Dependency Upon A Proprietary API

The value of a LIBlet-Dependency-<n> or MIDlet-Dependency-<n> specifying a dependency upon a proprietary API is of the form

    proprietary;<level>;<name>;<vendor>;<version>

The value of level is of the form

    required|optional

See Dependency Levels

The value of <name> is the name of the API.

The value of <vendor> specifies the entity that defined the API.

The value of <version> specifies the constraints on the version of the API as described here.

Example

A LIBlet attribute specifying a required dependency on version 1.1 of the proprietary PossiblyUseful API defined by ExampleMIDletsRUs.

    LIblet-Dependency-1: proprietary;required;PossiblyeUseful;ExampleMIDletsRUs;1.1

Example

A LIblet Suite attribute specifying an optional dependency on any version of the proprietary ICantBelieveItsNotUseful API defined by Emerald.

    LIblet-Dependency-1: proprietary;optional;ICantBelieveItsNotUseful;Emerald;*

5. Signed LIBlets ?

One of the features we might perhaps expect given the MIDP security model is the ability to sign LIBlets
in the same way as MIDlet Suites.

MIDP supports signed MIDlet Suites effectively so three questions about a given MIDlet Suite can be answered

• should the user be allowed to use it, which translates to, should it be installed ?
• what should it be allowed to do ?
• has is been tampered wih ?

In the LIBlet model the first question becomes the responsibility of the developer of a MIDlet Suite,
or LIBlet. The developer decides which LIBlet or LIBlets to use, employing the criteria they consider
important, and then specify them as dependencies. If a MIDlet suite or LIBlet uses, that is dependant upon, a LIBlet it is installed automatically
on that basis.

In the LIBlet model the second question has the same answer in every case, whatever the MIDlet suite that is dependant upon it can do,
so it effectively disappears

The third question remains, and there is a new one

• is this actually the LIBlet the developer decided to use ?

The LIBlet model reduces these two questions to a single one

• does the Jar of this LIBlet have the SHA1 hash the developer says it does ?

At installation time the SHA1 hash of the LIBlet Jar is computed and compared with the value
defined in the LIBlet dependency that has resulted in the LIBlet installation. If they do not
match the installation will fail.

This of course raises a further question

• how do we know the value specified in the dependency has not been tampered with ?

The specification states that a MIDlet-Dependency-Jar-SHA1-<n> specifying
the hash must appear in the JAD and manifest of the MIDlet suite.

If the MIDlet Suite is signed, the value in the manifest cannot be modified as it is
protected by its signature. The value in the JAD can be changed but then it will no
longer match the value in the manifest which will cause the installation to fail since in MIDP3
the values of attributes which appear in both the JAD and the manifest of a must match exactly.

If the MIDlet Suite is not signed then the values of the attribute can be modified, but then so can everything
else including the code in the MIDlet Suite.

In the case of a dependency specified in a LIBlet the LIBlet-Dependency-Jar-SHA1-<n> specifying
the hash must appear in the JAD and manifest of the LIBlet. This is a requirement on all LIBlet
attributes.

The value in the manifest cannot be modified since this would cause the SHA1 hash of its Jar to
change which will cause its installation to fail. The value in the JAD can be changed but then
its value will not match which again will cause the installation to fail.

Note

There are now question marks over the SHA1 algorithm itself, but if there are problems in this area it will affect
a lot more than just LIBlets in MIDP3

---

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