CHAPTER 2 The JBoss JMX Microkernel

Managed Beans or MBeans

An MBean is a Java object that implements one of the standard MBean interfaces and follows the associated design patterns. The MBean for a resource exposes all necessary information and operations that a management application needs to control the resource.

The scope of the management interface of an MBean includes the following:

• Attributes values that may be accessed by name
• Operations or functions that may be invoked
• Notifications or events that may be emitted
• The constructors for the MBean's Java class

JMX defines four types of MBeans to support different instrumentation needs:

• Standard MBeans These use a simple JavaBean style naming convention and a statically defined management interface. This is currently the most common type of MBean used by JBoss.
• Dynamic MBeans These must implement the javax.management.DynamicMBean interface, and they expose their management interface at runtime when the component is instantiated for the greatest flexibility. JBoss makes use of Dynamic MBeans in circumstances where the components to be managed are not known until runtime.
• Open MBeans These are an extension of dynamic MBeans. Open MBeans rely on basic, self-describing, user-friendly data types for universal manageability. JBoss 3.0.6+ and 3.2+ implement the JMX 1.1 OpenMBeans.
• Model MBeans These are also an extension of dynamic MBeans. Model MBeans must implement the javax.management.modelmbean.ModelMBean interface. Model MBeans simplify the instrumentation of resources by providing default behavior. Although JBoss does not use any Model MBeans for its core services as of the 3.2.0 release, there is a Model MBean implementation known as an XMBean.

We will present an example of a Standard and a Model MBean in the section that discusses extending JBoss with your own custom services.

Notification Model

JMX Notifications are an extension of the Java event model. Both the MBeanServer and MBeans can send notifications to provide information. The JMX specification defines the javax.management package Notification event object, NotificationBroadcaster event sender, and NotificationListener event receiver interfaces. The specification also defines the MBeanServer operations that allow for the registration of notification listeners.

MBean Metadata Classes

There is a collection of metadata classes that describe the management interface of an MBean. Users can obtain a common metadata view of any of the four MBean types by querying the MBeanServer with which the MBeans are registered. The metadata classes cover an MBean's attributes, operations, notifications, and constructors. For each of these, the metadata includes a name, a description, and its particular characteristics. For example, one characteristic of an attribute is whether it is readable, writable, or both. The metadata for an operation contains the signature of its parameter and return types.

The different types of MBeans extend the metadata classes to be able to provide additional information as required. This common inheritance makes the standard information available regardless of the type of MBean. A management application that knows how to access the extended information of a particular type of MBean is able to do so.

MBean Server

A key component of the agent level is the managed bean server. Its functionality is exposed through an instance of the javax.management.MBeanServer . An MBeanServer is a registry for MBeans that makes the MBean management interface available for use by management applications. The MBean never directly exposes the MBean object itself; rather, its management interface is exposed through metadata and operations available in the MBeanServer interface. This provides a loose coupling between management applications and the MBeans they manage.

MBeans can be instantiated and registered with the MBeanServer by the following:

• Another MBean
• The agent itself
• A remote management application (through the distributed services)

When you register an MBean, you must assign it a unique object name. The object name then becomes the unique handle by which management applications identify the object on which to perform management operations. The operations available on MBeans through the MBeanServer include the following:

• Discovering the management interface of MBeans
• Reading and writing attribute values
• Invoking operations defined by MBeans
• Registering for notifications events
• Querying MBeans based on their object name or their attribute values

Protocol adaptors and connectors are required to access the MBeanServer from outside the agent's JVM. Each adaptor provides a view via its protocol of all MBeans registered in the MBeanServer the adaptor connects to. An example adaptor is an HTML adaptor that allows for the inspection and editing of MBeans using a Web browser. As was indicated in See The Relationship between the components of the JMX architecture., there are no protocol adaptors defined by the current JMX specification. Later versions of the specification will address the need for remote access protocols in standard ways.

A connector is an interface used by management applications to provide a common API for accessing the MBeanServer in a manner that is independent of the underlying communication protocol. Each connector type provides the same remote interface over a different protocol. This allows a remote management application to connect to an agent transparently through the network, regardless of the protocol. The specification of the remote management interface will be addressed in a future version of the JMX specification.

Adaptors and connectors make all MBean server operations available to a remote management application. For an agent to be manageable from outside of its JVM, it must include at least one protocol adaptor or connector. JBoss currently includes a custom HTML adaptor implementation and a custom JBoss RMI adaptor.

Agent Services

The JMX agent services are objects that support standard operations on the MBeans registered in the MBean server. The inclusion of supporting management services helps you build more powerful management solutions. Agent services are often themselves MBeans, which allow the agent and their functionality to be controlled through the MBean server. The JMX specification defines the following agent services:

