MicroEJ Classpath

MicroEJ Applications run on a target device and their footprint is optimized to fulfill embedded constraints. The final execution context is an embedded device that may not even have a file system. Files required by the application at runtime are not directly copied to the target device, they are compiled to produce the application binary code which will be executed by the Core Engine.

As a part of the compile-time trimming process, all types not required by the embedded application are eliminated from the final binary.

MicroEJ Classpath is a developer defined list of all places containing files to be embedded in the final application binary. MicroEJ Classpath is made up of an ordered list of paths. A path is either a folder or a zip file, called a JAR file (JAR stands for Java ARchive).

Application Classpath explains how the MicroEJ Classpath is built from a MicroEJ Application project.
Classpath Load Model explains how the application contents is loaded from MicroEJ Classpath.
Classpath Elements specifies the different elements that can be declared in MicroEJ Classpath to describe the application contents.

Application Classpath

The following schema shows the classpath mapping from a MicroEJ Application project to the MicroEJ Classpath ordered list of folders and JAR files. The classpath resolution order (left to right) follows the project appearance order (top to bottom).

Note

For Sandboxed Applications, when a library cannot be added as a dependency (because it is not available in a repository for example), its JAR file can be directly added in the META-INF/libraries folder of the Application project. It is then automatically added in the compilation classpath and is available for the Application.

Classpath Load Model

A MicroEJ Application classpath is created via the loading of :

an entry point type,
all *.[extension].list files declared in a MicroEJ Classpath.

The different elements that constitute an application are described in Classpath Elements. They are searched within MicroEJ Classpath from left to right (the first file found is loaded). Types referenced by previously loaded MicroEJ Classpath elements are loaded transitively.

Classpath Elements

The MicroEJ Classpath contains the following elements:

An entrypoint described in section Application Entry Points;
Types in .class files, described in section Types;
Immutables Object data files, described in Section Immutable Objects;
Raw Resources, Images, Fonts and Native Language Support (NLS) described in Application Resources;
*.[extension].list files, declaring contents to load. Supported list file extensions and format is specific to declared application contents and is described in the appropriate section.

At source level, Java types are stored in src/main/java folder of the module project, any other kind of resources and list files are stored in the src/main/resources folder.

Application Entry Points

MicroEJ Application entry point declaration differs depending on the application kind:

In case of a Standalone Application, it is a class that contains a public static void main(String[]) method, declared using the option application.main.class.
In case of a Sandboxed Application, it is a class that implements ej.kf.FeatureEntryPoint, declared using the entryPoint property in the .kf file in the src/main/resources/ folder.

Types

MicroEJ types (classes, interfaces) are compiled from source code (.java) to classfiles (.class). When a type is loaded, all types dependencies found in the classfile are loaded (transitively).

A type can be declared as a Required type in order to enable the following usages:

to be dynamically loaded from its name (with a call to Class.forName(String));
to retrieve its fully qualified name (with a call to Class.getName()).
when Tiny-Sandbox capability is enabled, to retrieve its package (with a call to Class.getPackage()).

A type that is not declared as a Required type may not have its fully qualified name (FQN) embedded. Its FQN can be retrieved using the stack trace reader tool (see Stack Trace Reader).

Required Types are declared in MicroEJ Classpath using *.types.list files. The file format is a standard Java properties file, each line listing the fully qualified name of a type. Example:

# The following types are marked as MicroEJ Required Types
com.mycompany.MyImplementation
java.util.Vector

Resources

Resources are binary files that need to be embedded by the application.

Note

For more details on all supported resources types, please refer to Application Resources chapter.

Raw resources are resources that can be dynamically retrieved with a call to java.lang.Class.getResourceAsStream(String). Raw Resources are declared in *.resources.list files (and in *.externresources.list for external resources, see Application Resources).

$digraph D { internalRaw [shape=diamond, label="internal?"] rawList [shape=box, label="*.resources.list"] rawExt [shape=box, label="*.resources.list +\l*.externresources.list"] subgraph cluster_Raw { label ="Raw Resource" internalRaw -> rawList [label="yes"] internalRaw -> rawExt [label="no=external"] } }$

The file format is a standard Java properties file, each line is a relative / separated name of a file in MicroEJ Classpath to be embedded as a resource. Example:

# The following resource is embedded as a raw resource
com/mycompany/MyResource.txt

A resource is 4-bytes aligned in memory by default. Starting from Architecture 8.0.0, it is possible to modify the alignment constraint. Example:

# The following resource is linked to a 32-bytes aligned address in memory.
com/mycompany/MyResource.txt:32

Note

If a Resource is declared multiple times in the classpath, the alignment constraint with the highest value is used. If the alignment constraints are specific to the target, it is recommended to only declare them in the Application project instead of libraries.

If a resource filename contains a delimiter (such as a whitespace, :, or =), the delimiter must be escaped using the backslash \ character in the *.resources.list file. Example:

# The resource filename: "resource name contains whitespace.txt"
com/mycompany/resource\ name\ contains\ whitespace.txt

Immutable Objects

Immutables objects are regular read-only objects that can be retrieved with a call to ej.bon.Immutables.get(String). Immutables objects are declared in files called immutable objects data files, which format is described in the [BON] specification. Immutables objects data files are declared in MicroEJ Classpath using *.immutables.list files. The file format is a standard Java properties file, each line is a / separated name of a relative file in MicroEJ Classpath to be loaded as an Immutable objects data file. Example:

# The following file is loaded as an Immutable objects data files
com/mycompany/MyImmutables.data

System Properties

System Properties are key/value string pairs that can be accessed with a call to System.getProperty(String).

System Properties are defined when building a Standalone Application, by declaring *.properties.list files in MicroEJ Classpath.

The file format is a standard Java properties file. Example:

Example of Contents of a MicroEJ Properties File

# The following property is embedded as a System property
com.mycompany.key=com.mycompany.value
microedition.encoding=ISO-8859-1

System Properties are resolved at runtime, and all declared keys and values are embedded as intern Strings.

System Properties can also be defined using Standalone Application Options. This can be done by setting the option with a specific prefix in their name:

Properties for both the Core Engine and the Simulator : name starts with microej.java.property.*
Properties for the Simulator only: name starts with sim.java.property.*
Properties for the Core Engine only: name starts with emb.java.property.*

For example, to define the property myProp with the value theValue, set the following option :

Example of MicroEJ System Property Definition as Application Option

microej.java.property.myProp=theValue

Note

A System Property defined as an Application Option takes precedence over a System Property defined in the classpath.

Note

When building a Sandboxed Application, *.properties.list files found in MicroEJ Classpath are silently skipped.

Constants

Constants are key/value string pairs that can be accessed with a call to ej.bon.Constants.get[Type](String), where Type if one of:

Boolean,
Byte,
Char,
Class,
Double,
Float,
Int,
Long,
Short,
String.

Constants are declared in MicroEJ Classpath *.constants.list files. The file format is a standard Java properties file. Example:

Example of Contents of a BON constants File

# The following property is embedded as a constant
myconstantkey=myconstantvalue

Starting from Architecture 8.3.0, it is also possible to define a constant using the following Application Option:

Example of declaration of a BON constant Application Option

microej.constant.myconstantkey=myconstantvalue

Note

A Constant defined as an Application Option takes precedence over a constant defined in the classpath.

Constants are resolved at binary level without having to recompile the sources.

At link time, constants are directly inlined at the place of Constants.get[Type] method calls with no cost.

The String key parameter must be resolved as an inlined String:

either a String literal "myconstantkey"
or a static final String field resolved as a String constant

The String value is converted to the desired type using conversion rules described by the [BON] API.

A boolean constant declared in an if statement condition can be used to fully remove portions of code. This feature is similar to C pre-processors #ifdef directive with the difference that this optimization is performed at binary level without having to recompile the sources.

Example of if code removal using a BON boolean constant

if (Constants.getBoolean("myconstantkey")) {
       System.out.println("this code and the constant string will be fully removed when the constant is resolved to 'false'")
}

Please mind that Constants.getXXX must be inlined in the if condition to take effect. The following piece of code will not remove the code:

static final boolean MY_CONSTANT = Constants.getBoolean("myconstantkey");

...

if(MY_CONSTANT){
   System.out.println("this code will not be removed when MY_CONSTANT is resolved to 'false'")
}

Note

In Multi-Sandbox environment, constants are processed locally within each context. In particular, constants defined in the Kernel are not propagated to Sandboxed Applications.