Version 15
Created by starksm64 on Sep 3, 2007 11:10 PM. Last modified by alrubinger on May 7, 2009 1:02 PM.

    ManagedObjectsThis page will be expaned to document how deployers annotate their metadata to produce the ManagedObjects used by the ProfileService

    Management Classes

    • org.jboss.managed.api.ManagedObject is an interface for a manageable element. It consists of:

      • - a name/name type for a registry/references

      • - an attachment name to associate the ManagedObject with a deployment attachment

      • - annotations from the metadata making up the ManagedObject

      • - the attachment instance

      • - the ManagedPropertys for the interface

      • - the ManagedOperations for the interface

    • org.jboss.managed.api.ManagedProperty is an interface describing a manageable field in a ManagedObject. Its analogous to the JavaBean property/JMX mbean attribute. Its a type safe wrapper around the Fields interface.

    • org.jboss.managed.api.ManagedOperation an interface for representing an operation in a management interface.

    • org.jboss.managed.api.ManagedParameter a parameter in a ManagedOperation

    • org.jboss.managed.api.Fields is an interface for a collection of named values that are associated with a managed property or operation.

    • org.jboss.managed.api.ManagedDeployment is an interface describing a collection of ManagedComponent and structural information about a deployment.

    • org.jboss.managed.api.ManagedComponent is an interface that extends ManagedObject to define a runtime component associated with a deployment.

    • org.jboss.managed.api.ComponentType a type/subtype qualification of a ManagedComponent

    • org.jboss.managed.api.DeploymentTemplateInfo a named collection of ManagedPropertys needed to create a deployment or component

    • org.jboss.managed.spi.factory.ManagedPropertyConstraintsPopulatorFactory - factory for obtaining a ManagedPropertyConstraintsPopulator
    • org.jboss.managed.spi.factory.ManagedPropertyConstraintsPopulator - Plugin for the ManagedProperty fields constraint related info.

     

    Meta Type Classes

    • org.jboss.metatype.api.types.MetaType<T extends Serializable> - root interface for meta types

      • org.jboss.metatype.api.types.AbstractMetaType<T extends Serializable> - base abstract class implementing MetaType

        • org.jboss.metatype.api.types.AbstractCompositeMetaType - base abstract class implementing CompositeMetaType

          • org.jboss.metatype.api.types.MapCompositeMetaType - A CompositeMetaType for Map<String, MetaValue>

        • org.jboss.metatype.api.types.ArrayMetaType - array of MetaType

        • org.jboss.metatype.api.types.EnumMetaType - java enum type.

        • org.jboss.metatype.api.types.GenericMetaType - an opaque pass through wrapper for types that don't fit into another MetaType.

        • org.jboss.metatype.api.types.SimpleMetaType - a wrapper type for primatives; BigDecimal, BigInteger, Boolean/boolean, Byte/byte, Character/char, Date, Double/double, Float/float, Integer/int, Long/long, Short/short, String, Void/void.

      • org.jboss.metatype.api.types.CompositeMetaType - a key/value collection type.

      • org.jboss.metatype.api.types.PropertiesMetaType - a java.util.Properties type

      • org.jboss.metatype.api.types.TableMetaType - a table structure with the rows being a CompositeMetaType.

      • org.jboss.metatype.api.types.MetaTypeFactory - A factory api for resolving java class names, java.lang.reflect.Type(s), and org.jboss.reflect.spi.TypeInfo(s) to a MetaType. The api supports MetaTypeBuilder plugin which can be used to specify how to create the MetaType for a given Class.
        • setBuilder(Class<?> clazz, MetaTypeBuilder builder);
      • org.jboss.metatype.spi.types.MetaTypeBuilder - a factory that returns a MetaType. Its associated with a Java Class via the MetaTypeFactory#setBuilder(Class<?> clazz, MetaTypeBuilder builder).
      • org.jboss.metatype.api.annotations.MetaMapping - Specifies a MetaMapper implementation class to use for a property.
      • org.jboss.metatype.api.annotations.MetaMappingFactory - Specifies a MetaMapperFactory to create a MetaMapper.
      • org.jboss.metatype.plugins.types.DefaultMetaTypeFactory - a default implementation of MetaTypeFactory that handles the basic Java to MetaType mappings.

    MetaValue Classes

    • org.jboss.metatype.spi.values.MetaMapper<T> - defines type mappings and MetaValue wrapping/unwrapping:
      • MetaType getMetaType();
      • Type mapToType();
      • MetaValue createMetaValue(MetaType metaType, T object);
      • T unwrapMetaValue(MetaValue metaValue);
    • org.jboss.metatype.spi.values.MetaMapperFactory<T> - A factory spi for creating MetaMapper<T> instances.
      • MetaMapper<T> newInstance();
      • MetaMapper<T> newInstance(String...args);
    • org.jboss.metatype.spi.values.MetaValueBuilder<T> - a factory that creates a MetaValue for a given MetaType and T instance
      • MetaValue buildMetaValue(MetaType metaType, T object);
    • org.jboss.metatype.api.values.MetaValue extends Serializable, Cloneable - the base value interface that defines access to MetaType and cloning.
      • ArrayValue  extends MetaValue, Iterable<Object>
      • CollectionValue extends MetaValue, Iterable<MetaValue>
      • CompositeValue extends MetaValue
      • EnumValue extends MetaValue
      • GenericValue extends MetaValue
      • SimpleValue extends MetaValue, Comparable<SimpleValue>
      • TableValue extends MetaValue
    • org.jboss.metatype.api.values.InstanceFactory<T> - factory for creating Java bean instances from a org.jboss.beans.info.spi.BeanInfo
      • T instantiate(BeanInfo beanInfo) throws Throwable;
    • org.jboss.metatype.api.values.MetaValueFactory - A MetaValue wrapping/unwrapping factory that can be customized via the setBuilder and setInstanceFactory methods.
      • MetaValue create(Object value);
      • MetaValue create(Object value, Type type);
      • MetaValue create(Object value, TypeInfo type);
      • setBuilder(Class<?> clazz, MetaValueBuilder<?> builder);
      • setInstanceFactory(Class<T> clazz, InstanceFactory<T> factory);
      • Object unwrap(MetaValue metaValue);
      • Object unwrap(MetaValue metaValue, Type type);
      • Object unwrap(MetaValue metaValue, TypeInfo type);
    • org.jboss.metatype.plugins.values.DefaultMetaValueFactory - the default MetaValueFactory which handles the normal Java to MetaValue wrapping/unwrapping.

    Controlling Java to MetaValue Mappings

    The org.jboss.metatype.api.types.MetaTypeFactory and org.jboss.metatype.api.values.MetaValueFactory apis are used to convert to/from Java types and values to MetaTypes and MetaValues. You can change type mapping behavior by using the MetaTypeFactory.setBuilder plugin.

     

    For ManagedProperty definition, you can control the type and value mappings using a MetaMapper on the property. This can be done by populating the ManagedProperty transient attachments, or using a MetaMapping/MetaMappingFactory annotation as shown below.

    @ManagementObject
