Tuesday, June 10, 2008

A Second Look at JMX Web Services Connector: winrm

In A First Look at JMX Web Services Connector (also available as a previous blog entry), I demonstrated using JConsole to access a simple sample server using the reference implementation of the JMX Web Services Connector (JSR-262). In this blog entry, I am going to scratch the surface of using Vista's winrm (a WS-Management implementation) to access an MBean server using the JMX Web Services Connector.

Although I primarily use a Vista-based laptop for my blogging and other "outside of my day job" work, I have not used winrm previously and so much of the challenge for me in working out examples of accessing the JMX Web Services Connector without a Java client was trying to understand how winrm works. In this blog entry, I'll use examples from the thorough Java Management Extensions (JMX) Interoperation With Non Java Technologies document (written by Jean-Francois Denise and Daniel Fuchs) and add some descriptive text to describe how select commands from that document work. Before moving on, I'll reiterate that the this JMX Interoperation with Non Java Technologies PDF includes significantly more background and examples than the two I'm focusing on here.

For my example, I'm running the simple sample server that is bundled with the JSR-262 reference implementation. There is an Ant build.xml file included in the jsr262-ri\samples\simple\server directory that can be run without options to start the server portion. The next screen snapshot shows this:



As I did for running the JSR-262 reference implementation simple sample server, I'm going to use the Command Shell for running the winrm client side portions. It is vital in Vista that you start this shell as an administrator. Running Command Shell as an administrator is demonstrated in the next screen snapshot and is done by right-clicking on a shortcut for the Command Shell and selecting "Run as administrator."



For the client side, it is necessary to configure winrm by using the winrm qc (or winrm quickconfig) command. This and three other commands that should be run to configure winrm properly for the example are spelled out in the "Windows Vista WinRM Set up" section of the JMX Interoperation with Non Java Technologies document.

While in the JMX Interoperation with Non Java Technologies document, refer also to the section "Extras - WinRM Command Line Tool Examples" (toward the end). This section contains many direct winrm (no VBScript required) commands that can be run against the simple server started earlier. This is an easier way to see winrm work as a WS-Management implementation with the JMX Web Services Connector than trying to use VBScript (though the document contains VBScript code snippets as well).

One of the highlighted "extra WinRM Command Line Tool Examples" is the command to obtain MBean Server domain names. It is as follows:


winrm get http://jsr262.dev.java.net/MBeanServerResource -fragment://:Domain -r:http://127.0.0.1:9998/jmxws -a:None


This can appear a little cryptic when not used to winrm syntax. A good starting point for learning to use winrm is its usage information. You can get usage/help information by entering winrm -? (or winrm help) at the command-line. This shows, for example, that the get command used above could also have been expressed as simply “g” and is used for getting or retrieving management information. Likewise, the invoke or “i” is used to execute an operation on the managed resource.

To get more information on the get command, one can enter winrm help get and the usage displayed shows that a RESOURCE_URI should be passed to the get command.

In the example above, there is a clause –fragment://:Domain. The command winrm help switches provides more details on this. The help for –fragment:VALUE tells us that this option is used to specify a portion of the instance XML file. In this case, the value is //:Domain which corresponds to any Domain element in the XML structure (the // is XPath syntax for recursive search and : is XPath syntax for namespace separator).

The winrm help remoting command tells us what the –r option (or –remote) option does. The –r:VALUE command specifies the remote endpoint. As used in the example above it is a URL consisting of four pieces: transport, host, protocol, and prefix.

The final option in the command above is –a:None. The –a (or –authentication) option is used to specify the authentication mechanism used and is None in this example, but could have been Basic, Digest, Negotiate, or Kerberos. More information on the authentication mechanism can be found using the command winrm help auth.

Another useful winrm command that can be used against the JMX Web Services implementation allows us to retrieve the ObjectNames of all registered MBeans:


winrm enumerate http://jsr262.dev.java.net/DynamicMBeanResource -returnType:EPR -r:http://127.0.0.1:9998/jmxws -a:None


