Contact Us 1-800-596-4880
  1. Homepage
  2. Anypoint Connector DevKit (3.3)
  3. Writing Mule Extensions

  4. Configuring Extensions

Configuring Extensions

Normally a Mule extension will have global configuration parameters and operation specific parameters. The former, is related to instance variables or global state meaning that is state persistent across operations.

Instance variables that need to be exposed to Mule need to have a special metedata to signal the Annotation Processor that the field can be assigned inside a Mule configuration XML file. The DevKit provides the @Configurable annotation for this case. In other words, any instance variable of a Connector or Module that needs to be configured by the users has to marked with @Configurable

An extension can have any number of @Configurable fields and these fields can be of primitive or complex types. Additionally, a @Configurable field can be optionally set from Mule and can take a default value in case a value is not assigned to it.

Note: all of the examples and explanations in this page apply for @Connector annotated classes as well as @Module annotated ones.

The @Configurable Annotation

The @Configurable annotation is used to signal the generator for all the bean properties that will be configurable for each instance of your connector. In addition to the @Configurable annotation, a public setter is needed.

Usage example:

import org.mule.api.annotations.Configurable;
import org.mule.api.annotations.Connector;

@Connector(name = "myconnector")
public class MyConnector {

    @Configurable
    private String key;

    public void setKey(String key) {
       this.key = key;
    }

Then the module or connector can be configured as follows:

<myconnector:config key="myKey" />

Notice that by annotating a field only with @Configurable it is mandatory to assign a value it when configuring the extension in the xml.

@Optional

The @Optional annotation is used together with the @Configurable field and it indicates that the field is configurable but it is not mandatory to do so.

Usage example:

@Module(name = "mymodule")
public class MyModule {

    @Configurable
    @Optional
    private String key;

    public void setKey(String key) {
       this.key = key;
    }

Then the connector can be configured as follows:

<myconnector:config key="myKey" />

And the following is valid as well since it is optional to assign a value to it:

<myconnector:config />

@Default

The @Default annotation is used together with @Configurable and @Optional and is used to provide a default value to a configurable field in case one is not assigned explicitly.

Usage example:

@Module(name = "mymodule")
public class MyModule {

    @Configurable
    @Optional
    @Default("testKey")
    private String key;

    public void setKey(String key) {
       this.key = key;
    }

Then the connector can be configured as follows:

<myconnector:config key="myKey" />

Or if the key attribute is not present it will implicitly be assigned the value testKey as defined by the @Default annotation:

<myconnector:config />

Multiple Configurations

It is possible to have more than one configuration. Such case may be the Mongo Connector having one configuration to access a database in one server (username, host, port, etc.) and another one for a different server. When multiple configurations are present it is necessary to provide a name to them so that they can be referenced later.

One configuration, notice that the invoking a message processor it is not required to specify a name for the configuration because there is only one:

<mongo:config host="{db.host}" port="{db.port}" username="${db.username}"
                  password="${db.password}" database="${db.name}"/>

    <flow name="ListCollections">
        <http:inbound-endpoint address="http://localhost:8080/list-collections"/>
        <mongo:list-collections />
    </flow>

Two configurations, when multiple configurations are defined a name for each of them must be provided so they can be referenced later. Notice the name attribute fot the mongo:config element and the config-ref attribute in mongo:list-collections:

<mongo:config host="${db.host1}" port="${db.port1}" username="${db.username1}"
                  password="${db.password1}" database="${db.name1}" name="config1"  />

    <mongo:config host="${db.host2}" port="${db.port2}" username="${db.username2}"
                  password="${db.password2}" database="${db.name2}" name="config2"  />

    <flow name="ListCollections1">
        <http:inbound-endpoint address="http://localhost:8080/list-collections1"/>
        <mongo:list-collections config-ref="config1" />
    </flow>

    <flow name="ListCollections2">
        <http:inbound-endpoint address="http://localhost:8080/list-collections2"/>
        <mongo:list-collections config-ref="config2" />
    </flow>

Note: there is no restriction as to the number of configurations a extension can have.

Restrictions

Some restrictions apply to @Configurable annotated fields:

  • can only be used in classes annotated with @Connector or @Module

  • cannot be applied to static fields

  • cannot be applied to final fields

  • cannot be applied to array fields

Configuration-less

There are cases in which modules do not actually expect any configuration or they can work out of the box with the configuration default values.

Since DevKit 3.3 the config element is now entirely optional when the following conditions are met:

  • The module does not use any @Configurable or if it does they are all options with proper defaults.

  • In the case of connectors, they cannot use OAuth 1.0a nor OAuth 2.0 annotations since those annotations introduce mandatory configuration.