Providing some actions for consumers/clients

In some cases you will desire to add some actions unrelated to the runtime. A simple example is to enable clients - the users of the plugin/library - to test if a connection works. Even more concretely: does my database is up?.

To do so you need to define an @Action which is a method with a name (representing the event name) in a class decorated with @Service:

public class MyDbTester {
    @Action(family = "mycomp", "test")
    public Status doTest(final IncomingData data) {
        return ...;
services are singleton so if you need some thread safety ensure they match that requirement. They shouldn’t store any state too (state is held by the component) since they can be serialized any time.
services are usable in components as well (matched by type) and allow to reuse some shared logic like a client. Here is a sample with a service used to access files:
@Emitter(family = "sample", name = "reader")
public class PersonReader implements Serializable {
    // attributes skipped to be concise

    public PersonReader(@Option("file") final File file,
                        final FileService service) {
        this.file = file;
        this.service = service;

    // use the service
    public void open() throws FileNotFoundException {
        reader = service.createInput(file);

service is passed to constructor automatically, it can be used as a bean. Only call of service’s method is required.

Particular action types

Some actions are that common and need a clear contract so they are defined as API first citizen, this is the case for wizards or healthchecks for instance. Here is the list of all actions:

API Type Description Return type Sample returned type



Mark a method as being useful to fill potential values of a string option for a property denoted by its value. You can link a field as being completable using @Proposable(value). The resolution of the completion action is then done through the component family and value of the action. The callback doesn’t take any parameter.





This class marks an action doing a connection test


{"comment":"Something went wrong","status":"KO"}



Mark an action as returning a discovered schema. Its parameter MUST be the type decorated with @Structure.










Mark a method as being used to validate a configuration. IMPORTANT: this is a server validation so only use it if you can’t use other client side validation to implement it.


{"comment":"Something went wrong","status":"KO"}

Scroll to top