public class ObjectNameBean
{
   private ObjectName nameAsString;
   private ObjectName nameAsComposite;
   private ObjectName nameAsCompositeFixedKeys;
   private ObjectName nameAsProperties;

   @ManagementProperty()
   @MetaMapping(StringObjectNameMetaMapper.class)
   public ObjectName getNameAsString()
   {
      return nameAsString;
   }
   public void setNameAsString(ObjectName nameAsString)
   {
      this.nameAsString = nameAsString;
   }

   @ManagementProperty()
   @MetaMapping(ObjectNameMetaMapper.class)
   public ObjectName getNameAsComposite()
   {
      return nameAsComposite;
   }
   public void setNameAsComposite(ObjectName nameAsComposite)
   {
      this.nameAsComposite = nameAsComposite;
   }

   @ManagementProperty()
   @MetaMapping(PropertiesObjectNameMetaMapper.class)
   public ObjectName getNameAsProperties()
   {
      return nameAsProperties;
   }
   public void setNameAsProperties(ObjectName nameAsProperties)
   {
      this.nameAsProperties = nameAsProperties;
   }
   @ManagementProperty()
   @MetaMappingFactory(value=ObjectNameMetaMapperFactory.class,
    args={"key1", "The first key", "key2", "The second key"})
   public ObjectName getNameAsCompositeFixedKeys()
   {
      return nameAsCompositeFixedKeys;
   }
   public void setNameAsCompositeFixedKeys(ObjectName nameAsCompositeFixedKeys)
   {
      this.nameAsCompositeFixedKeys = nameAsCompositeFixedKeys;
   }   
}

     

     

    The Management Annotations

    The annotations available for defining the management interfaces include:

     

    • org.jboss.managed.api.annotation.ManagementObject - a class level annotation that identifies a metadata class as a ManagedObject.

    • org.jboss.managed.api.annotation.ManagementObjectID - identifies a ManagedObject key/type qualifier source.

    • org.jboss.managed.api.annotation.ManagementObjectRef - indicates a property that references another ManagedObject

    • org.jboss.managed.api.annotation.ManagementRuntimeRef - identifies a property as a runtime component name provider property

    • org.jboss.managed.api.annotation.ManagementProperty - annotation for describing a ManagedProperty

    • org.jboss.managed.api.annotation.ManagementComponent - identifies a property as metadata identifying a ManagedComponent.

    • org.jboss.managed.api.annotation.ManagementOperation - An annotation for describing a ManagedOperation

    • org.jboss.managed.api.annotation.ManagementParameter - Annotation for documenting a ManagementOperation parameter

    • org.jboss.managed.api.annotation.ManagementDeployment - Annotation identifying a managed deployment
    • org.jboss.managed.api.annotation.ManagementPropertyFactory - An annotation describing the implementation class for a ManagedProperty. This can be used on fields,methods for an individual property, or on a type to specify the default factory for all properties in a managed object.
    • org.jboss.managed.api.annotation.ConstraintsPopulatorFactory - An annotation describing the ManagedPropertyConstraintsPopulatorFactory for a property. This can be used on fields,methods for an individual property, or on a type to specify the default factory for all properties in a managed object.
    • org.jboss.managed.api.annotation.FieldsFactory - An annotation for describing the Fields class to use for a ManagedProperty. This can be used on fields,methods for an individual property, or on a type to specify the default factory for all properties in a managed object.
    • org.jboss.managed.api.annotation.ViewUse - An enum for the types of management uses a  is associated with.
      • CONFIGURATION, A read-write property used for creating/updating a config
      • RUNTIME, A read-write type of property that can be set on the runtime component
      • STATISTIC, A read-only type of property that provides runtime stats

     

    Annotating a Service MBean Class

    To create the ManagedObjects for an mbean service, annotate the class referred to by the mbean code attribute:

     

    import org.jboss.managed.api.ManagedOperation.Impact;
