IBM WebSphere scripting with wsadmin: containment paths, configuration IDs and object names

Vincent Partington

logo_websphere2
In my previous blog on the deployment capabilities of the major application servers, I asked, as a joke, whether anybody knew the difference between containment paths, configuration IDs and object names in WebSphere's scripting interface wsadmin. I didn't get (nor expect ;-) ) an answer. But instead of keeping you in the dark, this blog will explain the difference between these three and how you can translate between them.

Configuration ID

Configuration IDs are the most common id you will encounter when working with wsadmin. They uniquely specify an element in the configuration of WebSphere Application Server and are needed to modify the configuration with one of the commands in the AdminConfig object.

Configuration IDs have the following syntax:

name(directory|filename#XML-fragment-id)

As an example the following configuration ID points to the configuration for the application server with the name server1:

server1(cells/was-70Cell01/nodes/was-70Node01/servers/server1|server.xml#Server_1254421834316)

Configuration objects that don't have a name also don't have a name in their configuration ID. For example, this is the configuration ID for a "JAAS/J2C Authentication Data" object:

(cells/was-70Cell01|security.xml#JAASAuthData_1258718081490)

The configuration ID actually tells you where you can find the configuration on disk. Let's take the configuration ID for the application server in the example above. If you open the file WAS_HOME/profiles/PROFILE_NAME/config/cells/was-70Cell01/nodes/was-70Node01/servers/server1/server.xml and look for the string xmi:id="Server_1254421834316" you will find the corresponding XML fragment in the WebSphere configuration. However, in general it is best to just use the configuration ID as an opaque value.

You can get a configuration ID by invoking either the AdminConfig.list command or the AdminConfig.getid command. The first will return all the configuration IDs for objects of a certain type (you can list all the types by invoking AdminConfig.types), while the second will return all configuration IDs that match a containment path.

The third way to get a configuration ID is by passing an object name to the AdminControl.getConfigId method. But you'd first need to get one of those, so read on...

Containment path

Before we move on the object name, let's discuss the containment path first. Because a configuration ID contains a seemingly random XML fragment ID, you cannot know the configuration ID of something if you only know its name. To solve that problem. IBM introduced the concept of a containment path. A containment path specifies the hierarchical path of how to reach the object you are looking for. The general syntax, which may remind some people of XPath, is as follows:

/type:name/type:name/type:name/.../

Each path element must have a type (one of the types returned by AdminConfig.types) and can optionally have a name. If no name is specified all the objects of the specified type match.

As an example, you can retrieve the configuration ID of the server called server1 as follows (using Jython syntax):

print AdminConfig.getid('/Server:server1/')

If there are multiple servers called server1 running on different nodes, you can get the right one like this:

print AdminConfig.getid('/Node:was-70Node01/Server:server1/')

If you want to find out where a certain type of configuration objects resides in the WebSphere configuration tree, you can invoke the AdminConfig.parents command with the type as the first parameter.

Once translated into a configuration ID, containment paths are no longer needed.

Object name

OK, that leaves only the object name to discuss. The object name refers to a running JMX MBean that can be controlled with one of the commands in the AdminControl object. It has the standard JMX object name syntax. The domain is always "WebSphere" so that the syntax becomes like this:

WebSphere:key=value,key=value,key=value,...

The MBean hierarchy is a different hierarchy than the hierarchy of configuration objects:

  • For some configuration objects there is a corresponding MBean. As an example, the MBean that corresponds to the server mentioned above has the name WebSphere:name=server1,process=server1,platform=proxy,node=was-70Node01,j2eeType=J2EEServer,version=7.0.0.5,type=Server,mbeanIdentifier=cells/was-70Cell01/nodes/was-70Node01/servers/server1/server.xml#Server_1254421834316,cell=was-70Cell01,spec=1.0,processType=ManagedProcess.

    You can get this object name by invoking the AdminConfig.getObjectName command with the configuration ID as the first parameter. If there is no corresponding MBean, or the object is not running, nothing is returned.
  • For some configuration objects, such as the JAAS/J2C Authentication Data, there is no corresponding MBean because there is no runtime state to control.
  • And finally, there are also MBeans that do not correspond to configuration objects. You can invoke AdminControl.queryNames or AdminControl.queryNames_jmx and pass in a JMX query to get the corresponding object names. Of course that also works for MBeans that do have a corresponding configuration ID.

To use an object name, you need to get a reference to an actual MBean by invoking AdminControl.getObjectInstance. You can also directly query for MBeans with the AdminControl.queryMBean command.

Overview

Knowing the difference between these three kinds of IDs is essential if you want to use wsadmin effectively. To figure out which ID to use in what case and how to get the IDs, please consult the table below.

Configuration ID Containment path Object name
Represents A static configuration object A shortname for a configuration object A running MBean
Used by AdminConfig AdminConfig AdminControl
Query AdminConfig.list N/A AdminControl.queryNames and
AdminControl.queryNames_jmx
Translate from configuration ID N/A N/A AdminConfig.getObjectName
Translate from containment path AdminConfig.getid N/A N/A
Translate from object name AdminControl.getConfigId N/A N/A

Comments (9)

  1. Doug - Reply

    February 23, 2010 at 7:05 pm

    This is flat out, the best post on this subject I've found anywhere - including the IBM documentation. Many thanks for sharing your expertise.

  2. Vincent Partington - Reply

    February 25, 2010 at 8:42 am

    @Doug: Glad to hear that my post helped someone out. :-)

  3. JayShah - Reply

    August 17, 2010 at 4:32 pm

    Concur with Doug. Very lucid explanation - removed a lot of my confusion.

  4. Edwin Madari - Reply

    September 3, 2010 at 5:52 pm

    thanks to Vincents posting, able to view and manupulate all objects. this provided information that no other documentation including IBMs have provided. thanks a lot Vincent. much appreciated.

  5. Chander - Reply

    November 30, 2010 at 5:37 pm

    Can't agree more with Doug.
    Thank you Vincent../

  6. Joe Potgieter - Reply

    August 4, 2011 at 9:32 pm

    I agree with Doug. This is the coolest post on the net about this subject. Even IBM does not explain it in such understandable terms.

    A post that I would love to see is how to get the "specialEndpoints" from another server in the cluster, using the ConfigServiceProxy class in a jsp page.

  7. [...] configuration ids. For more important details on containment paths and configuration ids read this excellent article by Vincent Partington. As mentioned above, this only works when there is a single server defined on the node - with [...]

  8. Alex - Reply

    January 27, 2012 at 10:48 pm

    I'm trying to access a config ID for a TCPInboundChannel in server.xml. I need the containment path for this object, but don't know how to find it.

    So far, I have /Node:mynode/Server:myserver/TCPInboundChannel:TCP_2/ but it's returning null.

    Anybody have any ideas?

  9. Srini - Reply

    April 8, 2014 at 2:15 am

    I can't thank you enough. Removed all my confusion.
    Thank you SO VERY MUCH, Vincent.
    I saved my day...

Add a Comment