2/4 - Using the SE Wizard of NB 6.0...

Tags: OpenESB, JBI, Integration, enterprise bus

In my previous entry I talked about the creation of an XACML service engine. Now, this is the first step. Use the SE wizard that is provided with the OpenESB version of netbeans 6.0 . Why use the wizard? Well, a lot of the code when creating the SE will always be the same. So using a code generator makes sense. Here a few of the perks I found by using the wizard:

• All the NMR interface is already coded.
• Only need to code in the placeholders.
• The WSDL interface is complete enough.
• The code is multithreaded in nature (and multi-SU friendly)

I found a few things that may help you if you want to follow the same development path:

1. Before you start, you will need to know the JBI spec. This may sounds annoying to some, but remember that what you are doing is actually working in the hearth of the beast. If you haven't done so, there is two pieces that will be required reading for you. The JBI specs, and the source code the OpenESB will generate for you. Of course, reading its documentation may help too and you may even be able to skip on reading the specs first! But I have to confess, I was not that lucky... This is all assuming that you know your way around netbeans, Web Service and other accompanying technologies. This may sound like a lot, but most JEE folks already know a lot of that stuff.

2. Pay attention about the fields the wizard will provide you. In this case, I want to use sun-xacml-engine for the project name. Of course, like a lot of developers I used a name like test1. This got me into having to change the constant values in places I was not yet ready to do... So, choose your names carefully! Also, note that the component's name is used to do the connection between the components. So, while eventually this will need to be governed in some way, for now, it is up to you to ensure that your own components wont clash between themselves.

3. The wizard actually generates a full blown XSLT SE. So, when reading the code, you are actually reading a fully functional SE. This also means that the SE you are creating using this wizard can't be considered a new piece of code from a development standpoint. It is mostly a refactoring effort. See the documentation as I have mentioned in step 1 will help.

4. So by now, you know at least a bit, Web Services, J2EE, JBI (Spec and OpenESB implementation), and the source code that is generated by the wizard. Now were ready to modify it.

Implementation Levels in the Service Engine

You can implement a service engine to be more or less useful. I have to admit, the current implementation of the XACML engine is very basic. It responds from a message, evaluate its conformance to the policy of the SU, and returns the response. Different enhancements could include:

• Allow a new API to change the policy files without redeploying SU, indexing on the policy file name.
• Integrate into the JMX management structure.

Structure of the Code of the Wizard

Nothing I write in here will replace the documentation for the wizard. So I'll focus on the work I did to refactor the code it generated into the XACML SE, but I'll touch the high level structure of the code a little bit.

Step 1, Code Generation

Use the <JBI Components/Service Engine> wizard. This will generate two projects. One is the service engine itself, the other one is the JBI deployment plugin, a.k.a. the Service Unit (SU) generator. For today, we focus on the service engine itself.

The code that is generated is divided 4 main packages.

Three packages you will not touch. com.sun.jbi.sample.component.common and its two sub packages, deployment and WSDL. There may be some code modification you would wish to do here, but we'll get to that a little later. The bulk of the work you will be doing will be in the project that has the same name as the service engine you just created. For me, this is sunxacmlengine.

The bulk of the work will go into the third one, the sunxacmlengine. Most of the classes are prefixed <ProviderSE> My guess is, this will eventually be customizable, but for now, you can either rename all the classes or live with it. You'll note that there is a set of files the starts with XSLT. This is because this wizard generates an XSLT engine.

The first the thing you need to do is: Make sure your own code is working ! This may sounds trivial, but in using this wizard we integrate our code with someone else's. Being diligent on our unit testing will cut down time in searching for bugs. The second thing: Use the logger structure. Being able to turn on/off trace flags is invaluable, especially when you'll start doing debugging with multiple SEs.

The second thing you need to do is: Understand what this code is doing ! Yeah, trivial to say, but it can take you a few days to figure it out. That is where reading its documentation will help cut down on the time. For now, we will just state the following:

1. The <ProviderSE>MessageExchangeHandler is where the call to your service will be. This is the main decoupling point.
2. One of the rules for me of refactoring, is to leave no sent of the previous incarnation behind. So, I changed/renamed all the XSLT into XACML in the code, variables, text and comments. Just a personal pet peeve. This doesn't change anything about the quality of the code, it just makes it easier to follow, once your in maintenance mode. And it does avoid some questions...

Step 2, Code Replacement and Adding the functionality

• Like I have mentioned, I changed the XSLT for XACML in the method names, object names and so forth. Since this doesn't change any of the functionality, but makes the maintenance cycle easier, I would recommend it, but I will not go over the details.
• When going over the IDE's warning, you see a fair amount of @override recommendation. You can either ignore it, or bite the bullet and do the changes.

In ProviderSEMessageExchangeHandler.processInMessageOnProvider(InOut...)

This is where the message is being processed, so it makes sense that is where you will need to change the code behavior.

1. Here there is two places where we changed the code. First, we configure the XACMLService with the policy file that corresponds to the service name, operation. Using this structure provided by the wizard, we can support multiple services/operations in a single SE. These services/operations are defined in the SU.
2. When the policy file is found and considered a proper file, we then proceed with the evaluation with the evaluatePolicy method.

In WSDLProcessor.isWSDLFor()

The WSDLProcess is a class that is generated for us, and that we are not supposed to touch... But I got into a situation where the method would return me false and I didn't understand why. So, I added the following traces (see the source code for the complete method). I didn't use the logger structure because I was not available to this class, and honestly, when this error happens, it is problematic enough to always get logged. BTW, for a good description of the logging structure go see Mark White's blog on this.

In XACMLService.evaluatePolicy()

This class is my wrapper to the XACML jar file that was created by Sun Labs. In here is where I make the bridge between the <jbi> format and the <xacml> format. The following piece of code is the first section of the evaluatePolicy Method. So, here we see the part where the message is extracted from the exchange. From there, the message is walked down from the <jbi.message> to the <xac:Request> which is the top part of the XACML Request. Now, this is not very "document-oriented", but it got the job done. A more robust way would have been to allow for walking down the xml tree up until the XACML Request member is found.

In the following segment, the namespace is removed on all nodes (a limitation of the XACML processor), and the evaluation is requested.

And lastly, the response is returned. This is where the document is recreated from the outstream.

Step 3, Anything else needs to be done?

Well, yes and no. There is one file, called the xstlmap.properties, that I renamed xacmlmap.properties. This file is to be defined in the JBI deployment plugin, but it is to be used by the SE. In short, this is where you map services/operation to a specific policy file.

Step 4, Compile, Deployment and Test?

Yes, this is normally what we would do. In fact, the SE wizard generates a section to put our testing code. But I won't using? I figure that to test the SE, I'll need an SU. And the JBI deployment is there exactly for that, creating a JBI Module out of the SU definition. Consequently, the testing of the SE is differed until the JBI deployment module is done. For this, I kept the JBI deployment module intelligence to the minimum that the wizard generated. So, I'm testing with a UI based SU. In a production environment, I would usually go back and create a way to chain multiple SU testing structure. This would involve the SE test code, but also some open esb scripting. I'll keep that for later... For now, I simply use the IDE to compile and deploy this into the Glassfish installation that came with the open esb download. The logs tell me that this has gone fine.

Step 5, the JBI Deployment Module

Sorry, this will be the subject of another weblog entry...

Posted at 12:00PM Dec 04, 2007 by sergeblais in OpenESB  |  Comments[4]