Friday Jun 20, 2008

RESTful is Rastafarian thinking!

I am back from The Server Side Java Symposium (TSSJS) that occurred in Prague. I was invited to speak about JMX, Monitoring, Management and Troubleshooting in the JDK 6 platform. I spoke 1 hour and enjoyed the conference (only 2 days, I had to leave Prague before the end of the conference).

Some people went to me at the end of my talk with questions related to the ability to persist information that Visual VM or JConsole tools are exposing. My next post will cover this topic in details and should come with a Conf Dumper helping you achieve this use case.

TSSJS is a fantastic conference (it was the first time that I participated). Really it is. It is full of excellent talks from free and open minded speakers. It has been a delight to attend (more particularly) Ted Neward and John Davis talks.

I had already planed to leave Prague not before the promising Ted's REST and SOAP: Arch Enemies or BFF? presentation. And I have been well advised to do so...

Ted has simply presented us the Genesis of the Web Services... From the first second to the last one, it has been a flow full of excellent comparisons, well chosen anecdotes, funny paradoxes, well targeted criticisms, technical excellence, hope, joy, anger,...

The paroxysm has been reached when he has compared Restful with the way Rastafarians see human/business relationships. He described such relations as "cool point to point ones, no intermediary (notion that doesn't exist for Rastafari), nothing expected back, simply giving... exactly like an HTTP URL..." I can't re-transcript the demonstration but it was so true...

When he ended his talk by "Questions?", it has been, for me, like your grand father, seated nearby the fire camp, ending counting you his famous frightening story...

Ted had transformed a technical debates onto a Computing Tale...

Furthermore, I fully adhere with his analysis. He summarized the novelty of the REST approach by "the ability to identify values of your software thanks to URL". This is exactly what I have tried to describe in the 2 parts of the RESTful Access to JMX Instrumentation discussions (and more precisely by the notion of Well Known URL).

So to conclude, if one day you have the chance to go to the TSSJS, please do so, you will be not disappointed.

Really not.

Jean-Francois Denise

Tuesday Jun 03, 2008

RESTful Access to JMX Instrumentation, second part

This post is an answer to William Vambenepe who recently wrote an interesting post related to JSR 262 and the REST access to JMX I discussed a few months ago. William shows some interest in the REST adaptor for JMX and asks for the next steps. Here they are...

A bit of context

The REST approach is a possible solution for interaction with JMX agents mostly due to the fact that monitoring and management is increasingly present in our systems at a much higher level than it used to be.

The data exposed tends to be directly understandable. There is no need for complex processing on the client side to understand what is going on. Why is this possible? I think that it comes from the fact that the new trend in Monitoring and Management consoles (consoles such as JConsole or Visual VM), is to display "raw" data.

This raw data is interpreted by only viewing or displaying it graphically. It makes MBean designers think more and more about their MBean interfaces as human-readable APIs. My colleague Daniel Fuchs shows the limits of this approach in a recent blog entry. But I also remember Daniel saying a few years ago that people will soon start to design MBeans to comply with JConsole's capabilities. I think that he was absolutely right. This is what is emerging now.

So it seems an appropriate time to build an HTTP based access, along standardized lines, to allow web designers to benefit from this valuable management information by making it possible to embed it directly in Web pages.

My previous post put in place the foundations of the REST adaptor for JMX agents. This post covers the next features that should be added in the near future. I write “should be added” because I would like to hear your reactions to them before I add them to the current implementation. Please let me know whether or not they will meet any of your requirements, so that we can discuss how to improve them. The adaptor will be much more valid if it answers the needs of the community.


HTTPS and Basic AUTH seem natural choices. Nothing special, simple and safe. They should cover most cases. Is Basic AUTH enough or do we also want to offer “mutual authentication”, to allow the server to authenticate clients based on client certificates? What about access control? We could easily add access control based on JMX permissions as is done today when you provide an access and password file when starting the JVM.

Snapshot of values

Currently we can't retrieve a complex MBean attribute atomically. Say that we want to retrieve all the values contained in the HeapMemoryUsage attribute of the Memory MBean. This attribute is of type CompositeData. The well-known URLs (that point to plain text data) associated to this attribute are the following:





Currently, we can only retrieve committed, init, max and used individually.

If we introduce a new query parameter named capture, we could ask the adaptor to construct a frozen view of an attribute value (or more generally of a sub-tree). We could then retrieve the values located in the snapshot.

In practice:

GET http://curcuma:9999/rest/jmx/java.lang:type=Memory/HeapMemoryUsage?capture=mysnapshot1

Returned resource :


The returned URLs reference the captured data. We now have the freedom to analyze the values outside the ever-changing real world. This pattern could also be applied higher up in the tree (at the MBean level, for example) to create a snapshot of multiple attributes.


