JSR-77 Overview

In 2001, JSR-77 was introduced to address the issue of managing J2EE servers. While most of the deployable modules in J2EE can be created in ways that are independent of the hosting servers, it was not possible to use a generic management tool to manage different J2EE servers. This is because the management APIs of most network-management products are proprietary.

JSR-77 addresses this issue by defining a standard model (a meta-model) and a set of conventions for J2EE Management. JSR-77 is based on the JMX specification. While the JMX specification’s focus is on management of generic resources (such as hardware components, software services, and so on), the JSR-77 specification is focused on management of J2EE servers and components. This specification became final in July of 2002 (with an update in August of 2005).

Implementation of JSR-77 can lead to manageable servers that work with a variety of management tools. That is, a JSR-77 management tool or system should be able to manage any JSR-77-compliant server.

Management EJB

In the JSR-77 model, the management application communicates with and obtains management information on the server through a Management EJB (MEJB) component. The API to this MEJB is defined by JSR-77.

Through the MEJB, you can look up and access exposed management attributes, invoke exposed operations, or receive events from manageable server components. If this starts to sounds like JMX to you, you are right on the money.

In fact, the MEJB actually operates at the Agent level of functionality (with respect to the JMX model). Being a J2EE management model, the use of EJB at the Agent level is one of the natural ways of implementing JMX remote access. However, even though access through MEJB is preferred, JSR-77 also specified information for an SNMP MIB and CIM mappings to ensure backward compatibility with legacy management tools and systems. The specification does not require the support and implementation for these legacy management protocols. Specific implementations may have connectors and protocol converters at the Agent level to communicate via these legacy systems.

A JSR-77 management application can locate the MEJB in a JSR-77-compliant server (such as Geronimo) via Java Naming and Directory Interface (JNDI). The code that is typically used is shown here. It is not important that you understand this code; just note the lookup in the highlighted line.

 Context ctx = new InitialContext( ); Object objref = ctx.lookup("ejb/mgmt/MEJB"); ManagementHome home = (ManagementHome)     PortableRemoteObject.narrow(objref,ManagementHome.class); Management mejb = home.create( );

On a JSR-77-complaint server, looking up ejb/mgmt/MEJB using JNDI will always provide the MEJB instance. In addition, any components that the MEJB returns must be valid JMX MBeans consistent with the model defined in JSR-77. Of course, the MBeans can all have exposed attributes and operations, or fire events.

Figure 7-3 shows the operations of the JSR-77 MEJB.

Figure 7-3: Operations of an MEJB in a JSR-77 server such as Geronimo

In Figure 7-3, you can see that the JSR-77 management application (considered a client) queries the EJB for information on the server. In return, the MEJB returns JMX MBeans to the JSR-77 client application. Figure 7-3 also shows that the JMX MBeans can be from different domains. A domain is a namespace - roughly corresponding to a specific component category. Domains are specific to a JSR-77 implementation. You will see how Geronimo makes use of the domain shortly.

Meanwhile, it is important to realize that the Geronimo debug console is actually a JSR-77 client application. It makes queries into the set of Geronimo’s kernel-managed objects via the MEJB agent. Figure 7-4 shows the internal architecture of the debug console.

Figure 7-4: Geronimo debug console is a JSR-77 client application

In Figure 7-4, you can see that the debug console actually runs as a Web-tier application inside the Geronimo server. It is a JSR-77 client application that runs within Geronimo. You interact with the debug console via a Web browser, and internally it queries the MEJB agent using JSR-77-specified APIs. The core function of the debug console is to query and report information from JMX MBeans of Geronimo kernel-managed components.

Unlike many other JSRs, JSR-77 does not mandate the inclusion of specific Java implementation classes for the server (except for the MEJB component). However, JSR-77 does have very specific requirements of how components should be named, what components must be available, and how components are related. This is spelled out explicitly in the model described by JSR-77.

One very important aspect of the JSR-77 model is the way objects are named.

Object Names in JSR-77

