Top Description Inners Methods
org.glassfish.gmbal

public Interface ManagedObjectManager

extends Closeable
Known Direct Implementers
org.glassfish.gmbal.ManagedObjectManagerNOPImpl
Imports
java.io.Closeable, java.lang.annotation.Annotation, java.lang.reflect.AnnotatedElement, java.util.ResourceBundle, javax.management.MBeanServer, .ObjectName, org.glassfish.pfl.tf.timer.spi.ObjectRegistrationManager
An interface used to managed Open MBeans created from annotated objects. This is mostly a facade over MBeanServer. Note that certain methods must be called in the correct order:
  1. Methods suspendJMXRegistration, resumeJMXRegistration, getDomain, getMBeanServer, getResourceBundle, setRuntimeDebug, setRegistrationDebugLevel, setTypelibDebug, and close may be called at any time.
  2. All calls to addAnnotation, stripPrefix, and stripPackageName must occur before any call to a createRoot method.
  3. All of the register and registerAtRoot methods and unregister, getObject, getObjectName, and dumpSkeleton may only be called after a createRoot method is called.
  4. Only one call to a createRoot method is permitted on any ManagedObjectManager.
  5. A call to close returns the MOM to the pre-createRoot state.
If these constraints are violated, an IllegalStateException is thrown.

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static enum
ManagedObjectManager.RegistrationDebugLevel

DebugLevel used to control how much debug info is printed for registration of objects.

Method Summary

Modifier and TypeMethod and Description
public void
addAnnotation(AnnotatedElement
The annotated element (class or method for our purposes).
element, Annotation
The annotation we wish to add to the element.
annotation)

Method to add an annotation to an element that cannot be modified.

public void
addInheritedAnnotations(Class<?>
Class to analyze for inherited annotations.
cls)

Add all annotations for this class as if they were declared on the inheritance parent(s) of the class (immediate superclass for a class, all immediate superinterfaces for an interface).

public GmbalMBean

Returns:

A default root MBean which supports only the AMX attributes.
createRoot()

Create a default root MBean.

public GmbalMBean

Returns:

The newly constructed MBean.
createRoot(Object
The Java object to be used to construct the root.
root)

Create a root MBean from root, which much have a method with the @NameValue annotation.

public GmbalMBean

Returns:

The newly constructed MBean.
createRoot(Object
The Java object to be used to construct the root.
root, String
The ObjectName name field to be used in the ObjectName of the MBean constructed from root.
name)

Create a root MBean from root with the given name.

public String

Returns:

The string representation of the skeleton.
dumpSkeleton(Object
The registered object whose skeleton should be displayed.
obj)

Dump the skeleton used in the implementation of the MBean for obj.

public AMXClient

Returns:

An AMXClient that acts as a proxy for this MBean.
getAMXClient(Object
The object corresponding to an MBean.
obj)

Get an AMXClient instance for the object obj, if obj is registered as an MBean in this mom.

public String

Returns:

Get the domain name for this ManagedObjectManager.
getDomain()

Return the domain name that was used when this ManagedObjectManager was created.

public MBeanServer

Returns:

The current MBeanServer, either the default, or the value passed to setMBeanServer.
getMBeanServer()

Get the current MBeanServer.

public Object

Returns:

The Object passed to the register call.
getObject(ObjectName
The ObjectName used to register the object.
oname)

Get the Object that was registered with the given ObjectName.

public ObjectName

Returns:

The ObjectName used to register the MBean.
getObjectName(Object
The object originally passed to a register call.
obj)

Get the ObjectName for the given object (which must have been registered via a register call).

public ObjectRegistrationManager
getObjectRegistrationManager()

Return an ObjectRegistrationManager as required in the pfl timer services.

public ResourceBundle

Returns:

The resource bundle set by setResourceBundle: may be null.
getResourceBundle()

Get the resource bundle (if any) set by setResourceBundle.

public Object

Returns:

the root constructed in a createRoot operation, or null if called before a createRoot call.
getRoot()

Return the root of this ManagedObjectManager.

