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 attribute is both readable and writable. This is the implied default.
• getMethod: The getMethod attribute defines the name of the method which reads the named attribute. This must be specified if the managed attribute should be obtained from the MBean instance.
• setMethod: The setMethod attribute defines the name of the method which writes the named attribute. This must be specified if the managed attribute should be obtained from the mbean instance.

The key child elements of the attribute element include:

• description: A description of the attribute.
• name: The name of the attribute as would be used in the MBeanServer.getAttribute() operation.
• type: The fully qualified class name of the attribute type.
• descriptors: Any additional desciptors that affect the attribute persistence, caching, default value, etc.

FIGURE 2-10. The XMBean operation element and its content model

The impact attribute defines the impact of executing the operation and must be one of:

• ACTION, The operation changes the state of the MBean component (write operation)
• INFO, The operation should not alter the state of the MBean component (read operation).
• ACTION_INFO, The operation behaves like a read/write operation.

The child elements are:

• description: This element specifies a human readable description of the operation.
• name: This element contains the operation's name
• parameter: This element describe the operation's signature.
• return-type: This element contains a fully qualified class name of the return type from this operation. If not specified it defaults to void.
• descriptors: Any descriptors to associate with the operation metadata.

FIGURE 2-11. The XMBean notification element and content model.

The child elements are:

• description: This element gives a human readable description of the notification.
• name: This element contains the fully qualified name of the notification class.
• notification-type: This element contains the dot-separated notification type string.
• descriptors: Any descriptors to associate with the notification metadata.

For a reference of the complete DTD content model see the expanded view of the complete provided in See An expanded view of the jboss_xmbean_1_0 DTD.. We will work through examples of creating an XMBeans when we discuss the JBoss MBean services notion. See XMBean Examples. for these examples.

FIGURE 2-12. An expanded view of the jboss_xmbean_1_0 DTD

The jmx-console.war web.xml and jboss-web.xml descriptors with the security elements uncommented.

<?xml version="1.0"?>

<!DOCTYPE web-app PUBLIC

"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"

"http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>

...

<!-- A security constraint that restricts access to the HTML JMX console

to users with the role JBossAdmin. Edit the roles to what you want and

uncomment the WEB-INF/jboss-web.xml/security-domain element to enable

secured access to the HTML JMX console.

-->

<security-constraint>

<web-resource-collection>

<web-resource-name>HtmlAdaptor</web-resource-name>

<description>An example security config that only allows users with the

role JBossAdmin to access the HTML JMX console web application

</description>

