Ken Cavanaugh - The Gmbal project

Gmbal 

Sustaining TOI 

Ken Cavanaugh 

Friday, December 11, 2009 

1

Outline 

MBeans 

AMX 

Review of Gmbal API 

Use in GF and CORBA 

Build and release details 

Implementation packages and overview 

Debugging tips 

Current tests 


2

MBeans 

Management interface defined in JMX 

Gmbal is a convenient way to create MBeans 

Gmbal creates MBeans that are: 

Open MBeans (dynamic MBeans with Open data) 

AMX compliant 

Have Model MBean metadata 

Are JDK 5 compliant 

JDK 6 has significant JMX changes 

Still supporting JDK 5 while Gmbal’s customers require it 


3

AMX 

AMX MBeans are GlassFish v3’s version of MBeans 

AMX is an interface specification: Gmbal is an implementation of AMX 

AMX requirements: 

ObjectNames have a very specific form that defines a parent/child 

hierarchy 

A number of required attributes for metadata 

Several required MBean attributes: 

Parent 

Name 

Children 


4

Gmbal API: Annotations 

8 basic annotations: 

@ManagedObject and @ManagedData 

@ManagedAttribute 

@ManagedOperation and @ParameterNames 

@NameValue 

@Description 

@AMXMetadata 

5 specialized annotations: 

@InheritedAttribute and @InheritedAttributes 

@IncludeSubclass 

@DescriptorKey and @DescriptorFIelds 


5

Gmbal API: Interface and Factory 

One interface (ManagedObjectManager) that handles registration and 

related operations. 

One concrete class (ManagedObjectManagerFactory) to obtain 

ManagedObjectManagers. 


6

ManagedObjectManager API: 

registration 

public interface ManagedObjectManager { 

NotificationEmitter getRoot() ; 

NotificationEmitter createRoot() ; 

NotificationEmitter createRoot( Object obj ) ; 

NotificationEmitter createRoot( Object obj, String name ) ; 

NotificationEmitter register( Object obj ) ; 

NotificationEmitter registerAtRoot( Object obj ) ; 

NotificationEmitter registerAtRoot( Object obj, String name ) ; 

NotificationEmitter register( Object parent, Object obj ) ; 

NotificationEmitter register( Object parent, Object obj, String name ) ; 

void unregister( Object obj ) ; 

} 

• Each MOM must have 1 root 

• Unregister when needed 

• Name required unless object has @NameValue method 


7

Deferred and Suspended 

Registration 

Registration with the MBean server does not alway happen 

immediately 

MOM has a suspend/resume API to allow program to defer 

registration until some later point (usually after all init has completed) 

Problem: as soon as an MBean is registered, it can (and will!) be 

called asynchronously (AMX validator always runs) 

Can suspend before any MBeans created, then resume after all init 

completes 

MOM created by createFederated may have deferred registration 

Can’t create MOM root until root parent exists (AMX requirement) 

Transparent to Gmbal client in most ways 

Note that AMX is NOT started in GFv3 by default 

All of this is handled in the JMXRegistrationManager 


8


miscellaneous 

public interface ManagedObjectManager { 

void suspendJMXRegistration() ; 

void resumeJMXRegistration() ; 

ObjectName getObjectName( Object obj ) ; 

Object getObject( ObjectName oname ) ; 

void stripPrefix( String... str ) 

String getDomain() ; 

MBeanServer getMBeanServer() ; 

void setMBeanServer( MBeanServer server ) ; 

ResourceBundle getResourceBundle() ; 

void setResourceBundle( ResourceBundle rb ) ; 

void addAnnotation( AnnotatedElement element, Annotation annotation ) 

} 

Suspend/resume to deal with registration in constructor problem 

Access object name object mapping for registered objects 

set/get MBeanServer and description resource bundle 

stripPrefix and addAnnotations discussed later 


9


Debugging 

interface ManagedObjectManager { 

public enum RegistrationDebugLevel { NONE, NORMAL, FINE } ; 

void setRegistrationDebugLevel( RegistrationDebugLevel level ) ; 

} 

void setRuntimeDebug( boolean flag ) ; 

void setTypelibDebug( int level ) ; 

void setJMXRegistrationDebug( boolean flag ) ; 

String dumpSkeleton( Object obj ) ; 

void suppressDuplicateRootReport( boolean suppressReport ) ; 

Several different tracing capabilities 

Tracing when MBeans are constructed 

FINE adds 

Tracing when MBean methods are invoked 