Some of this is the same as the previous command analyzed here. The –r (remote) option takes the same URL as before and the –a:None indicates that we don’t want any authentication employed for this example.

A difference in this example from the last one is the use of enumerate instead of get. Using winrm help enumerate provides information on its usage and explains that this option allows application of a filter to the returned results. In this case, one of enumerate’s options (-returnType=VALUE) is set to EPR which means that only end point references (applicable Resource URI and selectors) are displayed. The other two objects are object form (hierarchical presentation of object values) or ObjectAndEPR (a combination of the other two).

I'll show the full output of the most concise of these return types (EPR only) here:


EndpointReference
Address = http://127.0.0.1:9998/jmxws
ReferenceParameters
ResourceURI = http://jsr262.dev.java.net/DynamicMBeanResource
SelectorSet
Selector: ObjectName = java.lang:type=Memory

EndpointReference
Address = http://127.0.0.1:9998/jmxws
ReferenceParameters
ResourceURI = http://jsr262.dev.java.net/DynamicMBeanResource
SelectorSet
Selector: ObjectName = java.lang:type=GarbageCollector,name=Copy

EndpointReference
Address = http://127.0.0.1:9998/jmxws
ReferenceParameters
ResourceURI = http://jsr262.dev.java.net/DynamicMBeanResource
SelectorSet
Selector: ObjectName = DefaultDomain:type=Sample

EndpointReference
Address = http://127.0.0.1:9998/jmxws
ReferenceParameters
ResourceURI = http://jsr262.dev.java.net/DynamicMBeanResource
SelectorSet
Selector: ObjectName = java.lang:type=MemoryPool,name=Code Cache

EndpointReference
Address = http://127.0.0.1:9998/jmxws
ReferenceParameters
ResourceURI = http://jsr262.dev.java.net/DynamicMBeanResource
SelectorSet
Selector: ObjectName = com.sun.xml.ws.util:type=RuntimeVersion

EndpointReference
Address = http://127.0.0.1:9998/jmxws
ReferenceParameters
ResourceURI = http://jsr262.dev.java.net/DynamicMBeanResource
SelectorSet
Selector: ObjectName = com.sun.xml.ws.transport.http:type=HttpDump

EndpointReference
Address = http://127.0.0.1:9998/jmxws
ReferenceParameters
ResourceURI = http://jsr262.dev.java.net/DynamicMBeanResource
SelectorSet
Selector: ObjectName = java.lang:type=Runtime

EndpointReference
Address = http://127.0.0.1:9998/jmxws
ReferenceParameters
ResourceURI = http://jsr262.dev.java.net/DynamicMBeanResource
SelectorSet
Selector: ObjectName = java.lang:type=ClassLoading

EndpointReference
Address = http://127.0.0.1:9998/jmxws
ReferenceParameters
ResourceURI = http://jsr262.dev.java.net/DynamicMBeanResource
SelectorSet
Selector: ObjectName = java.lang:type=MemoryPool,name=Perm Gen [shared-rw]

EndpointReference
Address = http://127.0.0.1:9998/jmxws
ReferenceParameters
ResourceURI = http://jsr262.dev.java.net/DynamicMBeanResource
SelectorSet
Selector: ObjectName = java.lang:type=Threading

EndpointReference
Address = http://127.0.0.1:9998/jmxws
ReferenceParameters
ResourceURI = http://jsr262.dev.java.net/DynamicMBeanResource
SelectorSet
Selector: ObjectName = java.util.logging:type=Logging

EndpointReference
Address = http://127.0.0.1:9998/jmxws
ReferenceParameters
ResourceURI = http://jsr262.dev.java.net/DynamicMBeanResource
SelectorSet
Selector: ObjectName = java.lang:type=MemoryPool,name=Perm Gen [shared-ro]

EndpointReference
Address = http://127.0.0.1:9998/jmxws
ReferenceParameters
ResourceURI = http://jsr262.dev.java.net/DynamicMBeanResource
SelectorSet
Selector: ObjectName = java.lang:type=Compilation

EndpointReference
Address = http://127.0.0.1:9998/jmxws
ReferenceParameters
ResourceURI = http://jsr262.dev.java.net/DynamicMBeanResource
SelectorSet
Selector: ObjectName = java.lang:type=MemoryPool,name=Eden Space

EndpointReference
Address = http://127.0.0.1:9998/jmxws
ReferenceParameters
ResourceURI = http://jsr262.dev.java.net/DynamicMBeanResource
SelectorSet
Selector: ObjectName = com.sun.management:type=HotSpotDiagnostic

EndpointReference
Address = http://127.0.0.1:9998/jmxws
ReferenceParameters
ResourceURI = http://jsr262.dev.java.net/DynamicMBeanResource
SelectorSet
Selector: ObjectName = java.lang:type=GarbageCollector,name=MarkSweepCompact

EndpointReference
Address = http://127.0.0.1:9998/jmxws
ReferenceParameters
ResourceURI = http://jsr262.dev.java.net/DynamicMBeanResource
SelectorSet
Selector: ObjectName = java.lang:type=MemoryPool,name=Survivor Space

EndpointReference
Address = http://127.0.0.1:9998/jmxws
ReferenceParameters
ResourceURI = http://jsr262.dev.java.net/DynamicMBeanResource
SelectorSet
Selector: ObjectName = java.lang:type=MemoryPool,name=Tenured Gen

EndpointReference
Address = http://127.0.0.1:9998/jmxws
ReferenceParameters
ResourceURI = http://jsr262.dev.java.net/DynamicMBeanResource
SelectorSet
Selector: ObjectName = java.lang:type=MemoryPool,name=Perm Gen

EndpointReference
Address = http://127.0.0.1:9998/jmxws
ReferenceParameters
ResourceURI = http://jsr262.dev.java.net/DynamicMBeanResource
SelectorSet
Selector: ObjectName = java.lang:type=OperatingSystem

EndpointReference
Address = http://127.0.0.1:9998/jmxws
ReferenceParameters
ResourceURI = http://jsr262.dev.java.net/DynamicMBeanResource
SelectorSet
Selector: ObjectName = JMImplementation:type=MBeanServerDelegate

EndpointReference
Address = http://127.0.0.1:9998/jmxws
ReferenceParameters
ResourceURI = http://jsr262.dev.java.net/DynamicMBeanResource
SelectorSet
Selector: ObjectName = java.lang:type=MemoryManager,name=CodeCacheManager


The object version and object+EPR versions are significantly longer than this and I won't show them here.

So what's the big deal about all of this? The big deal is that this demonstrates the use of a non-Java client (in this case Windows Vista winrm) to access Java Management Extensions on the server. With the JMX Web Services Connector, you no longer need a Java-based client to monitor and manage JMX-instrumented resources (including the JVM itself)!

2 comments:

jfdenise said...

Hello Dustin,
I have been very impressed by your first post related to the WS Connector in which you made a great job to present WS Connector examples. I noticed that your blog entry has been re-published on Java Lobby.

This current blog is also a very good one. It shows real interoperability with winRM. Something that I am also demonstrating every year at JavaOne (WinRM 2008 demo explained).
Now that you can install WinRM on Windows XP systems, the WinRM usage to interact with JMX should be very large.

It seems that your investigations went quite well. If you have any comments/feedbacks/suggestions on the connector, feel free to contact us (jean-francois dot denise at sun dot com).

Thanks for your interest in this technology.

JF.

Dustin said...

JF,

Thanks for the feedback. I have enjoyed learning about and applying the JMX Web Services Connector and have used your blog entries and even your 2007 and 2008 JavaOne presentations as part of that learning. I'll let you know if I have any comments, feedback, or suggestions. Related to that, I have been intrigued by your work looking into REST-based connection because I think that could be very handy down the road.