We could map from JMX Notifications to atom feeds. This could be a good approach. However, here I would like to keep it simple and carry on with the resource-centric approach and try not to break the model. I would like to make the number of required technologies as minimal as possible. Relying on HTTP(S) with a bit of HTML/XML should be the maximum we allow ourselves... ;-)

So, how can we proceed? JMX MBeans are the event sources. Clients generally subscribe to MBean notifications then pull notifications from the MBean server. Pulling seems very appropriate in our web context. Pushing has never really worked.

If you want reliable, zero-loss notifications then you should stop reading this post. You are going to be frightened by what I am about to say. In JMX we generally see notifications as an unreliable way to receive information. You can't count on a high level of reliability. Lost notifications are not common but they can occur. Once you know the context in which notifications are handfed, you can design an event system that copes with it. Making your MBean re-emit notifications until an acknowledgement comes back can be a decent solution.

If we agree with what has been said previously, we can attach a rolling buffer to each MBean resource that contains the last n emitted notifications (10 is a possible default value). This buffer can be pointed to using the URL scheme we have already put in place.

Here is an example URL for retrieving notifications:


If events occur, the list of emitted notifications is returned in the GET response.

       Notification 1 
       Notification 2
       Notification N

Representation of notifications

A Notification is a complex type for which we can define a set of well known URLs. By nature, a notification is a snapshot of data, and its URL contains the information that makes it unique. The JMX API doesn't guarantee a unique sequence number. The emission time seems a better identifier.

  <li>http://curcuma:9999/rest/notifications/jmx/java.lang:type=Memory/25_12_1970_12_00_00/userdata/<...possible path if complex type></li>
   ... user data URL continue if complex content.

Custom notifications

If the emitted notification is custom-built, and some getters are exposed, then the added field is discovered and exposed. For example, the following notification defines a getPriority field:

public class PriorityNotification extends Notification {
  public int getPriority() {

This will be returned as follows:

 <li>http://curcuma:9999/rest/jmx/notifications/java.lang:type=Memory/25_12_1970_12_00_00/userdata/<...possible path if complex type></li>

Filtering based on emission time

You could argue that only keeping 10 notifications is insufficient and that all notifications should be stored. OK, but in this case, we would like to be able to filter out the old ones. That can be done by adding a since query parameter when getting notifications. For example:


We just need to agree on a date format.

Notification retrieval scope

This approach allows us to express a homogenous "retrieval scope”. By choosing a location in the tree (a URL where we can get notifications), we can retrieve notifications emitted by :

  • MBean servers (all MBeans, and potentially all attributes too, could add a JMX pattern to narrow the scope)

  • MBeans

  • MBean attributes (equivalent to AttributeChange).

  • Information inside an attribute value (namely, is it a real scope, and do we want it?)


It seems that things are still being kept simple here without compromising the JMX technology's philosophy. Or perhaps not, and you think it is already too complicated and I should stop mining this seam... just let me know and I will down tools! ;-)

What do we have on the plate for the next post? Setting attributes and invoking MBean operations. If you have some ideas, please let me know. They are tough ones!


Jean-François Denise

Friday May 23, 2008

Use VBScript to cheat at poker with JMX!

This year at JavaOne Eamonn and I presented during our technocal Session, where we stand with respect to JMX. Eamonn covered JMX in general and JMX 2.0, while I covered the Web Services Connector for JMX. At the end of the talk, we performed a demo named “CSPoker, JMX Technology, Java VisualVM and WinRM at the JavaOne Tournament's Final Table”. We linked together a set of JMX related technologies to offer, in an original Online Poker Web Site use case, an interesting setup highlighting the power of JMX (here's a PDF file of the demo architecture) .

At the end of the talk, some people asked me some questions about the WS-Management access to JMX we had just demonstrated. More details on the WS-Management to JMX interoperability can be found in this article.

Here, I am providing some details on the actual script used during the demo. This script automates the Poker Engine monitoring and management tasks. It first registers to listen for JMX Notifications exposed as WS-Eventing notifications. Each time a “Poker table joined” notification is received, it checks that the IP address from which the player joined is not already known to the system. If an IP address is already known, it means that another user already joined from the same host.... which is very bad if you want to avoid the same player using multiple identities....

When such a “bad user” is detected, the script ejects all the players that joined from that machine.

Intialisation of the WS-Management access

dim wsmanObj
set wsmanObj = CreateObject("WSMAN.Automation")
dim objConnectionOptions
set objConnectionOptions = wsmanObj.CreateConnectionOptions
dim iFlags
iFlags = wsmanObj.SessionFlagUseNoAuthentication
dim session
set session = wsmanObj.CreateSession("http://localhost:8080/admin", iFlags)

At this point, you have a WS-Management proxy (the session object), that allows you to interact with a JMX Agent attached to the Web Services Connector.

Subscription to the MBean notifications

The MBean we want to subscribe to is named : cspoker:type=CSPokerControl

Because the WS-Management session doesn't offer a nice API for subscriptions, we need to construct the subscription invocation request using the “all purpose” invoke method :

Dim reply
reply = session.invoke("", _
"", _
"<wse:Subscribe xmlns:wse=''>"_
& "<wse:Delivery Mode=''/></wse:Subscribe>")

At this point we have sent a WS-Eventing subscription request (in PULL mode, meaning that the client will send a request to pull notifications from the server) and received a response. The response contains the WS-Eventing context to be used to retrieve notifications.

Retrieving the Eventing context

To get the eventing context from the response, we need to make use of the VBScript DOM library : Microsoft.XMLDOM

Warning : Because namespaces are not handled well in this DOM library, we are trying to discover the Namespace prefix based on our knowledge of the way they are declared (ns<i>). I am not a VBScript expert and would be very interested to know if there is an equivalent to getElementsByTagNameNS using VBScript???

Function findElement(elem, tagElem)
' wscript.echo "Finding Element " & tagElem
 for i = 0 to 15
  set findElement = elem.getElementsByTagName("ns"& i &":" & tagElem)
  If findElement.Length > 0 Then Exit For
End Function

Dim objXMLDoc
set objXMLDoc = CreateObject("Microsoft.XMLDOM")
objXMLDoc.async = False

' Get the Eventing context to use in the next WS-Eventing Pull request
Dim nodeList
set nodeList = findElement(objXMLDoc.documentElement, "EnumerationContext")
dim context 
context = nodeList(0).text
wscript.echo "Subscription Enumeration Context " & context

At this point, the context variable contains the WS-Eventing context that identifies our subscription. This context is to be used to retrieve notifications.

Retrieving the Notifications

This is done by sending a Pull request to the server and providing it the context. The pull request blocks until some Notifications are emitted or the timeout (1 minute by default) is reached. As for subscribe requests, no Pull API is offered. We need to use the general purpose invoke operation. We have written a pull function that handles pull request timeouts properly. When the timeout occurs, instead of exiting the script, the error is trapped and the script continues. Because we expect multiple notifications, the Notification pulling is done in a loop.

Function pull(session, context)
 On Error Resume Next
Dim pullXml
pullXml = "<wsen:Pull xmlns:wsen=''><wsen:EnumerationContext>" & context & "</wsen:EnumerationContext><wsen:MaxTime>PT1M0.000S</wsen:MaxTime><wsen:MaxElements>1000</wsen:MaxElements></wsen:Pull>"
 pull = session.invoke("", "", pullXml)
  On Error Goto 0
End Function

' This piece of script is called in an infinite loop

Dim notifs