• A Dynamic class loading MLet (management applet) service. This allows for the retrieval and instantiation of new classes and native libraries from an arbitrary network location.
• Monitor services. These observe an MBean attribute's numerical or string value, and can notify other objects of several types of changes in the target.
• Timer services. These provide a scheduling mechanism based on a one-time alarm-clock notification or on a repeated, periodic notification.
• The relation service. This service defines associations between MBeans and enforces consistency on the relationships.

Any JMX-compliant implementation will provide all of these agent services. JBoss currently does not rely on any of these standard agent services.

The ExCCEc class used to demonstrate ClassCastException due to duplicate class loaders

1. package org.jboss.chap2.ex0;
2.  
3. import java.io.File;
4. import java.net.URL;
5. import java.net.URLClassLoader;
6. import java.lang.reflect.Method;
7.  
8. import org.apache.log4j.Logger;
9.  
10. import org.jboss.util.ChapterExRepository;
11. import org.jboss.util.Debug;
12.  
13. /** An example of a ClassCastException that results from classes loaded through
14. * different class loaders.
15. * @author Scott.Stark@jboss.org
16. * @version $Revision:$
17. */
18. public class ExCCEc
19. {
20. public static void main(String[] args) throws Exception
21. {
22. ChapterExRepository.init(ExCCEc.class);
23.  
24. String chapDir = System.getProperty("chapter.dir");
25. Logger ucl0Log = Logger.getLogger("UCL0");
26. File jar0 = new File(chapDir+"/j0.jar");
27. ucl0Log.info("jar0 path: "+jar0.toString());
28. URL[] cp0 = {jar0.toURL()};
29. URLClassLoader ucl0 = new URLClassLoader(cp0);
30. Thread.currentThread().setContextClassLoader(ucl0);
31. Class objClass = ucl0.loadClass("org.jboss.chap2.ex0.ExObj");
32. StringBuffer buffer = new StringBuffer("ExObj Info");
33. Debug.displayClassInfo(objClass, buffer, false);
34. ucl0Log.info(buffer.toString());
35. Object value = objClass.newInstance();
36.  
37. File jar1 = new File(chapDir+"/j0.jar");
38. Logger ucl1Log = Logger.getLogger("UCL1");
39. ucl1Log.info("jar1 path: "+jar1.toString());
40. URL[] cp1 = {jar1.toURL()};
41. URLClassLoader ucl1 = new URLClassLoader(cp1);
42. Thread.currentThread().setContextClassLoader(ucl1);
43. Class ctxClass2 = ucl1.loadClass("org.jboss.chap2.ex0.ExCtx");
44. buffer.setLength(0);
45. buffer.append("ExCtx Info");
46. Debug.displayClassInfo(ctxClass2, buffer, false);
47. ucl1Log.info(buffer.toString());
48. Object ctx2 = ctxClass2.newInstance();
49.  
50. try
51. {
52. Class[] types = {Object.class};
53. Method useValue = ctxClass2.getMethod("useValue", types);
54. Object[] margs = {value};
55. useValue.invoke(ctx2, margs);
56. }
57. catch(Exception e)
58. {
59. ucl1Log.error("Failed to invoke ExCtx.useValue", e);
60. throw e;
61. }
62. }
63. }

The ExCtx, ExObj, and ExObj2 classes used by the examples

1. package org.jboss.chap2.ex0;
2.  
3. import java.io.IOException;
4.  
5. import org.apache.log4j.Logger;
6.  
7. import org.jboss.util.Debug;
8.  
9. /** A classes used to demonstrate various class loading issues
10. * @author Scott.Stark@jboss.org
11. * @version $Revision: 1.2 $
12. */
13. public class ExCtx
14. {
15. ExObj value;
16.  
17. public ExCtx() throws IOException
18. {
19. value = new ExObj();
20. Logger log = Logger.getLogger(ExCtx.class);
21. StringBuffer buffer = new StringBuffer("ctor.ExObj");
22. Debug.displayClassInfo(value.getClass(), buffer, false);
23. log.info(buffer.toString());
24. ExObj2 obj2 = value.ivar;
25. buffer.setLength(0);
26. buffer = new StringBuffer("ctor.ExObj.ivar");
27. Debug.displayClassInfo(obj2.getClass(), buffer, false);
28. log.info(buffer.toString());
29. }
30. public Object getValue()
31. {
32. return value;
33. }
34. public void useValue(Object obj) throws Exception
35. {
36. Logger log = Logger.getLogger(ExCtx.class);
37. StringBuffer buffer = new StringBuffer("useValue2.arg class");
38. Debug.displayClassInfo(obj.getClass(), buffer, false);
39. log.info(buffer.toString());
40. buffer.setLength(0);
41. buffer.append("useValue2.ExObj class");
42. Debug.displayClassInfo(ExObj.class, buffer, false);
43. log.info(buffer.toString());
44. ExObj ex = (ExObj) obj;
45. }
46. void pkgUseValue(Object obj) throws Exception
47. {
48. Logger log = Logger.getLogger(ExCtx.class);
49. log.info("In pkgUseValue");
50. }
51. }
52.  

The ExObj and ExObj2 classes used in the examples

package org.jboss.chap2.ex0;

 

import java.io.Serializable;

 

/**

* @author Scott.Stark@jboss.org

* @version $Revision:$

*/

public class ExObj implements Serializable

{

public ExObj2 ivar = new ExObj2();

}

----------------------------------------------------------------------------

package org.jboss.chap2.ex0;

 

import java.io.Serializable;

 

/**

* @author Scott.Stark@jboss.org

* @version $Revision: 1.1$

*/

public class ExObj2 implements Serializable

{

}

 

The ExCCEc.main method uses reflection to isolate the classes that are being loaded by the URLClassLoaders ucl0 and ucl1 from the application class loader. Both are setup to load classes from the output/chap2/j0.jar, the contents of which are:

[nr@toki examples]$ jar -tf output/chap2/j0.jar

...

org/jboss/chap2/ex0/ExCtx.class

org/jboss/chap2/ex0/ExObj.class

org/jboss/chap2/ex0/ExObj2.class

We will run an example that demonstrates how a ClassCastException can occur and then look at the specific issue with the example. See Appendix C for instructions on installing the examples accompanying the book, and then run the example from within the examples directory using the following command:

[nr@toki examples]$ ant -Dchap=chap2 -Dex=0c run-example

Buildfile: build.xml

...

[java] [ERROR,UCL1] Failed to invoke ExCtx.useValue

[java] java.lang.reflect.InvocationTargetException

[java] at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)

[java] at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)

[java] at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)

[java] at java.lang.reflect.Method.invoke(Method.java:324)

[java] at org.jboss.chap2.ex0.ExCCEc.main(ExCCEc.java:58)

[java] Caused by: java.lang.ClassCastException

[java] at org.jboss.chap2.ex0.ExCtx.useValue(ExCtx.java:44)

[java] ... 5 more

[java] Java Result: 1

Only the exception is shown here. The full output can be found in the logs/chap2-ex0c.log file. At line 55 of ExCCEc.java we are invoking ExcCCECtx.useValue(Object) on the instance loaded and created in lines 37-48 using the URLClassLoader ucl1. The ExObj passed in is the one loaded and created in lines 25-35 via the URLClassLoader ucl0. The exception results when the ExCtx.useValue code attempts to cast the argument passed in to a ExObj . To understand why this fails consider the debugging output from the chap2-ex0c.log file shown in See The chap2-ex0c.log debugging output for the ExObj classes seen..

The chap2-ex0c.log debugging output for the ExObj classes seen

[INFO,UCL0] ExObj Info

org.jboss.chap2.ex0.ExObj(113fe2).ClassLoader=java.net.URLClassLoader@6e3914

..java.net.URLClassLoader@6e3914

....file:/C:/Scott/JBoss/Books/AdminDevel/education/books/admin-devel/examples/output/chap2/j0.jar

++++CodeSource: (file:/C:/Scott/JBoss/Books/AdminDevel/education/books/admin-devel/examples/output/chap2/j0.jar <no certificates>)

Implemented Interfaces:

++interface java.io.Serializable(7934ad)

++++ClassLoader: null

++++Null CodeSource

 

[INFO,ExCtx] useValue2.ExObj class

org.jboss.chap2.ex0.ExObj(415de6).ClassLoader=java.net.URLClassLoader@30e280

..java.net.URLClassLoader@30e280

....file:/C:/Scott/JBoss/Books/AdminDevel/education/books/admin-devel/examples/output/chap2/j0.jar

++++CodeSource: (file:/C:/Scott/JBoss/Books/AdminDevel/education/books/admin-devel/examples/output/chap2/j0.jar <no certificates>)

Implemented Interfaces:

++interface java.io.Serializable(7934ad)

++++ClassLoader: null

++++Null CodeSource

The first output prefixed with [INFO,UCL0] shows that the ExObj class loaded at line ExCCEc.java:31 has a hash code of 113fe2 and an associated URLClassLoader instance with a hash code of 6e3914, which corresponds to ucl0. This is the class used to create the instance passed to the ExCtx.useValue method. The second output prefixed with [INFO,ExCtx] shows that the ExObj class as seen in the context of the ExCtx.useValue method has a hash code of 415de6 and a URLClassLoader instance with an associated hash code of 30e280, which corresponds to ucl1. So even though the ExObj classes are the same in terms of actual bytecode since it comes from the same j0.jar, the classes are different as seen by both the ExObj class hash codes, and the associated URLClassLoader instances. Hence, attempting to cast an instance of ExObj from one scope to the other results in the ClassCastException .

