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.

The Essentials web application includes a Swagger UI for manually testing and interacting with the built-in (rather than the dynamic) REST endpoints. That UI is available at http://localhost:8080/essentials/docs/rest-api/index.html. It should be noted that these REST endpoints are not part of the stable Plugin SDK API.


(*) 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.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?