 notifs = pull(session, context)

At this point, the notifs variable contains (or does not contain, if the timeout occurred) the JMX notifications in an XML format.

Extracting the Notification content and tracking the cheat

We only do this extraction if the list of notifications is not null. The VBScript DOM library is again used to parse the notifications. Because a pull request can return multiple notifications, we must iterate on all TargetedNotification elements contained in the notification list. A TargetedNotification is an XML representation of a JMX Notification defined by the JSR 262 (JSR in which the Web Services Connector is defined).

In our case, the TargetedNotification/Message XML Element contains the Player name. The TargetedNotification/UserData XML Element contains the IP Address as a string (eg:<jmx:String></jmx:String>)

To keep the IP <==> Player relationship, we use a Map data structure and array. In VBScript, we use a dictionnary (scripting.dictionary Libray)

' Create a Map
dim dict
set dict = CreateObject("scripting.dictionary")
Dim ipArray(10)
Dim arrayIndex
arrayIndex = 0

if Not(isNull(notifs)) then

  set objXMLNotif = CreateObject("Microsoft.XMLDOM")
  objXMLNotif.async = False
  set NodeListNotifs = findElement(objXMLNotif.documentElement, "TargetedNotification")
  WScript.echo "Pull returned " & NodeListNotifs.length & " notifications"

  ' Now that we get the list of notifications, extract the content.
  Dim i
  Dim EventType
  Dim msgObj
  ' Loop over the received Notifications
  For i = 0 To NodeListNotifs.length - 1
      Dim listMsg
      set listMsg = findElement(NodeListNotifs(i), "Message")
      Dim eventMessage 
      eventMessage = listMsg(0).text