This type of error is common when one redeploys an application to which other applications are holding references to classes from the redeployed application. For example, a standalone war accessing an ejb. If you are redeploying an application, all dependent applications must flush their class references. Typically this requires that the dependent applications themselves be redeployed.

An alternate means of allowing independent deployments to interact in the presence of redeployment would be to isolate the deployments by configuring the EJB layer to use the standard call-by-value semantics rather than the call-by-reference JBoss will default to for components collocated in the same VM. An example of how to enable call-by-value semantics is presented in "Chapter 5, Enabling Call by Reference TODO: replace with real reference".

The ExIAEd class used to demonstrate IllegalAccessException due to duplicate class loaders

1. package org.jboss.chap2.ex0;
2.  
3. import java.io.File;
4. import java.net.URL;
5. import java.net.URLClassLoader;
6. import java.lang.reflect.Method;
7.  
8. import org.apache.log4j.Logger;
9.  
10. import org.jboss.util.ChapterExRepository;
11. import org.jboss.util.Debug;
12.  
13. /** An example of IllegalAccessExceptions due to classes loaded by two class
14. * loaders.
15. * @author Scott.Stark@jboss.org
16. * @version $Revision: 1.2$
17. */
18. public class ExIAEd
19. {
20. public static void main(String[] args) throws Exception
21. {
22. ChapterExRepository.init(ExIAEd.class);
23.  
24. String chapDir = System.getProperty("chapter.dir");
25. Logger ucl0Log = Logger.getLogger("UCL0");
26. File jar0 = new File(chapDir+"/j0.jar");
27. ucl0Log.info("jar0 path: "+jar0.toString());
28. URL[] cp0 = {jar0.toURL()};
29. URLClassLoader ucl0 = new URLClassLoader(cp0);
30. Thread.currentThread().setContextClassLoader(ucl0);
31.  
32. StringBuffer buffer = new StringBuffer("ExIAEd Info");
33. Debug.displayClassInfo(ExIAEd.class, buffer, false);
34. ucl0Log.info(buffer.toString());
35.  
36. Class ctxClass1 = ucl0.loadClass("org.jboss.chap2.ex0.ExCtx");
37. buffer.setLength(0);
38. buffer.append("ExCtx Info");
39. Debug.displayClassInfo(ctxClass1, buffer, false);
40. ucl0Log.info(buffer.toString());
41. Object ctx0 = ctxClass1.newInstance();
42.  
43. try
44. {
45. Class[] types = {Object.class};
46. Method useValue = ctxClass1.getDeclaredMethod("pkgUseValue", types);
47. Object[] margs = {null};
48. useValue.invoke(ctx0, margs);
49. }
50. catch(Exception e)
51. {
52. ucl0Log.error("Failed to invoke ExCtx.pkgUseValue", e);
53. }
54. }
55. }

The ExIAEd.main method uses reflection to load the ExCtx class via the ucl0 URLClassLoaders while the ExIEAd class was loaded by the application class loader. We will run this example to demonstrate how the IllegalAccessException can occur and then look at the specific issue with the example. Run the example using the following command:

[orb@toki examples]$ ant -Dchap=chap2 -Dex=0d run-example

Buildfile: build.xml

...

[java] [ERROR,UCL0] Failed to invoke ExCtx.pkgUseValue

[java] java.lang.IllegalAccessException: Class org.jboss.chap2.ex0.ExIAEd can not access a member of class org.jboss.chap2.ex0.ExCtx with modifiers ""

[java] at sun.reflect.Reflection.ensureMemberAccess(Reflection.java:57)

[java] at java.lang.reflect.Method.invoke(Method.java:317)

[java] at org.jboss.chap2.ex0.ExIAEd.main(ExIAEd.java:48)

 

The truncated output shown here illustrates the IllegalAccessException . The full output can be found in the logs/chap2-ex0d.log file. At line 48 of ExIAEd.java the ExCtx.pkgUseValue(Object) method is invoked via reflection. The pkgUseValue method has package protected access and even though both the invoking class ExIAEd and the ExCtx class whose method is being invoked reside in the org.jboss.chap2.ex0 package, the invocation is seen to be invalid due to the fact that the two classes are loaded by different class loaders. This can be seen by looking at the debugging output from the chap2-ex0d.log file. The key lines are:

[INFO,UCL0] ExIAEd Info

org.jboss.chap2.ex0.ExIAEd(65855a).ClassLoader=sun.misc.Launcher$AppClassLoader@3f52a5

..sun.misc.Launcher$AppClassLoader@3f52a5

...

[INFO,UCL0] ExCtx Info

org.jboss.chap2.ex0.ExCtx(70eed6).ClassLoader=java.net.URLClassLoader@113fe2

..java.net.URLClassLoader@113fe2

...

The ExIAEd class is seen to have been loaded via the default application class loader instance sun.misc.Launcher$AppClassLoader@3f52a5 , while the ExCtx class was loaded by the java.net.URLClassLoader@113fe2 instance. Because the classes are loaded by different class loaders, access to the package protected method is seen to be a security violation. So, not only is type a function of both the fully qualified class name and class loader, the package scope is as well.