import org.jboss.managed.api.annotation.ManagementObject;
import org.jboss.managed.api.annotation.ManagementObjectID;
import org.jboss.managed.api.annotation.ManagementOperation;
import org.jboss.managed.api.annotation.ManagementParameter;
import org.jboss.managed.api.annotation.ManagementProperties;
import org.jboss.managed.api.annotation.ManagementProperty;
import org.jboss.managed.api.annotation.ViewUse;

@ManagementObject(componentType=@ManagementComponent(type="DataSourcePool",
     subtype="PoolBySubject"), properties=ManagementProperties.EXPLICIT)
public class SomePool extends ServiceMBeanSupport 
   implements SomePoolMBean
{
   @ManagementOperation(description="Obtain a formatted statistics report",
         impact=Impact.ReadOnly,
         params={@ManagementParameter(name="formatClassName",
          description="The StatisticsFormatter class name")})
   public Object listFormattedSubPoolStatistics(String formatClassName)
   {
...
   }

   @ManagementOperation(description="Obtain a formatted statistics report",
         impact=Impact.ReadOnly)
   public Object listFormattedSubPoolStatistics()
   {
   }
   
   @ManagementOperation(description="Obtain a statistics report",
         impact=Impact.ReadOnly)
   public Object listStatistics()
   {
   }
   
   @ManagementProperty(use={ViewUse.STATISTIC}, description="number of available connection")
   public long getAvailableConnectionCount()
   {
   }

   @ManagementProperty(use={ViewUse.STATISTIC},
     description="number of maximum connections in use")
   public long getMaxConnectionsInUseCount()
   {
   }

   @ManagementProperty(use={ViewUse.STATISTIC},
     description="number of connections currently in use")
   public long getInUseConnectionCount ()
   {
   }

   @ManagementProperty(use={ViewUse.STATISTIC})
   public int getMinSize()
   {
   }

   @ManagementProperty(use={ViewUse.STATISTIC})
   public int getMaxSize()
   {
      return poolParams.maxSize;
   }

   @ManagementOperation(description="Flush the connections in the pool",
         impact=Impact.WriteOnly)
   public void flush()
   {
   }

   @ManagementProperty(use={ViewUse.STATISTIC})
   public int getConnectionCount()
   {
   }

   @ManagementProperty(use={ViewUse.STATISTIC})
   public int getConnectionCreatedCount()
   {
   }

   @ManagementProperty(use={ViewUse.STATISTIC})
   public int getConnectionDestroyedCount()
   {
   }

   @ManagementObjectID(type="DataSourcePool")
   @ManagementProperty(use={ViewUse.RUNTIME})
   public String getPoolJndiName()
   {
      return this.poolJndiName;
   } 
}

    Specifying an MCBean management interface via xml

    The following example shows the transaction manager service MC bean exposing a management interface via the @org.jboss.managed.api.annotation.ManagementObject annotation, based on the com.arjuna.ats.jbossatx.jta.TransactionManagerServiceMBean.class mbean interface. Note that although the annotation is wrapped to fit in the text field here, the declaration must be a single line due to annotation parsing limitation currently.

     

        <bean name="TransactionManager" class="com.arjuna.ats.jbossatx.jta.TransactionManagerService">
      <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss:service=TransactionManager", exposedInterface=com.arjuna.ats.jbossatx.jta.TransactionManagerServiceMBean.class, registerDirectly=true)</annotation>
      <annotation>@org.jboss.managed.api.annotation.ManagementObject(name="TransactionManager",
componentType=@org.jboss.managed.api.annotation.ManagementComponent(type = "MCBean",
subtype = "JTA"),
targetInterface=com.arjuna.ats.jbossatx.jta.TransactionManagerServiceMBean.class)</annotation>
...

     

    Specifying Constraints on Properties

     

    @ManagementObject
