It actually intercepts twice, right before an operation is executed, and
It actually intercepts twice, right before an operation is executed, and right after.
right after.
Its main focus is to help integrations. It gives an opportunity to
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:
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
- Modify the API call inputs/outputs immediately before/after they reach its executor.
reach its executor.
- Trigger additional internal logic.
- Trigger additional internal logic.
- Notify third party systems.
- Notify third party systems.
Core Plugin
Core Plugin
-----------
-----------
To archive these goals is necessary to provide a core plugin of the type
To archive these goals is necessary to provide a core plugin of the type 'api-listener' to the AS:
'api-listener' to the AS:
### Plugin.properties
### Plugin.properties
It is required to provide an 'operation-listener.class' indicating the
It is required to provide an 'operation-listener.class' indicating the class name of the listener that will be loaded.
class name of the listener that will be loaded.
Additionally any number of properties following the
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.
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.
operation-listener.your-config-property = Your Config Message
```
### lib
### lib
The core plugin should contain a lib folder with a jar containing a
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:
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
- setup: Runs on startup. Gives one opportunity to read the configuration provided to the core plugin
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.
- beforeOperation: Runs before each operation occurs. In addition to
- 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.
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.
```{warning}
```{warning}
Implicit Requirements
Implicit Requirements
**Requirement 1: The Listener should be Thread Safe Code**
**Requirement 1: The Listener should be Thread Safe Code**
A single instance of the Listener is created during the server startup.
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.
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**
**Requirement 2: The Listener should not throw Exceptions**
...
@@ -78,73 +60,76 @@ All API Operations go through every listener so the method signatures should use
...
@@ -78,73 +60,76 @@ All API Operations go through every listener so the method signatures should use
You can download a complete example with sources [here](/download/attachments/132286253/api-listener-example.zip?version=1&modificationDate=1663665058217&api=v2) to use as a template to make your own.
[here](/download/attachments/132286253/api-listener-example.zip?version=1&modificationDate=1663665058217&api=v2) to
