Multi-Sandbox Enabled Libraries

A Multi-Sandbox enabled library is a Foundation or Add-On Library which can be embedded into the Kernel and exposed as API. MicroEJ Foundation Libraries provided in MicroEJ SDK are already Multi-Sandbox enabled. A stateless library - i.e. a library that does not contain any method modifying an internal global state - is Multi-Sandbox enabled by default.

This section details the Multi-Sandbox semantic that have been added to MicroEJ Foundation Libraries in order to be Multi-Sandbox enabled.

MicroUI

Note

This chapter describes the current MicroUI version 3, provided by UI Pack version 13.0.0 or higher. If you are using the former MicroUI version 2 (provided by MicroEJ UI Pack version up to 12.1.x), please refer to this MicroEJ Documentation Archive.

Physical Display Ownership

The physical display is owned by only one context at a time (the Kernel or one Feature). The following cases may trigger a physical display owner switch:

• during a call to Display.requestShow(Displayable), Display.requestHide(Displayable), Display.requestRender() or Display.requestFlush(): after the successful permission check, it is assigned to the context owner.
• during a call to MicroUI.callSerially(Runnable): after the successful permission check it is assigned to owner of the Runnable instance.

The physical display switch performs the following actions:

• If a Displayable instance is currently shown on the Display, the method Displayable.onHidden() is called,
• All pending events (input events, display flushes, call serially runnable instances) are removed from the display event serializer,
• System Event Generators handlers are reset to their default EventHandler instance,
• The pending event created by calling Display.callOnFlushCompleted(Runnable) is removed and will be never added to the display event serializer.

Warning

The display switch is performed immediately when the current thread is the MicroUI thread itself (during a MicroUI event such as a MicroUI.callSerially(Runnable)). The caller looses the display and its next requests during same MicroUI event will throw a new display switch. Caller should call future display owner’s code (which will ask a display switch) in a dedicated MicroUI.callSerially(Runnable) event.

The call to Display.callOnFlushCompleted(Runnable) has no effect when the display is not assigned to the context owner.

Automatically Reclaimed Resources

Instances of ResourceImage and Font are automatically reclaimed when a Feature is stopped.

BON

Kernel Timer

A Kernel Timer instance can handle TimerTask instances owned by the Kernel or any Features.

It should not be created in clinit code, otherwise you may have to manually declare explicit clinit dependencies.

Automatically Reclaimed Resources

TimerTask instances are automatically canceled when a Feature is stopped.

ECOM

The ej.ecom.DeviceManager registry allows to share devices across Features. Instances of ej.ecom.Device that are registered with a Shared Interface type are made accessible through a Proxy to all other Features that embed the same Shared Interface (or an upper one of the hierarchy).

ECOM-COMM

Instances of ej.ecom.io.CommConnection are automatically reclaimed when a Feature is stopped.

FS

Instances of java.io.FileInputStream, java.io.FileOutputStream are automatically reclaimed when a Feature is stopped.

NET

Instances of java.net.Socket, java.net.ServerSocket, java.net.DatagramSocket are automatically reclaimed when a Feature is stopped.

SSL

Instances of javax.net.ssl.SSLSocket are automatically reclaimed when a Feature is stopped.