|
|||||||||||
PREV NEXT | FRAMES NO FRAMES |
See:
Description
Packages | |
org.objectweb.fractal.fraclet | contains the available Fraclet generators. |
org.objectweb.fractal.fraclet.doclets | contains the available Fraclet annotations. |
Fraclet is 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:
Fraclet uses the XDoclet2 as annotation parser and generation engine.
XDoclet is an open source code generation engine. It enables Attribute-Oriented Programming for java. In short, this means that you can add more significance to your code by adding meta data (attributes) to your java sources. This is done in special JavaDoc tags. This use of JavaDoc tags for attributes formed the original ideas for Java 5 Annotations.
XDoclet2 is the next generation of this technology. Based on Generama, it uses standard template engines such as Velocity and Freemarker for generation of text-oriented output, and Jelly for XML output. The function of XDoclet2 is to seed the generation contexts for these template engines.
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.
Some annotations have been defined in order to describe the component meta-information. The list below describes these annotations.
Annotation | Location | Description |
---|---|---|
@fractal.itf | Class | Annotation to describe a Fractal business interface. |
@fractal.ctrl | Class | Annotation to describe the controller part of a Fractal component. |
@fractal.tmpl | Class | Annotation to describe the controller part of a Fractal template component. |
@monolog.handler | Class | Annotation to describe a custom Monolog handler. |
@fractal.ac | Field | Annotation to describe an attribute of a Fractal component. |
@fractal.bc | Field | Annotation to describe a binding of a Fractal component. |
@fractal.rc | Field | Annotation to describe a reflective control on a Fractal component. |
@fractal.log | Field | Annotation to describe a logger in a Fractal component. |
Details:
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:
Parameter | Description | Contingency |
---|---|---|
name | the name of the Fractal interface. | Required |
signature | the signature of the Fractal interface. | Optional (default value is the Class signature) |
Examples:
/** @fractal.itf name="m" */ public interface Main { ... } /** @fractal.itf name="r" signature="java.lang.Runnable" */ public class Client implements Runnable { ... }
Details:
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:
Parameter | Description | Contingency |
---|---|---|
desc | the definition name of the controller part of the Fractal component. | Required |
Example:
/** @fractal.ctrl desc="primitive" */ public class Client implements Runnable { ... }
Details:
This class annotation allows the developer to describe the description of the controller part that should be associated to the template part of the Fractal component.
Parameters:
Parameter | Description | Contingency |
---|---|---|
desc | the definition name of the controller part of the Fractal template component. | Required |
Example:
/** @fractal.tmpl desc="primitiveTemplate" */ public class Client implements Runnable { ... }
Details:
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:
Parameter | Description | Contingency |
---|---|---|
name | the identifier of the handler. | Required |
type | the type of the handler. | Optional (default value is Console ) |
output | the output flow of the handler. | Optional (default value is System.out ) |
pattern | the output pattern of the handler. | Optional (default value is %l: %m%n ) |
max-size | the maximal size of the output file. | Optional |
file-number | the number of files used by the handler. | Optional |
append-mode | tag to use the handler in append mode (true |false ). | Optional (default value is false ) |
Example:
/** @monolog.handler name="clientHandler" output="System.err" pattern="%-5l [%h] <%t> %m%n" */ public class Client implements Runnable { ... }
Details:
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:
Parameter | Description | Contingency |
---|---|---|
name | the name of the Fractal attribute. | Optional (default value is the Field name) |
argument | the name of the component argument used to configure the Fractal attribute. | Optional (default value is the Field name is no value is defined) |
value | the default value of the Fractal attribute. | Optional |
Example:
public class Client implements Runnable { /** @fractal.ac name="count" value=2 */ protected int counter; // field should be declared as protected or public. /** @fractal.ac argument="client-prefix" */ protected String pref; /** @fractal.ac */ protected String suffix; ... }
Details:
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:
Parameter | Description | Contingency |
---|---|---|
name | the name of the Fractal binding. | Optional (default value is the Field name) |
signature | the signature of the Fractal binding. | Optional (default value is the Field signature) |
contingency | the contingency of the Fractal binding (mandatory |optional ). | Optional (default value is mandatory ) |
cardinality | the cardinality of the Fractal binding (singleton |collection ). | Optional (default value is singleton ) |
Example:
public class Client implements Runnable { /** @fractal.bc name="s" signature="Service" cardinality="collection" */ protected Map servers = new HashMap(); // collections are stored in a map /** @fractal.bc */ protected Service service; ... }
Details:
This field annotation provides a way to refer a control interface provided by the controller part of the associated Fractal component.
Parameters:
Parameter | Description | Contingency |
---|---|---|
controller | the name of the Fractal controller. | Optional (default value is component ) |
Example:
public class Client implements Runnable { /** @fractal.rc controller="name-controller" */ protected NameController nc; // field should be declared as protected or public. /** @fractal.rc */ protected Component self; ... }
Details:
This field annotation provides a way to define a Monolog logger to log the execution of the Fractal component.
Parameters:
Parameter | Description | Contingency |
---|---|---|
name | the name of the Monolog logger. | Optional (default value is the Class name) |
level | the level of the Monolog logger. | Optional (default value is INFO ) |
additivity | the additivity tag for the Monolog logger (true |false ). | Optional (default value is true ) |
clean-handlers | the clean-handlers tag for the Monolog logger (true |false ). | Optional (default value is true ) |
Example:
public class Client implements Runnable { /** @fractal.log name="c" handler="clientHandler,consoleHandler" */ protected Logger log; // field should be declared as protected or public. /** @fractal.log */ protected Logger log2; ... }
Julia Configuration:
To enable the Monolog support in Julia, the julia.cfg
configuration file should be modified to override the lifecycle-controller-impl
definition as follows:
... # 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 build.properties
configuration file should be modified to activate the feature.loggable.on
property as follows:
... # 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 ...
Some plugins have been defined in order to generate the component artifacts. The list below describes these plugins:
Plugin | Dependency | Description |
---|---|---|
AttributeControllerPlugin | - | Plugin to generate the AttributeController interface of a Fractal component. |
PrimitiveComponentPlugin | AttributeControllerPlugin | Plugin to generate the component glue class of a Fractal component. |
PrimitiveDefinitionPlugin | - | Plugin to generate the FractalADL definition associated to the Fractal component. |
CompositeDefinitionPlugin | PrimitiveDefinitionPlugin | Plugin to generate the FractalADL assembly definition containing the Fractal component. |
MonologConfigurationPlugin | - | Plugin to generate the Monolog configuration file associated to the Fractal components. |
Details:
Generates the <CLASS>AttributeController
interface associated to a <CLASS>
class if it defines at least an attribute using the
@fractal.ac
annotation.
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>
Details:
Generates the Fc<CLASS>
class associated to a <CLASS>
class.
class if it defines either a @fractal.ac
,
@fractal.bc
,
@fractal.rc
or/and
@fractal.log
annotation.
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>
Generates the <CLASS>.fractal
definition associated to a <CLASS>
class (or interface).
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>
Details:
Generates the <CLASS>Comp.fractal
definition associated to a <CLASS>
class if it
defines at least a @fractal.bc
annotation.
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>
Details:
Generates the monolog.properties
configuration file for the Monolog tool.
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>
|
|||||||||||
PREV NEXT | FRAMES NO FRAMES |