How To clean up a service
1. What you will learn
In this guide you will learn to implement a service usable by commands that automatically registers itself to the engine to receive a cleanup on engine termination.
2. Prerequisites
-
Roughly 10 minutes
-
JDK11+ installed with JAVA_HOME configured appropriately
-
An IDE (we recommend IntelliJ)
-
Some kind of build tool (like gradle, maven or ant)
-
Know how to configure the service processor
-
Understand the basics of command services
3. The IRequireCleanup interface
3.1. Service states
Some services might be stateful. That means their state might change during an engine run.
A state is a representation of data and processes managed by the instance.
For new engine runs the state should be reset to prevent unnecessary resources being consumed by data persisting or processes continuing to run after engine termination.
3.2. How does it work
The interface provides two main points of interest needing further explanation:
-
The cleanup method
-
Automatically registering services implementing the interface to the engine
The cleanup method is designed to implement service specific cleanup that resets a services state. This method is called by the engine whenever the Engine is entering its terminating state and therefore shutting down. That can happen if an error occurs, the user aborts or suspends the execution of an engine run, or the current run simply finished executing.
A service implementing the interface does not need to be registered manually to the engine as long as it winds up in the engines service provider. For example a IPakService or a IHumanTaskJavaBridge will be automatically registered.
| Apps might also want cleanups on some of their services. The same rules with the engines service provider also apply. |
3.3. Special Case ILiteService
Services of type ILiteService will also be automatically registered, however their cleanup works a little different to regular services.
Instances of ILiteService are stateless by design because the instances only persist for the one command they are injected into. This design ensures instance states have no effect of other usages of the same ILiteService. However, if the ILiteService uses a static state then it might affect other instances of the class. A cleanup therefore is only useful for static states on the ILiteService.
| A static state is a state is a member of the service class itself and not the instances. |
3.4. Interface structure
The basic structure of a cleanup service looks like this:
public class CleanupStructureService implements IRequireCleanup { (1)
// [...]
public void cleanup() { (2)
// cleanup impl
}
}| 1 | The service class must implement the IRequireCleanup interface |
| 2 | The cleanup() method of the Interface with the cleanup behaviour for the specific class |
4. Example Cleanup Service Step by Step
4.1. Remarks
After understanding how the Interface works and how the basic structure looks like, it is time to implement such a service.
The example focuses on implementing a IPakService.
|
| In the following example configuring of the service processor was omitted and is considered already done beforehand. |
4.2. Implementing the Service
First the service interface registered to the service processor needs to be defined:
public interface ICacheService extends IPakService { (1)
void cacheValue(final int value); (2)
int getCachedValue();
}| 1 | The interface extents IPakService and therefore is a service loaded by the engines service provider |
| 2 | Two methods to call for the services users to cache a value or read the cached value. |
Afterwards behaviour can be added in the implementation of the just defined interface:
@PakService (1)
public class CacheService implements ICacheService, IRequireCleanup { (2)
private int cachedValue = 0; (3)
public void cacheValue(final int value) { (4)
this.cachedValue = value;
}
public int getCachedValue() { (5)
return this.cachedValue;
}
public void cleanup() { (6)
this.cachedValue = 0;
}
}| 1 | The annotation required by instances of IPakService |
| 2 | The definition of the service implementation implementing the previously defined ÌCacheService and the IRequireCleanup interface |
| 3 | A private variable that defines the state of the service with initial state value being 0 |
| 4 | A method from the service interface to change the cached value |
| 5 | A method from the service interface to read out a state value |
| 6 | The cleanup method to reset the state variable to its initial state value |
Logging was omitted in the example. However, in order to make the cleanup visible in the Workflow Executor, some logging was added before and after the state variable reset within the cleanup() method.
|
4.3. Using the service in commands
After defining the service, we can use it in a command just like any other service. If everything was configured correctly there should be no difference between regular services and services requiring cleanups when implementing a command.
/**
* @workflowDocu Simple command that uses a service with self-cleanup
*/
@JavaCommand
@CommandGroup("org.example")
public class CacheWriteRead {
/**
* @workflowDocu Service that cleans itself up
*/
@Service (1)
private CacheService cacheService;
/**
* @workflowDocu The Value to cache in the service
*/
@Persistent
private int valueToCache;
/**
* @workflowDocu The cache value before the write operation
*/
@Persistent(scope = FieldScope.WRITE_ONLY)
private int oldCacheValue;
/**
* @workflowDocu The cache value after the write operation
*/
@Persistent(scope = FieldScope.WRITE_ONLY)
private int newCacheValue;
@Run
public void cacheValue() { (2)
this.oldCacheValue = this.cacheService.getCachedValue();
this.cacheService.cacheValue(this.valueToCache);
this.newCacheValue = this.cacheService.getCachedValue();
}
}| 1 | Injecting of the service to be able to use it in the command |
| 2 | Simulating of two read operations with a write operation on the state variable in between |
The state was changed by the command and therefore on a new engine run it is expected that the cache is reset.
4.4. Running the command
After building the command, it can be executed using the Workflow Executor. Following outcome is expected:
The expected outcome is the following:
The datastore now stores values it that were read during the command execution. The oldCacheValue was the initial value and the newCacheValue is the same value that was given to the command as input. If the service would persist over engine runs by adjusting the @PakService annotation to @PakService(persistentClassLoader = true, singletonInstance = true), the initial value of the cache would now be the same as the newCacheValue of the previous run. As a cleanup was implemented, that is not the case as can be seen from the logs of the cleanup method:
| 1 | This log was called before we reset the cached value returning the value from the engine run |
| 2 | This log was called after we reset the cached value returning the initial value again |
5. Use Cases
At last here are some basic use cases where a cleanup might be helpful.
-
Service caching data
-
Service creating temporary files
-
Service managing processes
5.1. Caching Data
A service might handle request made to an api returning big response payloads. In order to reduce the amount requests made to the api the service might want to cache the responses to reuse them later on. The cleanup then clears the cache to ensure the request data does not consume memory beyond the engine run.
| The cleanup in this use case would be useful if the service instance persists over multiple engine runs. |
5.2. Creating Temp files
Another way a service might process data is to create temporary files to store some information and then discard them later on. In order to prevent those files from persisting beyond an engine run a cleanup might be wise to delete those temporary files.
5.3. Managing Processes
A different variant of a service might handle some processes running on the computer. These processes might only be needed for the runtime of the engine and can be discarded afterwards. This can also be done by managing the processes in a service which then kills the processes when the engine terminates.