|
|||||||||
Consortium Activities Projects Forge Events |
Fractal |
About the Fraclet Annotation Framework
Fraclet is both an implementation of the Fractal specifications conformed to the level 0.1, and an annotation framework for the Fractal component model. Fraclet is composed of several annotations and plugins to generate automatically various artifacts required by the Fractal component model. Annotations provide a way to describe the component meta-information directly in the source code of the content class. Fraclet plugins generate either Fractal component glue, FractalADL definitions or Monolog configurations. This approach has several benefits:
Two implementations of the Fraclet annotation framework exist: Fraclet XDoc and Fraclet Annotation.
This tutorial describes the Fraclet Xdoc implementation. Table of Contents1. Fraclet XDoc: An XDoclet2 plugin for FractalFraclet uses the XDoclet2 as annotation parser and generation engine.
XDoclet2 is supported by XDoclet2 plugins, which provide task-specific generation functionality. This part describes the features of this XDoclet2 plugin for Fractal, and the way to use them. 1.1 Available AnnotationsSome annotations have been defined in order to describe the component meta-information. The list below describes these annotations.
The @provides annotationDetails: This class annotation adds the name information to the definition of a Fractal interface. This name is required by the Fractal component model to identify the interfaces required and provided by a Fractal component. This annotation can also override the associated interface signature to introduce interface meta-information at the class level. Parameters:
Examples: /** @provides name=m */ public interface Main { ... } /** @provides name=r signature=java.lang.Runnable */ public class Client implements Runnable { ... } The @component annotationDetails: This class annotation allows the developer to describe the description of the controller part that should be associated to the content part of the Fractal component. Parameters:
Example: /** @component name=fc.client controller=primitive */ public class Client implements Runnable { ... } /** @component controller=primitive template=primitiveTemplate */ public class Client implements Runnable { ... } The @data annotationDetails: This class annotation provides a way to define a data used by a Fractal component. Example: /** @data */ public class Message { ... } The @monolog.handler annotationDetails: This class annotation allows the developer to describe a Monolog handler specific to the Fractal component. The available annotation attributes support the various properties that can be defined in a Monolog configuration file. Parameters:
Example: /** @monolog.handler name=clientHandler output=System.err pattern="%-5l [%h] <%t> %m%n" */ public class Client implements Runnable { ... } The @attribute annotationDetails: This field annotation describes a Fractal attribute. A Fractal attribute is a Java attribute whose value can be configured and introspected from the Fractal component. Fractal attributes are managed by the attribute control feature of the Fractal component model. Parameters:
Example: public class Client implements Runnable { /** @attribute name=count value=2 */ protected int counter; // field should be declared as protected or public. /** @attribute value="->" */ protected String prefix; /** @attribute */ protected String suffix; ... } The @requires annotationDetails: This field annotation describes a Fractal binding. A Fractal binding is a Java attribute representing a client interface. Fractal bindings are managed by the binding control feature of the Fractal component model. Parameters:
Example: public class Client implements Runnable { /** @requires name=s signature=Service cardinality=collection */ protected Map servers = new HashMap(); // collections are stored in a map /** @requires */ protected Service service; ... } The @control annotationDetails: This field annotation provides a way to refer a control interface provided by the controller part of the associated Fractal component. Parameters:
Example: public class Client implements Runnable { /** @control name=name-controller */ protected NameController nc; // field should be declared as protected or public. /** @control */ protected Component self; ... } The @logger annotationDetails: This field annotation provides a way to define a Monolog logger to log the execution of the Fractal component. Parameters:
Example: public class Client implements Runnable { /** @logger name=c handler="clientHandler,fileHandler" */ protected Logger log; // field should be declared as protected or public. /** @logger */ protected Logger log2; ... } Julia Configuration: To enable the Monolog support in Julia, the ... # LifeCycleController implementation (for primitive or composite components) (lifecycle-controller-impl ((org.objectweb.fractal.julia.asm.MixinClassGenerator LifeCycleControllerImpl org.objectweb.fractal.julia.BasicControllerMixin org.objectweb.fractal.julia.UseComponentMixin org.objectweb.fractal.julia.control.lifecycle.BasicLifeCycleCoordinatorMixin org.objectweb.fractal.julia.control.lifecycle.BasicLifeCycleControllerMixin # to check that mandatory client interfaces are bound in startFc: org.objectweb.fractal.julia.control.lifecycle.TypeLifeCycleMixin # to automatically assign the logger and logger factory: org.objectweb.fractal.julia.BasicInitializableMixin org.objectweb.fractal.julia.logger.LoggerLifeCycleMixin # to notify the encapsulated component (if present) when its state changes: org.objectweb.fractal.julia.control.lifecycle.ContainerLifeCycleMixin ) # optional initialization parameter (monolog configuration file name): (monolog-conf-file monolog.properties) ) ) ... AOKell Configuration: To enable the Monolog support in AOKell, the ... # The loggable feature determines whether primitive components are equipped # with a monolog logger or not (which is the default case). # Uncomment the following property for using primitive components equipped # with a monolog logger. feature.loggable.on true ... The @lifecycle annotationDetails: This method annotation provides a way to define a lifecycle handler supported by the controller part of the associated Fractal component. Parameters:
Example: public class Client implements Runnable { /** @lifecycle when=start */ protected void init() { System.out.println("Starting the component Client..."); } ... } 1.2 Available PluginsSome plugins have been defined in order to generate the component artifacts. The list below describes these plugins:
The AttributeControllerPlugin generatorDetails: Generates the Usage: <target name="compile"> <taskdef name="xdoclet" classname="org.xdoclet.ant.XDocletTask" classpathref="classpath"/> <mkdir dir="${gen}"/> <xdoclet> <fileset dir="${src}" includes="**/*.java" /> <component destdir="${gen}" classname="org.objectweb.fractal.fraclet.AttributeControllerPlugin"/> </xdoclet> ... </target> The PrimitiveComponentPlugin generatorDetails: Generates the Usage: <target name="compile"> <taskdef name="xdoclet" classname="org.xdoclet.ant.XDocletTask" classpathref="classpath"/> <mkdir dir="${gen}"/> <xdoclet> <fileset dir="${src}" includes="**/*.java" /> <component destdir="${gen}" classname="org.objectweb.fractal.fraclet.PrimitiveComponentPlugin"/> </xdoclet> ... </target> The PrimitiveDefinitionPlugin generatorGenerates the Usage: <target name="compile"> <taskdef name="xdoclet" classname="org.xdoclet.ant.XDocletTask" classpathref="classpath"/> <mkdir dir="${build}"/> <xdoclet> <fileset dir="${src}" includes="**/*.java" /> <component destdir="${build}" classname="org.objectweb.fractal.fraclet.PrimitiveDefinitionPlugin"/> </xdoclet> ... </target> The CompositeDefinitionPlugin generatorDetails: Generates the Usage: <target name="compile"> <taskdef name="xdoclet" classname="org.xdoclet.ant.XDocletTask" classpathref="classpath"/> <mkdir dir="${build}"/> <xdoclet> <fileset dir="${src}" includes="**/*.java" /> <component destdir="${build}" classname="org.objectweb.fractal.fraclet.CompositeDefinitionPlugin"/> </xdoclet> ... </target> The MonologConfigurationPlugin generatorDetails: Generates the Usage: <target name="compile"> <taskdef name="xdoclet" classname="org.xdoclet.ant.XDocletTask" classpathref="classpath"/> <mkdir dir="${build}"/> <xdoclet> <fileset dir="${src}" includes="**/*.java" /> <component destdir="${build}" classname="org.objectweb.fractal.fraclet.MonologConfigurationPlugin"/> </xdoclet> ... </target> 1.3 Revisiting the HelloWorld Example with FracletThis section provides a quick overview of the benefits of Fraclet. It shows that using annotations, Fractal source code becomes more concise and easier to maintain. It shows that using Fractlet, more than 60% of the source code (Java, FractalADL, properties) can be saved. HelloWorld Architecture OverviewThe figure below introduces the well-known HelloWorld example implemented with Fractal components.
HelloWorld ImplementationThe source code below represents the Java code and the Fraclet annotations written to implement the /** @provides name=r signature=java.lang.Runnable */ public class Client implements Runnable { /** @requires */ protected Service s ; /** @attribute value="Hello !" */ protected String message; public void run() { this.defaut.print(this.message); } } The /** @provides name=s */ public interface Service { void print(String message); } The public class Server implements Service { /** @attribute */ protected String header; /** @attribute */ protected int counter; public void print(final String message) { for (int i = 0; i < this.counter; i++) System.out.println(this.header + message); } } The HelloWorld Architecture DefinitionThe assembly definition below represents the FractalADL assembly defined to describe the <definition name="HelloWorld" extends="ClientComposite"> <component name="s" definition="Server(>>,2)"/> </definition> This definition creates a composite component Compilation with AntThe following piece of XML presents the compilation process enhanced with the Fractal plugins. <project name="helloworld" default="compile"> ... <target name="compile"> <taskdef name="xdoclet" classname="org.xdoclet.ant.XDocletTask" classpathref="classpath"/> <mkdir dir="${gen}"/> <mkdir dir="${build}"/> <xdoclet> <fileset dir="${src}" includes="**/*.java" /> <component destdir="${gen}" classname="org.objectweb.fractal.fraclet.AttributeControllerPlugin"/> <component destdir="${gen}" classname="org.objectweb.fractal.fraclet.PrimitiveComponentPlugin"/> <component destdir="${build}" classname="org.objectweb.fractal.fraclet.PrimitiveDefinitionPlugin"/> <component destdir="${build}" classname="org.objectweb.fractal.fraclet.CompositeDefinitionPlugin"/> <component destdir="${build}" classname="org.objectweb.fractal.fraclet.MonologConfigurationPlugin"/> </xdoclet> <javac srcdir="${src}:${gen}" destdir="${build}" classpathref="classpath"> <include name="**/*.java"/> </javac> <copy todir="${build}"> <fileset dir="${src}"> <exclude name="**/*.java"/> <exclude name="**/*.html"/> </fileset> </copy> </target> ... </project> Directory StructureThe directory structure below presents the list of compiled, generated and written files when using Fraclet to implement the HelloWorld example: %example% * build/ - Client.class - Client.fractal - ClientAttributes.class - ClientComposite.fractal - FcClient.class - FcServer.class - HelloWorld.fractal - Server.class - Server.fractal - ServerAttributes.class - Service.class - Service.fractal * generated/ - ClientAttributes.java - FcClient.java - FcServer.java - ServerAttributes.java * src/ - Client.java - HelloWorld.fractal - Server.java - Service.java 2. Fraclet AvailabilityFraclet is freely available under an LGPL licence at the following URLs:
3. Dissemination
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Copyright © 1999-2009, OW2 Consortium | contact | webmaster | Last modified at 2012-12-03 09:57 PM |