Module Repository

A module repository is a module that bundles a set of modules in a portable ZIP file. It is a tree structure where modules organizations and names are mapped to folders.

Example of MicroEJ Module Repository Tree

Example of MicroEJ Module Repository Tree

A module repository takes its input modules from other of repositories, usually the MicroEJ Central Repository which is itself built by MicroEJ Corp. as a module repository.

A module repository is often called an offline repository as it includes the settings file for a local configuration in MicroEJ SDK. It can also be imported in MicroEJ Forge.

Create a Repository Project

In MicroEJ SDK, first create a new module project using the artifact-repository skeleton.

  • The ivysettings.xml file describes how MicroEJ SDK will fetch the content of this repository when it is extracted locally on file system. This file will be packaged at the root of the zip file and does not need to be modified.
  • The module.ivy file describes how to build repository and lists the module dependencies that will be included in this repository.

Configure Resolver for Input Modules

MicroEJ Module Manager (MMM) needs to fetch dependencies to build the module repository. The location fetched by MMM is defined by a resolver. The resolver is configured with the parameter bar.populate.from.resolver. The preset value is the resolver provided by default in MicroEJ SDK configuration, which is connected to MicroEJ Central Repository.

<ea:property name="bar.populate.from.resolver" value="MicroEJChainResolver"/>

The MicroEJChainResolver is an URL resolver defined defined in $USER_HOME\.microej\microej-ivysettings-[VERSION].xml that points to MicroEJ Central Repository.

To ensure the repository will be compliant with the MMM specification, add the following option:

<ea:property name="bar.check.as.v2.module" value="true"/>

There are other advanced options that do not need to be modified by default. These options are described in the module.ivy generated by the skeleton.

Include Modules

Modules bundled into the module repository must be declared in the dependencies element of the module.ivy file.

Include a Single Module

To add a module, declare the module dependency using the artifacts configuration:

<dependencies>
   <dependency conf="artifacts->*" transitive="false" org="[module_org]" name="[module_name]" rev="[module_version]" />

   <!-- ... other dependencies ... -->
</dependencies>

For example, to add the ej.api.edc library version 1.2.3, write the following line:

<dependency conf="artifacts->*" transitive="false" org="ej.api" name="edc" rev="1.2.3" />

Note

We recommended to manually describe each dependency of the module repository, in order to keep full control of the included modules as well as included modules versions. Module dependencies can still be transitively included by setting the dependency attribute transitive to true. In this case, the included module versions are those that have been resolved when the module was built.

Multiple versions of the same module can be included by declaring each dependency using a different configuration. The artifacts configuration has to be derived with a new name as many times as there are different versions to include.

<configurations defaultconfmapping="default->default;provided->provided">
   <conf name="artifacts" visibility="private"/>
   <conf name="artifacts_1" visibility="private"/>
   <conf name="artifacts_2" visibility="private"/>

   <!-- ... other configurations ... -->
</configurations>

<dependencies>
   <dependency conf="artifacts->*" transitive="false" org="[module_org]" name="[module_name]" rev="[module_version_1]" />
   <dependency conf="artifacts_1->*" transitive="false" org="[module_org]" name="[module_name]" rev="[module_version_2]" />
   <dependency conf="artifacts_2->*" transitive="false" org="[module_org]" name="[module_name]" rev="[module_version_3]" />

   <!-- ... other dependencies ... -->
</dependencies>

Include a Module Repository

To add all the modules already included in an other module repository, declare the module repository dependency using the repository configuration:

<dependencies>
   <dependency conf="repository->*" transitive="false" org="[repository_org]" name="[repository_name]" rev="[repository_version]" />

   <!-- ... other dependencies ... -->
</dependencies>

Build the Repository

In the Package Explorer, right-click on the repository project and select Build Module.

The build consists of two steps:

  1. Gathers all module dependencies. The whole repository content is created under target~/mergedArtifactsRepository folder.
  2. Checks the repository consistency. For each module, it tries to fetch it from this repository and fails the build if at least one of the dependencies cannot be resolved.

The module repository .zip file is built in the target~/artifacts/ folder. This is file is also published possibly with the CHANGELOG.md, LICENSE.txt and README.md.

Use the Offline Repository

By default, when starting an empty workspace, MicroEJ SDK is configured to fetch dependencies from MicroEJ Central Repository.

To configure MicroEJ SDK to fetch dependencies from a local module repository:

  1. Unzip the module repository .zip file to the folder of your choice,
  2. Configure MicroEJ SDK repository using the ivysettings.xml file located at the root of the folder where the repository has been extracted.