public class ConstrainedBean
{
   private float temperature;
   private Float pi;
   private Short dayOfYear;
   private int day;
   private String month;

   @ManagementProperty()
   @ConstraintsPopulatorFactory(value=NumberConstraintsPopulatorFactory.class,
         min="0",max="100")
   public float getTemperature()
   {
      return temperature;
   }
   public void setTemperature(float temperature)
   {
      this.temperature = temperature;
   }
   @ManagementProperty()
   @ConstraintsPopulatorFactory(value=NumberConstraintsPopulatorFactory.class,
         min="3",max="3.14159")
   public Float getPi()
   {
      return pi;
   }
   public void setPi(Float pi)
   {
      this.pi = pi;
   }
   @ManagementProperty()
   @ConstraintsPopulatorFactory(value=NumberConstraintsPopulatorFactory.class,
         min="1",max="365")
   public Short getDayOfYear()
   {
      return dayOfYear;
   }
   public void setDayOfYear(Short dayOfYear)
   {
      this.dayOfYear = dayOfYear;
   }
   @ManagementProperty()
   @ConstraintsPopulatorFactory(value=StringLegalValuesPopulatorFactory.class,
         legalValues={"JAN", "FEB", "MAR", "APR", "MAY", "JUN", "JUL", "AUG", "SEP", "OCT", "NOV", "DEC"})
   public String getMonth()
   {
      return month;
   }
   public void setMonth(String month)
   {
      this.month = month;
   }
   @ManagementProperty()
   @ConstraintsPopulatorFactory(value=NumberConstraintsPopulatorFactory.class,
         min="1",max="31")
   public int getDay()
   {
      return day;
   }
   public void setDay(int day)
   {
      this.day = day;
   }
}

     

    Debugging

     

    In order to print out all ManagementObjects in a TXT trace, use the simple Servlet included in the JMX Console:


    http://localhost:8080/jmx-console/ProfileServiceDebugServlet?op=listDeploymentTree


    8554 Views Categories: Tags: