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

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.