      Dim listUserData
      set listUserData = findElement(NodeListNotifs(i2), "String")
      ' We have an IP address
      if(listUserData.length > 0) then
           Dim ipAddress
           ipAddress = listUserData(0).text
           wscript.echo eventMessage & " Joined From " & ipAddress
           if dict.exists(ipAddress) then
              Dim prev
              prev = dict.item(ipAddress)
              if Not StrComp(prev,eventMessage) Eqv 0 Then 
                 dim users
                  users = Array(eventMessage, prev)
                  For Each user In users
                    wscript.echo user & " already connected from same host [" & ipAddress &"], will eject him." '"Type return."
                    wscript.echo "Ejecting player " & user
                    ejectPlayer session, user
                    wscript.echo "Player " & user & " ejected"
              end if
             dict.add ipAddress, eventMessage
           end if
         wscript.echo eventMessage
      end if

Ejecting the player

The function ejectPlayer calls the ejectPlayer MBean operation by making use of the general purpose invoke operation.

Function ejectPlayer(session, playerName)
 dim pokerURI
 pokerURI = ""
 dim xmlInvoke
 xmlInvoke = "<jmx:ManagedResourceOperation name=" & Chr(34) & "ejectPlayer" & Chr(34) & " xmlns:jmx=" & Chr(34) & "" & Chr(34) & "><jmx:Input><jmx:Param><jmx:String>" & playerName & "</jmx:String></jmx:Param></jmx:Input></jmx:ManagedResourceOperation>"
 session.invoke "", pokerURI, xmlInvoke
End Function

Hope that these VBScript extracts helped you understand better how you can use this path to interoperate with JMX.


Jean-François Denise


Monday Feb 18, 2008

Web Services Connector for JMX enters Public Review

The JSR 262 has just entered the Public Review phase. The Early Access 3 of the Connector, that implements the Public Review, can be downloaded from

Specification changes since Early Access 2:

  • PUSH mode supported for notifications. This is specified in the client by including JMXWSDefinitions.JMX_WS_NOTIFICATION_PUSH_MODE_URL in the Map given to JMXConnectorFactory.connect. Some related Map entries on the client and server configure security. A new interface JMXWSCredentialsProvider specifies how the connector server gets the credentials it needs to connect to any given client and push notifications.

  • New JMX types supported for MBean operations: NotificationResult, NotificationFilterSupport, AttributeChangeNotificationFilter, MBeanServerNotificationFilter. This allows the JSR 262 connector to support the new Event Service being defined by JSR 255, which has MBean operations that use those types. We also added support for java.lang.Enum and java.util.Set.

  • Connection identifiers supported consistently with the JMX Remote API (JSR 160) specification. This was already alluded to in the Early Draft 2 but is now formalized consistently.

  • Removed the interface JMXWSManResourceHandler. This was a halfway house between the Connector and Adaptor models. The model now is that for a Connector (client sees the JMX Remote API), the protocol is completely specified and invariable.

  • Some minor reshuffling of static final fields between JMXWSConnectorServer and JMXWSDefinitions.

  • The getMBeanInfo operation is now mapped as a Custom Action. Previously the MBeanInfo was a property of the MBean resource, alongside all the attributes of the MBean. This mix of data and metadata was strange.

  • JMXAuthenticator.authenticate method. The passed Object parameter used to be a String[2]. It is now a String[3]. The third element contains a client certificate in case HTTPS Mutual authentication is enabled (null otherwise).

  • XML Element NotificationLost has been removed from the schema. WS-Management already offers such definition by the mean of DroppedEvents XML element. NotificationLost was a redundant redefinition.

  • The schema has been updated, mostly to reflect the changes above, and some minor refactoring.

Implementation changes since Early Access 2:

  • Leverage of the Metro stack components (as detailed in my previous blog entry) in order to increase interoperability and efficiency of the Connector. We are currencly observing a \*3 increase in performance.

  • Rely on the latest JAX-WS 2.1.3 release.

