RequestHandlers: at your service!
RequestHandlers: at your service! by Mendix
Sometimes you need a little more than what Mendix gives you. We’re really good at delivering forms, webservices and files that are easily generated, used and configured. But there’s so much more. RSS, custom webservices (no authentication anyone?), how about a REST handler? How are you supposed to do that in the Mendix Modeler? If you’re interested in any of the above, this article is for you.
A couple of years ago we tried running on IBM Websphere, Apache Tomcat and a bunch of other standard webcontainers. We quickly realized that that wasn’t going to really work if you wanted to run Mendix apps properly (these appservers tend to get in the way of what makes Mendix run so well. The exact reasons warrant another blog post but the short story is: running Mendix inside one of these app servers is like buying a Ferrari and then driving it around inside a truck. Sure you can do it but do you really want to?).
However, we did learn a lot about running and configuring apps. One of the things we had in 2.4 (anyone around who’s reading this and has used that version gets a beer from me) was a magical web.xml. You can even read about it here. One of the cool things you could do was map whatever servlet you wanted to whatever URL you wanted. Most people weren’t technically savvy enough to write their own servlets, but it was possible. Sometime during the 2.5 development process we decided to junk the whole web.xml servlet deployment method (in fact, we dumped servlets entirely because it was just useless overhead), but we needed to include some mechanism to allow the runtime to map some type of requesthandler to a URL, such as /xas/, /ws/ etc. This became the addRequestHandler method in the Core API, and this is the exact same method that the runtime actually uses to map /xas/, /ws/, /file/ and /ws-doc/.
So this is all fine and dandy, but how does this help you guys? Well, this Core API method can be called at any time to create a new url-to-requesthandler mapping. (Although it’s generally recommended to call it in a startup action so that you’ll know that it’s always available.) This requesthandler can do whatever you want. You could write a cool hello world handler:
To register this handler, put the following code in a Java action that you call from your startup Microflow:
And then simply surf to http://localhost:8080/hello/ to view your requesthandler!
Or you could create a generic app that’ll let you access a particular Microflow or form based on the URL, such as the Deeplink module in the AppStore.
A slightly more complicated example would be a REST handler:
This RequestHandler takes a path (depending on where you’ve registered it) and takes the last part of the URL. In the example above, we use it to search for a domain Entity “Person”, in the domain model “MyFirstModule”. We query for the Name attribute, but you could change the code around to suit your needs. It then takes all member values and converts them to a JSONObject to send over the wire. This example shows how easy it is to set up relatively complex and cool pieces of functionality that allows you to extend and integrate your apps with third party clients easily. The important thing to keep in mind, though, is that by adding RequestHandlers like this to the Runtime, you’re also immediately bypassing important parts of Mendix that you now have to worry about. For instance, the above example runs everything using the System Context, thus allowing anyone to read any user from the outside.
Note that although this is all pretty easy to do in Java, you should take care to check whether any extra configuration is needed for your deployment environment. IIS, nginx and apache all need to be set up to proxy the /yourcoolrequesthandler/ URL through to your app. If you happen to host it on the Mendix custom cloud, you can file a ticket to have them set this up for you.
If you are already using custom RequestHandlers, let us know in the comments below! We’re certainly interested in the use cases.