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
LLEXT_RES_impl.h
implementation (see LLEXT_RES: External Resources Loader).
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.