  • Introduction of an adaptor API that allows you to change the way MBeans are exposed in the WS-Management world (javadoc is bundled in the Early Access 3 auto extractible jar under docs directory).

The document that covers interoperability with Microsoft WinRM tooling (winrm command line, VBScript API and Event Viewer support for WS-Management events) has been updated in order to reflect the Public Review changes.

Feedbacks on the specification can be sent to Feedbacks on the connector implementation can be sent to


Jean-Francois Denise

Monday Feb 11, 2008

Up the Metro stack to JMX Technology: A Wise Man's Journey

Up the Metro stack to JMX Technology: A Wise Man's Journey

What a long trip... We started by driving on the HTTP highway, slid on SOAP, turned left at the XML crossroads, passed over the WS-Addressing bridge, visited WS-Enumeration, WS-Eventing and WS-Transfer, got a bit lost in WS-Management country, discovered that JMX was not so far off, and finally took a rest (but not a RESTful one) in the Web Services Connector... Did we do all that on our own? No, we did it with a set of friends, the Metros, or the high-performance, extensible, easy-to-use web service stack.

OK, I guess you get it. This little journey lists the set of standards that have been pressed into service to expose JMX MBeans as WS-Management resources. Luckily we didn't have to implement them all. The JAX-WS (a core Metro component) and WiseMan (a WS-Management Java implementation) projects have been of great help.

Now Sun has announced that the WiseMan project is to become part of the Glassfish community. So, it seems to be an appropriate time to look at how the Web Services Connector for JMX Agent RI makes use of WiseMan and Metro.

In this article, I will describe how we changed WiseMan to use part of the Metro stack, what the benefits were, and finally how these technologies are leveraged in the Web Services Connector for JMX Technology

Moving WiseMan to the Stack

In 2007, some significant engineering tasks were undertaken in the WiseMan project to bring the benefits of Metro to WiseMan. This section outlines the steps that were needed to make this move a reality.

The details of this technology switch are of interest to anyone who wants to make their existing applications benefit from Metro's features.

From Servlet to JAX-WS 2.0

WiseMan, was, in its pre-1.0 release, closely coupled with Servlet. At the time, Servlet container was the only way to deploy a WiseMan-based application. We decided to add a JAX-WS Endpoint to the WiseMan project and suddenly we found we could be much more agile. Deployments like the Java SE and Java EE platforms became possible. What a change! For example, being able to base our test suite on the lightweight HTTP server bundled with JAX-WS made our lives much easier...

The JAX-WS Endpoint we developed is a Provider<SOAPMessage>. Simply annotating with @WebService was not possible. WS-Addressing makes intensive use of SOAP headers to convey part of the protocol information. To access to such headers, we need full access to the SOAP Message. After some redesigning of the existing code we extracted a WSManAgent Class that is accessible from a JAX-WS Endpoint or a Servlet.

We took this opportunity to switch to the JAXB release contained in Metro.

So we were happy and impatient to move forward. We already knew that the JAX-WS team was working on adding WS-Addressing support and were waiting for it eagerly.

From JAX-WS 2.0 to JAX-WS 2.1

JAX-WS 2.1 comes with support for WS-Addressing. It's a very smart integration. By just using annotations, your Endpoint becomes addressable thanks to WS-A.

The @Addressing annotation that you can use to tag your Endpoint implies that the WS-Addressing 1.0 release is to be used. However, WS-Management requires the use of another release of the WS-A standard, which is a great pity. We discovered that we were not able to leverage this support. We were afraid this was the end of the road, but the JAX-WS engineering team came back to us showing us the Metro specific API. We were not the first customer with a dependency on a Membership Submission and they defined another “non standard but supported” Annotation to express our requirement :

With this annotation added, we removed all the code related to WS-A request-response headers.

So we were happy...but not for long. Our great friends Yves and Sandra of the JMX QA team started to develop some simple stress tests and we started to discover horrible things...

From SOAPMessage to Message

We discovered that 80% of the time spent handling a request was spent in the DOM/SAAJ layer. That's 80% of some big numbers, too...

You remember? Our Endpoint is a Provider<SOAPMessage>. This means that when called, a SOAPMessage object is injected and a SOAPMessage object is expected as the returned value. So we were either stuck, or we had to re-implement the SOAP layer to rely on the STAX API, or we were left with our disapointing figures.

Could the Metro API solve this issue? Yes, the Metro API solved this issue. Once again we were not the first customer, etc., etc., etc. As a solution, an efficient implementation of SAAJ, that is very well integrated with JAXB, is exposed as the Message API (located in the package). In order to benefit from its power, you must completely forget all the development you have done on top of SAAJ and rewrite everything on top of this new API. Which is exactly what we did. OK, we re-designed it to make both approaches live together nicely, but we also designed a new API for WiseMan, that was completely isolated from SAAJ. And things started to work much faster (3 to 4 times quicker). The numbers were becoming acceptable, for this kind of XML based processing.

Current WiseMan Architecture

The diagram above shows the different products that are used to build the WiseMan stack on the client and the server. You can see that the WiseMan client stack doesn't rely on Metro, yet. A work-in-progress aims to define and implement such a move, which will greatly improve performance and ease of use.

Improvements for the WiseMan Project

This move helped the project to:

  • Improve deployability

  • Improve alignment and reuse

  • Improve interoperability

  • Improve performance

Deployability, interoperability and performance are the key words of the Web Services Connector for JMX Technology. Based on these new capabilities, WiseMan is becoming the WS-Man implementation of choice for the Web Services Connector for JMX.

When using this connector you are not directly in contact with the stack but you indirectly benefit from the properties you are interested in.

Web Services Connector for JMX Continues Leveraging Metro

This section looks at how the the Web Services Connector for JMX Technology continues leveraging Metro.

Fast Infoset

- "Increase performance!"

- "Increase performance? Hmm..."

Simple, use Fast Infoset! It comes with the stack, it's efficient, it doesn't break interoperability and it's easy to use. We did it and we experienced another big improvement. To enable Fast Infoset in your client API, access the BindingProvider and provide a Fast Infoset key to the request context. For example:

BindingProvider provider = (BindingProvider) port;

Map<String, Object> requestContext = provider.getRequestContext();

requestContext.put("", "pessimistic");

Dispatch<Message> on the client side.

On the client side of the connector, we use the JAX-WS Dispatch class. A Dispatch instance can be seen as an Endpoint proxy that deals with the complete SOAP Message (as opposed to classical JAX-WS proxies that expose a service level API). Since JAX-WS 2.1, Dispatch also handles WS-Addressing. Using Metro specific API, we are creating an efficient Dispatch that is compliant with the WS-Addressing Membership Submission release.

The following code extract shows how to create a Dispatch<Message> for Membership Submission:

Dispatch<Message> port = service.createDispatch(JMXWSConfiguration.JMX_WS_CONNECTOR_PORT, Message.class, Service.Mode.MESSAGE, new MemberSubmissionAddressingFeature(true, true));

Endpoint on the client side

WS-Management defines a way for a WS-Management Agent to deliver its Events in a PUSH mode. This delivery mode implies that the event sink (the client) is itself an Endpoint. We deploy a JAX-WS Endpoint (Provider<Message>) inside our connector client to receive pushed events.

WS-A EndPointReference API

The JMX Web Services Connector RI exposes a non-standard API to customize the mapping of MBeans to WS-Management resources. In this API, we allow customers to hook their customization as low as the WS-Management protocol itself. We needed a WS-Addressing Endpoint reference to expose.

The JAX-WS class offers a standard 1.0 representation that we are internally translating into a Membership Submission via the Metro API (using the class


JAX-WS offers support for HTTP Basic Authentication and HTTPS. We are leveraging both.

HTTP Basic Auth

You provide the credentials to a Dispatcher via the request context. The following code extract shows how to provide your credentials.

BindingProvider provider = (BindingProvider) port;

Map<String, Object> requestContext = provider.getRequestContext(); requestContext.put(BindingProvider.USERNAME_PROPERTY, “user); requestContext.put(BindingProvider.PASSWORD_PROPERTY, “password”);

Server Side Security

The way you secure the server side depends on the container in which the Connector is deployed. For more details about how to use the HTTP server bundled in Metro, check the HTTP server API documentation.

Current Web Services Connector Architecture


Based on this architecture, we performed interoperability testing with WinRM (Microsoft's WS-Management based set of tools and API).

This document sums up the scenarios we are testing.

We didn't experience any problems related to interoperability.


Choosing Metro was definitely the right choice. On nearly all levels it has offered the features we were hoping for. When the boundaries of the standards were reached, Metro-specific API entered the scene and offered a solution. Metro really is ahead of the field in terms of improving performance.

So who is the wise man? The ones who defined such long stacks? No, I don't think so....

But Glassfish could be. Its management and monitoring features are based on JMX technology.


So, by deploying the Web Services Connector for JMX (for which the Public Review specification and Early Access 3 RI will be available mid-February) in a Glassfish Server, all the existing MBeans (such as those defined by AMX, by JSR 77, and by you) are automatically exposed as WS-Management resources.

You can imagine the long journey we went through. Would you want to do this on your own, to expose your tiniest resources?

Be wise and use JMX, let us fill in the gaps!

Jean-François Denise

PS: My sincere thanks to Jitendra and Rama from the JAX-WS team for their help. Special thanks to Stuart Clements, my personnal editor and grammar checker.

Wednesday Sep 05, 2007

WS-Security to secure JMX Web Services Connector

In a previous post, Securing JMX Web Services Connector, I explained how to enable HTTPS when using the JSR 262 RI. Basic Authentication and HTTPS are the basic building blocks on which you can rely to secure remote WS access to your JMX instrumentation. These technologies are very commonly used and are simple to put in place when you need point-to-point security. For more complex architectures, however, where messages contexts contain multiple nodes, HTTPS is not the best solution.


WS-Security, a Web Services standard defined by OASIS, aims to secure communication at the SOAP message level (as opposed to HTTPS, that secures messages at the transport level) in a unified, flexible and extensible way. WS-Security supports partial message signing and encryption, in case you need to encrypt the SOAP message body element and keep the headers non-encrypted; for example, when encrypting credit card numbers or any XML subtrees.

In addition to confidentiality and authentication (also offered by HTTPS + Basic Authentication), WS-Security offers message integrity, thanks to XML signatures. With XML signatures, you can protect your communication against message-tampering.

Interoperability at the security level

Due to the huge number of alternatives you can use when trying to secure your communications, you will generally run into interoperability problems. WS-Security has been designed to offer interoperability while still allowing you to plug in various technologies. The WSIT project on (JavaOne 2007 Technical Session TS-4865 offers a good introduction to WSIT) offers an interoperable WS-\* stack that, along with a full set of other WS standards, integrates a Java technology implementation of WS-Security. WSIT is the solution I have adopted to plug WS-Security into the Connector.

Plugging WS-Security into the JMX Web Services Connector

Now that we have briefly introduced WS-Security and WSIT, let's go back to what really interests us, namely plugging WS-Security into the Web Services Connector. The XWSS project, that is part of WSIT, offers everything we need to enable WS-Security in our context. How is this achieved? Simply because the JMX Connector is a JAX-WS Web Service (compliant with WS-Management but still a classical JAX-WS Web Service) and XWSS works well with JAX-WS.

So, I started by reading a XWSS article on how to add WS-Security to your Web Services on top of the Java SE 6 platform. I then adapted the XWSS sample application to create a simple JMX client and server. I interacted with Kumar Jayanti from the XWSS team to get our two technologies working well together. We encountered some issues with WSIT Milestone 6 (mainly related to the fact that WS-Policy was still linked to a Java EE platform type of deployment, and the JMX Connector was being deployed on the Java SE platform), but these have been fixed in the latest WSIT builds. The next WSIT FCS Milestone should contain all the necessary fixes. The usage of WS-Policy makes for a transparent usage of WS-Security. If you package your WS-Security configuration files properly, you can enable WS-Security on the client side and on the server side without touching a single line of code (see the next section for full details of how to make this work).
To enable WS-Security you simply need to package your application with the WSIT binaries and the WS-Security configuration file.

Building and Running the JMX WS Connector Sample Secured with WS-Security

  1. Dowload the XWSS sample application.
  2. Unzip it. A directory named src is created.
  3. Download the sample JMX Agent file.
  4. Copy into the src/simplejdk6ws/ directory. The ConnectorServer is started on port 8080. In case of conflict, update the file (be sure to update the client code accordingly, see the next section for the client side).
  5. Download the sample JMX Client file.
  6. Copy into the src/simplejdk6ws/ directory. The Connector connects to port 8080. In case of conflict, update the file (it should follow the value you previously provided when starting the server). This client application is a very simple one, it connects to the server and asks for the Default Management domain (MBeanServerConnection.getDefaultDomain()).
  7. The server side security configuration file is src/META-INF/server_security_config.xml. Any message received and response sent is Authenticated, Signed and Encrypted according to the configuration defined in this configuration file. You don't need to update this file.
  8. The c lient side security configuration file is src/META-INF/client_security_config.xml. Any message sent and response received is Authenticated (user Ron), Signed and Encrypted according to the configuration defined in this configuration file. Again, you don't need to update this file.
  9. Download WSIT (which contains JAX-WS).
  10. Install WSIT with the following command:
    java -jar jax-ws-latest-wsit-installer_nightly.jar
    The jax-ws-latest-wsit directory is created.
  11. Create a directory named endorsed. Move jax-ws-latest-wsit/lib/webservices-api.jar into this directory.
  12. If you have not already done so ;-), download JMX Web Services Connector Early Access 2.
  13. Call the following command:
    java -jar jsr262-ri.jar
    The jsr262-ri directory is created.
  14. To build your sample, go to the src directory and type the following command:
    javac -cp :../endorsed/webservices-api.jar:../jax-ws-latest-wsit/lib/webservices-rt.jar simplejdk6ws/\*.java
  15. Download the Java mail JAR file .
  16. Start your server from the src directory. The command should be something similar to the following:
    java -cp .:../mail-1.4.jar:../jsr262-ri/lib/jmxws.jar:../jsr262-ri/lib/wiseman-core.jar:../jax-ws-latest-wsit/lib/webservices-rt.jar -Djava.endorsed.dirs=../endorsed/ simplejdk6ws.Main
    You should see the following message:
    JSR 262 ConnectorServer is ready to serve on http://localhost:8080/jmxws
  17. Start your client from the src directory. The command should be something similar to the following:
    java -cp .:../mail-1.4.jar:../jsr262-ri/lib/jmxws.jar:../jsr262-ri/lib/wiseman-core.jar:../jax-ws-latest-wsit/lib/webservices-rt.jar -Djava.endorsed.dirs=../endorsed/ simplejdk6ws.SimpleWSClient
    You should observe a very verbose output containing the secured received and sent SOAP messages. You will notice that the user Ron never appears in the messages, because the user name is encrypted. At the end, the Default Management domain will be displayed.
  18. You are done. Not a line of code was written, and all that was needed was some configuration and packaging.

Bridging with Authorization

When a request is received, the JMX WS Connector Server looks for the existence of Principals in order to create a that will be used to check the Java platform's permissions. XWSS, after having dealt with Security, creates a Subject that contains all the authenticated principals (X500 certificate, Trusted user, etc.). XWSS makes this Subject accessible thanks to the call SubjectAccessor.getRequesterSubject(context). This call is XWSS-implementation-dependent and other WS-Security implementations are likely to offer their own way. This is why we have added a hook to plug a Subject extractor into the ConnectorServer to retrieve the Subject and make it accessible to the ConnectorServer.

The following XWSSSecuritySubjectExtractor class is an example of such an XWSS-aware SubjectExtractor:

        class XWSSSecuritySubjectExtractor extends JMXWSSubjectExtractor {
            protected Subject getExtraSubject(WebServiceContext context) {
                try {
                    return SubjectAccessor.getRequesterSubject(context);
                } catch (XWSSecurityException ex) {
                return null;

To pass the extractor instance to the ConnectorServer, use the environment map :

        Map env = new HashMap();
        // Provide the extended SubjectExtractor to inject WS-Security Subject
        env.put(JMXWSConfiguration.JMX_WS_SUBJECT_EXTRACTOR, new XWSSSecuritySubjectExtractor());
        JMXConnectorServer server =
                newJMXConnectorServer(new JMXServiceURL("service:jmx:ws:" +
                "//localhost:8080/jmxws"), env,

This is the updated file that contains the Subject Extractor.

WARNING: You need the updated JMX WS Connector RI jmxws.jar and wiseman-core.jar file to use the SubjectExtractor API. You can download these jars here.
Call java -jar jsr262-patch-ws-security.jar to extract the jmxws.jar and wiseman-core.jar files.
When compiling the agent, add both JAR files to your classpath.

So, if one day you reach the limits of the capabilities of HTTPS + Basic Authentication, you should think about using WS-Security. I hope that I have demonstrated to you that enabling it is straightforward. But you should be aware that enabling WS-Security will significantly impact the performance of the WS Connector. The time needed to check security added to the time needed to create and parse a secured SOAP Message (here is an example of a AUTH+PRIV+SIGN getDefaultDomain response SOAP message) makes for much slower client/server interaction.

Enjoy and have fun.


Tuesday Jun 05, 2007

J2EE Deployment of JMX WS Connector

If you are already evaluating the Early Access 2 of JSR 262, you have perhaps a need to deploy the Connector in your servlet container.
A sample, located in samples/servletdeployment directory, shows you how to achieve such deployment. The provided example shows how to deploy the JSR262 JAX-WS Endpoint inside a JAX-WS compliant servlet container. When created, the endpoint gets a reference to the platform MBeanServer (thanks to
If the MBeans you want to manage are registered inside the platform MBeanServer, you can reuse this sample code. Registering MBeans in the platform MBeanServer is something that we encourage.
If you want to attach the connector to another MBeanServer, then you need to subclass JMXWSManServiceEndpoint and provide your own MBeanServer.

Extending JMXWSManServiceEndpoint JAX-WS endpoint

When extending an annotated class (JMXWSManServiceEndpoint JAX-WS endpoint is annotated), the extended class doesn't inherite from the mother class annotations, you need to re-annotate the extended class.
When deploying in J2EE, no JMXServiceURL is provided to the connector (as opposite to the JMX J2SE way of deploying a Connector). You need to provide to the Connector the URL on which it has been deployed. This is done by calling setURL on JMXWSManServiceEndpoint class. This URL is used when translating from MBean ObjectName to WS-Addressing EPR.

Extended class

The following sample code is a ready to deploy extended class that gets a reference to the first MBeanServer found thanks to the class. The URL on which the endpoint has been deployed is hard coded. You can easily externalize it, for example read it from a property file.

import javax.annotation.Resource;
public class ExtendedEndpoint extends JMXWSManServiceEndpoint {
   private WebServiceContext context;

   public ExtendedEndpoint() throws Exception {
       super(new JMXWSManDispatcher(null, 

   protected WebServiceContext getWebServiceContext() {
        return context;

Packaging the connector

You simply need to update the endpoint implementation in the sun-jaxws.xml file and repackage the extended class in a war file similar to the sample.

sun-jaxws.xml file

<?xml version="1.0" encoding="UTF-8"?>
< endpoints
        < endpoint


The simpler way to deploy the Connector is by using the JMXConnectorServerFactory class. This will answer your needs when you want to take benefit of the JAX-WS http server. Direct JAX-WS endpoint deployment is the other way when reusing an existing infrastructure.




« July 2016