This article is the third in a series on BEA WebLogic Server administration and management for developers.

The first installment (WLDJ, Vol. 2, issue 10) focused on WebLogic Server administration concepts and terminology, and the graphical tools for packaging an application and setting up and configuring a WebLogic Server domain. In the second article (WLDJ, Vol. 2, issue 11), we focused on application deployment, runtime management, and monitoring facilities available with WebLogic Server that did not require knowledge of JMX.

In this article, we'll discuss the basic concepts and terminology of JMX and the BEA WebLogic Server 8.1 JMX infrastructure. We will also show you how to use JMX-specific tools that come with WebLogic Server 8.1.

JMX Concepts and Terminology
BEA WebLogic Server 8.1 implements the Java Management Extensions (JMX) version 1.0 specification. This specification consists of two parts: the instrumentation and the agent specifications.

In the instrumentation level, JMX provides a specification for implementing manageable resources. Manageable resources can be anything from a single Java object to an entire application, from some sort of device to the user of an application, or anything else that is implemented in such a way that it can be managed by a JMX-compliant application. A manageable resource is implemented to allow JMX-compliant applications to manage them by defining one or more managed beans, better known as MBeans.

A JMX agent directly controls the manageable resources and makes them available to JMX-compliant applications. Agents typically live on the same machine as the resources that they control. An agent provides a registry of managed objects that the agent exposes to JMX-compliant applications; this registry is known as an MBean Server. In addition, the agent exposes an additional set of management services for loading classes dynamically, monitoring changes to MBean attributes, creating timers, and defining relationships between MBeans.

Managed Beans
An MBean is a Java class that provides management capabilities for controlling and monitoring a resource. These management capabilities are exposed through the MBean's management interface, which may be defined either statically at compile time, or dynamically at runtime. JMX calls an MBean that defines its management interface statically, a standard MBean and one that does it dynamically, a dynamic MBean.

A standard MBean is a Java class that exposes its management interface through a Java interface that the class implements. The interface class name must be derived from the implementation class name by adding the MBean suffix to the end of the implementation class name. For example, a standard MBean class called com.example.MyDevice would expose its management interface through an interface class called com.example.MyDeviceMBean.

MBeans expose attributes and operations. An attribute is always exposed through the MBean's management interface with getter and/or setter methods using the standard JavaBean naming conventions. The access to the specific attribute is indicated through the management interface by the presence, or lack thereof, of a getter or setter method. For example, a read-only attribute would not have a corresponding setter method exposed in the MBean's management interface.

An operation is any method that does not conform to the conventions of an attribute's getter or setter method. A JMX management program uses introspection of the MBean's management interface to determine the management functionality the MBean exposes.

MBeans support notification. The JMX notification model is based on the Java event model. A notification broadcaster is an MBean that emits notifications. Management applications and others register their interest in these notifications with the broadcaster. Notifications are delivered to registered objects through their implementation of the NotificationListener interface.

The payload of a notification is sent using a Notification object, which contains a type, sequence number, timestamp, message, and any associated data. Notification types are expressed as a string using dot notation. For example, a type name for a notification emitted when a new device is brought on-line might be com.example.mydevice.start. Listeners can also define a notification filter that limits the types of notifications a listener receives. We will talk more about JMX notification in another article.

A dynamic MBean is a Java class that implements the javax.management.DynamicMBean interface, shown here:

public interface DynamicMBean
{
Object getAttribute(String attribute);
AttributeList getAttributes(String[] attributes);
MBeanInfo getMBeanInfo();
Object invoke(String actionName, Object[] params,
String[] signature)
void setAttribute(Attribute attribute);
AttributeList setAttributes(AttributeList attributes) ;
}

Dynamic MBeans are more flexible than standard MBeans. This is because their management interface is exposed through the return value of the getMBeanInfo() method rather than a statically defined interface class. Management applications are expected to use the information in the MBeanInfo class returned to determine the set of attributes and operations that can be manipulated. All subsequent attribute access or operation invocations are performed using the methods defined on the DynamicMBean interface.

