Module development "Isolated"

Modules that are newly developed should also meet the requirements of Isolated Mode. We recommend using Gradle with the FirstSpirit Module Gradle Plugin for module development. The plugin creates a module-isolated.xml for you, with all the features described below.

Module Naming Scheme

It makes sense to develop a naming scheme for modules and module components running on a FirstSpirit server. The names have to be unique within a FirstSpirit server. The server creates directories based on these names, which should be readable.

General Recommendation:

• only use small letters (no capitals)
• no spaces
• word separation with hyphens (-)
• use prefixes for product families (in our example: mpl and xxx)
• module names are used as prefixes for component names

Example

1. Module name: mpl-example-login

• Components
  • Public (name according to purpose)
    • providing a config: mpl-example-login-config
    • a schedule task factory: mpl-artifactory-deployment-scheduletask
    • ...
  • Service: mpl-example-login-service
  • Webapp: mpl-example-login-webapp

2. Module name: xxx-example-integration

• Project app: xxx-example-integration-projectapp (or ...-projectconfig)

Display names

• CamelCase
• With spaces
• Example: Maple Example Login Module (I,L)

Isolated resources

To be able to use the advantages of the Isolated Mode, all libraries required by the module must be contained in the module as a resources.
First, the module developer should define which libraries are required by the module. These resources must be added to the module (as a component, see Ressourcen (→Manual for Module Developers)).

In the Der Komponenten-<components>-Deskriptor-Teil (→Manual for Module Developers) a unique name and other properties must be defined:

Allocating Unique Names to Resources

Resources have unique names. If a library is added to a module as a resource, a unique name must be defined for the resource in the Der Komponenten-<components>-Deskriptor-Teil (→Manual for Module Developers).

We not only recommend allocating unique names but also ensuring that names are consistent with one another (in accordance with the Maven schema) so that identical or compatible resources can be identified, e.g.,:

<web-resources>
   <resource name="org.apache.httpcomponents:httpclient" version="4.4">lib/httpclient-compatibility.jar</resource>
</web-resources>

The name (in accordance with Maven) first comprises a “groupID” (in this case: org.apache.httpcomponents) and then an “artifactID” (in this case: httpclient) separated by a colon. The “groupID” is a group description (similar to Java package names) and is used to uniquely identify the manufacturer. It usually corresponds to the manufacturer's domain name in reverse. The “artifactID” is the name of the resource (see Maven conventions).

Using the name and other properties (see below), it is possible to determine whether different resources (libraries in this case) are compatible. Dependencies on other product components and migration costs can often be avoided as a result.

Versioning Resources

If names are identical, an attempt is made to ascertain whether resources are compatible with one another. In order to do this, the unique identifier (“name”) and the version of the resource supplied (“version”) are required and optionally the minimum compatible version (“minVersion”) and the maximum compatible version (“maxVersion”) can be specified:

<web-resources>
   <resource name="org.apache.httpcomponents:httpclient" version="4.4" minVersion="4.4" maxVersion="4.5.2">lib/httpclient-compatibility.jar</resource>
</web-resources>

For the “maxVersion”, the following specification:

minVersion="4.4" maxVersion="4.9.9"

is also permitted if the library remains stable within a minor series (even if this version of the library does not exist at the time that the module is created).

If a resource exists in several different versions, this information can be used to determine the best intersection between the resources.

The following applies:

• If the names are identical and there is no version specification (“version”) for one or both of the resources, the resources are not compatible.
• If the names are identical and the version specifications (“version”) are different – the specification of “minVersion” and “maxVersion” – the resources are compatible.
• If the names are identical and the version specifications (“version”) are different but scope for compatibility is created through the specification of “minVersion” and “maxVersion”, the newest (most recent) resource is always used, which is compatible with all modules:
  • If the specification of “minVersion” is missing, the scope for compatibility is not limited by a lower limit (0 to “maxVersion”)
  • If the specification of “maxVersion” is missing, the scope for compatibility is not limited by an upper limit (“minVersion” to infinity)

Examples of Resource Definition (Scope for Compatibility: Libraries)

Defining Classloading Mode (Attribute "mode")

To be able to operate a module in Isolated mode, the mode attribute must be defined for the desired resources of the module with the value isolated.

• isolated: The “new” classloading technique is used for the resource.
  The module in question must supply all required libraries itself; access to internal resources of the FirstSpirit server is no longer possible without restrictions. See also Classloading in "Isolated mode"
• legacy: The “old” classloading technique is used for the resource.
  The resource in question has access to internal implementations and libraries of the server. See also Classloading: Previous behavior.
  If the attribute is not set, Legacy mode is applied to the resource in question.

The attribute is only available in the tag <resource>, not for the surrounding <resources>.
Example:

<module>
...
 <resources> 
 <resource name="..." version="..." scope="..." mode="isolated">lib/isolated.jar</resource>  
 </resources>
</module>

The attribute scope can be used to control library visibility. See chapter Explanation: Classloading