MicroEJ Runtime

Language

MicroEJ allows to develop Applications in the Java® Language Specification version 7 with some limitations, and supports code extensions written in JavaScript.

Basically, Java source code is compiled by the Java compiler [1] into the binary format specified in the JVM specification [2]. This binary code is linked by a tool named SOAR before execution: .class files and some other application-related files (see Classpath chapter) are linked to produce the final binary file that the Core Engine will execute.

Note

When opened in the SDK 5, make sure that the Compiler Compliance Level of your project is set to 1.7 to ensure the bytecode produced by the Java compiler is compatible with MicroEJ. The Compliance Level can be changed from the menu: Window > Preferences > Java > Compiler.

[1]

The JDT compiler from the Eclipse IDE.

[2]

Tim Lindholm & Frank Yellin, The Java™ Virtual Machine Specification, Second Edition, 1999

Java Lambdas

Note

This feature is available for SDK 6 only and requires an Architecture version 8.0.0 or higher.

Starting from SDK 6 1.0.0, it is possible to use Java lambdas in the code of your Application. This feature is disabled by default, you can enable it as follows:

• Apply the Foojay Toolchains Plugin in the settings.gradle.kts file of your project:

  plugins {
      id("org.gradle.toolchains.foojay-resolver-convention").version("0.9.0")
  }
  

• Set the project property java.lambdas.enabled to true in command line with the -P argument:

$ ./gradlew runOnSimulator -Pjava.lambdas.enabled=true

or by adding it in the gradle.properties file of your project:

java.lambdas.enabled=true

Core Libraries

This section describes the core libraries which make up the runtime. Theses Foundation Libraries are tightly coupled with the Core Engine.

Embedded Device Configuration (EDC)

The Embedded Device Configuration specification defines the minimal standard runtime environment for embedded devices.

This module is always required in the build path of an Application project; and all others libraries depend on it. This library provides a set of options. Refer to the chapter Standalone Application Options which lists all available options.

Specification Summary:

Java APIs	java.io java.lang java.lang.annotation java.lang.ref java.lang.reflect java.util
Latest Version	1.3
Module Dependency	SDK 6SDK 5 implementation("ej.api:edc:1.3.7")
Module Location	https://repository.microej.com/modules/ej/api/edc/

Beyond Profile (BON)

This profile defines a suitable and flexible approach to fully control both memory usage and startup sequences on devices with limited memory resources, while remaining within the boundaries of Java semantics.

More precisely, it allows:

• Controlling the initialization sequence in a deterministic way.

• Defining persistent, immutable, read-only objects (that may be placed into non-volatile memory areas), and which do not require copies to be made in RAM to be manipulated.

• Defining immortal, read-write objects that are always alive.

• Accessing compile-time constants.

Read the Beyond Profile specification for more details.

Specification Summary:

Java APIs	ej.bon
Latest Version	1.4
Module Dependency	SDK 6SDK 5 implementation("ej.api:bon:1.4.4")
Module Location	https://repository.microej.com/modules/ej/api/bon/

Simple Native Interface (SNI)

SNI provides a simple mechanism for implementing native Java methods in the C language.

SNI allows you to:

• Call a C function from a Java method.

• Share memory between C and Java using Immortal arrays (see the Beyond Profile (BON) to learn about immortal objects).

SNI also provides some Java APIs to manipulate some data arrays between Java and the native (C) world.

Read the Simple Native Interface specification for more details.

Specification Summary:

Java APIs	ej.sni
Latest Version	1.4
Module Dependency	SDK 6SDK 5 implementation("ej.api:sni:1.4.3")
Module Location	https://repository.microej.com/modules/ej/api/sni/

Kernel & Features (KF)

The Kernel & Features semantic (KF) extends the runtime for managing Multi-Sandboxed Applications.

Read the Kernel & Features specification for more details, the Multi-Sandbox capability of the Core Engine and more generally the Kernel Developer Guide chapter.

Specification Summary:

Java APIs	ej.kf
Latest Version	1.7
Module Dependency	SDK 6SDK 5 implementation("ej.api:kf:1.7.0")
Module Location	https://repository.microej.com/modules/ej/api/kf/

Specifications

• Beyond Profile Specification (BON)
• Simple Native Interface Specification (SNI)
• Kernel & Features Specification (KF)

Scheduler

The Core Engine features a Green Threads model. The semantic is as follows:

• preemptive for different priorities,

• round-robin for same priorities,

• “priority inheritance protocol” when priority inversion occurs. [3]

Threads stacks automatically adapt their sizes according to the thread requirements: once a thread terminates, its associated stack is reclaimed, freeing the corresponding RAM memory.

[3]

This protocol raises the priority of a thread that is holding a monitor needed by a higher-priority thread, to the priority of that higher-priority thread (until exiting the monitor).

Garbage Collector

The Core Engine includes a state-of-the-art memory management system, the Garbage Collector (GC). It manages a bounded piece of RAM memory, devoted to the Java world. The GC automatically frees dead Java objects, and defragments the memory in order to optimize RAM usage. This is done transparently while the Application keep running.

See also Garbage Collector options for more details.

Death Notification

Most objects are reclaimable objects. Sometimes, they interact with the native or system resources using handles. Those handles represent underlying data that needs to be closed/freed/acknowledged/… when the object that holds the handle dies.

The Application can get notified when an object is dead through the use of WeakReference objects. When such objects get their weak reference set to null by the system, they are added to the ReferenceQueue they were assigned to at their creation.

Death Notification Actions

Once an object has expired, it cannot be brought to life again. It is the responsibility of the application to make provisions for all actions that have to be taken on an object death. Such provisions are materialized by subclasses of the WeakReference class.

ReferenceQueue.poll() and ReferenceQueue.remove() methods allow the execution of a hook at the death of the object referenced by the weak reference. The first one returns null when queue is empty whereas the second one blocks while the queue is empty.

The Application is responsible of the execution of such hook.

Limitations

Primitive Types

Getting a Class instance of a primitive type is not supported:

• boolean.class,

• byte.class,

• char.class,

• short.class,

• int.class,

• long.class,

• float.class,

• double.class.

On Architecture 8.x, you will get the following dedicated error message:

SOAR-L ERROR :
[M79] - Unsupported access to the Class instance of a primitive type (found 'boolean.class' in method 'com.mycompany.MyClass.myMethod()void')

On Architecture 7.x you will get the following default error message:

No such field TYPE at com/mycompany/MyClass.myMethod()V.

Architecture Characteristics

The Application can retrieve some characteristics of the Architecture on which it is running. Architecture characteristics are automatically provided as constants. Here are the most notable ones:

• com.microej.architecture.capability=[tiny|single|multi]: Core Engine Capability

• com.microej.architecture.name=[architecture_uid]: Architecture name.

• com.microej.architecture.level=[eval|prod]: Usage level (Evaluation or Production).

• com.microej.architecture.toolchain=[toolchain_uid]: Toolchain name.

• com.microej.architecture.version=[M.m.p]: Architecture version.

See also Architecture Naming Convention for more details.

The following code prints the formatted Architecture characteristics on standard output. You can copy-paste and adapt it to your needs.

String name = Constants.getString("com.microej.architecture.name");
String version = Constants.getString("com.microej.architecture.version");
String buildLabel = Constants.getString("com.microej.architecture.buildLabel");

String usage = Constants.getString("com.microej.architecture.level");
String usageStr;
if (usage.equals("prod") || usage.equals("dev")) {
  usageStr = "Production";
} else if (usage.equals("eval")) {
  usageStr = "Evaluation";
} else {
  usageStr = usage;
}

String capability = Constants.getString("com.microej.architecture.capability");
String capabilityStr;
if (capability.equals("multi")) {
  capabilityStr = "Multi";
} else if (capability.equals("tiny")) {
  capabilityStr = "Tiny";
} else if (capability.equals("single") || capability.equals("mono")) {
  capabilityStr = "Mono";
} else {
  capabilityStr = capability;
}

String isaStr = Constants.getString("com.microej.architecture.architecturePrintableName");
String toolchainName = Constants.getString("com.microej.architecture.toolchainPrintableName");
String toolchainFullName = Constants.getString("com.microej.architecture.toolchain");

System.out.println("- Name:                         " + name);
System.out.println("- Version:                      " + version + " (" + buildLabel + ")");
System.out.println("- Usage:                        " + usageStr);
System.out.println("- Core Engine Capability:       " + capabilityStr + "-Sandbox");
System.out.println("- Instruction Set Architecture: " + isaStr);
System.out.println("- Compilation Toolchain:        " + toolchainName + " (" + toolchainFullName + ")");