The V3 API listener core plugin is an implementation of the interceptor pattern: https://en.wikipedia.org/wiki/Interceptor_pattern
It actually intercepts twice, right before an operation is executed, and right after.
Its main focus is to help integrations. It gives an opportunity to integrators to execute additional functionality before or after an api call with the next purposes:
- Modify the API call inputs/outputs immediately before/after they reach its executor.
- Trigger additional internal logic.
- Notify third party systems.
To archive these goals is necessary to provide a core plugin of the type 'api-listener' to the AS:
It is required to provide an 'operation-listener.class' indicating the class name of the listener that will be loaded.
Additionally any number of properties following the pattern 'operation-listener.<your-custom-name>' can be provided. Custom properties are provided to help maintainability, they give an opportunity to the integrator to only need to compile the listener once and configure it differently for different instances.
The core plugin should contain a lib folder with a jar containing a class that implements the interface IOperationListener, this interface is provided with the V3 API jar and provides 3 methods:
- setup: Runs on startup. Gives one opportunity to read the configuration provided to the core plugin
- beforeOperation: Runs before each operation occurs. In addition to the operation intercepted it also provides access to the api and the session token used for the operation.
- afterOperation: Intercepts after the operation occurs. In addition to the operation intercepted it also provides access to the api, the session token used for the operation, the operation result and any exception that happened during the operation.
Requirement 1: The Listener should be Thread Safe Code
A single instance of the Listener is created during the server startup.
Since a single instance is used to serve all requests thread safe code is a requirement.
We strongly suggest to not to keep any state.
Requirement 2: The Listener should not throw Exceptions
If the listener throw an exception it will make the API call fail.
Requirement 3: The Listener should use IOperation and IOperationResult as indicated below
All API Operations go through every listener so the method signatures should use IOperation and IOperationResult.
Please use instanceof for safe casting.
Example - Logging
The next implementation example captures the calls and logs on the standard openbis log the operation name:
Example - Loggin Sources
You can download a complete example with sources here to use as a template to make your own.