The JMX specification also defines two additional types of MBeans: open MBeans and model MBeans. An open MBean is a dynamic MBean whose management interface is defined in terms of a limited set of specified Java types. The idea is that by restricting the types an MBean's management interface exposes, management applications can be packaged to include all of the required classes needed to manage a set of applications without requiring dynamic class loading of application-specific classes by the management application.

A model MBean is a dynamic MBean that provides a configurable, generic template that allows anyone to quickly instrument any resource. A JMX agent provides the implementation for the Model MBean that a resource provider can instantiate, configures the management interface it exposes, specifies the mapping between the management interface and the method that the agent should call, and registers it with the JMX agent. The idea is to significantly reduce the programming burden for adding manageability to a resource.

Now that you understand the basic MBean concepts, let's talk about JMX agents.

JMX Agents
A JMX agent is a Java component that acts as the intermediary between a management application and a set of MBeans. The agent is composed of an MBean server, a set of MBeans representing the managed resources, and a set of agent services. In addition, an agent typically includes some mechanism for providing remote access to support communication between the managed resources and management applications. The JMX 1.0 specification suggests that this support is achieved by the JMX agent providing one or more connectors and/or protocol adapters; exactly how these connectors or protocol adapters work is not specified.

MBean Server
The MBean server is the central registry for MBeans. All management operations on MBeans must go through the MBean server. It is a Java object that implements the javax.management.MBeanServer interface. If you look at the MBeanServer interface, part of which is shown in Listing 1, you will quickly see that the methods closely resemble those defined by the DynamicMBean interface. This allows the MBean server to provide a uniform interface to a management application regardless of the type of MBean that the resource developer chose to implement.

Notice that each method takes an ObjectName as its first argument. A management application uses the object name to specify the MBean, or set of MBeans, on which method invocation applies. Object names consist of two parts: a domain name and an unordered set of key properties. The canonical representation of the object name is a string with the following syntax:

[domainName]:property=value[,property=value]*

For example, the canonical name for the MBean that represents a WebLogic Server instance might be:

mydomain:Name=myserver,Type=Server

Object names also include support for specifying a set of MBeans. By specifying only a subset of information, JMX allows the agent to find any MBeans that match the supplied information. For example, specifying the object name mydomain:Type=Server would cause the agent to match all MBeans in mydomain of type Server.

Object names support implicit domain names and wildcards. To use an implicit domain name, simply omit the domain name from the object name and the agent will automatically apply the name to the default domain. For example, the object name :Name=myserver,Type=Server is the same as the example above if the default domain is mydomain. Object names can also contain the standard file globbing characters:

• * - matches any character sequence
• ? - matches any single character

Agent Services
JMX agents must also provide a set of management services:

• Dynamic class loading
• Monitoring
• Timers
• Relations

The monitoring service allows a management application to tell the agent to observe the value of an MBean attribute at periodic intervals and to notify the management application when the attribute's value satisfies a particular condition. JMX defines three types of monitors for specifying the conditions in which the management application wants to be notified. They are:

The timer service allows a management application to have the agent send out notifications at specific dates and times or repeatedly at a constant interval. We will talk more about the monitoring and timer services in another article.

The relation service allows a management application to define relationships between MBeans. Once defined, the agent is responsible for checking the validity of any existing relationships after any management operations are performed. Any operation that causes a relationship's values to change will cause the agent to generate a notification. (A detailed discussion of the relation service is beyond the scope of this article. See Chapter 11 of the JMX 1.0 specification for more information.)

Now that you have an understanding of the basic concepts of JMX, let's briefly discuss BEA WebLogic Server 8.1's JMX implementation.

WebLogic Server 8.1 JMX
BEA WebLogic Server 8.1 implements the JMX 1.0 specification. Almost every WebLogic Server resource is instrumented using MBeans, and any JMX-compliant management application can plug in and communicate with WebLogic Server's JMX agent implementation.