An example of how this can happen in practise is to include the same classes in two different SAR deployments. If classes in the deployment have a package protected relationship, users of the sar service may end up loading one class from SAR class loading at one point, and then load another class from the second SAR at a later time. If the two classes in question have a protected access relationship an IllegalAccessError will result. The solution is to either include the classes in a separate jar that is referenced by the SARs, or to combine the SARs into a single deployment. This can either be a single SAR, or an EAR the includes both SARs.

Classes demonstrating the need for loading constraints

class

{

void f()

{

x = .g();

x.secret_value = 1; // Should not be allowed

}

}

----------------------------------------------------------------------------

class

{

static g() {...}

}

----------------------------------------------------------------------------

class

{

public int secret_value;

}

----------------------------------------------------------------------------

class

{

private int secret_value;

}

The class C is defined by L 1 and so L 1 is used to initiate loading of the classes Spoofed and Delegated referenced in the C.f() method. The Spoofed class is defined by L 1 , but Delegated is defined by L 2 because L 1 delegates to L 2 . Since Delegated is defined by L 2 , L 2 will be used to initiate loading of Spoofed in the context of the Delegated.g() method. In this example both L 1 and L 2 define different versions of Spoofed as indicated by the two versions shown at the end of See Classes demonstrating the need for loading constraints.. Since C.f() believes x is an instance of it is able to access the private field scecret_value of returned by Delegated.g() due to the 1.1 and earlier Java VM's failure to take into account that a class type is determined by both the fully qualified name of the class and the defining class loader.

Java 1.2 and beyond addresses this problem by generating loader constraints to validate type consistency when the types being used are coming from different defining class loaders. For the See Classes demonstrating the need for loading constraints. example, the VM generates a constraint when the first line of method C.f() is verified to indicate that the type Spoofed must be the same regardless of whether the load of Spoofed is initiated by L 1 or L 2 . It does not matter if L 1 or L 2 , or even some other class loader defines Spoofed . All that matters is that there is only one Spoofed class defined regardless of whether L 1 or L 2 was used to initiate the loading. If L 1 or L 2 have already defined separate versions of Spoofed when this check is made a LinkageError will be generated immediately. Otherwise, the constraint will be recorded and when Delegated.g() is executed, any attempt to load a duplicate version of Spoofed will result in a LinkageError .

Now let's take a look at how a LinkageError can occur with a concrete example. See A concrete example of a LinkageError. gives the example main class along with the custom class loader used.

A concrete example of a LinkageError

1. package org.jboss.chap2.ex0;
2.  
3. import java.io.File;
4. import java.net.URL;
5.  
6. import org.apache.log4j.Logger;
7. import org.jboss.util.ChapterExRepository;
8. import org.jboss.util.Debug;
9.  
10. /** An example of a LinkageError due to classes being defined by more than
11. * one class loader in a non-standard class loading environment.
12. * @author Scott.Stark@jboss.org
13. * @version $Revision: 1.1$
14. */
15. public class ExLE
16. {
17. public static void main(String[] args) throws Exception
18. {
19. ChapterExRepository.init(ExLE.class);
20.  
21. String chapDir = System.getProperty("chapter.dir");
22. Logger ucl0Log = Logger.getLogger("UCL0");
23. File jar0 = new File(chapDir+"/j0.jar");
24. ucl0Log.info("jar0 path: "+jar0.toString());
25. URL[] cp0 = {jar0.toURL()};
26. Ex0URLClassLoader ucl0 = new Ex0URLClassLoader(cp0);
27. Thread.currentThread().setContextClassLoader(ucl0);
28. Class ctxClass1 = ucl0.loadClass("org.jboss.chap2.ex0.ExCtx");
29. Class obj2Class1 = ucl0.loadClass("org.jboss.chap2.ex0.ExObj2");
30. StringBuffer buffer = new StringBuffer("ExCtx Info");
31. Debug.displayClassInfo(ctxClass1, buffer, false);
32. ucl0Log.info(buffer.toString());
33. buffer.setLength(0);
34. buffer.append("ExObj2 Info, UCL0");
35. Debug.displayClassInfo(obj2Class1, buffer, false);
36. ucl0Log.info(buffer.toString());
37.  
38. File jar1 = new File(chapDir+"/j1.jar");
39. Logger ucl1Log = Logger.getLogger("UCL1");
40. ucl1Log.info("jar1 path: "+jar1.toString());
41. URL[] cp1 = {jar1.toURL()};
42. Ex0URLClassLoader ucl1 = new Ex0URLClassLoader(cp1);
43. Class obj2Class2 = ucl1.loadClass("org.jboss.chap2.ex0.ExObj2");
44. buffer.setLength(0);
45. buffer.append("ExObj2 Info, UCL1");
46. Debug.displayClassInfo(obj2Class2, buffer, false);
47. ucl1Log.info(buffer.toString());
48.  
49. ucl0.setDelegate(ucl1);
50. try
51. {
52. ucl0Log.info("Try ExCtx.newInstance()");
53. Object ctx0 = ctxClass1.newInstance();
54. ucl0Log.info("ExCtx.ctor succeeded, ctx0: "+ctx0);
55. }
56. catch(Throwable e)
57. {
58. ucl0Log.error("ExCtx.ctor failed", e);
59. }
60. }
61. }

