Providing actions for consumers

In some cases you can need to add some actions that are not related to the runtime. For example, enabling users of the plugin/library to test if a connection works properly.

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:

@Service
public class MyDbTester {
    @Action(family = "mycomp", "test")
    public Status doTest(final IncomingData data) {
        return ...;
    }
}
Services are singleton. If you need some thread safety, make sure that they match that requirement. Services should not store any status either because they can be serialized at any time. Status are held by the component.

Services can be used in components as well (matched by type). They 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
    @PostConstruct
    public void open() throws FileNotFoundException {
        reader = service.createInput(file);
    }

}

The service is automatically passed to the constructor. It can be used as a bean. In that case, it is only necessary to call the service method.

Particular action types

Some common actions need a clear contract so they are defined as API first-class citizen. For example, this is the case for wizards or health checks. Here is the list of the available actions:

Close Connection

Mark an action works for closing runtime connection, returning a close helper object which do real close action. The functionality is for the Studio only, studio will use the close object to close connection for existed connection, and no effect for cloud platform.

  • Type: close_connection

  • API: @org.talend.sdk.component.api.service.connection.CloseConnection

  • Returned type: org.talend.sdk.component.api.service.connection.CloseConnectionObject

  • Sample:

{
 "connection": "..."
}

Create Connection

Mark an action works for creating runtime connection, returning a runtime connection object like jdbc connection if database family. Its parameter MUST be a datastore. Datastore is configuration type annotated with @DataStore. The functionality is for the Studio only, studio will use the runtime connection object when use existed connection, and no effect for cloud platform.

  • Type: create_connection

  • API: @org.talend.sdk.component.api.service.connection.CreateConnection

Discoverdataset

This class marks an action that explore a connection to retrieve potential datasets.

  • Type: discoverdataset

  • API: @org.talend.sdk.component.api.service.discovery.DiscoverDataset

  • Returned type: org.talend.sdk.component.api.service.discovery.DiscoverDatasetResult

  • Sample:

{
 "datasetDescriptionList": "..."
}

Dynamic Dependencies

Mark a method as returning a list of dynamic dependencies with GAV formatting.

  • Type: dynamic_dependencies

  • API: @org.talend.sdk.component.api.service.dependency.DynamicDependencies

  • Returned type: java.util.List

  • Sample:

{

}

Dynamic Values

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.

  • Type: dynamic_values

  • API: @org.talend.sdk.component.api.service.completion.DynamicValues

  • Returned type: org.talend.sdk.component.api.service.completion.Values

  • Sample:

{
  "items":[
    {
      "id":"value",
      "label":"label"
    }
  ]
}

Healthcheck

This class marks an action doing a connection test

  • Type: healthcheck

  • API: @org.talend.sdk.component.api.service.healthcheck.HealthCheck

  • Returned type: org.talend.sdk.component.api.service.healthcheck.HealthCheckStatus

  • Sample:

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

Schema

Mark an action as returning a discovered schema. Its parameter MUST be a dataset. Dataset is configuration type annotated with @DataSet. If component has multiple datasets, then dataset used as action parameter should have the same identifier as this @DiscoverSchema.

  • Type: schema

  • API: @org.talend.sdk.component.api.service.schema.DiscoverSchema

  • Returned type: org.talend.sdk.component.api.record.Schema

  • Sample:

{
  "entries":[
    {
      "comment":"The column 1",
      "metadata":false,
      "name":"column1",
      "nullable":false,
      "props":{

      },
      "rawName":"column 1",
      "type":"STRING"
    },
    {
      "comment":"The int column",
      "metadata":false,
      "name":"column2",
      "nullable":false,
      "props":{

      },
      "rawName":"column 2",
      "type":"INT"
    }
  ],
  "metadata":[
  ],
  "props":{
    "talend.fields.order":"column1,column2"
  },
  "type":"RECORD"
}

Schema Extended

Mark a method as returning a Schema resulting from a connector configuration and some other parameters.Parameters can be an incoming schema and/or an outgoing branch.`value' name should match the connector’s name.

  • Type: schema_extended

  • API: @org.talend.sdk.component.api.service.schema.DiscoverSchemaExtended

  • Returned type: org.talend.sdk.component.api.record.Schema

  • Sample:

{
  "entries":[
    {
      "comment":"The column 1",
      "metadata":false,
      "name":"column1",
      "nullable":false,
      "props":{

      },
      "rawName":"column 1",
      "type":"STRING"
    },
    {
      "comment":"The int column",
      "metadata":false,
      "name":"column2",
      "nullable":false,
      "props":{

      },
      "rawName":"column 2",
      "type":"INT"
    }
  ],
  "metadata":[
  ],
  "props":{
    "talend.fields.order":"column1,column2"
  },
  "type":"RECORD"
}

Suggestions

Mark a method as being useful to fill potential values of a string option. You can link a field as being completable using @Suggestable(value). The resolution of the completion action is then done when the user requests it (generally by clicking on a button or entering the field depending the environment).

  • Type: suggestions

  • API: @org.talend.sdk.component.api.service.completion.Suggestions

  • Returned type: org.talend.sdk.component.api.service.completion.SuggestionValues

  • Sample:

{
  "cacheable":false,
  "items":[
    {
      "id":"value",
      "label":"label"
    }
  ]
}

Update

This class marks an action returning a new instance replacing part of a form/configuration.

  • Type: update

  • API: @org.talend.sdk.component.api.service.update.Update

User

Extension point for custom UI integrations and custom actions.

  • Type: user

  • API: @org.talend.sdk.component.api.service.Action

Validation

Mark a method as being used to validate a configuration.

this is a server validation so only use it if you can’t use other client side validation to implement it.
  • Type: validation

  • API: @org.talend.sdk.component.api.service.asyncvalidation.AsyncValidation

  • Returned type: org.talend.sdk.component.api.service.asyncvalidation.ValidationResult

  • Sample:

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

Built In Actions

These actions are provided - or not - by the application the UI runs within.

always ensure you don’t require this action in your component.

built_in_suggestable

Mark the decorated field as supporting suggestions, i.e. dynamically get a list of valid values the user can use. It is however different from @Suggestable by looking up the implementation in the current application and not the services. Finally, it is important to note that it can do nothing in some environments too and that there is no guarantee the specified action is supported.

  • API: @org.talend.sdk.component.api.configuration.action.BuiltInSuggestable

Internationalization

Internationalization is supported through the injection of the $lang parameter, which allows you to get the correct locale to use with an @Internationalized service:

public SuggestionValues findSuggestions(@Option("someParameter") final String param,
                                        @Option("$lang") final String lang) {
    return ...;
}
You can combine the $lang option with the @Internationalized and @Language parameters.
Scroll to top