Isolated Mode – Default mode since FirstSpirit 2019-02

FirstSpirit extensions are developed in Java. The integration of an external implementation into the FirstSpirit Server and FirstSpirit Client applications (FirstSpirit SiteArchitect, FirstSpirit ServerManager, etc.) takes place via FirstSpirit APIs. These provide access to information, services and functions within FirstSpirit.

During runtime, the fs-server.jar file (or fs-client.jar) is located in the classpath. In addition to FirstSpirit APIs, the fs-server.jar file contains internal FirstSpirit classes and various libraries (see figure below).

Classloading: Previous Behavior

Until now (Legacy modes), all components of the fs-server.jar file have been loaded in the Java VM. As a result, the VM Classloader not only has access to official FirstSpirit interfaces, but also to internal classes and libraries that are contained in the jar as well (see figure).

What Disadvantages Are There?

For module development, this “surplus supply” is initially unproblematic. The resources available (libraries, classes, APIs) can easily be used within module implementation.

Known disadvantages include:

• The libraries contained in the fs-server.jar file (e.g., Log4J; Apache Commons) result in global dependencies. Conflicts then occur, for example, if a library is used on the FirstSpirit Server and the module developer would like to use the same library in another (newer) version. An exchange of certain libraries locally within a module is currently not possible.
• The libraries contained in the fs-server.jar file are not a guaranteed product component and are therefore also not subject to organized change management (unlike FirstSpirit APIs). The version of a library available in the fs-server.jar file depends on the version of FirstSpirit used. This means that conflicts can also occur when a FirstSpirit Server is upgraded or downgraded. If the version of a library changes on the server in the process, then this can result in incompatibilities with modules that are already installed there and that use this library from FirstSpirit.
• Another point of conflict is the uncontrolled use of internal implementation classes that are also contained in the fs-server.jar file. As these are available in the JVM Classloader hierarchy, they can also be unofficially used for module implementation. This is convenient at first if an official method does not exist, but naturally these internal classes are also not subject to stability requirements and can be changed at any time.

Purpose and Advantages of Isolated mode

• More freedom in selecting the libraries used
• Global dependencies on other product components are largely avoided
• Overall, module development is more reliable and stable
• Modules are easier to maintain
• Lower migration costs when upgrading or downgrading the FirstSpirit Server

Example: For example, if FirstSpirit uses “Apache Commons Logging” in version 1.2 internally for logging within a web application, a conflict will always occur in legacy mode if a module developer wants to use “Apache Commons Logging” in another version for a customer-specific module implementation. This is particularly problematic if the module development contains third-party dependencies that cannot be easily customized.

Classloading in "Isolated Mode"

In Isolated mode, FirstSpirit APIs are contained in the fs-isolated-server.jar file. This means that all methods and interfaces of the API are visible in Classloader and can be used for module development (see figure below).

To establish connections and for other essential functions, a minimal infrastructure in the form of additional classes is also required (“basic infrastructure”, see figure). These internal infrastructure classes are also still visible in Classloader.

All other internal classes (“Impl”) as well as the libraries available in the fs-server.jar file until now are no longer contained in the Classloader hierarchy in “shielded” mode. This content is transferred to a hidden area (to a directory within the jar file) and can no longer be located by Classloader (“hidden” area, see figure). As a result, conflicts no longer occur if a module uses a library that is already available in a different version in the hidden area of the fs-isolated-server.jar file. Conflicts with other modules that use the same library in a different version can still occur however (if these libraries are globally integrated).

Classloading with FirstSpirit web applications

On the application server, conflicts with libraries used internally are prevented through “shading”. In this process, any libraries used in internal FirstSpirit web applications were renamed; the packages were renamed for this purpose:

For instance, the

org.apache.commons.logging

package becomes

de.espirit.apache.commons.logging

These renamed classes should not be used in module implementation.

The two methods (shading as well as transferring internal libraries and classes to a hidden area) prevent conflicts with resources in other product components or other module implementations, and also prevent access to these resources.

Restrictions

Mixed Operation Not Possible in Cluster Environments

Mixed operation of isolated servers and legacy servers is not permitted in a cluster group. This means that an isolated master server cannot be operated in a group with a legacy slave server (or vice versa), for example.

Schedule: Introducing Isolated Mode

Current plans for restructuring module development (subject to change without prior notice):

(February 2017) Public Beta (introduction of isolated mode)
Changing over to isolated mode is very easy but must be active. To ensure the compatibility of existing modules, the previous behavior (“legacy mode”) is still also being supported. This means that if modules are already designed so that they are reliant on the use of internal libraries, these modules can continue to be used – no adjustments are needed for this.

(January 2019) Migration of FirstSpirit internal modules
Starting with FirstSpirit 2019-01, the FirstSpirit modules delivered by e-Spirit / Crownpeak are being converted into the Isolated mode. The display name of the modules (tag <displayname>) was supplemented by the addition (I, L). This indicates that the respective module can be operated both on FirstSpirit servers that are already running in Isolated mode, as well as on servers that are still running in Legacy mode laufen. The unique identifier / name of the modules (tag <name>) remains unaltered.

(February 2019) Release
Isolated mode is officially released: FirstSpirit servers that are newly installed with this release or later use Isolated mode by default (when using the file fs-install-[version].tar.gz). If modules are used, they should be isolated-capable to ensure smooth operation. See also page Module development "Isolated".
Existing FirstSpirit modules that exclusively use resources that are available on the FirstSpirit server (such as services, libraries, project applications) can run directly on an Isolated Server. No adjustments are necessary here in the short term. In the medium term, however, all resources in modules should be adapted to the new conditions in order to be able to use the advantages of Isolated mode. See pages Module development "Isolated" and Server: Installation and Migration.

(January 2022) Announcement: Elimination of the Legacy Mode
Legacy Mode will be discontinued at the beginning of 2022. All servers should have been converted by then.

(March 2022) Legacy files are no longer provided
The legacy binaries

• fs-access.jar
• fs-server.jar
• fs-webrt.jar

are no longer provided and must be replaced with the isolated equivalents.
In addition, the installer (fs-install tar.gz) and updater (fs-update tar.gz) no longer support legacy mode. FirstSpirit servers that are still operated in legacy mode are therefore no longer updated to newer releases (via fs-update tar.gz).

End of 2022: Elimination of the Legacy Mode for customer modules
It is planned to end the support of legacy mode for modules. All modules should have been converted by then.