In the JSR-77 model, every single object is a descendent of J2EEManagedObject.

The J2EEManagedObject contains attributes that must exist on every JSR-77 object. These include the following:

• An object name

• A stateManageable Boolean indicating if the operational lifecycle states of the object is manageable by the container

• A statisticsProvider Boolean indicating if the object provides statistics (through well-defined attributes in JSR-77)

• An eventProvider Boolean indicating if the object fires an event

As Geronimo administrators, the attribute of most interest to us is the object name - since the other attributes are really meant for consumption of the JSR-77 management tool/client.

The object name is the primary means for you to get information on GBean components using the debug console. Familiarity with JSR-77 naming will help you in working with the debug console.

Each object name in JSR-77 is in the following form:

 [domain name]:j2eeType=value,name=value,<parent j2eeType>[,property=value]*

This form requires some explanation. First, the domain name is optional. Then, a series of key-value pairs are specified. The order of appearance of these key-value pairs in the name is not important.

The mandatory keys are shown in Table 7-1.

Table 7-1: Mandatory Keys in the JSR-77 Object Name
Open table as spreadsheet

Key	Description
j2eeType	The type of J2EE component that is represented by the object. It can be one of the following JSR-77 defined values or a container-specific value: J2EEDomain, J2EEServer, J2EEApplication, AppClient Module, EJBModule, WebModule, ResourceAdapterModule, EntityBean, StatefulSessionBean, StatelessSessionBean, MessageDrivenBean, Servlet, ResourceAdapter, JavaMail- Resource, JCAResource, JCAConnectionFactory, JCAManaged- ConnectionFactory, JDBCResource, JDBCDataSource, JDBC-Driver, JMSResource, JNDIResource, JTAResource, RMI_IIOPResource, URLResource, JVM.
name	A name for the object; the format of this name can be specific to the server. However, for j2eeType=J2EEDomain objects, the name must be the name of the domain.
<parent j2eeType>	This is actually a key-value pair in the form of <j2eeType of parent> = <name of parent object>. Depending on the j2eeType of the object, there are different mandatory <parent j2eeType> keys. See the Table 7-2 for more information.

Other than these mandatory keys, the server can also add other related property=value pairs to the name.

Table 7-2 shows the mandatory parent J2EE types that must be specified depending on the type of the object.

Table 7-2: J2EE Types of Mandatory Parent Keys
Open table as spreadsheet

Type of Object	Parent j2eeType That Must Be Specified
J2EEDomain
J2EEServer
J2EEApplication	J2EEServer
AppClientModule	J2EEServer, J2EEApplication
EJBModule	J2EEServer, J2EEApplication
WebModule	J2EEServer, J2EEApplication
ResourceAdapterModule	J2EEServer, J2EEApplication
EntityBean	J2EEServer, J2EEApplication,EJBModule
StatefulSessionBean	J2EEServer, J2EEApplication,EJBModule
StatelessSessionBean	J2EEServer, J2EEApplication,EJBModule
MessageDrivenBean	J2EEServer, J2EEApplication, EJBModule
Servlet	J2EEServer, J2EEApplication, WebModule
ResourceAdapter	ResourceAdapterModule, J2EEServer, J2EEApplication
JavaMailResource	J2EEServer
JCAResource	ResourceAdapter, J2EEServer
JCAConnectionFactory	JCAResource, J2EEServer
JCAManagedConnectionFactory	J2EEServer
JDBCResource	J2EEServer
JDBCDataSource	JDBCResource, J2EEServer
JDBCDriver	J2EEServer
JMSResource	J2EEServer
JNDIResource	J2EEServer
JTAResource	J2EEServer
RMI_IIOPResource	J2EEServer
URLResource	J2EEServer
JVM	J2EEServer

By enforcing the explicit naming of the parent’s j2eeType, a tree of objects is specified through this naming convention. An example will make it clear why this is important. Consider that you have just deployed an enterprise application EAR file, named progeron.ear, with the following components in the archive:

• A stateless session bean named AuthorEJB (the name as configured by an <ejb-ref> element in the deployment descriptor)

• An EJB JAR file called progeron-ejbs.jar, which contains AuthorEJB

• A servlet named Show authors (the name is configured by a <servlet-name> element in the deployment descriptor)

• A WAR file called progeron.war, which contains the Show authors servlet

The JSR-77 object name for the progeron-ejbs.jar EJB JAR file is:

 geronimo.server: J2EEApplication=progeron,J2EEServer=geronimo,j2eeType=EJBModule, name=progeron-ejbs.jar

The j2eeType for progeron-ejbs.jar is EJBModule, and the required parent j2eeTypes according to Table 7-2, are just J2EEServer and J2EEApplication.

The JSR-77 object name for the AuthorEJB session bean, contained within the progeron-ejbs.jar file, is:

 geronimo.server: EJBModule=progeron-ejbs.jar,J2EEApplication=progeron,J2EEServer=geronimo, j2eeType=StatelessSessionBean,name=AuthorEJB

Checking against Table 7-2, the mandatory parent j2eeTypes in this case, for a StatelessSession Bean are J2EEServer, J2EEApplication, and EJBModule. Specifically, the parent EJBMoudle key contains progeron-ejbs.jar, creating a parent-child relationship between the two objects.

The JSR-77 object name for the progeron.war file is:

 geronimo.server:J2EEApplication=progeron,J2EEServer=geronimo,j2eeType=WebModule, name=progeron.war

The j2eeType of this object is WebModule, and the only parents required are J2EEServer and J2EEApplication.

The Show authors servlet, contained in progeron.war, has the following JSR-77 name:

 geronimo.server:J2EEApplication=progeron,J2EEServer=geronimo, WebModule=progeron.war,j2eeType=Servlet,name=Show authors

The j2eeType is Servlet in this case, and the WebModule - progeron.war - is named as its parent.

Armed with Table 7-2, you can locate any deployed application component by specifying its JSR-77 name. This will be very useful when you work with the debug console.

You will notice that all of the previous components are in the geronimo.server domain. In fact, all deployed application components will be in this domain. Table 7-3 describes all the JSR-77 domains used in object names in Geronimo.

Table 7-3: Geronimo’s JSR-77 Domains
Open table as spreadsheet

Geronimo’s JSR-77 Domain Name	Description
geronimo.boot	Component used during kernel boot.
geronimo.config	Currently running or recently failed configurations in the server.
geronimo.remoting	Server for JAAS remote login.
geronimo.security	Component representing the keystore, and perhaps other security components in the future.
geronimo.server	The application components that have been deployed. This domain is where you will find most of the interesting components.
geronimo and openejb	OpenEJB system components.

You should now have a workable understanding of how components in a server are given JSR-77 names. In the upcoming debug console troubleshooting example, you can put this knowledge to good use.

Understanding JSR-77 object naming conventions is very important to system administrators. In addition to their use in the debug console, you can also reference Geronimo managed objects in deployment plans using the JSR-77 naming conventions.

JSR-77 Manageable States

As mentioned, every JSR-77 manageable object is an instance of a J2EEManagedObject. A J2EEManagedObject has a mandatory Boolean attribute called stateManageable. If this attribute is valued true, it indicates that the container is managing the lifecycle of the component. This is always the case with deployable application modules in Geronimo.

A JSR-77 stateManageable component can have its state queried by a JSR-77 client application. It is also possible to find out how long a component has been running, or start and stop the component using the exposed operations.

A JSR-77 stateManageable component can be in any one of the following states:

• Starting

• Running

• Stopping

• Stopped

• Failed

These are the states that every deployable Geronimo application component may be in. The possible state transitions are shown in Figure 7-5.

Figure 7-5: State transitions and JSR-77 manageable states

As a JSR-77 client application, the debug console can show you the JSR-77 state of managed components. This information is invaluable in many troubleshooting scenarios.

It is time to get some hands-on working time with the debug console tool.