Tracing for type evaluation in typelib 

Tracing for registration of MBean with JMX 

Dump the skeleton for any registered object 

Control reporting of duplicate setRoot calls 


10

ManagedObjectManagerFactory 

public final class ManagedObjectManagerFactory { 

public static ManagedObjectManager createStandalone( String domain ) { ... } 

} 

public static ManagedObjectManager createFederated( ObjectName rootParentName ) { ... } 

• Only concrete class in the API 

• createStandalone(String) takes a domain used in all ObjectNames from 

this ManagedObjectManager. 

• Typically used in standalone case 

• createFederated(rootParentName) takes an AMX-compliant ObjectName 

which is the parent of the ManagedObjectManager’s root 

• Typically used in GFv3 case 


11

Use of Gmbal 

In GlassFish v3 

Annotations used along with GF probes 

Used to create MBeans for GF monitoring 

In CORBA 

Create MBeans directly for management API 

ORB MBean Hierarchy: 

gmbal root (amx parent in GlassFish) 

various internal APIs are available as MBean 

I’ll talk about this more in the CORBA TOI 

Lloyd will talk about tools for viewing AMX MBeans in GFv3 


12

Workspace and Artifacts 

Project is at http://kenai.com/projects/gmbal 

Currently master is the gmbal repository at http://kenai.com/hg/ 

gmbal~master (tag is VERSION-3.0.0-b023) 

Artifacts are all available in Maven at http://download.java.net/ 

maven/2/org/glassfish/gmbal 

Current valid artifacts: 

Group ID Artifact ID Current Version 

(in GF 3.0-FCS) 

org.glassfish.gmbal gmbal-api-only 3.0.0-b023 

org.glassfish.gmbal gmbal-api-only-source 3.0.0-b023 

org.glassfish.gmbal gmbal 3.0.0-b023 

org.glassfish.gmbal gmbal-source 3.0.0-b023 


13

Build and Integration Process 

Make a clone of the repository at https://hg.kenai.com/hg/ 

gmbal~master 

use -r option for a specific version (e.g. -r 3.0-FCS) 

hg tags command will display all versions 

Build with “ant all” 

To make a new release: 

edit build.properties 

change build.int to the new build version 

or if necessary the other gmbal.* properties for different versions 

hg commit/hg tag /hg push 

“ant release” to release to maven repository 


14

Gmbal Implementation: Packages 

Gmbal API: 

org.glassfish.gmbal 

org.glassfish.gmbal.util 

Gmbal impl: 

org.glassfish.gmbal.generic 

org.glassfish.gmbal.logex 

org.glassfish.gmbal.typelib 

org.glassfish.gmbal.impl 

Tools and test support: 

org.glassfish.gmbal.tools.argparser 

org.glassfisdh.gmbal.tools.file 

org.glassfish.gmbal.main 


15

Gmbal API packages 

org.glassfish.gmbal 

previously discussed annotations 

previously discussed ManagedObjectManager and 

ManagedObjectManagerFactory 

org.glassfish.gmbal.util 

Contains GenericConstructor 

GenericConstructor( final Class type, String className, 

final Class... signature ) 

T create( Object... args ) 

ManagedObjectManagerFactory creates instances of 

GenericConstructor for the createFederated and createStandalone 

method in ManagedObjectManagerImpl 

Decouples interface from implementation 

gmbal-api-only has just the org.glassfish.gmbal and 

org.glassfish.gmbal.util package 


16

org.glassfish.gmbal.generic 

Provides interfaces that represent functions 

Also algorithms that operate on functions (things like map, fold, 

find) 

Provides debugging facilities 

DprintUtil for method tracing 

OperationTracer for gathering context information for exceptions 

MethodMonitor to tie this together 

Facet accessor to provide limited dynamic inheritance 

Construct MBean with standard AMX attributes and application 

specific attributes 

Generic support for printing out arbitrary objects 

Uses annotations to control printing behavior 


17

org.glassfish.gmbal.logex 

Uses an annotated interface to generate exceptions and log messages 

Also supports I18N for messages 

Example: 

@ExceptionWrapper( idPrefix="GMBALTLIB", resourceBundle = "org.glassfish.gmbal.logex.LogStrings" ) 