----------------------------------------------------------------------------

1. package org.jboss.chap2.ex0;
2.  
3. import java.net.URLClassLoader;
4. import java.net.URL;
5.  
6. import org.apache.log4j.Logger;
7.  
8. /** A custom class loader that overrides the standard parent delegation model
9. * @author Scott.Stark@jboss.org
10. * @version $Revision:$
11. */
12. public class Ex0URLClassLoader extends URLClassLoader
13. {
14.  
15. private static Logger log = Logger.getLogger(Ex0URLClassLoader.class);
16. private Ex0URLClassLoader delegate;
17.  
18. public Ex0URLClassLoader(URL[] urls)
19. {
20. super(urls);
21. }
22.  
23. void setDelegate(Ex0URLClassLoader delegate)
24. {
25. this.delegate = delegate;
26. }
27.  
28. protected synchronized Class loadClass(String name, boolean resolve)
29. throws ClassNotFoundException
30. {
31. Class clazz = null;
32. if( delegate != null )
33. {
34. log.debug(Integer.toHexString(hashCode())+"; Asking delegate to loadClass: "+name);
35. clazz = delegate.loadClass(name, resolve);
36. log.debug(Integer.toHexString(hashCode())+"; Delegate returned: "+clazz);
37. }
38. else
39. {
40. log.debug(Integer.toHexString(hashCode())+"; Asking super to loadClass: "+name);
41. clazz = super.loadClass(name, resolve);
42. log.debug(Integer.toHexString(hashCode())+"; Super returned: "+clazz);
43. }
44. return clazz;
45. }
46.  
47. protected Class findClass(String name)
48. throws ClassNotFoundException
49. {
50. Class clazz = null;
51. log.debug(Integer.toHexString(hashCode())+"; Asking super to findClass: "+name);
52. clazz = super.findClass(name);
53. log.debug(Integer.toHexString(hashCode())+"; Super returned: "+clazz);
54. return clazz;
55. }
56. }

The key component in this example is the URLClassLoader subclass Ex0URLClassLoader . This class loader implementation overrides the default parent delegation model to allow the ucl0 and ucl1 instances to both load the ExObj2 class and then setup a delegation relationship from ucl0 to ucl1. At lines 28 and 29 of ExLE.main the ucl0 Ex0URLClassLoader is used to load the ExCtx and ExObj2 classes. At line 43 of ExLE.main the ucl1 Ex0URLClassLoader is used to load the ExObj2 class again. At this point both the ucl0 and ucl1 class loaders have defined the ExObj2 class. A delegation relationship from ucl0 to ucl1 is then setup at line 49 via the ucl0.setDelegate(ucl1) method call. Finally, at line 53 of ExLE.main an instance of ExCtx is created using the class loaded via ucl0. The ExCtx class is the same as presented in See The ExCtx, ExObj, and ExObj2 classes used by the examples., and the constructor was:

1. public ExCtx() throws IOException
2. {
3. value = new ExObj();
4. Logger log = Logger.getLogger(ExCtx.class);
5. StringBuffer buffer = new StringBuffer("ctor.ExObj");
6. Debug.displayClassInfo(value.getClass(), buffer, false);
7. log.info(buffer.toString());
8. ExObj2 obj2 = value.ivar;
9. buffer.setLength(0);
10. buffer = new StringBuffer("ctor.ExObj.ivar");
11. Debug.displayClassInfo(obj2.getClass(), buffer, false);
12. log.info(buffer.toString());
13. }

Now, since the ExCtx class was defined by the ucl0 class loader, and at the time the ExCtx constructor is executed, ucl0 delegates to ucl1, line 24 of the ExCtx constructor involves the following expression which has been rewritten in terms of the complete type expressions:

 

This generates a loading constraint of since the ExObj2 type must be consistent across the ucl0 and ucl1 class loader instances. Because we have loaded ExObj2 using both ucl0 and ucl1 prior to setting up the delegation relationship, the constraint will be violated and should generate a LinkageError when run. Run the example using the following command:

[nr@toki examples]$ ant -Dchap=chap2 -Dex=0e run-example

Buildfile: build.xml

...

[java] java.lang.LinkageError: loader constraints violated when linking org/jboss/chap2/ex0/ExObj2 class

