From do-not-reply at jboss.org Mon Aug 23 09:30:31 2010 Content-Type: multipart/mixed; boundary="===============2458627304809485909==" MIME-Version: 1.0 From: do-not-reply at jboss.org To: exo-jcr-commits at lists.jboss.org Subject: [exo-jcr-commits] exo-jcr SVN: r2975 - in jcr/branches/1.12.x/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules: kernel and 1 other directory. Date: Mon, 23 Aug 2010 09:30:31 -0400 Message-ID: <201008231330.o7NDUVMQ024775@svn01.web.mwc.hst.phx2.redhat.com> --===============2458627304809485909== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: sergiykarpenko Date: 2010-08-23 09:30:30 -0400 (Mon, 23 Aug 2010) New Revision: 2975 Added: jcr/branches/1.12.x/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docb= ook/en-US/modules/kernel/manageability.xml Modified: jcr/branches/1.12.x/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docb= ook/en-US/modules/kernel.xml Log: EXOJCR-896: Port Manageability article into docbook Added: jcr/branches/1.12.x/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/= docbook/en-US/modules/kernel/manageability.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- jcr/branches/1.12.x/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/doc= book/en-US/modules/kernel/manageability.xml (rev 0) +++ jcr/branches/1.12.x/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/doc= book/en-US/modules/kernel/manageability.xml 2010-08-23 13:30:30 UTC (rev 29= 75) @@ -0,0 +1,223 @@ + + + + + + Manageability + +
+ Introduction + + The kernel has a framework for exposing a management view of the + various sub systems of the platform. The management view is a lose term + for defining how we can access relevant information about the system a= nd + how we can apply management operations. JMX is the de facto standard f= or + exposing a management view in the Java Platform but we take in + consideration other kind of views such as REST web services. Therefore= the + framework is not tied to JMX, yet it provides a JMX part to define more + precisely details related to the JMX management view. The legacy frame= work + is still in use but is deprecated in favor of the new framework as it = is + less tested and less efficient. It will be removed by sanitization in = the + future. +
+ +
+ Managed framework API + + The managed frameworks defines an API for exposing a management = view + of objects. The API is targeted for internal use and is not a public A= PI. + The framework leverages Java 5 annotations to describe the management = view + from an object. + +
+ Annotations + +
+ @org.exoplatform.management.annotations.Managed + annotation + + The @Managed annotates elements that wants to expose a + management view to a management layer. + + @Managed for objects + + The framework will export a management view for the objects + annotated. + + @Managed for + getter/setter + + Defines a managed property. An annotated getter defines a re= ad + property, an annotated setter defines a write property and if matc= hing + getter/setter are annotated it defines a read/write property. + + @Managed on method + + Defines a managed operation. +
+ +
+ @org.exoplatform.management.annotations.ManagedDescription<= /title> + + <para>The @ManagedDescription annotation provides a description of= a + managed element. It is valid to annotated object or methods. It ta= kes + as sole argument a string that is the description value.</para> + </section> + + <section> + <title>@org.exoplatform.management.annotations.ManagedName + + The @ManagedName annotation provides an alternative name for + managed properties. It is used to accomodate legacy methods of an + object that can be renamed for compatibility reasons. It takes as = sole + argument a string that is the name value. +
+ +
+ @org.exoplatform.management.annotations.ManagedBy + + The @ManagedBy annotation defines a delegate class for expos= ing + a management view. The sole argument of the annotation are class + litterals. The delegate class must provide a constructor with the + managed object as argument. +
+
+
+ +
+ JMX Management View + +
+ JMX Annotations + +
+ @org.exoplatform.management.jmx.annotations.Property + annotation + + The @Property annotation is used to within other annotations + such as @NameTemplate or @NamingContext. It should be seen as a + structural way for a list of properties. A property is made of a k= ey + and a value. The value can either be a string litteral or it can be + surrounded by curly brace to be a dynamic property. A dynamic prop= erty + is resolved against the instance of the object at runtime. +
+ +
+ @org.exoplatform.management.jmx.annotations.NameTemplate + annotation + + The @NameTemplate defines a template that is used at + registration time of a managed object to create the JMX object nam= e. + The template is formed of properties. + + @NameTemplate({ + @Property(key=3D"container", value=3D"workspace"), + @Property(key=3D"name", value=3D"{Name}")}) +
+ +
+ @org.exoplatform.management.jmx.annotations.NamingContext + annotation + + The @NamingContext annotations defines a set of properties w= hich + are used within a management context. It allows to propagate + properties down to managed objects which are defined by an object + implementing the ManagementAware interface. The goal is to scope + different instances of the same class that would have the same obj= ect + name otherwise. + + @NamingContext(@Property(key=3D"workspace", value= =3D"{Name}")) +
+
+
+ +
+ Example + +
+ CacheService example + + The cache service delegates most of the work to the + CacheServiceManaged class by using the @ManagedBy annotation. At run= time + when a new cache is creates it calls the CacheServiceManaged class in + order to let the CacheServiceManaged object register the cache. + + @ManagedBy(CacheServiceManaged.class) +public class CacheServiceImpl implements CacheService { + + CacheServiceManaged managed; + ... + synchronized private ExoCache createCacheInstance(String region) throws = Exception { + ... + if (managed !=3D null) { + managed.registerCache(simple); + } + ... + } +} + + The ExoCache interface is annotated to define its management v= iew. + The @NameTemplate is used to produce object name values when ExoCache + instance are registered. + + @Managed +(a)NameTemplate({@Property(key=3D"service", value=3D"cache"), @Property(ke= y=3D"name", value=3D"{Name}")}) +(a)ManagedDescription("Exo Cache") +public interface ExoCache { + + @Managed + @ManagedName("Name") + @ManagedDescription("The cache name") + public String getName(); + + @Managed + @ManagedName("Capacity") + @ManagedDescription("The maximum capacity") + public int getMaxSize(); + + @Managed + @ManagedDescription("Evict all entries of the cache") + public void clearCache() throws Exception; + + ... +} + + The CacheServiceManaged is the glue code between the CacheServ= ice + and the management view. The main reason is that only exo services a= re + registered automatically against the management view. Any other mana= ged + bean must be registered manually for now. Therefore it needs to know + about the management layer via the management context. The management + context allows an object implementing the ManagementAware interface = to + receive a context to perform further registration of managed + objects. + + @Managed +public class CacheServiceManaged implements ManagementAware { + + /** . */ + private ManagementContext context; + + /** . */ + private CacheServiceImpl cacheService; + + public CacheServiceManaged(CacheServiceImpl cacheService) { + this.cacheService =3D cacheService; + + // + cacheService.managed =3D this; + } + + public void setContext(ManagementContext context) { + this.context =3D context; + } + + void registerCache(ExoCache cache) { + if (context !=3D null) { + context.register(cache); + } + } +} +
+
+ Modified: jcr/branches/1.12.x/exo.jcr.docs/exo.jcr.docs.developer/en/src/ma= in/docbook/en-US/modules/kernel.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- jcr/branches/1.12.x/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/doc= book/en-US/modules/kernel.xml 2010-08-23 12:54:52 UTC (rev 2974) +++ jcr/branches/1.12.x/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/doc= book/en-US/modules/kernel.xml 2010-08-23 13:30:30 UTC (rev 2975) @@ -51,9 +51,6 @@ = - - - - - + --===============2458627304809485909==--