Module descriptor

A module descriptor is a Magnolia-specific XML file that identifies and defines the module. The descriptor file is in the META-INF/magnolia directory. When you start Magnolia, the system identifies available modules by locating each module's descriptor file. 

The module descriptor:

• Is an XML file with a Document Type Definition (DTD).
• Is stored in src/main/resources/META-INF/magnolia/<module-name>.xml
• Can refer to nodes of the module pom file.

Module descriptor elements

Elements to use in a module descriptor: file

Here is an example of a module descriptor that defines a module class (class element), a module version handler (versionHandler element), an IoC component, and a dependency on the ui-admincentral module:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE module SYSTEM "module.dtd">
<module>
  <name>acme-geotagging-module</name>
  <displayName>Acme geotagging module.</displayName>
  <class>com.acme.GeotaggingModule</class>
  <versionHandler>com.acme.GeotaggingModuleVersionHandler</versionHandler>
  <version>${project.version}</version>
  <components>
    <id>main</id> <!-- Container ID -->
    <component>
      <type>com.acme.geo.GeoService</type>
      <implementation>com.acme.geo.GeoServiceImpl</implementation>
    </component>
  </components>
  <dependencies>
    <dependency>
      <name>ui-admincentral</name>
      <version>${project.version}</version>
    </dependency>
  </dependencies>
</module>

Module naming

For each module you have to provide:

1. artifactId and groupId to the identify the Maven artifact
2. Name of the module descriptor file.
3. <name> of the module in the module descriptor file.

There are no strict naming conventions. You should give a name that reflects the purpose of the module. The name may also contain the name of your company.

Depending on the module purpose it might be a good idea to use the same value for the artifact ID and module name.

It is definitively good practice to name the module descriptor file by the pattern <module-name>.xml.

Example:

• Module name: Social Media Hub
• Artifact ID: social-media-hub
• Group ID: com.tinext.magnolia (contains the name of the creator Tinext.com)
• Module descriptor file: social-media-hub.xml

Module versions

The syntax for a version is:

from version / to version

where the version number consists of three parts: x.y.z. In this notation x.y denotes a major version and z a maintenance release. The last two parts are optional. For a strict version dependency, use just one version string.

The  VersionRange  class supports the following notation to indicate version dependency.

• * - Includes all versions
• 1.2 - Matches only 1.2 exactly.
• 1.2/* - Matches all versions including and above 1.2.
• 1.2/1.2.9 - Matches all versions including and between 1.2 and 1.2.9.
• [1.2,1.2.9] - Inward square brackets mean inclusion. Same as above. Matches all versions including and between 1.2 and 1.2.9.
• [1.2,1.2.9[ - Outward square brackets mean exclusion. Matches all versions between 1.2 and 1.2.9, including 1.2 but excluding 1.2.9.
• [1.2,1.2.9) - Parentheses mean exclusion. Same as outward square brackets above. Matches all versions between 1.2 and 1.2.9, including 1.2 but excluding 1.2.9.

Examples:

Module class

See Module class for more.

Module version handler

See Maintaining your module for more.

Properties

See Properties for more.

Components

See Dependency injection and inversion of control for more.

Module dependencies

You can define runtime or install time dependencies (not build dependencies). If you define a dependency on a module, then this module will be installed and started before your module. A dependency can be optional. Optional in this context means that if an optional module is not present, installation will proceed, but if the optional module is present, this module will be installed first. The dependencies could look like this:

<dependencies>
   <dependency>
      <name>core</name>
      <version>3.6.0/*</version>
   </dependency>
   <!--  in case cache module is present, 
   make sure we install after so we can add a bypass -->
   <dependency>
      <name>cache</name>
      <version>3.6.0/*</version>
      <optional>true</optional>
   </dependency>
</dependencies>

Servlets

See Registering a servlet for more.

Repositories

Repositories and/or workspaces can be defined in the module descriptor. If necessary Magnolia initializes these workspaces before the installation starts. As an example look at the data module:

  <repositories>
    <repository>
      <name>magnolia</name>
      <workspaces>
        <workspace>data</workspace>
      </workspaces>
      <nodeTypeFile>/mgnl-nodetypes/magnolia-module-data-nodetypes.xml</nodeTypeFile>
    </repository>
  </repositories>

Under the hood, these repository workspaces are registered and initialized by the SetupModuleRepositoriesTask when the module is installed.