Announcing DevKit 3.1: easy OAuth, API docs and more

December 21 2011

2 comments 0

Less than a month ago we released the 3.0 and we are on a roll here. Just in case you are jumping onto the bandwagon a little late, the is a tool for authoring Mule extensions. The model is quite easy. First you write a POJO, then you annotate your POJO with Mule concepts and then when you run on the code you authored it will generate all the needed boiler plate code including a Mule-compatible schema. Sounds exciting, isn’t it? Unfortunately this blog post is all about whats change since the last release, but if you want to learn more you can do so at our website here.

We added several features in this release but to keep this blog post short I will cover just a few of them.


Mule Services Injection

It has been brought up over and over again by several of our users the need for some extensions to access certain Mule features, whenever that is raw access to the MuleContext, or very specific need like accessing the expression manager.

This time around we introduced a new feature in the DevKit that allows the injection of several services into your module without having to worry about how to get to them. Some of them can be easy to access others like the object store manager are buried deep inside the Mule registry and can be a little hard to find them. Regardless, this new feature makes it easy to access all of them in the same fashion.

The following is an example of how to inject an ExpressionManager:

this one is about gaining access to the MuleContext

There are 12 services that can be injected into a module. All of them are listed here.

Custom Content in Generated Docs

We added the ability to include custom docs (in Markdown format) as tabs in the generated documentation. Each markdown file represents a tab at the top (there is no limit to the number of tabs aside from screen real state). You need to add the following command line to our Doclet:



The first argument is the ID of the tab, the second is the Markdown file, and the third is the title of the tab.  Each generated tab will be added after Install Guide but before the Java API Reference.
The following is full extract for a JavaDoc config in our Salesforce cloud connector:

New OAuth Dance Message Processor

It used to be that when you called a generated message processor that required OAuth, the dance would automatically start. We have changed this behavior. It generated a lot of confusion within our user base and the reality also was that it wasn’t as flexible as we would like. So, the way it works now, is… that once you annotate a module with an OAuth annotation a custom MP called authorize will be created. That MP sole purpose is to do the OAuth dance.

If a DevKit-generated MP is called before the module is authorized a custom exception (NotAuthorizedException) will be thrown.

Authorize MP must be called from a message originated at an HTTP inbound-endpoint. This is due to OAuth mechanics and we made improvements in the documentation to state so.

OAuth Callback Customization

The DevKit OAuth implementation shares its codebase with our HTTP callback functionality, which lead to the creation of an element (http-callback-config) in the module configuration which could be used to customize the OAuth callback. The two concepts (HTTP callback and OAuth) were not properly linked and not many users know that one change the other behavior. The lack of proper documentation and the naming of element were at fault here.

We break backward compatibility to fix this one. We renamed the generated element  to oauth-callback-config (instead of http-callback-config) to make it more self-explanatory and on top of that we know generate substancial documentation on how to use it including (but not limited to) iON specifics.

Saving and Restoring OAuth State

The authorize MP that we mentioned earlier changes internal state in the connector. That state is kept in-memory and if the instance of Mule (that the connector is running on) ever shuts down then that state is lost and the whole authorize process needs to be restarted.

Recognizing that there is no one-solution that would fit all, we made a conscious decision not to save and restore state our selves. Instead, we provide hooks to attach custom MPs that can handle the saving and restoring.

Let’s go step by step on how this works.

As you can see from the previous example save-oauth-access-token is a message processor chain inside the module config element. That is the chain that will be responsible for serializing the OAuth state. The DevKit will invoke (once the dance is complete) using the same exact Mule event that was used to trigger authorize plus two new INBOUND properties. Those properties are: OAuthAccessToken and OAuthAccessTokenSecret.

How those properties are stored or where is up the user of the connector, the user can either use an file:outbound-endpoint and serialize them to disk or use our Mongo Cloud Connector and save them to a Mongo collection. One could even use Redis.

Restoring the access token happens before the dance is attempted. It works the exact same way as save-oauth-access-token but in reverse. The restore chain that can be configured at the config element and when its done executing the response of that chain should contain two OUTBOUND properties with OAuthAccessToken and OAuthAccessTokenSecret.

The following is an example:

They can be used in combination for example we our recently released ObjectStore module to save and restore the access tokens from a persistent store.

What’s Coming Next?

So much! I cannot disclose yet but I can tell you this: We are just getting started. I would recommend that you follow us closely because what’s coming is going to blow your mind.

You can keep track of us at @mulejockey in Twitter .

As always you are welcome to contribute back your thoughts either here or in our forums.

See you next time!

We'd love to hear your opinion on this post

2 Responses to “Announcing DevKit 3.1: easy OAuth, API docs and more”

  1. Where can I find a working example code? doesn’t look updated for the DevKit 3.1.

  2. there is a lot of changes in this area, a heads up of some changes token names are invalid (or may have changed against the current xsd)

    – the article has linkedin:save-oauth-access-token
    it is now linkedin:oauth-save-access-token

    – it now linkedin:oauth-restore-access-token and not linkedin:restore-oauth-access-token

    – and the object store uses “value-ref” and not “value”