Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
This page is about the XML-based module descriptor file which identifies and defines a Magnolia Maven module. If you are using a Magnolia light module, you should use a YAML-based module descriptor.
The XML file:
src/main/resources/META-INF/magnolia/<module-name>.xml
When you start Magnolia, the system identifies available modules by locating each module's descriptor file.
The XML based module descriptor has a number of benefits:
Here is an example XML Maven 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>app-geotagging</id> </components> <components> <id>app-geotagging-main</id> <component> <type>com.acme.geo.app.main.GeoTaggingMainSubappView</type> <implementation>com.acme.geo.app.main.GeoTaggingMainSubappViewImpl</implementation> </component> </components> <dependencies> <dependency> <name>ui-admincentral</name> <version>${project.version}</version> </dependency> </dependencies> </module>
Lines 8, 22: Note how you can refer to Maven properties within the module descriptor.
| required The functional name of the module. You will see this name in the config workspace. |
| required The module version. |
| optional The display name of the module. |
| optional Full description of the module. |
| optional The name of a module class. |
| optional The name of the version handler class. |
| optional Properties that can be used with the version handler. |
| optional Dependencies on other modules - the module will install only after the specified modules. |
| optional Servlets which will be included in the servlet filter. |
| optional The repositories which must exist or will be created for this module. |
components | optional Injected components used by the module. Example: Defining an app or subapp as a component |
For each module you have to provide:
artifactId
and groupId
to the identify the Maven artifact<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:
social-media-hub
com.tinext.magnolia
(contains the name of the creator Tinext.com)social-media-hub.xml
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.
Only three parts are supported. The major, minor and security version positions. The build number is not supported. See Runtime.Version for more information.
*
- Includes all versions - *
with quotes (version: "*"
)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:
Example | Description |
---|---|
| Must have major version 3. |
| Must have major version 3.6. |
| Must have major version 3.6 and maintenance version 3. |
| Must have major version 3 or higher. |
| Must have major version 3.6 or higher. |
| Must have major version 3.6 and maintenance version 3 or higher. |
| Must have major version 3 or lower. |
| Must have major version 3.6 or lower. |
| Must have major version 3.6 and maintenance version 3 or lower. |
| Version not lower than 3.5 and not higher than 3.6.2. |
[3.5/3.6.2] | Versions between 3.5 and 3.6.2 including the boundaries. |
[3.5/3.6.2[ | Versions between 3.5 and 3.6.2, excluding the upper boundary 3.6.2. |
[3.5/3.6.2) | Versions between 3.5 and 3.6.2, excluding the upper boundary 3.6.2. Same as above but alternative syntax. |
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>
module-a
depends on module-b
, module-b
will be loaded before module-a.
The order becomes important, for example, if both module-a
and module-b
decorate the same definition or if module-a
inherits a definition from module-b
.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.