public interface Exceptions { 

static final Exceptions self = WrapperGenerator.makeWrapper( Exceptions.class ) ; 

// Allow 100 exceptions per class 

static final int EXCEPTIONS_PER_CLASS = 100 ; 

// TypeEvaluator 

static final int TYPE_EVALUATOR_START = 1 ; 

@Message( "Internal error in TypeEvaluator" ) 

@Log( id=TYPE_EVALUATOR_START + 0 ) 

IllegalStateException internalTypeEvaluatorError( @Chain Exception exc ) ; 

} 

@Message( "evaluateType should not be called with a Method ({0})" ) 

@Log( id=TYPE_EVALUATOR_START + 1 ) 

IllegalArgumentException evaluateTypeCalledWithMethod( Object type ) ; 


18


Converts the standard java Class/java.lang.reflect.Type hierarchy into 

an internal form for Gmbal. 

Main interfaces: 

EvaluatedType (parent) 

EvaluatedDeclaration (types that can have annotations) 

EvaluatedFieldDeclaration 

EvaluatedMethodDeclaration 

EvaluatedClassDeclaration 

EvaluatedArrayType 

TypeEvaluator 

Main implementation class 

Provides public static EvaluatedType 

getEvaluatedType( Class ) method 

No need for Java’s type variables and wildcard types: these are 

evaluated out of the result (which is the whole reason for doing this) 


19


Evaluated generic types (replaces type variables with types) so that 

Gmbal can easily use type information to generate open types 

Example: 

@ManagedData 

public interface Bar { 


String getName() ; 

} 


String getAddress() ; 

@ManagedData 

public interface Foo { 


List getElems() ; 

} 

@ManagedObject 

public interface Baz { 


Foo getFoo() 

} 

Foo is annotated as @ManagedData 

Needs to be OpenData 

But we can’t tell what type T is in Foo 

Baz has an instance of Foo with T 

instantiated to Bar 

Note that Foo also has an instance of the 

standard List, with is declared with its own 

type variable T (see java.util.List) 

Typelib replaces all type variables with the 

values to which they are bound 

It is a bit tricky due to the need to handle 

complex recursive references to types 


20

org.glassfish.gmbal.impl 

The main implementation package 

Classes: 

ManagedObjectManagerInternal (interface for MOM used in impl 

package) 

ManagedObjectManagerImpl 

MBeanSkeleton (contains most of the implementation for a specific 

MBean) 

MBeanImpl (actually class used to represent MBean) 

MBeanTree (containment hierarchy of MBeans) 

JMXRegistrationManager (manages MBean registrations) 

TypeConverter(Impl) (handle java type open type conversions) 

AttributeDescriptor (main implementation of attributes) 

AMXImpl (implements AMX attributes) 


21

Tools and test support 

org.glassfish.gmbal.tools.argparser 

Attribute driven command line parser 

org.glassfish.gmbal.tools.file 

General purpose file and directory processing tools from CORBA 

Used here to generate resource bundle for logex exception 

wrappers 

org.glassfish.gmbal.main 

Provides ProfileMain, which is used for simple performance testing 

None of this code is delivered in the OSGi bundles for Gmbal 


22

Construction and Registration 1 

ManagedObjectManagerImpl data: 

MBeanTree (maintains registration of all MBeans for this MOM) 

skeletonMap (maps class to skeleton) 

typeConverterMap (maps class to type converter) 

Registration starts at ManagedObjectManagerImpl.register( Object 

parent, Object obj, String name ) 

get the MBeanImpl corresponding to the parent 

construct the MBean for obj 

register the MBean in the tree 


23

Construction and Registration 2 

ConstructMBean 

Use typelib to get an EvaluatedType for the class of obj 

get a skeleton for the evaluated type 

Analyzes the annotations for attributes and operations 

gets the TypeConverters for all attribute and operation types 

Constructs the JMX metadata for all types, attributes, and 

operations 

construct AMX Metadata 

construct MBeanImpl 


24

Attributes and Operations 

MBeanImpl implements the dynamic MBean interface by delegating to 

the MBeanSkeleton 

MBeanImpl implements the FacetAccessor interface 

MBeanSkeleton uses the appropriate AttributeDescriptor for 

attribute get/set 

The AttributeDescriptor uses the FacetAccessor interface to get/set 

the actual attribute value (either from a method or a field) 

The AttributeDescriptor also uses the TypeConverter to convert to/ 

from the OpenType as needed 


25

Debugging: MethodMonitor 

Most of the code in typelib and impl uses the MethodMonitor 

Allows internal tracing of method entry, exit, and other interesting 

points in the method 

Currently used for two purposes: 

To record interesting context in the OperationTracer 

To hook in DprintUtil for support of debug flags, which are 