public boolean
isManagedObject(Object obj)

Return true if object is assignment compatible with a class or interface that has an @ManagedObject annotation, otherwise false.

public GmbalMBean

Returns:

The MBean constructed from obj.
register(Object
The parent object that contains obj.
parent, Object
The managed object we are registering.
obj, String
The name to use for registering this object.
name)

Construct an Open Mean for obj according to its annotations, and register it with domain getDomain() and the appropriate ObjectName.

public GmbalMBean

Returns:

The MBean constructed from obj.
register(Object
The parent object that contains obj.
parent, Object
The managed object we are registering.
obj)

Same as register( parent, obj, name ), but here the name is derived from an @NameValue annotation.

public GmbalMBean

Returns:

The MBean constructed from obj.
registerAtRoot(Object
The object for which we construct and register an MBean.
obj, String
The name of the MBean.
name)

Registers the MBean for obj at the root MBean for the ObjectManager, using the given name.

public GmbalMBean

Returns:

The MBean constructed from obj.
registerAtRoot(Object
The managed object we are registering.
obj)

Same as registerAtRoot( Object, String ), but here the name is derived from an @ObjectKeyName annotation.

public void
resumeJMXRegistration()

Decrements the suspend counter, if the counter is greater than 0.

public void
setJMXRegistrationDebug(boolean
True to enalbed registration tracing.
flag)

Set debugging for JMX registrations.

public void
setMBeanServer(MBeanServer
The MBeanServer to set as the MBeanServer for this ManagedObjectManager.
server)

Set the MBeanServer to which all MBeans using this interface are published.

public void
setRegistrationDebug(ManagedObjectManager.RegistrationDebugLevel
NONE is no debugging at all, NORMAL traces high-level construction of skeletons and type converters, and dumps results of new skeletons and type converters, FINE traces everything in great detail. The tracing is done with INFO-level logger calls. The logger name is that package name (org.glassfish.gmbal.impl).
level)

Print debug output to System.out.

public void
setResourceBundle(ResourceBundle
The resource bundle to use. May be null.
rb)

Set the ResourceBundle to use for getting localized descriptions.

public void
setRuntimeDebug(boolean
true to enable runtime debug, false to disable.
flag)

Enable generation of debug log at INFO level for runtime MBean operations to the org.glassfish.gmbal.impl logger.

public void
setTypelibDebug(int
set to 1 to just see the results of the TypeEvaluator, >1 to see lots of details.

Warning

values >1 will result in a large amount of output.

level)

Enabled generation of debug log for type evaluator debugging.

public void
stripPackagePrefix()

Change the default type name algorithm so that if nothing else applies, the entire package prefix is stripped form the Class name.

public void
stripPrefix(String...
Class package name to strip from type name.
str)

Add a type prefix to strip from type names, to shorten the names for a better presentation to the user.

public void
suppressDuplicateRootReport(boolean suppressReport)

Suppress reporting of a duplicate root name.

public void
suspendJMXRegistration()

If called, no MBeans created after this call will be registered with the JMX MBeanServer until resumeJMXRegistration is called.

public void
unregister(Object
The object originally passed to a register method.
obj)

Unregister the Open MBean corresponding to obj from the mbean server.

Inherited from java.io.Closeable:
close

Method Detail

addAnnotationback to summary
public void addAnnotation(AnnotatedElement element, Annotation annotation)

Method to add an annotation to an element that cannot be modified. This is typically needed when dealing with an implementation of an interface that is part of a standardized API, and so the interface cannot be annotated by modifiying the source code. In some cases the implementation of the interface also cannot be inherited, because the implementation is generated by a standardized code generator. Another possibility is that there are several different implementations of the standardized interface, and it is undesirable to annotate each implementation with @InheritedAttributes.

Parameters
element:AnnotatedElement

The annotated element (class or method for our purposes).

annotation:Annotation

The annotation we wish to add to the element.

Exceptions
IllegalStateException:
if called after a call to a createRoot method.
addInheritedAnnotationsback to summary
public void addInheritedAnnotations(Class<?> cls)

