Defining Parameters

Parameters must not be of byte[] type. Use InputStream instead. Mule automatically transforms any byte[] parameter value into an InputStream.

String parameters are perfectly fine, but always consider what are the odds of the assigned values to become larger than 4 KB. If that’s a possibility, then the parameter must be an InputStream instead and use an InputTypeResolver to provide metadata on the media type that’s expected.

Required parameters must always be in the default group and tab, and must be the first to appear in the generated UI.

Required parameters must be placed on the main group and tabs so that the end user can see at all of them at first glance.

Optional parameters should not be placed in the main view. This is to not overload the view with too much content that in most cases won’t be configured by the average customer.

Exceptions:

Optional parameters of Collection or Map types must be annotated with @NullSafe to guarantee that null values are avoided by automatically providing empty instances instead.

When talking about security parameters, it’s important to distinguish between actual security parameters and connection parameters. For example, username and password could be thought of as security parameters because they’re used for access control. But in reality, you can’t establish a connection without those in the first place, so they are also required connection parameters.

As explained earlier, required parameters must also be shown first, but in which order should they be listed? The same thing applies to optional parameters: we know they go after the required ones, but in which order?

Parameter ordering considerations:

When working on Java based connectors, the connector must not expose types from external libraries.

For example: if is being used the MongoDB Library to create a MongoDB Connector, the result of the queries are represented as BSON objects. This could never be the output or input of an operation because of many reasons:

For optional parameters that don’t specify a default, the @Example annotation should provide an example of a valid value. This increases the UX of Mule developers to be more sure about the kind and structure of data that they should configure.

The SDK and Studio makes a best effort at transforming the parameter’s name to what is shown in the UI, but sometimes this is not enough. A name that makes sense on the connector’s DSL maybe doesn’t make sense in the UI and vice versa. For these cases, you should use the @DisplayName feature.

Also because the parameter name used on the extension is also the one used for the DSL (XML) and the display name, once the connector is released, this name can’t change since that would break backwards compatibility. The @DisplayName annotation is also useful in those cases to change the name shown in the UI without affecting backwards compatibility. Lastly, keep in mind that unlike Java or the Mule DSL, the @DisplayName does accept spaces.

By default, parameters accept expressions. There are some cases in which this default should be changed.

Disable expression support when it doesn’t make sense to support expressions in the context of a configuration or connection provider parameter, for example, the port number in which to place an http listener. It doesn’t make sense for the port of an inbound listener to be changing each time mule processes a message.

Make the use of expression mandatory when there’s no use case in which that parameter is to take a fixed value. For example, an aggregator’s group identifier.

All parameters have a matching Javadoc that explains the purpose of that parameter and its semantics. Sometimes, that explanation can be quite lengthy. For those cases, it’s a good practice to use the @Summary annotation to provide a one liner description of the parameter. It’s ok if this summary doesn’t fully cover its meaning and purpose. It’s just intended to be a quick one liner that the UI can turn into a tooltip.

Sometimes a configuration object defines a parameter that should globally affect a connector. However, some components might want to override that parameter.

The canonical example of this is a charset encoding. A file connector could define the encoding to use at a configuration level. However, in the context of an application, one might have one specific flow in which a different encoding should be used (even though the rest of the application might still use the one specified in the config). The @ConfigOverride annotation must be used in these cases. This is not only a matter of simplifying your own code (as opposed to manually checking for an override and defaulting to the config one instead). The @ConfigOverride not only does that automatically, but in Studio also overrides the config parameter allowing the UI to surface this accordingly.

Configuration Overrides are explained at length in this article.

Here’s an example of how the hinting features can interact together

One use case for a POJO parameter is when the same set of parameters constantly repeat across several components (either operations or sources). The Java good practice would be to put those together into a single reusable class.

For example, consider the Aggregators module, in which all group-based aggregators require a set of common parameters. This example creates the GroupBasedAggregatorParameterGroup class:

This object would then be used as follows:

This approach however introduces some problems:

Therefore, modifications to it, or even the decision to replace it with something else, results in a backwards compatibility problem.

All of the these issues can be traced to one root cause: the module’s structure should not reflect nor be affected by the nuances of the programming language being used (notice that we wouldn’t be having this discussion if the XML SDK would be used here instead).

To be able to still maintain parameters in a POJO without generating the side effects in the generated module, use the @ParameterGroup annotation:

This annotation opens the POJO and exposes its inner parameters, as if they had been inlined as method arguments. As far as the user and the type catalog know, there’s no GroupBasedAggregatorParameterGroup and the operation simply defines multiple String parameters. However, the developer still needs to leverage the Java POJO.

Another use case for POJO parameters is forcing certain parameters to appear as child elements in the Mule DSL. For instance, consider this example from the email connector:

The <email:body> is a POJO that contains the content and contentType parameters. Because the email connector is quite complex, we want the body to appear as a child element in the Mule DSL, for increased readability.

To use a POJO just for this has the same drawbacks as in the prior example, but again, you can use the @ParameterGroup annotation to overcome them:

As you can see, the @ParameterGroup annotation has a showInDsl attribute that can be used to force the DSL to put the inner parameters as a child element.

Another use case is the ability to define a global element (which is not a Configuration) to referenced from another component.

For example, the File connector has the concept of a matcher, which is a set of rules that are used to decide whether a file should be processed or ignored. Matchers can be used in either the <file:list> operation or in any of the message sources defined in the connector.

Because the exact same matcher might be needed in different flows, the connector provides the ability to define global matchers than can be later referenced. For example:

For these cases, it makes sense to define the matcher parameter as a POJO, without the use of the @ParameterGroup annotation. Notice that in this case, having the concept of a matcher being listed in the connector’s type catalog makes sense, since this is not an implementation detail but a core piece of functionality.

There’s one caveat though: for this to work, the class in which the matcher is implemented needs to declare that it is to be used as a global element:

As a summary, here’s a simple flow chart to aid with the decision process of how to use POJOs and parameter groups.