While this JMX-compliant interface is sufficient for any management task at hand, the fact is that the introspective and loosely typed nature of the MBeanServer interface makes writing JMX management programs to automate simple management tasks more difficult than we would like. As such, WebLogic Server also exposes its own strongly typed MBean interfaces as an alternative to the one defined by JMX. Through these interfaces, you can perform the same set of operations as you can through the standard JMX MBeanServer interface but do so using the more typical strongly-typed Java programming model that provides a much better compile-time checking of your application code. We will go into the details of each of these two approaches at another time.

WebLogic Server 8.1 defines three primary types of MBeans that serve different purposes:

Configuration MBeans are further classified as:

To find a description of all of the WebLogic Server 8.1 MBeans, see the BEA WebLogic Server 8.1 Javadocs for the weblogic.management.configuration, weblogic.management.runtime, and weblogic.management.security.* packages at http://edocs.bea.com/wls/docs81/javadocs/index.html.

WebLogic JMX Client Tools
BEA WebLogic Server 8.1 includes two client tools for accessing its underlying JMX MBeans. The first tool is the weblogic.Admin utility discussed in our last article. WebLogic Server 8.1 also includes the wlconfig Ant task that allows you to easily write scripts to create or modify a domain's configuration. With both of these tools, you must understand the object naming scheme that WebLogic Server uses.

WebLogic Server uses the standard JMX canonical representation for object names. Most object names include the Name and Type properties and many require a Location property.

The Type property value is determined by the class name of the MBean and whether or not the WebLogic MBean is an administration, local configuration, or runtime MBean. For administration MBean types, the Type value is derived by simply removing the MBean suffix from the configuration MBean's interface class name. For example, MBeans that implement the weblogic.management.configuration.JDBCConnectionPoolMBean class have a Type value of JDBCConnectionPool.

Runtime MBeans have a similar scheme so that the Type for MBeans that implements the weblogic.management.runtime.JDBCConnectionPoolRuntimeMBean interface is JDBCConnectionPoolRuntime. To specify the Type for a local configuration MBean, simply add the Config suffix to the Type of the equivalent administration MBean. Following our previous examples, the local configuration MBean's Type value would be JDBCConnectionPoolConfig.

Both runtime and local configuration MBeans require you to specify the Location property in their object names. The value of this property is the name of the WebLogic Server instance where the MBean of interest resides. This location information is required since many other servers in the domain may have an MBean with the same Name and Type property values.

Now that you understand the object naming scheme, let's look at each of the JMX client tools and see how you can use them to automate basic administration tasks.

weblogic.Admin
The weblogic.Admin utility supports the following JMX commands:

There is really no way for us to explain all possible uses of these commands - there are just too many of them to fit here. We'll provide just a few examples for you to get a feel for what you can do

To create a new JMS connection factory, use the CREATE command:

java weblogic.Admin -url t3://AdminHost:7001
-username weblogic -password weblogic
CREATE -name jms/MyConnectionFactory
-type JMSConnectionFactory

To set the JNDI name of your new connection factory, use the SET command. However, the SET command requires that you specify the MBean's object name. If you're unsure about the exact object name, use the GET command to get all of the MBeans of the JMSConnectionFactory type:

java weblogic.Admin -url t3://AdminHost:7001
-username weblogic -password weblogic
GET -type JMSConnectionFactory

The MBean name is shown in the output below:

{MBeanName="medrec:Name=jms/MyConnectionFactory,Type=JMSConnectionFactory"
{AcknowledgePolicy=All}{AllowCloseInOnMessage=false}...

Now, use the SET command to set the JNDI name:

java weblogic.Admin -url t3://AdminHost:7001
-username weblogic -password weblogic
SET -mbean "medrec:Name=jms/MyConnectionFactory,
Type=JMSConnectionFactory"
-property JNDIName jms/MyConnectionFactory

The last thing to do is to deploy your new connection factory to the MedRecServer. Use the SET command again, but since the setTargets() method (on the JMSConnectionPoolMBean interface) takes an array of MBeans as the argument, you must use the object name for the MedRecServer's Server MBean:

java weblogic.Admin -url t3://AdminHost:7001
-username weblogic -password weblogic
SET -mbean "medrec:Name=jms/MyConnectionFactory,
Type=JMSConnectionFactory"
-property Targets "medrec:Name=MedRecServer,
Type=Server"

To add a new user, use the INVOKE command to invoke the createUser() method on the appropriate authenticator's UserEditorMBean interface (assuming your authenticator implements this interface). To find the object name of your authenticator's security MBean, use the QUERY command:

java weblogic.Admin -url t3://AdminHost:7001
-username weblogic -password weblogic QUERY -pattern "Security:*"

The MBean name of interest is shown here:

{MBeanName="Security:Name=myrealmDefaultAuthenticator" {ControlFlag=SUFFICIENT}...
{MBeanName="Security:Name=myrealmMedRecSampleAuthenticator"{ControlFlag=SUFFICIENT}...

Since the MedRecSampleAuthenticator does not implement the UserEditorMBean interface, you must add the user to the DefaultAuthenticator using the INVOKE command:

java weblogic.Admin -url t3://AdminHost:7001
-username weblogic -password weblogic
INVOKE -mbean "Security:Name=myrealmDefaultAuthenticator"
-method createUser rpatrick password "Robert Patrick"

To delete our example JMS connection factory, use the DELETE command:

java weblogic.Admin -url t3://AdminHost:7001
-username weblogic -password weblogic
DELETE -mbean "medrec:Name=jms/MyConnectionFactory,
Type=JMSConnectionFactory"

For more information on the weblogic.Admin commands for manipulating WebLogic MBeans, see http://edocs.bea.com/wls/docs81/admin_ref/cli.html#1240048.

wlconfig Ant task
The wlconfig Ant task provides a mechanism by which you can connect to your domain's admin server and query, create, or change the attributes of the domain's administration MBeans. BEA WebLogic Server 8.1 also provides four other Ant tasks: wlcompile, wlappc, wlserver, and wldeploy. These tasks allow you to fully automate the end-to-end process of creating and configuring your domain as well as compiling, packaging, and deploying your application. To use wlconfig, you need to write an Ant script. For more information on Ant, see http://ant.apache.org.

To connect to our MedRec administration server, we would use the following wlconfig tag in our Ant script:

<wlconfig url="t3://AdminHost:7001"
username="weblogic" password="weblogic">
...
</wlconfig>

wlconfig supports five nested tags with similar meanings to the equivalent weblogic.Admin commands covered earlier: create, delete, get, query, and set. We will provide just a few examples here to give you a feel for what you can do.

Listing 2 is an example of the use of wlconfig to modify your domain's configuration. We use the query tag to get a reference to the MedRecServer's Server MBean and store it in a property called medrecserver for use later in the script. Next, we use the create tag to create a JMS file store and store a reference to the newly created MBean in the myfilestore property. We use a nested set tag to specify the JMS file store's directory attribute. Then we use the create tag again to create a JMS server. Notice that the nested set tags use the properties we previously created to supply the appropriate MBeans when setting the attribute values of the JMS server's MBean.

Finally, we use a nested create tag inside the JMS server's create tag to create a JMS queue that is part of our newly created JMS server. This nesting structure is used to specify the MBean upon which the action is to be applied (in the case of set commands) or to specify the relationship between MBeans (in the case of the create commands).

For more information about the wlconfig Ant task, see http://edocs.bea.com/wls/docs81/admin_ref/ant_tasks.html.

Summary
This article provides an overview of JMX concepts and terminology and a discussion of the BEA WebLogic Server 8.1 JMX implementation. The article ended with a discussion of the WebLogic JMX client tools and how to use them to create, view, and modify the WebLogic Server MBeans. Our next article will dive into the Java APIs for building custom JMX programs. A later article will discuss creating custom MBeans and extending the Admin Console to display them.