<url-pattern>/*</url-pattern>

<http-method>GET</http-method>

<http-method>POST</http-method>

</web-resource-collection>

<auth-constraint>

<role-name>JBossAdmin</role-name>

</auth-constraint>

</security-constraint>

<login-config>

<auth-method>BASIC</auth-method>

<realm-name>JBoss JMX Console</realm-name>

</login-config>

<security-role>

<role-name>JBossAdmin</role-name>

</security-role>

</web-app>

<jboss-web>

<!-- Uncomment the security-domain to enable security. You will

need to edit the htmladaptor login configuration to setup the

login modules used to authentication users.

-->

<security-domain>java:/jaas/jmx-console</security-domain>

</jboss-web>

Make these changes and either with the server running or prior to starting and then when you try to access the jmx-console URL you will see a dialog similar to that shown in See The jmx-console basic HTTP login dialog presented after making the changes shown in Listing 2-11...

FIGURE 2-15. The jmx-console basic HTTP login dialog presented after making the changes shown in See The jmx-console.war web.xml and jboss-web.xml descriptors with the security elements uncommented...

Its generally a bad idea to use the properties files for securing access to the JMX console application. To see how to properly configure the security settings of web applications see Chapter 8.

To test the client access using the RMIAdaptor , run the following:

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

Buildfile: build.xml

validate:

[java] ImplementationTitle: JBoss [WonderLand]

[java] ImplementationVendor: JBoss.org

[java] ImplementationVersion: 3.2.3 (build: CVSTag=JBoss_3_2_3 date=200311301445)

[java] SpecificationTitle: JBoss

[java] SpecificationVendor: JBoss (http://www.jboss.org/)

[java] SpecificationVersion: 3.2.3

[java] JBoss version is: 3.2.3

fail_if_not_valid:

init:

[echo] Using jboss.dist=/Users/orb/java/jboss-3.2.3

compile:

[javac] Compiling 3 source files to /Users/orb/Desktop/jboss/AdminDevel 2/examples/output/classes

run-example:

run-example4:

[java] JNDIView Class: org.jboss.mx.modelmbean.XMBean

[java] JNDIView Operations:

[java] + java.lang.String list(boolean jboss:service=JNDIView)

[java] + java.lang.String listXML()

[java] + void create()

[java] + void start()

[java] + void stop()

[java] + void destroy()

[java] + java.lang.String getName()

[java] + int getState()

[java] + java.lang.String getStateString()

[java] JNDIView.list(true) output:

[java] <h1>Ejb Module: ClusteredHttpSessionEB.jar</h1>

[java] <h2>java:comp namespace of the ClusteredHTTPSession bean:</h2>

[java] <pre>

[java] +- env (class: org.jnp.interfaces.NamingContext)

[java] </pre>

[java] <h1>java: Namespace</h1>

[java] <pre>

[java] +- jaas (class: javax.naming.Context)

[java] | +- jbossmq-httpil (class: org.jboss.security.plugins.SecurityDomainContext)

[java] | +- other (class: org.jboss.security.plugins.SecurityDomainContext)

[java] | +- JmsXARealm (class: org.jboss.security.plugins.SecurityDomainContext)

[java] | +- jbosstest-web (class: org.jboss.security.plugins.SecurityDomainContext)

[java] | +- http-invoker (class: org.jboss.security.plugins.SecurityDomainContext)

[java] | +- jbossmq (class: org.jboss.security.plugins.SecurityDomainContext)

[java] | +- secure-jndi (class: org.jboss.security.plugins.SecurityDomainContext)

[java] | +- HsqlDbRealm (class: org.jboss.security.plugins.SecurityDomainContext)

[java] +- TransactionPropagationContextImporter (class: org.jboss.tm.TransactionPropagationContextImporter)

[java] +- JmsXA (class: org.jboss.resource.adapter.jms.JmsConnectionFactoryImpl)

[java] +- JBossCorbaNaming (class: org.omg.CosNaming.NamingContextExt)

[java] +- DefaultDS (class: org.jboss.resource.adapter.jdbc.WrapperDataSource)

[java] +- StdJMSPool (class: org.jboss.jms.asf.StdServerSessionPoolFactory)

[java] +- TransactionManager (class: org.jboss.tm.TxManager)

[java] +- JBossCorbaPOA (class: org.omg.PortableServer.POA)

[java] +- TransactionPropagationContextExporter (class: org.jboss.tm.TransactionPropagationContextFactory)

[java] +- ConnectionFactory (class: org.jboss.mq.SpyConnectionFactory)

[java] +- DefaultJMSProvider (class: org.jboss.jms.jndi.JBossMQProvider)

[java] +- XAConnectionFactory (class: org.jboss.mq.SpyXAConnectionFactory)

[java] +- JBossCorbaInterfaceRepositoryPOA (class: org.omg.PortableServer.POA)

[java] +- Mail (class: javax.mail.Session)

[java] +- JBossCorbaORB (class: org.omg.CORBA.ORB)

[java] +- cmrTransactionTest (class: org.jnp.interfaces.NamingContext)

[java] +- timedCacheFactory (class: javax.naming.Context)

[java] Failed to lookup: timedCacheFactory, errmsg=null

[java] +- SecurityProxyFactory (class: org.jboss.security.SubjectSecurityProxyFactory)

[java] +- comp (class: javax.naming.Context)

[java] </pre>

[java] <h1>Global JNDI Namespace</h1>

[java] <pre>

[java] +- OIL2ConnectionFactory (class: org.jboss.mq.SpyConnectionFactory)

[java] +- hello (class: org.jnp.interfaces.NamingContext)

[java] +- HAPartition (class: org.jnp.interfaces.NamingContext)

[java] | +- DefaultPartition (class: org.jboss.ha.framework.server.HAPartitionImpl)

[java] +- helloworld (class: org.jnp.interfaces.NamingContext)

[java] +- jbosstest (class: org.jnp.interfaces.NamingContext)

[java] | +- ejbs (class: org.jnp.interfaces.NamingContext)

[java] | | +- local (class: org.jnp.interfaces.NamingContext)

[java] +- XAConnectionFactory (class: org.jboss.mq.SpyXAConnectionFactory)

[java] +- queue (class: org.jnp.interfaces.NamingContext)

[java] | +- D (class: org.jboss.mq.SpyQueue)

[java] | +- C (class: org.jboss.mq.SpyQueue)

[java] | +- B (class: org.jboss.mq.SpyQueue)

[java] | +- A (class: org.jboss.mq.SpyQueue)

[java] | +- testQueue (class: org.jboss.mq.SpyQueue)

[java] | +- ex (class: org.jboss.mq.SpyQueue)

[java] | +- testObjectMessage (class: org.jboss.mq.SpyQueue)

[java] | +- DLQ (class: org.jboss.mq.SpyQueue)

[java] +- test (class: org.jnp.interfaces.NamingContext)

[java] | +- entity (class: org.jnp.interfaces.NamingContext)

[java] +- RMIConnectionFactory (class: org.jboss.mq.SpyConnectionFactory)

[java] +- exception (class: org.jnp.interfaces.NamingContext)

[java] +- UUIDKeyGeneratorFactory (class: org.jboss.ejb.plugins.keygenerator.uuid.UUIDKeyGeneratorFactory)

[java] +- testTCF[link -> ConnectionFactory] (class: javax.naming.LinkRef)

[java] +- ENCTests (class: org.jnp.interfaces.NamingContext)

[java] | +- ejbs (class: org.jnp.interfaces.NamingContext)

[java] +- idgen (class: org.jnp.interfaces.NamingContext)

[java] +- ejbcts2 (class: org.jnp.interfaces.NamingContext)

[java] +- commerce (class: org.jnp.interfaces.NamingContext)

[java] +- UIL2ConnectionFactory (class: org.jboss.mq.SpyConnectionFactory)

[java] +- UserTransactionSessionFactory (proxy: $Proxy10 implements interface org.jboss.tm.usertx.interfaces.UserTransactionSessionFactory)

[java] +- UILXAConnectionFactory[link -> UIL2XAConnectionFactory] (class: javax.naming.LinkRef)

[java] +- relation (class: org.jnp.interfaces.NamingContext)

[java] | +- manyToMany (class: org.jnp.interfaces.NamingContext)

[java] | | +- bidirectional (class: org.jnp.interfaces.NamingContext)

[java] | | +- unidirectional (class: org.jnp.interfaces.NamingContext)

[java] | +- manyToOne (class: org.jnp.interfaces.NamingContext)

[java] | | +- unidirectional (class: org.jnp.interfaces.NamingContext)

[java] | | | +- table (class: org.jnp.interfaces.NamingContext)

[java] | | | +- fk (class: org.jnp.interfaces.NamingContext)

[java] | +- oneToMany (class: org.jnp.interfaces.NamingContext)

[java] | | +- bidirectional (class: org.jnp.interfaces.NamingContext)

[java] | | | +- table (class: org.jnp.interfaces.NamingContext)

[java] | | | +- fk (class: org.jnp.interfaces.NamingContext)

[java] | | +- unidirectional (class: org.jnp.interfaces.NamingContext)

[java] | | | +- table (class: org.jnp.interfaces.NamingContext)

[java] | | | +- fk (class: org.jnp.interfaces.NamingContext)

[java] | +- oneToOne (class: org.jnp.interfaces.NamingContext)

[java] | | +- bidirectional (class: org.jnp.interfaces.NamingContext)

[java] | | | +- table (class: org.jnp.interfaces.NamingContext)

[java] | | | +- fk (class: org.jnp.interfaces.NamingContext)

[java] | | +- unidirectional (class: org.jnp.interfaces.NamingContext)

[java] | | | +- table (class: org.jnp.interfaces.NamingContext)

[java] | | | +- fk (class: org.jnp.interfaces.NamingContext)

[java] +- console (class: org.jnp.interfaces.NamingContext)

[java] | +- PluginManager (proxy: $Proxy26 implements interface org.jboss.console.manager.PluginManagerMBean)

[java] +- HTTPXAConnectionFactory (class: org.jboss.mq.SpyXAConnectionFactory)

[java] +- topic (class: org.jnp.interfaces.NamingContext)

[java] | +- testDurableTopic (class: org.jboss.mq.SpyTopic)

[java] | +- testTopic (class: org.jboss.mq.SpyTopic)

[java] | +- securedTopic (class: org.jboss.mq.SpyTopic)

[java] +- testQCF[link -> ConnectionFactory] (class: javax.naming.LinkRef)

[java] +- HAILXAConnectionFactory (class: org.jboss.mq.SpyXAConnectionFactory)

[java] +- ejb (class: org.jnp.interfaces.NamingContext)

[java] | +- local (class: org.jnp.interfaces.NamingContext)

[java] | +- jca (class: org.jnp.interfaces.NamingContext)

[java] | +- remote (class: org.jnp.interfaces.NamingContext)

[java] +- cmrTransactionTest (class: org.jnp.interfaces.NamingContext)

[java] +- UserTransaction (class: org.jboss.tm.usertx.client.ClientUserTransaction)

[java] +- HTTPConnectionFactory (class: org.jboss.mq.SpyConnectionFactory)

[java] +- arrays (class: org.jnp.interfaces.NamingContext)

[java] +- RMIXAConnectionFactory (class: org.jboss.mq.SpyXAConnectionFactory)

[java] +- HAILConnectionFactory (class: org.jboss.mq.SpyConnectionFactory)

[java] +- anotherContext (class: org.jnp.interfaces.NamingContext)

[java] | +- TopicInADifferentContext[link -> topic/myMDBTopic] (class: javax.naming.LinkRef)

[java] | +- QueueInADifferentContext[link -> queue/myMDBQueue] (class: javax.naming.LinkRef)

[java] +- psuedo-url: (class: org.jnp.interfaces.NamingContext)

[java] | +- ejb (class: org.jnp.interfaces.NamingContext)

[java] +- local (class: org.jnp.interfaces.NamingContext)

[java] +- eardeployment (class: org.jnp.interfaces.NamingContext)

[java] +- OIL2XAConnectionFactory (class: org.jboss.mq.SpyXAConnectionFactory)

[java] +- HASessionState (class: org.jnp.interfaces.NamingContext)

[java] | +- Default (class: org.jboss.ha.hasessionstate.server.HASessionStateImpl)

[java] +- ejbcts (class: org.jnp.interfaces.NamingContext)

[java] +- UIL2XAConnectionFactory (class: org.jboss.mq.SpyXAConnectionFactory)

[java] +- naming (class: org.jnp.interfaces.NamingContext)

[java] | +- local (class: org.jnp.interfaces.NamingContext)

[java] +- invokers (class: org.jnp.interfaces.NamingContext)

[java] | +- toki.local (class: org.jnp.interfaces.NamingContext)

[java] | | +- iiop (class: org.jboss.invocation.iiop.IIOPInvoker)

[java] | | +- http (class: org.jboss.invocation.http.interfaces.HttpInvokerProxy)

[java] | +- 0.0.0.0 (class: org.jnp.interfaces.NamingContext)

[java] | | +- pooled (class: org.jboss.invocation.pooled.interfaces.PooledInvokerProxy)

[java] +- UILConnectionFactory[link -> UIL2ConnectionFactory] (class: javax.naming.LinkRef)

[java] +- jmx (class: org.jnp.interfaces.NamingContext)

[java] | +- invoker (class: org.jnp.interfaces.NamingContext)

[java] | | +- RMIAdaptor (proxy: $Proxy25 implements interface org.jboss.jmx.adaptor.rmi.RMIAdaptor)

[java] | +- rmi (class: org.jnp.interfaces.NamingContext)

[java] | | +- RMIAdaptor[link -> jmx/invoker/RMIAdaptor] (class: javax.naming.LinkRef)

[java] +- clustering (class: org.jnp.interfaces.NamingContext)

[java] | +- HTTPSession (proxy: $Proxy31 implements interface org.jboss.ha.httpsession.beanimpl.interfaces.ClusteredHTTPSessionHome,interface javax.ejb.Handle)

[java] | +- LocalHTTPSession (proxy: $Proxy28 implements interface org.jboss.ha.httpsession.beanimpl.interfaces.LocalClusteredHTTPSessionHome)

[java] +- ConnectionFactory (class: org.jboss.mq.SpyConnectionFactory)

[java] +- cmp2 (class: org.jnp.interfaces.NamingContext)

[java] | +- perf (class: org.jnp.interfaces.NamingContext)

[java] | +- audit (class: org.jnp.interfaces.NamingContext)

[java] | +- readonly (class: org.jnp.interfaces.NamingContext)

[java] | +- simple (class: org.jnp.interfaces.NamingContext)

[java] | +- lob (class: org.jnp.interfaces.NamingContext)

[java] +- v2 (class: org.jnp.interfaces.NamingContext)

[java] | +- local (class: org.jnp.interfaces.NamingContext)

[java] +- v1 (class: org.jnp.interfaces.NamingContext)

[java] | +- local (class: org.jnp.interfaces.NamingContext)

[java] </pre>

FIGURE 2-16. the DTD for the MBean service descriptor parsed by the SARDeployer.

The elements of the DTD are:

• server/loader-repository: This element specifies the name of the UnifiedLoaderRepository MBean to use for the sar to provide sar level scoping of classes deployed in the sar. It is a unique JMX ObjectName string. It may also specify an arbitrary configuration by including a loader-repository-config element. The optional loaderRepositoryClass attribute specifies the fully qualified name of the loader repository implementation class. It defaults to org.jboss.mx.loading.HeirachicalLoaderRepository3 .
• server/loader-repository/loader-repository-config: This optional element specifies an arbitrary configuration that may be used to configure the loadRepositoryClass. The optional configParserClass attribute gives the fully qualified name of the org.jboss.mx.loading.LoaderRepositoryFactory.LoaderRepositoryConfigParser implementation to use to parse the loader-repository-config content.
• server/local-directory: This element specifies a path within the deployment archive that should be copied to the server/<config>/db directory for use by the MBean. The path attribute is the name of an entry within the deployment archive.
• server/classpath: This element specifies one or more external jars that should be deployed with the MBean(s). The optional archives attribute specifies a comma separated list of the jar names to load, or the "*" wild card to signify that all jars should be loaded. The wild card only works with file URLs, and http URLs if the web server supports the WEBDAV protocol. The codebase attribute specifies the URL from which the jars specified in the archive attribute should be loaded. If the codebase is a path rather than a URL string, the full URL is built by treating the codebase value as a path relative to the JBoss distribution server/<config> directory. The order of jars specified in the archives as well as the ordering across multiple classpath element is used as the classpath ordering of the jars. Therefore, if you have patches or inconsistent versions of classes that require a certain ordering, use this feature to ensure the correct ordering. Both the codebase and archives attributes values may reference a system property using a pattern "${x}" to refer to replacement of the "x" system property.
• server/mbean: This element specifies an MBean service. The required code attribute gives the fully qualified name of the MBean implementation class. The required name attribute gives the JMX ObjectName of the MBean. The optional xmbean-dd attribute specifies the path to the XMBean resource if this MBean service uses the JBoss XMBean descriptor to define a Model MBean management interface.
• server/mbean/attribute: Each attribute element specifies a name/value pair of the attribute of the MBean. The name of the attribute is given by the name attribute, and the attribute element body gives the value. The body may be a text representation of the value, or an arbitrary element and child elements if the type of the MBean attribute is org.w3c.dom.Element . For text values, the text is converted to the attribute type using the JavaBean java.beans.PropertyEditor mechanism.

As of the 3.0.5 release, the text value of an attribute may reference a system property "x" by using the pattern "${x}". In this case the value of the attribute will be the result of System.getProperty("x") , or null if no such property exists.

• server/mbean/depends and server/mbean/depends-list: these elements specify a dependency from the MBean using the element to the MBean(s) named by the depends or depends-list elements. See Specifying Service Dependencies for the details of specifying dependencies. Note that the dependency value can be another mbean element which defines a nested mbean.

When the SARDeployer is asked to deploy a service performs several steps. See A sequence diagram highlighting the main activities performed by the SARDeployer to start a JBoss MBean service.. is a sequence diagram that shows the init through start phases of a service.

FIGURE 2-17. A sequence diagram highlighting the main activities performed by the SARDeployer to start a JBoss MBean service.

The org.jboss.system.Service interface

package org.jboss.system;

public interface Service

{

public void create() throws Exception;

public void start() throws Exception;

public void stop();

public void destroy();

}

FIGURE 2-18. The interaction between the SARDeployer and ServiceController to start a service.

The ServiceController MBean has four key methods for the management of the service life cycle: create, start, stop and destroy.

The create(ObjectName) method

The create(ObjectName) method is called whenever an event occurs that affects the named services state. This could be triggered by an explicit invocation by the SARDeployer , a notification of a new Class, or another service reaching its created state.

When a service's create method is called, all services on which the service depends have also had their create method invoked. This gives an MBean an opportunity to check that required MBeans or resources exist. A service cannot utilize other MBean services at this point, as most JBoss MBean services do not become fully functional until they have been started via their start method. Because of this, service implementations often do not implement create in favor of just the start method because that is the first point at which the service can be fully functional.

The start(ObjectName) method

The start(ObjectName) method is called whenever an event occurs that affects the named services state. This could be triggered by an explicit invocation by the SARDeployer , a notification of a new Class , or another service reaching its started state.

When a service's start method is called, all services on which the service depends have also had their start method invoked. Receipt of a start method invocation signals a service to become fully operational since all services upon which the service depends have been created and started.

The stop(ObjectName) method

The stop(ObjectName) method is called whenever an event occurs that affects the named services state. This could be triggered by an explicit invocation by the SARDeployer , notification of a Class removal, or a service on which other services depend reaching its stopped state.

The destroy(ObjectName) method

The destroy(ObjectName) method is called whenever an event occurs that affects the named services state. This could be triggered by an explicit invocation by the SARDeployer , notification of a Class removal, or a service on which other services depend reaching its destroyed state.

Service implementations often do not implement destroy in favor of simply implementing the stop method, or neither stop nor destroy if the service has no state or resources that need cleanup.

Service descriptor fragments illustrating the usage of the depends and depends-list elements.

<mbean code="org.jboss.mq.server.jmx.Topic"

name="jms.topic:service=Topic,name=testTopic">

<!-- Declare a dependency on the "jboss.mq:service=DestinationManager" and

bind this name to the DestinationManager attribute -->

<depends optional-attribute-name="DestinationManager">

jboss.mq:service=DestinationManager

</depends>

<!-- Declare a dependency on the "jboss.mq:service=SecurityManager" and

bind this name to the SecurityManager attribute -->

<depends optional-attribute-name="SecurityManager">

jboss.mq:service=SecurityManager

</depends>

...

<!-- Declare a dependency on the "jboss.mq:service=CacheManager" without

any binding of the name to an attribute-->

<depends>jboss.mq:service=CacheManager</depends>

</mbean>

<mbean code="org.jboss.mq.server.jmx.TopicMgr"

name="jboss.mq.destination:service=TopicMgr">

<!-- Declare a dependency on the given topic destination mbeans and

bind these names to the Topics attribute -->

<depends-list optional-attribute-name="Topics">

<depends-list-element>jms.topic:service=Topic,name=A</depends-list-element>

<depends-list-element>jms.topic:service=Topic,name=B</depends-list-element>

<depends-list-element>jms.topic:service=Topic,name=C</depends-list-element>

</depends>

</mbean>

Another difference between the depends and depends-list elements is that the value of the depends element may be a complete MBean service configuration rather than just the ObjectName of the service. See An example of using the depends element to specify the complete configuration of a depended on service.. shows an example from the hsqldb-service.xml descriptor. In this listing the org.jboss.resource.connectionmanager.RARDeployment service configuration is defined using a nested mbean element as the depends element value. This indicates that the org.jboss.resource.connectionmanager.LocalTxConnectionManager MBean depends on this service. The "jboss.jca:service=LocalTxDS,name=hsqldbDS" ObjectName will be bound to the ManagedConnectionFactoryName attribute of the LocalTxConnectionManager class.

An example of using the depends element to specify the complete configuration of a depended on service.

<mbean code="org.jboss.resource.connectionmanager.LocalTxConnectionManager"

name="jboss.jca:service=LocalTxCM,name=hsqldbDS">

<depends optional-attribute-name="ManagedConnectionFactoryName">

<!--embedded mbean-->

<mbean code="org.jboss.resource.connectionmanager.RARDeployment"

name="jboss.jca:service=LocalTxDS,name=hsqldbDS">

<attribute name="JndiName">DefaultDS</attribute>

<attribute name="ManagedConnectionFactoryProperties">

<properties>

<config-property name="ConnectionURL" type="java.lang.String">

jdbc:hsqldb:hsql://localhost:1476

</config-property>

<config-property name="DriverClass" type="java.lang.String">

org.hsqldb.jdbcDriver

</config-property>

<config-property name="UserName" type="java.lang.String">sa

</config-property>

<config-property name="Password" type="java.lang.String"/>

</properties>

</attribute>

...

</mbean>

...

</mbean>

JNDIMapMBean interface and implementation based on the service interface method pattern

package org.jboss.chap2.ex1;

// The JNDIMap MBean interface

import javax.naming.NamingException;

public interface JNDIMapMBean

{

public String getJndiName();

public void setJndiName(String jndiName) throws NamingException;

public void start() throws Exception;

public void stop() throws Exception;

}

package org.jboss.chap2.ex1;

// The JNDIMap MBean implementation

import java.util.HashMap;

import javax.naming.InitialContext;

import javax.naming.Name;

import javax.naming.NamingException;

import org.jboss.naming.NonSerializableFactory;

public class JNDIMap implements JNDIMapMBean

{

private String jndiName;

private HashMap contextMap = new HashMap();

private boolean started;

public String getJndiName()

{

return jndiName;

}

public void setJndiName(String jndiName) throws NamingException

{

String oldName = this.jndiName;

this.jndiName = jndiName;

if( started )

{

unbind(oldName);

try

{

rebind();

}

catch(Exception e)

{

NamingException ne = new NamingException("Failed to update jndiName");

ne.setRootCause(e);

throw ne;

}

}

}

public void start() throws Exception

{

started = true;

rebind();

}

public void stop()

{

started = false;

unbind(jndiName);

}

private void rebind() throws NamingException

{

InitialContext rootCtx = new InitialContext();

Name fullName = rootCtx.getNameParser("").parse(jndiName);

System.out.println("fullName="+fullName);

NonSerializableFactory.rebind(fullName, contextMap, true);

}

private void unbind(String jndiName)

{

try

{

InitialContext rootCtx = new InitialContext();

rootCtx.unbind(jndiName);

NonSerializableFactory.unbind(jndiName);

}

catch(NamingException e)

{

e.printStackTrace();

}

}

}

Version two of the JNDIMapMBean interface and JNDIMap implementation class, which is based on the ServiceMBean interface and ServiceMBeanSupport class, is given in See JNDIMap MBean interface and implementation based on the ServiceMBean interface and ServiceMBeanSupport class.. In this version, the implementation class extends the ServiceMBeanSupport class and overrides the startService method and the stopService method. JNDIMapMBean also implements the abstract getName to return a descriptive name for the MBean. The JNDIMapMBean interface extends the org.jboss.system.ServiceMBean interface and only declares the setter and getter methods for the JndiName attribute because it inherits the Service life cycle methods from ServiceMBean . This is the third approach mentioned at the start of the "Writing JBoss MBean Services" section. The implementation differences between See JNDIMapMBean interface and implementation based on the service interface method pattern. and See JNDIMap MBean interface and implementation based on the ServiceMBean interface and ServiceMBeanSupport class. are highlighted in bold in See JNDIMap MBean interface and implementation based on the ServiceMBean interface and ServiceMBeanSupport class..

JNDIMap MBean interface and implementation based on the ServiceMBean interface and ServiceMBeanSupport class

package org.jboss.chap2.ex2;

// The JNDIMap MBean interface

import javax.naming.NamingException;

public interface JNDIMapMBean extends org.jboss.system.ServiceMBean

{

public String getJndiName();

public void setJndiName(String jndiName) throws NamingException;

}

package org.jboss.chap2.ex2;

// The JNDIMap MBean implementation

import java.util.HashMap;

import javax.naming.InitialContext;

import javax.naming.Name;

import javax.naming.NamingException;

import org.jboss.naming.NonSerializableFactory;

public class JNDIMap extends org.jboss.system.ServiceMBeanSupport

implements JNDIMapMBean

{

private String jndiName;

private HashMap contextMap = new HashMap();

public String getJndiName()

{

return jndiName;

}

public void setJndiName(String jndiName) throws NamingException

{

String oldName = this.jndiName;

this.jndiName = jndiName;

if( super.getState() == STARTED )

{

unbind(oldName);

try

{

rebind();

}

catch(Exception e)

{

NamingException ne = new NamingException("Failed to update jndiName");

ne.setRootCause(e);

throw ne;

}

}

}

public void startService() throws Exception

{

rebind();

}

public void stopService()

{

unbind(jndiName);

}

private void rebind() throws NamingException

{

InitialContext rootCtx = new InitialContext();

Name fullName = rootCtx.getNameParser("").parse(jndiName);

log.info("fullName="+fullName);

NonSerializableFactory.rebind(fullName, contextMap, true);

}

private void unbind(String jndiName)

{

try

{

InitialContext rootCtx = new InitialContext();

rootCtx.unbind(jndiName);

NonSerializableFactory.unbind(jndiName);

}

catch(NamingException e)

{

log.error("Failed to unbind map", e);

}

}

}

The source code for these MBeans along with the service descriptors is located in the examples/src/main/org/jboss/chap2/{ex1,ex2} directories.

The example 1 service descriptor is given in See The example 1 JNDIMap MBean service descriptor and a client usage code fragment.. along with a sample client usage code fragment. The JNDIMap MBean binds a HashMap object under the "inmemory/maps/MapTest" JNDI name and the client code fragment demonstrates retrieving the HashMap object from the "inmemory/maps/MapTest" location.

The example 1 JNDIMap MBean service descriptor and a client usage code fragment.

<!-- The SAR META-INF/jboss-service.xml descriptor -->

<server>

<mbean code="org.jboss.chap2.ex1.JNDIMap" name="chap2.ex1:service=JNDIMap">

<attribute name="JndiName">inmemory/maps/MapTest</attribute>

<depends>jboss:service=Naming</depends>

</mbean>

</server>

// Sample lookup code

InitialContext ctx = new InitialContext();

HashMap map = (HashMap) ctx.lookup("inmemory/maps/MapTest");

Version 1, the Annotated JNDIMap XMBean

Let's start with a simple XMBean variation of the standard MBean version of the JNDIMap that adds the descriptive information about the attributes and operations and their arguments. See The version 1 JNDIMap XMBean descriptor. shows the jboss-service.xml descriptor and the jndimap-xmbean1.xml XMBean descriptor. The source can be found in the src/main/org/jboss/chap2/xmbean directory of the book examples.

The version 1 JNDIMap XMBean descriptor

<?xml version='1.0' encoding='UTF-8' ?>

 

<!DOCTYPE server PUBLIC

"-//JBoss//DTD MBean Service 3.2//EN"

"http://www.jboss.org/j2ee/dtd/jboss-service_3_2.dtd"

>

 

<server>

<mbean code="org.jboss.chap2.xmbean.JNDIMap" name="chap2.xmbean:service=JNDIMap"

xmbean-dd="META-INF/jndimap-xmbean.xml">

<attribute name="JndiName">inmemory/maps/MapTest</attribute>

<depends>jboss:service=Naming</depends>

</mbean>

</server>

 

---

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE mbean PUBLIC

"-//JBoss//DTD JBOSS XMBEAN 1.0//EN"

"http://www.jboss.org/j2ee/dtd/jboss_xmbean_1_0.dtd">

 

<mbean>

<description>The JNDIMap XMBean Example Version 1</description>

 

<descriptors>

<persistence persistPolicy="Never"

persistPeriod="10"

persistLocation="data/JNDIMap.data"

persistName="JNDIMap"/>

<currencyTimeLimit value="10"/>

<state-action-on-update value="keep-running"/>

</descriptors>

 

<class>org.jboss.test.jmx.xmbean.JNDIMap</class>

 

<constructor>

<description>The default constructor</description>

<name>JNDIMap</name>

</constructor>

 

<!-- Attributes -->

<attribute access="read-write" getMethod="getJndiName" setMethod="setJndiName">

<description>The location in JNDI where the Map we manage will be bound</description>

<name>JndiName</name>

<type>java.lang.String</type>

<descriptors>

<default value="inmemory/maps/MapTest" />

</descriptors>

</attribute>

<attribute access="read-write" getMethod="getInitialValues" setMethod="setInitialValues">

<description>The array of initial values that will be placed into

the map associated with the service. The array is a collection of

key,value pairs with elements[0,2,4,...2n] being the keys and

elements [1,3,5,...,2n+1] the associated values. The "[Ljava.lang.String;"

type signature is the VM representation of the java.lang.String[] type.

</description>

<name>InitialValues</name>

<type>[Ljava.lang.String;</type>

<descriptors>

<default value="key0,value0" />

</descriptors>

</attribute>

 

<!-- Operations -->

<operation>

<description>The start lifecycle operation</description>

<name>start</name>

</operation>

<operation>

<description>The stop lifecycle operation</description>

<name>stop</name>

</operation>

<operation impact="ACTION">

<description>Put a value into the map</description>

<name>put</name>

<parameter>

<description>The key the value will be store under</description>

<name>key</name>

<type>java.lang.Object</type>

</parameter>

<parameter>

<description>The value to place into the map</description>

<name>value</name>

<type>java.lang.Object</type>

</parameter>

</operation>

<operation impact="INFO">

<description>Get a value from the map</description>

<name>get</name>

<parameter>

<description>The key to lookup in the map</description>

<name>get</name>

<type>java.lang.Object</type>

</parameter>

<return-type>java.lang.Object</return-type>

</operation>

 

<!-- Notifications -->

<notification>

<description>The notification sent whenever a value is get into the map

managed by the service</description>

<name>javax.management.Notification</name>

<notification-type>org.jboss.chap2.xmbean.JNDIMap.get</notification-type>

</notification>

<notification>

<description>The notification sent whenever a value is put into the map

managed by the service</description>

<name>javax.management.Notification</name>

<notification-type>org.jboss.chap2.xmbean.JNDIMap.put</notification-type>

</notification>

</mbean>

As noted previously, 3.2.2 release replaced the binding of the RMIAdaptor interface with the invoker adaptor service and this service does not yet support remoting of JMX notifications. Therefore, we need to create a config that uses the RMIAdaptorService . There is a config target that sets up a rmi-adaptor configuration with the jmx-rmi-adaptor.sar installed. Build this setup using:

[nr@toki]$ ant -Dchap=chap2 config

Buildfile: build.xml

 

...

 

config:

[echo] Preparing rmi-adaptor configuration fileset

[copy] Copying 148 files to /tmp/jboss-3.2.3/server/rmi-adaptor

[copy] Copying 2 files to /tmp/jboss-3.2.3/server/rmi-adaptor/deploy/jmx-rmi-adaptor.sar

[delete] Deleting directory /tmp/jboss-3.2.3/server/rmi-adaptor/deploy/jmx-invoker-adaptor-server.sar

[delete] Deleting directory /tmp/jboss-3.2.3/server/rmi-adaptor/deploy/management

 

Now, run the rmi-adaptor configuration, and then build, deploy and test the XMBean as follows:

[nr@toki examples]$ ant -Dchap=chap2 -Dex=xmbean1 -Djboss.deploy.conf=rmi-adaptor run-example

Buildfile: build.xml

 

validate:

[java] ImplementationTitle: JBoss [WonderLand]

[java] ImplementationVendor: JBoss.org

[java] ImplementationVersion: 3.2.2 (build: CVSTag=JBoss_3_2_2 date=2003101

82216)

[java] SpecificationTitle: JBoss

[java] SpecificationVendor: JBoss (http://www.jboss.org/)

[java] SpecificationVersion: 3.2.2

[java] JBoss version is: 3.2.2

 

fail_if_not_valid:

 

init:

[echo] Using jboss.dist=/cvs/Releases/jboss-3.2.2

 

compile:

 

run-example:

 

prepare:

 

chap2-ex1xmbean1-sar:

 

run-examplexmbean1:

[java] JNDIMap Class: org.jboss.mx.modelmbean.XMBean

[java] JNDIMap Operations:

[java] + void start()

[java] + void stop()

[java] + void put(java.lang.Object chap2.xmbean:service=JNDIMap,java.lang.Object chap2.xmbean:service=JNDIMap)

[java] + java.lang.Object get(java.lang.Object chap2.xmbean:service=JNDIMap)

[java] + java.lang.String getJndiName()

[java] + void setJndiName(java.lang.String chap2.xmbean:service=JNDIMap)

[java] + [Ljava.lang.String; getInitialValues()

[java] + void setInitialValues([Ljava.lang.String; chap2.xmbean:service=JNDIMap)

[java] handleNotification, event: null

[java] key=key0, value=value0

[java] handleNotification, event: javax.management.Notification[source=chap2.xmbean:service=JNDIMap,type=org.jboss.chap2.xmbean.JNDIMap.put,sequenceNumber=3,timeStamp=1083610215205,message=null,userData=null]

[java] JNDIMap.put(key1, value1) successful

[java] handleNotification, event: javax.management.Notification[source=chap2.xmbean:service=JNDIMap,type=org.jboss.chap2.xmbean.JNDIMap.get,sequenceNumber=4,timeStamp=1083610215376,message=null,userData=null]

[java] JNDIMap.get(key0): null

[java] handleNotification, event: javax.management.Notification[source=chap2.xmbean:service=JNDIMap,type=org.jboss.chap2.xmbean.JNDIMap.get,sequenceNumber=5,timeStamp=1083610215406,message=null,userData=null]

[java] JNDIMap.get(key1): value1

[java] handleNotification, event: javax.management.Notification[source=chap2.xmbean:service=JNDIMap,type=org.jboss.chap2.xmbean.JNDIMap.put,sequenceNumber=6,timeStamp=1083610215443,message=null,userData=null]

[java] handleNotification, event: javax.management.AttributeChangeNotification: source=chap2.xmbean:service=JNDIMap seq-no=3 time=1083610215448 message=InitialValues changed from javax.management.Attribute: name=InitialValues value=[Ljava.lang.String;@e02ee9 to javax.management.Attribute: name=InitialValues value=[Ljava.lang.String;@229bc1 attributeName=InitialValues attributeType=[Ljava.lang.String; oldValue=[Ljava.lang.String;@2445d7 newValue=[Ljava.lang.String;@65547d notificationType=jmx.attribute.change userData=null

 

BUILD SUCCESSFUL

Total time: 8 seconds

The functionality is largely the same as the Standard MBean with the notable exception of the JMX notifications. A Standard MBean has no way of declaring that it will emit notifications. An XMBean may declare the notifications it emits using notification elements as is shown in the version 1 descriptor. We see the notifications from the get and put operations on the test client console output. Note that there is also an jmx.attribute.change notification emitted when the InitialValues attribute was changed. This is a standard feature of ModelMBean s owning to the fact that the ModelMBean interface extends the ModelMBeanNotificationBroadcaster which supports AttributeChangeNotificationListeners .

The other major difference between the Standard and XMBean versions of JNDIMap is the descriptive metadata. Look at the "chap2.xmbean:service=JNDIMap" in the jmx-console , and you will see the attributes section as shown in See The Version 1 JNDIMapXMBean jmx-console view..

 

Version 2, Adding Persistence to the JNDIMap XMBean

In version 2 of the XMBean we add support for persistence of the XMBean attributes. The updated XMBean deployment descriptor is given in Lxxx2. The changes with respect to the version 1 descriptor of Lxxx1 are shown in bold.

Version 3, Adding Security and Remote Access to the JNDIMap XMBean

The last example version of the JNDIMap XMBean will demonstrate customization of the server interceptor stack as well as exposing a subset of the XMBean management interface via a typed proxy to a remote client using RMI/JRMP. On the server side we will add a simple security interceptor that only allows access to attributes or operations by a user specified in the interceptor configuration. We will also use another custom interceptor to implement the MBean detached invoker pattern described in a latter section entitled "See Remote Access to Services, Detached Invokers.". By implementing this pattern in an invoker rather than the XMBean, we demonstrate how to introduce a remote access aspect without having to modify the existing JNDMap implementation.

We will use the JRMPProxyFactory service to expose the ClientInterface shown in See The ClientInterface view of the JNDIMap XMBean exposed via RMI/JRMP. to remote clients. Our test client will obtain the ClientInterface proxy from JNDI and interact with the XMBean through RMI style calls instead of the RMIAdaptor and MBeanServer style used previously.