controlled by the debug methods 


26

Example of OperationTracer 

INFO: GMBAL406: registering MBean extern:pp=/gmbal-root/AMXClientTest$MyManagedClass[Root]/AMXClientTest 

$MyManagedClass[Child],type=AMXClientTest$MyManagedClass,name=GrandChild-2 

CONTEXT: 

( 0): register(org.glassfish.gmbal.impl.AMXClientTest$MyManagedClass@1d2b9b7,org.glassfish.gmbal.impl.AMXClientTest 

$MyManagedClass@19c0bd6,) 

( 1): register(MBeanImpl[type=AMXClientTest$MyManagedClass,name=Child,oname=extern:pp=/gmbal-root/AMXClientTest 

$MyManagedClass[Root],type=AMXClientTest$MyManagedClass,name=Child],org.glassfish.gmbal.impl.AMXClientTest 

$MyManagedClass@19c0bd6,MBeanImpl[type=AMXClientTest$MyManagedClass,name=GrandChild-2,oname=extern:pp=/gmbal-root/ 

AMXClientTest$MyManagedClass[Root]/AMXClientTest$MyManagedClass[Child],type=AMXClientTest 

$MyManagedClass,name=GrandChild-2]) 

java.lang.RuntimeException: StackTrace 

at org.glassfish.gmbal.logex.WrapperGenerator.makeException(WrapperGenerator.java:220) 

at org.glassfish.gmbal.logex.WrapperGenerator.handleFullLogging(WrapperGenerator.java:361) 

at org.glassfish.gmbal.logex.WrapperGenerator.access$300(WrapperGenerator.java:93) 

at org.glassfish.gmbal.logex.WrapperGenerator$1.invoke(WrapperGenerator.java:434) 

at $Proxy16.registeringMBean(Unknown Source) 

at org.glassfish.gmbal.impl.MBeanImpl.register(MBeanImpl.java:303) 

at org.glassfish.gmbal.impl.JMXRegistrationManager.register(JMXRegistrationManager.java:193) 

at org.glassfish.gmbal.impl.MBeanTree.register(MBeanTree.java:376) 

at org.glassfish.gmbal.impl.ManagedObjectManagerImpl.register(ManagedObjectManagerImpl.java:713) 

at org.glassfish.gmbal.impl.ManagedObjectManagerImpl.register(ManagedObjectManagerImpl.java:724) 

at org.glassfish.gmbal.impl.AMXClientTest.initializeMom(AMXClientTest.java:195) 

at org.glassfish.gmbal.impl.AMXClientTest.setUp(AMXClientTest.java:176) 

•This is taken from a test case which is registering an MBean 

•The context indicates the data being registered 

•( 0): This is the main register method discussed previously 

•( 1): This is the MBeanTree register call 

•Here we see a fully constructed MBean being registered under 

the parent 

•This gives information not available in the stack trace 

•The OperationTracer is avilable for all Gmbal exceptions 


27

The debug methods 

Gmbal has a number of methods that can be set to display more 

information 

There is no general user-exposed API for this 

But note that some of the Gmbal debug can be enabled using the 

ORB debug flags within the ORB 

All of the debug flags enabled various MethodMonitor calls which 

print out information in a method: 

On entry: ($thread): (GMBAL).impl..-> 

Info: ($thread): (GMBAL).impl..:: 

On exit: ($thread): (GMBAL).impl..

Gmbal tests 

Gmbal has an extensive test suite in the project 

tests use the same package names as source, but are in a different 

directory (standard NB project layout) 

Main test is in org.glassfish.gmbal.JmxaTest (old name) 

Emma reports pretty good code coverage 

block 69% 

class 78% 

line 69% 

method 69% 

Hudson job is at http://hudson.sfbay/view/corba/gmbal 

Unfortunately the job is currently broken 


29

Common Errors in Using Gmbal 

Just a few examples 

I don’t have time to do complete documentation on these 

Examples: 

Registering the same object twice 

Unregistering an object that was previously unregistered 

Passing something to a register method that cannot represent an 

MBean (e.g. no @ManagedObject annotation) 

Putting @ManagedAttribute on a method that is not a valid 

attribute (e.g. return non-void and takes an argument) 

Annotating object with @AMXMetadata( isSingleton = true ) and 

then creating more than one instance 

Forgetting @NameValue on an object registered without a name 


30

Ken Cavanaugh - The Gmbal project

Create successful ePaper yourself

Delete template?

Save as template?