Module org.mule.runtime.extensions.api
Package org.mule.runtime.extension.api.client

Interface ExtensionsClient

@MinMuleVersion("4.1") @NoImplement public interface ExtensionsClient
The ExtensionsClient is a simple interface for executing extension operations programmatically.

The operation to execute is referenced through its name and the name of the extension in which it's defined. Notice that the extension is referenced by name and not GAV, which means that the extension is assumed to be present and activated on the current execution context.

Once the operation is located, the operation execution is parameterized by not only providing parameter values, but also config reference, reconnection and streaming strategies, etc.

Note that this client will be reachable through the mule registry, and you will be able to inject it in any class with lifecycle.

A usage example for an operation with this signature public String getName(@UseConfig config, int account) could be: 

 {@code
 public class UsingExtensionsClient {
  @Inject ExtensionsClient client;
  ...
  public void executeWithClient() {
    client.<String, Object>executeAsync("myExtensionName", "getName", params ->
  		params.withConfigRef("conf").withParameter("account", 12)
  	).whenComplete((result, e) -> {
  		if (e != null) {
  			logError(e);
            } else {
  			processResult(result);
      }
   });
 }
 </pre>

 @since 1.0

  • Method Details

    • execute

      @MinMuleVersion("4.5.0") <T, A> CompletableFuture<Result<T,A>> execute(String extension, String operation, Consumer<OperationParameterizer> parameters)
      Executes an operation asynchronously by returning a CompletableFuture instance that will complete into a Result with the corresponding payload and attributes after the operation execution finished.

      If the executed operation is not asynchronous in nature, the client might choose to actually execute in a synchronous manner.

      Type Parameters:
      T - The generic type of the result's payload
      A - The generic type of the result's attribute
      Parameters:
      extension - the name of the extension that contains the operation to be executed.
      operation - the name of the operation to be executed.
      parameters - consumers an OperationParameterizer used to configure the operation
      Returns:
      a CompletableFuture instance that completes into a Result with the payload content and the corresponding attributes.
      Since:
      4.5.0

    • createSource

      @MinMuleVersion("4.5.0") @Experimental <T, A> SourceHandler createSource(String extension, String sourceName, Consumer<SourceResultHandler<T,A>> handler, Consumer<SourceParameterizer> parameters)
      Creates and initialises a Source using a given parameterization.

      The generated messages will be passed back to the caller through a Consumer passed in the callback argument. The provided SourceResultHandler has a pretty strict contract around how it should be consumed. Follow that contract thoroughly in order to avoid resource leaks or protocol issues with the remote system.

      The created source is returned in the form of a SourceHandler. The main purpose of it is to control the lifecycle of the underlying source. When returned, the source is already is initialised (as defined in Initialisable.initialise()) but not started, which means it isn't producing any messages. The source will be started when SourceHandler.start() is invoked. SourceHandler.stop() can be called for the source to stop producing messages, and SourceHandler.dispose() when the source is no longer needed. Stopped sources can be restarted, but disposed sources are not recoverable, they need to be created again through another call to this method.

      When {this ExtensionsClient is disposed, all active SourceHandler will be stopped and disposed as well.

      NOTE: Experimental feature. Backwards compatibility not guaranteed.

      Type Parameters:
      T - the generic type of the result output values produced by the source
      A - the generic type of the result attribute values produced by the source
      Parameters:
      extension - the name of the extension in which the source is defined
      sourceName - the name of the source to be created (as it appears in the ExtensionModel
      handler - a Consumer that will be invoked each time the source produces a new message, in the form of a SourceResultHandler
      parameters - consumers an OperationParameterizer used to configure the source. This is for the source main parameters, not it's callbacks
      Returns:
      a SourceHandler
      Since:
      1.5.0
      See Also:

    • executeAsync

      @Deprecated <T, A> CompletableFuture<Result<T,A>> executeAsync(String extension, String operation, OperationParameters parameters)
      Deprecated.
      since 4.5.0. Use execute(String, String, Consumer) instead
      Executes an operation asynchronously by returning a CompletableFuture instance that will complete into a Result with the corresponding payload and attributes after the operation execution finished.

      If the executed operation is not asynchronous in nature, the client might choose to actually execute in a synchronous manner.

      Parameters:
      extension - the name of the extension that contains the operation to be executed.
      operation - the name of the operation to be executed.
      parameters - an OperationParameters instance with all the parameters required to execute the operation.
      Returns:
      a CompletableFuture instance that completes into a Result with the payload content and the corresponding attributes.

    • execute

      @Deprecated <T, A> Result<T,A> execute(String extension, String operation, OperationParameters parameters) throws org.mule.runtime.api.exception.MuleException
      Deprecated.
      since 4.5.0. Use execute(String, String, Consumer) instead
      Executes an operation synchronously and returns a Result with the operation's output and attributes if available.

      Take in mind that if the executed operation is asynchronous in nature, this method will automatically wait for it to complete before returning the value

      Parameters:
      extension - the name of the extension that contains the operation to be executed.
      operation - the name of the operation to be executed.
      parameters - an OperationParameters instance with all the parameters required to execute the operation.
      Returns:
      a Result instance with the payload content and the corresponding attributes after the operation execution.
      Throws:
      org.mule.runtime.api.exception.MuleException - if any error occurred while executing the operation.