Add all annotations for this class as if they were declared on the inheritance parent(s) of the class (immediate superclass for a class, all immediate superinterfaces for an interface). Also add all method annotations for methods that override an inherited method. This acts as if all annotations on cls were actually applied to the immediate super class or interface.

Parameters
cls:Class<?>

Class to analyze for inherited annotations.

createRootback to summary
public GmbalMBean createRoot()

Create a default root MBean. One of the createRoot methods must be called before any of the registration methods may be called. Only one call to a createRoot method is permitted after an ManagedObjectManager is created.

Returns:GmbalMBean

A default root MBean which supports only the AMX attributes.

Exceptions
IllegalStateException:
if called after a call to any createRoot method.
createRootback to summary
public GmbalMBean createRoot(Object root)

Create a root MBean from root, which much have a method with the @NameValue annotation. One of the createRoot methods must be called before any of the registration methods may be called. Only one call to createRoot is permitted after an ManagedObjectManager is created.

Parameters
root:Object

The Java object to be used to construct the root.

Returns:GmbalMBean

The newly constructed MBean.

Exceptions
IllegalStateException:
if called after a call to any createRoot method.
createRootback to summary
public GmbalMBean createRoot(Object root, String name)

Create a root MBean from root with the given name. One of the createRoot methods must be called before any of the registration methods may be called. Only one call to createRoot is permitted after an ManagedObjectManager is created.

Parameters
root:Object

The Java object to be used to construct the root.

name:String

The ObjectName name field to be used in the ObjectName of the MBean constructed from root.

Returns:GmbalMBean

The newly constructed MBean.

Exceptions
IllegalStateException:
if called after a call to any createRoot method.
dumpSkeletonback to summary
public String dumpSkeleton(Object obj)

Dump the skeleton used in the implementation of the MBean for obj. Obj must be currently registered.

Must be called after a successful call to a createRoot method.

Parameters
obj:Object

The registered object whose skeleton should be displayed.

Returns:String

The string representation of the skeleton.

getAMXClientback to summary
public AMXClient getAMXClient(Object obj)

Get an AMXClient instance for the object obj, if obj is registered as an MBean in this mom.

Must be called after a successful createRoot call.

Parameters
obj:Object

The object corresponding to an MBean.

Returns:AMXClient

An AMXClient that acts as a proxy for this MBean.

getDomainback to summary
public String getDomain()

Return the domain name that was used when this ManagedObjectManager was created. This is the JMX domain that will be used in all ObjectNames created by this ManagedObjectManager.

May be called at any time.

Returns:String

Get the domain name for this ManagedObjectManager.

getMBeanServerback to summary
public MBeanServer getMBeanServer()

Get the current MBeanServer.

May be called at any time.

Returns:MBeanServer

The current MBeanServer, either the default, or the value passed to setMBeanServer.

getObjectback to summary
public Object getObject(ObjectName oname)

Get the Object that was registered with the given ObjectName. Note that getObject and getObjectName are inverse operations.

Must be called after a successful createRoot call.

Parameters
oname:ObjectName

The ObjectName used to register the object.

Returns:Object

The Object passed to the register call.

getObjectNameback to summary
public ObjectName getObjectName(Object obj)

Get the ObjectName for the given object (which must have been registered via a register call).

Must be called after a successful createRoot call.

Parameters
obj:Object

The object originally passed to a register call.

Returns:ObjectName

The ObjectName used to register the MBean.

getObjectRegistrationManagerback to summary
public ObjectRegistrationManager getObjectRegistrationManager()

Return an ObjectRegistrationManager as required in the pfl timer services.

Can be called at any time.

getResourceBundleback to summary
public ResourceBundle getResourceBundle()

Get the resource bundle (if any) set by setResourceBundle.

May be called at any time.

Returns:ResourceBundle

The resource bundle set by setResourceBundle: may be null.

getRootback to summary
public Object getRoot()

Return the root of this ManagedObjectManager. May be called at any time.

Returns:Object

the root constructed in a createRoot operation, or null if called before a createRoot call.

isManagedObjectback to summary
public boolean isManagedObject(Object obj)

Return true if object is assignment compatible with a class or interface that has an @ManagedObject annotation, otherwise false. Only such objects may be registered to create MBeans. May be called at any time.

registerback to summary
public GmbalMBean register(Object parent, Object obj, String name)

Construct an Open Mean for obj according to its annotations, and register it with domain getDomain() and the appropriate ObjectName. The MBeanServer from setMBeanServer (or its default) is used. Here parent is considered to contain obj, and this containment is represented by the construction of the ObjectName following the AMX specification for ObjectNames.

The MBeanInfo for the result is actually ModelMBeanInfo, and may contain extra metadata as defined using annotations defined with the @DescriptorKey and @DescriptorField meta-annotations.

Must be called after a successful createRoot call.

This version of register should not be used to register singletons.

Parameters
parent:Object

The parent object that contains obj.

obj:Object

The managed object we are registering.

name:String

The name to use for registering this object.

Returns:GmbalMBean

The MBean constructed from obj.

Exceptions
IllegalStateException:
if called before a createRoot method is called successfully.
registerback to summary
public GmbalMBean register(Object parent, Object obj)

Same as register( parent, obj, name ), but here the name is derived from an @NameValue annotation.

This version of register should also be used to register singletons.

Parameters
parent:Object

The parent object that contains obj.

obj:Object

The managed object we are registering.

Returns:GmbalMBean

The MBean constructed from obj.

Exceptions
IllegalStateException:
if called before a createRoot method is called successfully.
registerAtRootback to summary
public GmbalMBean registerAtRoot(Object obj, String name)

Registers the MBean for obj at the root MBean for the ObjectManager, using the given name. Exactly the same as mom.register( mom.getRoot(), obj, name ).

Must be called after a successful createRoot call.

This version of register should not be used to register singletons.

Parameters
obj:Object

The object for which we construct and register an MBean.

name:String

The name of the MBean.

Returns:GmbalMBean

The MBean constructed from obj.

Exceptions
IllegalStateException:
if called before a createRoot method is called successfully.
registerAtRootback to summary
public GmbalMBean registerAtRoot(Object obj)

Same as registerAtRoot( Object, String ), but here the name is derived from an @ObjectKeyName annotation. Exactly the same as mom.register( mom.getRoot(), obj ).

This version of register should also be used to register singletons.

Parameters
obj:Object

The managed object we are registering.

Returns:GmbalMBean

The MBean constructed from obj.

Exceptions
IllegalStateException:
if called before a createRoot method is called successfully.
resumeJMXRegistrationback to summary
public void resumeJMXRegistration()

Decrements the suspend counter, if the counter is greater than 0. When the counter goes to zero, it causes all MBeans created since a previous call to suspendJMXRegistration incremented the counter from 0 to 1 to be registered with the JMX MBeanServer. After this call, all new MBean registration calls to the JMX MBeanServer happen within the register call. May be called at any time.

setJMXRegistrationDebugback to summary
public void setJMXRegistrationDebug(boolean flag)

Set debugging for JMX registrations. If true, all registrations and deregistrations with the MBeanServer are traced.

Parameters
flag:boolean

True to enalbed registration tracing.

setMBeanServerback to summary
public void setMBeanServer(MBeanServer server)

Set the MBeanServer to which all MBeans using this interface are published. The default value is java.lang.management.ManagementFactory.getPlatformMBeanServer().

Must be called before a successful createRoot call.

Parameters
server:MBeanServer

The MBeanServer to set as the MBeanServer for this ManagedObjectManager.

setRegistrationDebugback to summary
public void setRegistrationDebug(ManagedObjectManager.RegistrationDebugLevel level)

Print debug output to System.out.

May be called at any time.

Parameters
level:ManagedObjectManager.RegistrationDebugLevel

