[WSO2 ESB | Micro Integrator] Few Tips in Writing a Custom Class Mediator
WSO2 ESB provides handful of mediators to perform the tasks you want. From the WSO2 document mediators in ESB you can find all the available mediators.
But the mediators and the functionalities provided are not limited to the above listed mediators only, when ever you encounter a limitation with the provided mediators, you may write your own mediator in ESB and use them. Now let’s have some high level look into writing a class mediator.
Lets divide this by diving into 3 major steps.
- Implementing the logic we want in class mediator.
- Building | Bundling the mediator.
- Including the mediator in mediation flow.
Implementing the Logic of the Mediator.
As a rule of thumb, the minimum requirement for a class mediators is to extend AbstractMediator class in and implement the mediate method.
To give some idea about this mediate method, MessageContext is the key object to which we will do all our customization and pass it down the flow. You may do number of things to the message in the flow.
- You may simply change the content of the whole message.
- You may change the content type of the message.
- You may define or alter properties of the message.
Please refer WSO2 documentation for all the available HTTP Transport Properties which you can play with. After you master these properties, its just a matter of manipulating the message context and getting all the things done in the class mediator.
Lets have a look at some of the key points that might be needed when writing a class mediator.
How to change the whole message content of the body in custom class mediator in ESB?
Following snippet in the mediation does it
In the above code, the JsonUtil is an dependency from synapse-commons, so make sure to add the following snippet to your pom file ( version might change upon the requirement).
Do I need to define a new object to add logs?
No :). This is not mandatory and you may use the log object instance which comes from the parent class itself.
P.S :- When you add info logs, make sure you enable the info logs in ESB for the particular class, because by default the log level “error” is enabled. You may refer WSO2 Documentation on how to enable the log level via Management Console.
Building | Bundling the custom class mediator.
There are two main ways in which you can bundle your own class mediator,
- As an OSGi bundle.
- As a Regular jar.
As an OSGi bundle
There are plenty of simple articles you may refer to get familiar with OSGi concepts.
When the class mediator is build as an OSGi bundle, we need to deploy it in <ESB_HOME>/repository/components/dropins folder or <MI_HOME>/dropins. We have some key advantages by building the mediator as an OSGi bundle rather than a regular jar. Some of them are,
- We can control the imports to the packages.
- We can restrict certain package imports or certain version of imports.
- We can use certain packages as embedded dependencies.
This option is preferable when we want to control the packages used in the mediator. Following is a sample pom file when you have build as an OSGi bundle, add the dependencies needed.
As a Regular jar
This is almost indirectly same as the first step. In first step we have to build the bundle and copy it to dropins folder but in this method we will be building it as a jar and placing it in <ESB_HOME>/repository/components/lib or <MI_HOME>/lib folder, ESB or Micro Integrator will convert it to a bundle and place in dropins folder on the startup :).
Following is the sample pom file which creates a regular jar, you may include the dependencies you need.
Including the mediator in mediation flow.
After we write the mediator, building it and deploying in ESB, now the question is how we use it in the mediation. This is again very simple, after you add the mediator and restart the server, you just need to add the following snippet to the mediation flow. The below code block include the class mediator to the mediation flow. The incoming context will pass through the custom class mediator and get transformed.
Say, if you don’t need to pass any properties to the mediator, it is simple as follows
When you pass the properties, you may refer them in the mediate method and use them to build the logic based on it. To obtain the properties inside the mediate method, you may use the following snippet of code,
messageContext.getProperty("Name_of_Property");Make sure you obtain the property from the relevant message context. Be it Message Context or axis2 Message Context.
Please refer WSO2 Official documentation [1] and [2] for more information on Custom Class Mediators.
Thank you :)
