Changing modules to Isolated Mode

Existing customer-specific modules can be easily converted to Isolated Mode step by step.

For information on how an existing FirstSpirit server can be switched to Isolated Mode, see page Server: Installation and Migration.

1) Identifying non-isolated resources

First, in existing modules, it should be determined whether there are non-isolated resources and what they are. To do this, the tool “FSM Dependency Checker” can be used (for login data please contact Technical Support).
The Dependency Checker displays all dependencies of the module, distinguishing between internal dependencies (to FirstSpirit classes) and external dependencies (classes that are neither contained in the module nor in FirstSpirit). The internal dependencies are also evaluated according to various criteria (e.g. not available in Isolated mode, use of deprecated API, use of internal classes that are not in the API, etc.).

All required libraries must be added to the module.

2) Creating compatibility (module-isolated.xml)

Modules that are switched to Isolated mode should transitionally be able to operate in both modes: legacy and isolated.
In legacy mode, the module to be converted can already be operated, no changes are required here.
In order that the module can also be operated in isolated mode, the additional required resources (libraries) should be added to the module.

In addition to the

module.xml

a file

module-isolated.xml

must be available. See also chapter Der Modul-Deskriptor (→Manual for Module Developers).

This file should define the resources required for Isolated mode. The file module.xml can be copied and then renamed and adapted.

If a module contains these two xml files, it can be run both on FirstSpirit servers that are still in legacy mode and on FirstSpirit servers that are already running in Isolated mode (see page Server: Installation and Migration): If the server is running in Isolated mode, the file module-isolated.xml used, if the server is running in Legacy mode, the file module.xml is used. If there is no module-isolated.xml file, the module.xml file is used as fallback in Isolated Mode.

3) Keep attribute "name"

The name of the legacy module must also be used for the isolated module (attribute name). Only then it is guaranteed that the module can be updated cleanly from older versions. Changing the name attribute would cause the changed module to be installed in addition to the existing module instead of replacing it.

4) Differentiation by "displayname"

It is recommended to use the displayname attribute to specify the server type on which the module can be operated:

• (L): The module can only be used on servers that are operated in legacy mode.
• (I): The module can only be used on servers running in Isolated mode.
• (I, L): The module can be used on both legacy and isolated servers.

Example:

...
<module>
   <name>MyModuleName</name>
   <displayname>Module XYZ (I, L)</displayname>
   <description>Module supported in legacy and isolated mode</description>
   ...
</module>

5) Activating isolated mode for resources (attribute "mode")

In order that a module can be operated in Isolated mode, the attribute mode must be defined for the desired resources of the module with the value isolated.

Example:

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

6) Web applications

In contrast to the FirstSpirit Server, access to “shielded” functionalities cannot be controlled on the application server. This means that all modules that use web applications no longer have access to libraries that were part of the FirstSpirit web application when used on an isolated server (see figure below). Consequently, a whole series of classes are no longer available ad hoc.

Example: the module uses Apache Commons Logging API functions for logging within a web application. In legacy mode, this library is part of the fs-webrt.jar file. This means that the corresponding classes can be used directly within module implementation without the module developer having to add this library to the module.

In isolated mode, this is no longer automatically possible as there is no longer an opportunity to access the library (“shading”). In this case the corresponding libraries must be brought as web-resource by adding them in the module-isolated.xml file accordingly.

7) Usage

If the module was subsequently newly built, it can be installed or updated as usual via the FirstSpirit ServerManager.

During the deployment of a Webanwendung (→Manual for Module Developers), all resources defined in the module are compared with those of other components based on their names, and duplicates are filtered out as described for parameter version. If conflicts are detected during this check, the rollout of the web application is aborted with a corresponding error

Note: You should use the FirstSpirit Module Gradle Plugin to create modules.