Essentials Plugin Back-End

An Essentials plugin is available in the Essentials web application if/when the plugin JAR is included in the deployed Essentials WAR.

Spring and JAX-RS

The Essentials web application uses the Spring framework (4.2) for dependency injection, and implements two JAX-RS (2.0) REST server applications: one at the root path "/" to provide the front-end Dashboard application with the basic operational data (primarily the project settings and the set of available plugins), and one at "/dynamic" where the REST resources provided by Essentials plugins are registered/mounted. The Essentials web application uses the Spring framework to inject the requested plugin SDK services into the back-end logic of an Essentials plugin.

Plugin Back-End Logic

There are two entry points for executing back-end code provided by a plugin:

Custom Instructions

During installation, a plugin can ask the Essentials web application to execute custom installation instructions. The Essentials web application parses the <execute> instructions, extracts the fully qualified class name of the custom instruction class, and instantiates a class for every instance of the <execute> element, requiring a zero-argument constructor. Before invoking any of the sdk.api.install.Instruction interface's methods, all API services requested by means of the @Inject annotation (*) get injected into the instruction instance. The code in the custom instruction class can then use these services as described in the corresponding Javadoc.

REST Classes

A plugin can specify a list of REST classes in its Plugin Descriptor, by means of their fully qualified class name. During the initialization of the front-end Dashboard application, all REST classes of all available plugins are registered with the "dynamic" REST server application. During this registration, the Essentials web application instantiates a singleton of the specified class, and injects all API services requested by means of the @Inject annotation (*). Since each REST class is registered as a singleton, these REST classes must not be stateful, i.e. they must not use non-final instance variables. The dependency injection mechanism used for REST classes allows you to inject all dependencies through constructor arguments, so you can make the corresponding instance variables final formally.

A plugin's REST classes need to annotate the class and exposed methods using regular JAX-RS annotations such as @Path, @GET etc., so the REST server knows how to dispatch incoming requests. In order to avoid clashes with other "dynamic" REST classes, each dynamic REST class must be annotated with a unique base @Path at the class level. Mounted successfully, the endpoints exposed by a dynamic REST class with base path "myDynamicRestBasePath" will be accessible under localhost:8080/essentials/rest/dynamic/myDynamicRestBasePath.

On the front-end, the Dashboard application implements an "HTTP-interceptor", inspecting all responses from the back-end. The plugin's REST endpoint method can return an instance of sdk.api.model.rest.UserFeedback, wrapping one or more messages for the Dashboard to display to the user. In this way, a custom REST class can push feedback to the Dashboard user. We recommend using concise messages in English. Technical details such as stack traces can better be left to the back-end logs, to which the user feedback may refer.

(*) Note: the fully qualified class of the  @Inject annotation is jakarta.inject.Inject for version 16.0 and up and javax.inject.Inject for lower versions.