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)!