NONE is no debugging at all, NORMAL traces high-level construction of skeletons and type converters, and dumps results of new skeletons and type converters, FINE traces everything in great detail. The tracing is done with INFO-level logger calls. The logger name is that package name (org.glassfish.gmbal.impl).

setResourceBundleback to summary
public void setResourceBundle(ResourceBundle rb)

Set the ResourceBundle to use for getting localized descriptions. If not set, the description is the value in the annotation.

Must be called before a successful call to a createRoot method.

Parameters
rb:ResourceBundle

The resource bundle to use. May be null.

setRuntimeDebugback to summary
public void setRuntimeDebug(boolean flag)

Enable generation of debug log at INFO level for runtime MBean operations to the org.glassfish.gmbal.impl logger.

May be called at any time.

Parameters
flag:boolean

true to enable runtime debug, false to disable.

setTypelibDebugback to summary
public void setTypelibDebug(int level)

Enabled generation of debug log for type evaluator debugging. This happens as part of the registration process for the first time a particular class is processed.

May be called at any time.

Parameters
level:int

set to 1 to just see the results of the TypeEvaluator, >1 to see lots of details.

Warning

values >1 will result in a large amount of output.

stripPackagePrefixback to summary
public void stripPackagePrefix()

Change the default type name algorithm so that if nothing else applies, the entire package prefix is stripped form the Class name. Otherwise, the full Class name is the type.

Exceptions
IllegalStateException:
if called after a createRoot method.
stripPrefixback to summary
public void stripPrefix(String... str)

Add a type prefix to strip from type names, to shorten the names for a better presentation to the user. This may only be called before a createRot method is called.

Parameters
str:String[]

Class package name to strip from type name.

Exceptions
IllegalStateException:
if called after createRoot method.
suppressDuplicateRootReportback to summary
public void suppressDuplicateRootReport(boolean suppressReport)

Suppress reporting of a duplicate root name. If this option is enabled, createRoot( Object ) and createRoot( Object, String ) will return null for a duplicate root name, otherwise a Gmbal error will be reported. Note that this applies ONLY to createRoot: the register methods are unaffected. Also note that any other errors that might occur on createRoot will be reported normally.

Must be called before a successful call to a createRoot method.

suspendJMXRegistrationback to summary
public void suspendJMXRegistration()

If called, no MBeans created after this call will be registered with the JMX MBeanServer until resumeJMXRegistration is called. Each call increments a counter, so that nested and overlapping calls from multiple threads work correctly. May be called at any time.

unregisterback to summary
public void unregister(Object obj)

Unregister the Open MBean corresponding to obj from the mbean server.

Must be called after a successful createRoot call.

Parameters
obj:Object

The object originally passed to a register method.

org.glassfish.gmbal back to summary

public final Enum ManagedObjectManager.RegistrationDebugLevel

extends Enum<ManagedObjectManager.RegistrationDebugLevel>
Class Inheritance
DebugLevel used to control how much debug info is printed for registration of objects.

Field Summary

Modifier and TypeField and Description
public static final ManagedObjectManager.RegistrationDebugLevel
FINE

public static final ManagedObjectManager.RegistrationDebugLevel
NONE

public static final ManagedObjectManager.RegistrationDebugLevel
NORMAL

Constructor Summary

AccessConstructor and Description
private
RegistrationDebugLevel()

Method Summary

Modifier and TypeMethod and Description
public static ManagedObjectManager.RegistrationDebugLevel
valueOf(String name)

public static ManagedObjectManager.RegistrationDebugLevel[]
values()

Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

FINEback to summary
public static final ManagedObjectManager.RegistrationDebugLevel FINE
NONEback to summary
public static final ManagedObjectManager.RegistrationDebugLevel NONE
NORMALback to summary
public static final ManagedObjectManager.RegistrationDebugLevel NORMAL

Constructor Detail

RegistrationDebugLevelback to summary
private RegistrationDebugLevel()

Method Detail

valueOfback to summary
public static ManagedObjectManager.RegistrationDebugLevel valueOf(String name)
valuesback to summary
public static ManagedObjectManager.RegistrationDebugLevel[] values()