[java] at org.jboss.chap2.ex0.ExCtx.<init>(ExCtx.java:24)

[java] at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)

[java] at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:39)

[java] at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:27)

[java] at java.lang.reflect.Constructor.newInstance(Constructor.java:274)

[java] at java.lang.Class.newInstance0(Class.java:308)

[java] at java.lang.Class.newInstance(Class.java:261)

[java] at org.jboss.chap2.ex0.ExLE.main(ExLE.java:53)

 

As expected, a LinkageError is thrown while validating the loader constraints required by line 24 of the ExCtx constructor.

Debugging Class Loading Issues

FIGURE 2-3. The JBoss 3.x core class loading components

The central component is the org.jboss.mx.loading.UnifiedClassLoader3 (UCL) class loader. This is an extension of the standard java.net.URLClassLoader that overrides the standard parent delegation model to use a shared repository of classes and resources. This shared repository is the org.jboss.mx.loading.UnifiedLoaderRepository3 . Every UCL is associated with a single UnifiedLoaderRepository3 , and a UnifiedLoaderRepository3 typically has many UCLs. As of the 3.0.5RC1 release, a UCL may have multiple URLs associated with it for class and resource loading. Prior to this release, a UCL always was associated with a single URL. This could lead to IllegalAccessExceptions and LikageErrors due to packaging issues we saw in the previous sections where we discussed how these types of errors can arise when multiple class loaders exist. With the 3.0.5RC1 release, deployers use the top-level deployment's UCL as a shared class loader and all deployment archives are assigned to this class loader. We will talk about the JBoss deployers and their interaction with the class loading system in more detail latter in the section JBoss MBean Services.

When a UCL is asked to load a class, it first looks to the repository cache it is associated with to see if the class has already been loaded. Only if the class does not exist in the repository will it be loaded into the repository by the UCL. By default, there is a single UnifiedLoaderRepository3 shared across all UCL instances. This means the UCLs form a single flat class loader namespace. The complete sequence of steps that occur when a UnfiedClassLoader3.loadClass(String, boolean) method is called is:

1. Check the UnifiedLoaderRepository3 classes cache associated with the UnfiedClassLoader3 . If the class is found in the cache it is returned.
2. Else, ask the UnfiedClassLoader3 if it can load the class. This is essentially a call to the superclass URLClassLoader.loadClass(String, boolean) method to see if the class is among the URLs associated with the class loader, or visible to the parent class loader. If the class is found it is placed into the repository classes cache and returned.
3. Else, the repository is queried for all UCLs that are capable of providing the class based on the repository package name to UCL map. When a UCL is added to a repository an association between the package names available in the URLs associated with the UCL is made, and a mapping from package names to the UCLs with classes in the package is updated. This allows for a quick determination of which UCLs are capable of loading the class. The UCLs are then queried for the requested class in the order in which the UCLs were added to the repository. If a UCL is found that can load the class it is returned, else a java.lang.ClassNotFoundException is thrown.

Viewing Classes in the Loader Repository

Another useful source of information on classes is the UnifiedLoaderRepository itself. This is an MBean that contains operations to display class and package information. The default repository is located under a standard JMX name of "JMImplementation:name=Default,service=LoaderRepository", and its MBean can be accessed via the JMX console by following its link from the front page. This hyperlink: LoaderRepository takes you to the JMX console view shown in See The default class LoaderRepository MBean view in the JMX console.. We discuss the JMX console in the next section, Connecting to the JMX Server.

 

Scoping Classes

If you need to deploy multiple versions of an application the default 3.x class loading model would require that each application be deployed in a separate JBoss server. Sometimes this is desirable as you have more control over security and resource monitoring, but it can be difficult to manage multiple server instances. An alternative mechanism exists that allows multiple versions of an application to be deployed using deployment based scoping.

With deployment based scoping, each deployment creates its own class loader repository in the form of a HeirarchicalLoaderRepository3 that looks first to the UnifiedClassLoader3 instances of the deployment units included in the EAR before delegating to the default UnifiedLoaderRepository3 . To enable an EAR specific loader repository, you need to create a META-INF/jboss-app.xml descriptor as shown in See An example jboss-app.xml descriptor for enabled scoped class loading at the ear level..

The Complete Class Loading Model

The previous discussion of the core class loading components introduced the custom UnifiedClassLoader3 and UnifiedLoaderRepository3 classes that form a shared class loading space. The complete class loading picture must also include the parent class loader used by UnifiedClassLoader3 s as well as class loaders introduced for scoping and other speciality class loading purposes. See A complete class loader view. shows an outline of the class hierarchy that would exist for an EAR deployment containing EJBs and WARs.

 

FIGURE 2-7. The descriptors element content model

The key descriptors child elements include:

• interceptors: The interceptors element specifies a customized stack of interceptors that will be used in place of the default stack. Currently this is only used when specified at the mbean level, but it could define a custom attribute or operation level interceptor stack in the future. The content of the interceptors element specifies a custom interceptor stack. If no interceptors element is specified the standard ModelMBean interceptors will be used. The standard interceptors are:
• org.jboss.mx.interceptor.PersistenceInterceptor
• org.jboss.mx.interceptor.MBeanAttributeInterceptor
• org.jboss.mx.interceptor.ObjectReferenceInterceptor

When specifying a custom interceptor stack you would typically include the standard interceptors along with your own unless you are replacing the corresponding standard interceptor.

Each interceptor element content value specifies the fully qualified class name of the interceptor implementation, and the class must implement the org.jboss.mx.interceptor.Interceptor interface. The interceptor class must also have either a no-arg constructor, or a constructor that accepts a ( javax.management.MBeanInfo , org.jboss.mx.server.MBeanInvoker ) pair.

The interceptor elements may have any number of attributes that correspond to JavaBean style properties on the interceptor class implementation. For each interceptor element attribute specified, the interceptor class is queried for a matching setter method. The attribute value is converted to the true type of the interceptor class property using the java.beans.PropertyEditor associated with the type. It is an error to specify an attribute for which there is no setter or PropertyEditor .

• persistence: The persistence element allows the specification of the persistPolicy, persistPeriod, persistLocation, and persistName persistence attributes suggested by the JMX specification. The persistence element attributes are:
• persistPolicy: The persistPolicy attribute defines when attributes should be persisted and its value must be one of:
• Never, attribute values are transient values that are never persisted
• OnUpdate, attribute values are persisted whenever they are updated
• OnTimer, attribute values are persisted based on the time given by the persistPeriod.
• NoMoreOftenThan, attribute values are persisted when updated unless but no more oten than the persistPeriod.
• persistPeriod: The persistPeriod attribute gives the update frequency in milliseconds if the perisitPolicy attribute is NoMoreOftenThan or OnTimer.
• persistLocation: The persistLocation attribute specifies the location of the persistence store. Its form depends on the JMX peristence implementation. Currently this should refer to a directory into which the attributes will be serialized if using the default JBoss persistence manager.
• persistName: The persistName attribute can be used in conjunction with the persistLocation attribute to further qualify the persistent store location. For a directory persistLocation the persistName specifies the file to which the attributes are stored within the directory.
• currencyTimeLimit: The currencyTimeLimit element specifies the time in seconds that a cached value of an attribute remains valid. Its value attribute gives the time in seconds. A 0 value indicates that an attribute value should always be retrieved from the mbean and never cached. A -1 value indicates that a cache value is always valid.
• state-action-on-update: The state-action-on-update element specifies the what happens to an mbean when one of its attributes is updated. The action is given by the value attribute. Its value attribute defines what happens to the mbean lifecycle state when one of its attributes is update. It must be one of:
• keep-running,
• restart,
• reconfigure,
• reinstantiate

However, note that this descriptor is not currently used.

• display-name: The display-name element specifies the human friendly name of an item.
• default: The default element specifes a default value to use when a field has not been set. Note that this value is not written to the MBean on startup as is the case with the jboss-service.xml attribute element content value. Rather, the default value is used only if there is no attribute accessor defined, and there is no value element defined.
• value: The value element specifies a management attribute's current value. Unlike the default element, the value element is written through to the MBean on startup provided there is a setter method available.
• persistence-manager: The persistence-manager element give the name of a class to use as the persistence manager. The value attribute specifies the class name that supplies the org.jboss.mx.persistence.PersistenceManager interface implementation. The only implementation currently supplied by JBoss is the org.jboss.mx.persistence.ObjectStreamPersistenceManager which serializes the ModelMBeanInfo content to a file using Java serialization.
• descriptor: The descriptor element specifies an arbitrary descriptor not know to JBoss. Its name attribute specifies the type of the descriptor and its value attribute specifies the descriptor value. The descriptor element allows for the attachment of arbitrary management metadata.

Note that any of the constructor, attribute, operation or notification elements may have a descriptors element to specify the specification defined descriptors as well as arbitrary extension descriptor settings.

FIGURE 2-8. The XMBean constructor element and its content model

The key child elements are:

• description: A description of the constructor.
• name: The name of the constructor, which must be the same as the implementation class.
• parameter: The parameter element describes a constructor parameter. The parameter element has the following attributes:
• description: An optional description of the parameter.
• name: The required variable name of the parameter.
• type: The required fully qualified class name of the parameter type.
• descriptors: Any descriptors to associate with the constructor metadata.

FIGURE 2-9. The XMBean attribute element and its content model

The attribute element supported attributes include:

• access: The optional access attribute defines the read/write access modes of an attribute. It must be one of:
• read-only: The attribute may only be read.
• write-only: The attribute may only be written.
• read-write: The at