Essentials Plugin Back-End
An Essentials plugin becomes available in the Essentials web application when its plugin JAR is included in the deployed Essentials WAR file.
Spring and JAX-RS Integration
The Essentials web application uses Spring Framework 4.2 for dependency injection. It provides two JAX-RS 2.0 REST server applications:
- The root path (
/) serves the front-end Dashboard with core operational data, including project settings and the list of available plugins. - The
/dynamicpath registers and exposes REST resources provided by Essentials plugins.
Spring injects the required plugin SDK services into the back-end logic of each Essentials plugin.
Plugin Back-End Execution
Plugins can execute back-end logic through two main entry points:
Custom Instructions
During plugin installation, a plugin can request the Essentials web application to run custom installation instructions. The web application processes <execute> elements in the plugin configuration, extracts the fully qualified class name for each custom instruction, and instantiates the class using a zero-argument constructor.
Before any sdk.api.install.Instruction interface methods are called, the application injects all requested API services into the instruction instance using the @Inject annotation (*). The custom instruction class can then use these services as described in the corresponding Javadoc.
REST Classes
A plugin can declare a list of REST classes in its Plugin Descriptor using their fully qualified class names. When the front-end Dashboard initializes, the Essentials web application registers all REST classes from available plugins with the "dynamic" REST server application.
During registration, the application creates a singleton instance of each REST class and injects all dependencies requested via the @Inject annotation (*). REST classes must remain stateless; do not use non-final instance variables. You can inject dependencies through constructor arguments and declare the corresponding instance variables as final.
REST classes must use standard JAX-RS annotations (such as @Path, @GET) on the class and its methods. Each dynamic REST class requires a unique base @Path annotation at the class level to prevent conflicts. For example, if a REST class uses the base path myDynamicRestBasePath, its endpoints are available at:
localhost:8080/essentials/rest/dynamic/myDynamicRestBasePath
On the front-end, the Dashboard application uses an HTTP interceptor to inspect all responses from the back-end. A plugin's REST endpoint can return an instance of sdk.api.model.rest.UserFeedback, which wraps one or more messages for the Dashboard to display. Use concise English messages for user feedback. Log technical details, such as stack traces, on the back end and refer to them in user feedback if necessary.
Info: The Essentials web application provides a Swagger UI for testing and interacting with built-in (not dynamic) REST endpoints. Access the Swagger UI at http://localhost:8080/essentials/docs/rest-api/index.html. These endpoints are not part of the stable Plugin SDK API.
(*) Note:
For version 16.0 and later, use jakarta.inject.Inject for the @Inject annotation. For earlier versions, use javax.inject.Inject.