External Resources Loader

Functional Description

The External Resources Loader is an optional module. When not installed, only internal resources are available for the MicroEJ Application. When the External Resources Loader is installed, the MicroEJ Core Engine tries first to retrieve the expected resource from its available list of internal resources, before asking the BSP to load it (using LLEXT_RES_impl.h functions).

See Application Resources for more information on how to declare external resources depending on its kind (raw resources, images, fonts, NLS).

Implementations

External Resources Loader module provides some Low Level API (LLEXT_RES) to let the BSP manage the external resources.

Open a Resource

The LLAPI to implement in the BSP are listed in the header file LLEXT_RES_impl.h. First, the framework tries to open an external resource using the open function. This function receives the resources path as a parameter. This path is the absolute path of the resource from the MicroEJ Application classpath (the MicroEJ Application source base directory). For example, when the resource is located here: com.mycompany.myapplication.resource.MyResource.txt, the given path is: com/mycompany/myapplication/resource/MyResource.txt.

The external resources loader implementation should, when possible, lock the resource when it is opened. Any modification of an opened resource may not be properly handled by the application.

Resource Identifier

This open function has to return a unique ID (positive value) for the external resource, or returns an error code (negative value). This ID will be used by the framework to manipulate the resource (read, seek, close, etc.).

Several resources can be opened at the same time. The BSP does not have to return the same identifier for two resources living at the same time. However, it can return this ID for a new resource as soon as the old resource is closed.

Resource Offset

The BSP must hold an offset for each opened resource. This offset must be updated after each call to read and seek.

Resource Inside the CPU Address Space Range

An external resource can be programmed inside the CPU address space range. This memory (or a part of memory) is not managed by the SOAR and so the resources inside are considered as external.

Most of time the content of an external resource must be copied in a memory inside the CPU address space range in order to be accessible by the MicroEJ algorithms (draw an image etc.). However, when the resource is already inside the CPU address space range, this copy is useless. The function LLEXT_RES_getBaseAddress must return a valid CPU memory address in order to avoid this copy. The MicroEJ algorithms are able to target the external resource bytes without using the other LLEXT_RES APIs such as read, mark etc.

External Resources Folder

The External Resource Loader module provides an option (MicroEJ launcher option) to specify a folder for the external resources. This folder has two roles:

  • It is the output folder used by some extra generators during the MicroEJ Application build. All output files generated by these tools will be copied into this folder. This makes it easier to retrieve the exhaustive list of resources to program on the board.
  • This folder is taken into consideration by the Simulator in order to simulate the availability of these resources. When the resources are located in another computer folder, the Simulator is not able to load them.

If not specified, this folder is created (if it does not already exist) in the MicroEJ project specified in the MicroEJ launcher. Its name is externalResources.

Dependencies

Installation

The External Resources Loader is an additional module. In the platform configuration file, check External Resources Loader to install this module.

Use

The External Resources Loader is automatically used when the MicroEJ Application tries to open an external resource.