The Mule 4 SDK: Intro

The Mule 4 SDK: Intro


The Mule SDK allows Mule developers to create modules that can be used just like any other module in Mule (e.g., HTTP module, Java module, Validation module). Put another way, the Mule SDK allows Mule developers to extend the Mule runtime to meet their needs in a way that is idiomatic to how Mule already operates. This is a good thing because it can greatly reduce the friction of learning a custom module.

Typically, the result of developing a module is a new connector, operation (e.g., validation), and/or DataWeave module, but you can also develop routers, scopes, and other things as well. I'll get into most of these throughout this series of blog posts.

Before you start developing your first Mule module using the Mule SDK, it's important to know a few things. The purpose of this post is to cover what the Mule SDK allows you to do, and what you need to know before you start development.

Why would you develop a Mule module?

There are many reasons why you might want to develop a Mule module, but it's difficult to come up with a single reason. That's one of the primary purposes of this blog series: by learning how to work with the SDK you'll be much more likely to identify areas where you should leverage it. Let's check out some examples.

Perhaps you have a Java library that you'd like to expose in a way that will be immediately familiar with Mule developers. To do this, you could create a Mule module containing a bunch of operations you can access via a Mule XML configuration file. If that library is something you'd like to have available to DataWeave, as opposed to a configuration file, you might create a DataWeave module. Perhaps you don't want to pick one or the other and you want to support both in the same code base. That's possible, too.

Maybe there's a system you need to get information from but it uses a proprietary networking protocol. The vendor provides a JAR that interfaces with the protocol for you. In this situation you'd want to use the Mule SDK to create a new connector. Like with all Mule modules, once it's created you can then share it across your organization to be used in other Mule apps.

What is the Mule SDK?

SDK stands for "software development kit." You might be curious about what the strict definition of an SDK is, and how an SDK is different from a traditional Java API like the one exposed by java.time. While this knowledge is not a prerequisite for understanding when and how to use the Mule SDK (and beyond the scope of this article), there is a great article about the difference here.

An important note about the Mule SDK is that has two parts. It has a Java SDK, and an XML SDK:


They're both used to create modules that extend the Mule Runtime, which begs the question: when should you choose one over the other?

Should you use the XML or Java SDK?

The Java SDK is feature-rich, providing a means to create inbound connectors, schedulers, routers, DataWeave modules, scopes, etc. If you can think of something you'd like to build for Mule that isn't currently implemented, chances are the Java SDK will be able to help. The Java SDK gives you a lot of control over the module you're developing. However, like most things in life, all of this control comes at a price. The learning curve for the Java SDK is significantly steeper than the XML SDK. In addition to this, if you were to develop the same module with the Java SDK and the XML SDK, you'd likely find that you could develop the module with the XML SDK much more quickly, and with fewer bugs. This is because the XML SDK allows you to leverage all of the existing modules in the Mule runtime. You have access to Database operations, HTTP calls, DataWeave, the File module... everything!

Given this, my recommendation is that you use the XML SDK unless you need features provided by the Java SDK. You get the benefits of a more shallow learning curve, the ability to leverage all of the existing Mule modules, and you're less likely to introduce a bug when doing something that would be trivial with a Mule module (e.g., issuing an HTTP request). In other words: you greatly reduce development time when compared with the Java SDK. You also reduce the amount of time developers will need to spend understanding your code should they need to modify it. This is partly because when using the XML SDK, you will develop your module in a single file. When using the Java SDK you will likely develop your module over multiple files. The developer modifying the module will need to understand how the files interact, which means they will need to have a fairly solid understanding of how a Mule module with the Java SDK is typically structured. Typically, modules implemented with the XML SDK do not require Java or traditional programming expertise, and can therefore be developed and maintained by a wider audience.

To give you an idea of how much more feature-rich and complex the Java SDK is compared to the XML SDK, consider that the Java SDK documentation spans over 75 web pages, while the XML SDK documentation is contained in a single page (partially because all the available modules are documented elsewhere).

Here's a convenient list of pros and cons so you can make an informed decision on whether you should use the XML SDK or Java SDK when developing your Mule module:


Feel free to add any pros and cons you've found in the comments sections below.

Choosing the SDK Version

After you've decided which SDK you're going to use, the next step is to choose which version of the SDK with which you will build your module. This is a very important decision, and perhaps counter-intuitive to how most developers would approach this.

When choosing what version of the SDK to use, you should select the lowest possible version that fits your needs. Why? Because every new version of the Mule Runtime is compatible with past versions of the SDK, but newer versions of the SDK will not be compatible with previous versions of the Mule Runtime (if this is confusing, the images ahead may help). By utilizing the lowest possible version, you're maximizing the amount of Mule Runtime versions your module can work with. Here's a visual representation:



Once you start developing using SDK 1.1, you can no longer use your module on the 4.0 runtime. Important to note is that no matter what SDK version you pick, it will always work with new versions of the Mule runtime. How is that possible?

The Mule Extensions API

When you develop a Mule module using either the Java or XML SDKs, you're building on top of something called the Mule Extensions API. This API is a well-defined contract for how modules can interact with the Mule Runtime. The SDKs themselves provide a convenient layer of abstraction over the Extensions API so developers do not need to get caught up in the details of how to use the API.

Conceptually, it looks something like this:


This API is what allows a module developed using SDK 1.0 to function in Mule Runtime 4.x. Features are added to the API as the Mule Runtime supports them, but features are not taken away.


The Mule SDK allows developers to extend the Mule runtime with new features. It is made up of two different SDKs, the Java SDK, and the XML SDK. Before you start writing a Mule module you should decide which SDK you're going to use, and which version of the SDK you should use. The decisions you make here will be highly dependent on your particular use case.