Mail Archive Home | fractal-commits List | January 2007 Index
| <-- Date Index --> | <-- Thread Index --> |
Date: Wednesday, January 17, 2007 @ 11:21:41
Author: pessemier
Path: /cvsroot/fractal/web/xml/root
Added: tutorials/fraclet/fracletannotation.xml
tutorials/fraclet/fracletxdoc.xml
Modified: fraclet/index.xml tutorials/fraclet/index.xml
+ Separation of the 2 Fraclet tutorial
+ update links
-----------------------------------------+
fraclet/index.xml | 11
tutorials/fraclet/fracletannotation.xml | 938 ++++++++++++++++++
tutorials/fraclet/fracletxdoc.xml | 763 ++++++++++++++
tutorials/fraclet/index.xml | 1560 ------------------------------
4 files changed, 1722 insertions(+), 1550 deletions(-)
Index: web/xml/root/fraclet/index.xml
diff -u web/xml/root/fraclet/index.xml:1.2 web/xml/root/fraclet/index.xml:1.3
--- web/xml/root/fraclet/index.xml:1.2 Sat Dec 16 15:20:06 2006
+++ web/xml/root/fraclet/index.xml Wed Jan 17 11:21:41 2007
@@ -29,7 +29,7 @@
<ul>
<li>Fraclet XDoc: uses <a
href="http://xdoclet.codehaus.org";>XDoclet2</a> annotations</li>
- <li>Fraclet Annotation: uses Java 5 annotations</li>
+ <li>Fraclet Annotation: uses Java 5 annotations and <a
href="http://spoon.gforge.inria.fr";>Spoon</a> processors</li>
</ul>
<subtitle anchor="download">Download</subtitle>
@@ -43,10 +43,13 @@
<subtitle anchor="documentation">Documentation</subtitle>
<ul>
- <li>The <a href="../tutorials/fraclet/index.html">Fraclet
documentation</a>
- explains how to use this tool.</li>
+ <li>The <a href="../tutorials/fraclet/fracletxdoc.html">Fraclet
XDoc</a>
+ documentation.</li>
+ </ul>
+ <ul>
+ <li>The <a
href="../tutorials/fraclet/fracletannotation.html">Fraclet Annotation</a>
+ documentation.</li>
</ul>
-
<subtitle>Mailing list</subtitle>
<p>
Index: web/xml/root/tutorials/fraclet/fracletannotation.xml
diff -u /dev/null web/xml/root/tutorials/fraclet/fracletannotation.xml:1.1
--- /dev/null Wed Jan 17 11:21:41 2007
+++ web/xml/root/tutorials/fraclet/fracletannotation.xml Wed Jan 17
11:21:41 2007
@@ -0,0 +1,938 @@
+<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
+<!DOCTYPE document SYSTEM '../../../../common/dtd/objectweb.dtd'>
+
+<document>
+ <properties>
+ <author email="fractal@xxxxxxxxxxxxx">Fractal Team</author>
+ <title>Fraclet</title>
+ <filename>fracletannotation.xml</filename>
+ <pathtoroot>../..</pathtoroot>
+ </properties>
+
+ <body>
+ <s1 name="About this document">
+ <p>This document is a tutorial of the
<strong>Fraclet Annotation</strong>
+ implementation of the <a
href="index.html">Fraclet Framework.</a></p>
+
+ <table border="0" width="100%">
+ <tr>
+ <td align="left" valign="bottom">
+ <ul>
+ <li><strong>Title:</strong>
Fraclet Tutorial</li>
+ <li><strong>Author:</strong>
<em>Nicolas Pessemier</em> (INRIA)</li>
+ <li><strong>Version:</strong>
<em>2.0</em> (Fraclet-annotation)</li>
+
<li><strong>Released:</strong> <em>January 17<sup>th</sup>, 2007</em></li>
+ </ul>
+ </td>
+ </tr>
+ </table>
+
+
+ </s1>
+ <s1 name="Table of Contents">
+
+ <ol>
+ <li><connect
href="fracletannotation.xml#fracletannotation">Fraclet Annotation: A Java 5
annotation support for Fractal</connect></li>
+ <ul>
+ <li><connect
href="fracletannotation.xml#fraclet-annotations">1.1 Available
Annotations</connect></li>
+ <li><connect
href="fracletannotation.xml#fraclet-example">1.2 Revisiting the HelloWorld
Example</connect></li>
+ </ul>
+ <li><connect
href="fracletannotation.xml#availability">Fraclet Availability</connect></li>
+ <li><connect
href="fracletannotation.xml#publication">Dissemination</connect></li>
+ </ol>
+ </s1>
+
+ <s1 name="1. Fraclet Annotation: A Java 5 annotation support for
Fractal" anchor="fracletannotation">
+
+
+ <p><strong>Fraclet</strong> is the annotation framework
of the
+ Fractal component model. Fraclet provides an
annotation-oriented
+ programming (@OP) style for developing
Fractal applications.
+ Fraclet leverages the process a writting a
Fractal application
+ by providing a set of annotations which reduces the
amount of
+ code which must be written by developers.
+
+ </p>
+ <p><strong>Fraclet-annotation</strong> is an implementation of
Fraclet using
+ Java5 annotations and <a
href="http://spoon.gforge.inria.fr";>Spoon</a>, an Java 5
+ annotation-driven open compiler and program transformation
tool.
+ </p>
+
+
+ <s2 name="About Spoon">
+
+ <table border="0" width="100%">
+ <tr>
+ <td align="center" valign="middle">
+ <a
href="http://spoon.gforge.inria.fr/pub/images/spoonpowered.jpg";><img
src="http://spoon.gforge.inria.fr/pub/images/spoonpowered.jpg"; alt=""
height="99" width="128" border="0"/></a>
+ </td>
+ <td align="left" valign="bottom">
+ <p>
+ Spoon is a Java 5 open compiler built
on javac. It uses compile-time reflection to specify program analysis and
transformations.
+ Spoon provides the user with a
representation of the Java AST called a meta-model, which allows both for
reading and writing.
+ Each interface of the meta-model is a
compile-time program element (CtElement),
+ which represents an AST node. Using
this meta-model and a specific API, Spoon allows the programmer to process
Java 5 programs.
+ This processing is implemented with a
visitor pattern that scans each visited program element and can apply some
user-defined processing jobs
+ called <strong>processors</strong>.
In particular, the processing can be annotation-driven, in a similar way to
XDoclet, but using Java 5 annotations.
+ In that case, programmers define
so-called <strong>annotation processors</strong>. Once the program's model
has been processed, a processor pretty prints the Java
+ program, which is usually compiled
again to generate the processed program's class files.
+ </p>
+ </td>
+ </tr>
+ </table>
+
+
+ <p>
+ In addition, Spoon provides templates in pure Java, which are
Java class that contains template parameters, which are defined as fields
annotated with
+ @Parameter. Template parameters can represent primitive
values (such as literal values, program element's names, types), or actual
CtElements (ASTs).
+ In the template code, all the references to template
parameters can be substituted by their actual values using the substitution
engine API provided
+ by Spoon. The templates are usefull to express patterns that
can be used for generating code, as exampled by Generative Programming.
+ </p>
+
+ <p>
+ To implement Fraclet-annotation with have used a set of Spoon
processors and templates to process our defined annotations.
+ This tutorial doesn't detail the implementation of the
processors and templates but explain how to use Fraclet-annotation
annotations and how features are generated or transformed.
+ </p>
+
+ </s2>
+
+
+
+ <s2 name="1.1 Available Annotations" anchor="fraclet-annotations">
+ <p>Some annotations have been defined in order to describe
the component meta-information.
+ The list below describes these annotations.</p>
+ <table border="1">
+ <tr>
+ <th>Annotation</th>
+ <th>Location</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><connect
href="fracletannotation.xml#fractalcomponent"><code>@FractalComponent</code></connect></td>
+ <td>Class</td>
+ <td>Annotation to describe a Fractal component.</td>
+ </tr>
+ <tr>
+ <td><connect
href="fracletannotation.xml#interface"><code>@Interface</code></connect></td>
+ <td>Interface</td>
+ <td>Annotation to describe a Fractal business
interface.</td>
+ </tr>
+ <tr>
+ <td><connect
href="fracletannotation.xml#aattribute"><code>@Attribute</code></connect></td>
+ <td>Field</td>
+ <td>Annotation to describe an attribute of a Fractal
component.</td>
+ </tr>
+ <tr>
+ <td><connect
href="fracletannotation.xml#requires"><code>@Requires</code></connect></td>
+ <td>Field</td>
+ <td>Annotation to describe a binding of a Fractal
component.</td>
+ </tr>
+ <tr>
+ <td><connect
href="fracletannotation.xml#provides"><code>@Provides</code></connect></td>
+ <td>Class</td>
+ <td>Annotation to specify that the component
provides a server interface which is not annotated with a <em>@Interface</em>
(such as <em>java.lang.Runnable</em>).</td>
+ </tr>
+ <tr>
+ <td><connect
href="fracletannotation.xml#alifecycle"><code>@LifeCycle</code></connect></td>
+ <td>Method</td>
+ <td>Annotation to specify that the annotated method
should be run at component starting or stopping.</td>
+ </tr>
+
+ <tr>
+ <td><connect
href="fracletannotation.xml#service"><code>@Service</code></connect></td>
+ <td>Field</td>
+ <td>Annotation to describe a component service: for
example "component" gives the component part reference.</td>
+ </tr>
+ </table>
+
+ <p>Note that the @FractalComponent,
@Interface, @Provides, and @Requires annotations are used together to
generate .fractal files for Fractal-ADL. See the revisiting of the Hello
World example for more details</p>
+
+ <p> In addition to these generic component
annotations, two more annotations are used to generate monolog configuration
file and getter/setter for the logger and the logger factory.</p>
+
+ <table border="1">
+ <tr>
+ <th>Annotation</th>
+ <th>Location</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><connect
href="fracletannotation.xml#annmonologHandler"><code>@MonologHandler</code></connect></td>
+ <td>Class</td>
+ <td>Annotation to generate the monolog.properties
file.</td>
+ </tr>
+ <tr>
+ <td><connect
href="fracletannotation.xml#annmonolog"><code>@Monolog</code></connect></td>
+ <td>Field</td>
+ <td>Annotation to inject the Logger and
LoggerFactory references.</td>
+ </tr>
+ </table>
+
+
+ <subtitle
anchor="fractalcomponent">@FractalComponent</subtitle>
+ <p><strong>Details:</strong></p>
+ <p>This interface annotation is used to generate the
<em>.fractal</em> file associated to a Fractal component.
+ The processor associated to this
annotation works with all the other annotations to retrieve the informations
required to generate a concrete definition of the component: its name, its
required interfaces, its provided interfaces, and its attributes.
+ </p>
+ <p><strong>Parameters:</strong></p>
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Description</th>
+ <th>Contingency</th>
+ </tr>
+ <tr>
+ <td>controllerDesc</td>
+ <td>the membrane description of the Fractal
component. For instance "primitive".</td>
+ <td>Optional</td>
+ </tr>
+ </table>
+ <p><strong>Examples:</strong></p>
+ <source>
+@FractalComponent(controllerDesc="MyPrimitiveType")
+public class MyComponent { ... }
+ </source>
+ <p> will generate the following <em>.fractal</em>
definition:</p>
+ <source>
+<component name="MyComponent">
+(...)
+ <controller desc="MyPrimitiveType"/>
+</component>
+ </source>
+
+
+ <subtitle anchor="interface">@Interface</subtitle>
+ <p><strong>Details:</strong></p>
+ <p>This interface annotation has to be used on Java
interfaces that need to be used as <strong>Fractal interfaces</strong>. This
annotation is also used by the <em>@FractalImportedInterface</em> annotation
as a nested annotation.</p>
+ <p> IMPORTANT NOTE: you don't need to put again this
annotation on content classes which provide this interface. Thanks to Spoon
meta model, this information is automatically computed.
+ So you just need to annotate your
interface with <em>@Interface</em>, your component with
<em>@FractalComponent</em>, and the processor of the
<em>@FractalComponent</em> annotation will automatically see that you
implement an interface that is annotated with <em>@Interface</em></p>
+
+ <p><strong>Parameters:</strong></p>
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Description</th>
+ <th>Contingency</th>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>the name of the Fractal interface.</td>
+ <td>Required</td>
+ </tr>
+ <tr>
+ <td>signature</td>
+ <td>the signature of the Fractal interface.</td>
+ <td>Optional<br/>(default value is the Class
signature)</td>
+ </tr>
+ <tr>
+ <td>cardinality</td>
+ <td>the cardinality of the Fractal interface.</td>
+ <td>Optional<br/>(default value is
Cardinality.SINGLETON)</td>
+ </tr>
+ <tr>
+ <td>contingency</td>
+ <td>the contingency of the Fractal interface.</td>
+ <td>Optional<br/>(default value is
Contingency.MANDATORY)</td>
+ </tr>
+ </table>
+ <p><strong>Examples:</strong></p>
+ <source>
+@Interface(name="m")
+public interface Main { ... }
+ </source>
+ <p>
+ ...will generate the following
Fractal ADL abstract definition:
+ </p>
+ <source>
+<definition name="primitive.Service">
+<interface name="service" signature="primitive.Service" role="server"
+ cardinality="singleton"
contingency="mandatory"/>
+</definition>
+ </source>
+ <p>
+ ... and the combination of the
<em>@FractalComponent</em> and <em>@FractalItf</em> annotations of the
following example:
+ </p>
+ <source>
+@Interface(name="service")
+public interface Service {
+ (...)
+}
+@FractalComponent
+public class ServerA implements Service {
+ (...)
+}
+ </source>
+ <p> ... will provide the following Fractal-ADL
definitions: </p>
+ <source>
+<definition name="primitive.Service">
+<interface name="service" signature="primitive.Service" role="server"
+ cardinality="singleton"
contingency="mandatory"/>
+</definition>
+
+<definition name="primitive.ServerA" extends="primitive.Service">
+ <content class="primitive.ServerA"/>
+</definition>
+ </source>
+
+ <subtitle anchor="aattribute">@Attribute</subtitle>
+ <p><strong>Details:</strong></p>
+ <p>This field annotation describes a <strong>Fractal
attribute</strong>. 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.</p>
+ <p> The <em>@Attribute</em> will transform
the original class to introduce getter/setter, and generate a new interface
for these getter/setter. See the examples below.</p>
+ <p> Used with the <em>@FractalComponent</em>
annotation, the Fractal-ADL definition of the Fractal attribute are also
generated. </p>
+ <p><strong>Parameters:</strong></p>
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Description</th>
+ <th>Contingency</th>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>the name of the Fractal attribute.</td>
+ <td>Optional<br/>(default value is the Field
name)</td>
+ </tr>
+ <tr>
+ <td>argument</td>
+ <td>the name of the component argument used to
configure the Fractal attribute.</td>
+ <td>Optional<br/>(default value is the Field name is
no value is defined)</td>
+ </tr>
+ <tr>
+ <td>value</td>
+ <td>the default value of the Fractal attribute.</td>
+ <td>Optional</td>
+ </tr>
+ </table>
+ <p><strong>Examples:</strong></p>
+ <p>
+ The following example:
+ </p>
+ <source>
+public class ServerA implements Service {
+
+ @Attribute(value=">>")
+ private String header ;
+
+ @Attribute(argument="msg")
+ private String message ;
+
+ (...)
+}
+ </source>
+ <p> ... will introduce the following getter/setter methods
and generate a ServerAAttributeController interface just as follows: </p>
+ <source>
+ public class ServerA implements ServerAAttributeController {
+ (...)
+ /**
+ * This method has been automatically injected by Spoon
+ *
+ * @return the reference of the field
+ */
+ public String getHeader() {
+ return header;
+ }
+
+ /**
+ * This method has been automatically injected by Spoon
+ *
+ * @return the reference of the field
+ */
+ public String getMessage() {
+ return message;
+ }
+
+ /**
+ * This method has been automatically injected by Spoon
+ *
+ * @param value
+ * the value to set to the field
+ */
+ public void setHeader(String value) {
+ header = value;
+ }
+
+ /**
+ * This method has been automatically injected by Spoon
+ *
+ * @param value
+ * the value to set to the field
+ */
+ public void setMessage(String value) {
+ message = value;
+ }
+
+}
+
+
+public interface ServerAAttributeController extends AttributeController {
+ /**
+ * This method has been automatically injected by Spoon
+ *
+ * @return the reference of the field
+ */
+ public String getHeader();
+ /**
+ * This method has been automatically injected by Spoon
+ *
+ * @return the reference of the field
+ */
+ public String getMessage();
+ /**
+ * This method has been automatically injected by Spoon
+ *
+ * @param value
+ * the value to set to the field
+ */
+ public void setHeader(String value);
+ /**
+ * This method has been automatically injected by Spoon
+ *
+ * @param value
+ * the value to set to the field
+ */
+ public void setMessage(String value);
+}
+ </source>
+
+ <p>
+ The combination of the
<em>@FractalComponent</em> and <em>@Attribute</em> annotations of the
following example:
+ </p>
+ <source>
+@FractalComponent
+public class ServerA implements Service {
+
+ @Attribute(value=">>")
+ private String header ;
+
+ @Attribute(argument="msg")
+ private String message ;
+
+ (...)
+}
+ </source>
+ <p> ... will provide the following Fractal-ADL
definitions: </p>
+ <source>
+<definition name="primitive.ServerA" arguments="msg">
+ <content class="primitive.ServerA"/>
+ <attributes signature="primitive.ServerAAttributeController">
+ <attribute name="message" value="${msg}"/>
+ <attribute name="header" value=">>"/>
+ </attributes>
+</definition>
+ </source>
+
+
+ <subtitle anchor="requires">@Requires</subtitle>
+ <p><strong>Details:</strong></p>
+ <p>This field annotation describes a <strong>Fractal
binding</strong>. 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.</p>
+ <p> Used with the <em>@FractalComponent</em>
annotation, the Fractal-ADL definition of the Fractal attribute are also
generated. See the following examples.</p>
+ <p><strong>Parameters:</strong></p>
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Description</th>
+ <th>Contingency</th>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>the name of the Fractal binding.</td>
+ <td>Required<br/></td>
+ </tr>
+ <tr>
+ <td>signature</td>
+ <td>the signature of the Fractal binding. Use this
parameter only to generate Java 1.4 compatible code for collection
interfaces. Don't use this parameter for singleton interfaces.</td>
+ <td>Optional<br/>(default value is
<code>None.class</code>)</td>
+ </tr>
+ <tr>
+ <td>contingency</td>
+ <td>the contingency of the Fractal binding
(<code>mandatory</code>|<code>optional</code>).</td>
+ <td>Optional<br/>(default value is
<code>Contingency.MANDATORY</code>)</td>
+ </tr>
+ <tr>
+ <td>cardinality</td>
+ <td>the cardinality of the Fractal binding
(<code>singleton</code>|<code>collection</code>).</td>
+ <td>Optional<br/>(default value is
<code>Cardinality.SINGLETON</code>)</td>
+ </tr>
+ </table>
+ <p><strong>Examples:</strong></p>
+ <source>
+public class Client implements Runnable {
+
+ @Requires(name = "default")
+ private Service defaut;
+
+ // signature of the Fractal binding is computed because the Map is well
typed
+ @Requires(name = "service", cardinality = Cardinality.COLLECTION)
+ private Map<String,Service> services = new
HashMap<String,Service>();
+
+}
+ </source>
+ <p> ... will transform the Client class into the
following: </p>
+ <source>
+public class Client implements Runnable {
+
+ private Service defaut;
+
+ // signature of the Fractal binding is computed because the Map is well
typed
+ private Map<String,Service> services = new
HashMap<String,Service>();
+ /**
+ * (non-Javadoc)
+ *
+ * @see
org.objectweb.fractal.api.control.BindingController#bindFc(java.lang.String,
+ * java.lang.Object) Method automatically generated with Spoon
+ * <http://spoon.gforge.inria.fr>
+ */
+ public void bindFc(String clientItfName, Object serverItf) throws
NoSuchInterfaceException,
+
IllegalBindingException {
+ if (clientItfName.equals("default")) {
+ if (!Service.class.isAssignableFrom(serverItf.getClass())) {
+ throw new IllegalBindingException((("server interfaces
connected to " + clientItfName)
+ + " must be instances of ") +
(Service.class.getName()));
+ }
+ defaut = ((Service)(serverItf));
+ return ;
+ }
+ if (clientItfName.startsWith("service")) {
+ if (!Service.class.isAssignableFrom(serverItf.getClass())) {
+ throw new IllegalBindingException((("server interfaces
connected to "
+ + clientItfName) + " must be
instances of ")
+ + (Service.class.getName()));
+ }
+ services.put(clientItfName ,((Service)(serverItf)));
+ return ;
+ }
+ throw new NoSuchInterfaceException(("Client interface \'" +
clientItfName)
+ + "\' is undefined.");
+ }
+
+ /**
+ * (non-Javadoc)
+ *
+ * @see org.objectweb.fractal.api.control.BindingController#listFc()
Method
+ * <http://spoon.gforge.inria.fr>
+ */
+ public String[] listFc() {
+ List<String> __interfaces__ = new ArrayList<String> ();
+ __interfaces__.add("default");
+ __interfaces__.addAll(services.keySet());
+ return __interfaces__.toArray(new String[]{ });
+ }
+
+ /**
+ * (non-Javadoc)
+ *
+ * @see
org.objectweb.fractal.api.control.BindingController#lookupFc(java.lang.String)
+ * Method automatically generated with Spoon
+ * <http://spoon.gforge.inria.fr>
+ */
+ public Object lookupFc(String clientItfName) throws
NoSuchInterfaceException {
+ if (clientItfName.equals("default")) {
+ return defaut;
+ }
+ if (clientItfName.startsWith(clientItfName)) {
+ return services.get(clientItfName);
+ }
+ throw new NoSuchInterfaceException(("Client interface \'" +
clientItfName)
+ + "\' is undefined.");
+ }
+
+ /**
+ * (non-Javadoc)
+ *
+ * @see
org.objectweb.fractal.api.control.BindingController#unbindFc(java.lang.String)
+ * Method automatically generated with Spoon
+ * <http://spoon.gforge.inria.fr>
+ */
+ public void unbindFc(String clientItfName) throws
NoSuchInterfaceException {
+ if (clientItfName.equals("default")) {
+ defaut = null;
+ return ;
+ }
+ if (services.containsKey(clientItfName)) {
+ services.remove(clientItfName);
+ return ;
+ }
+ throw new NoSuchInterfaceException(("Client interface \'"
+ + clientItfName) + "\' is
undefined.");
+ }
+}
+ </source>
+ <p>
+ The combination of the
<em>@FractalComponent</em> and <em>@Requires</em> annotations of the
following example:
+ </p>
+ <source>
+@FractalComponent
+public class Client implements Runnable {
+
+ @Requires(name = "default")
+ private Service defaut;
+
+ @Requires(name = "service", cardinality = Cardinality.COLLECTION)
+ // signature of the Fractal binding is computed because the Map is well
typed
+ private Map<String,Service> services = new
HashMap<String,Service>();
+
+}
+ </source>
+ <p> ... will provide the following Fractal-ADL
definitions: </p>
+ <source>
+<definition name="primitive.Client">
+ <interface name="default" signature="primitive.Service" role="client"
+ cardinality="singleton"
contingency="mandatory"/>
+ <interface name="service" signature="primitive.Service" role="client"
+ cardinality="collection"
contingency="mandatory"/>
+ <content class="primitive.Client"/>
+</definition>
+ </source>
+
+ <subtitle anchor="provides">@Provides</subtitle>
+ <p><strong>Details:</strong></p>
+ <p>This class annotation handles the particular case of
imported Fractal interface, i.e., Java interfaces that are not annotated with
<em>@Interface</em>, but directly used as Fractal interfaces.
+ The best example of this is the
<em>java.lang.Runnable</em> interface which is regularly used to start a
Fractal application. </p>
+ <p> This annotation use nested annotations
which are <em>@Interface</em> annotations. This allows the definition of
multiple imported interfaces. </p>
+ <p><strong>Parameters:</strong></p>
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Description</th>
+ <th>Contingency</th>
+ </tr>
+ <tr>
+ <td>@Interface[]</td>
+ <td>An array of <em>@Interface</em> annotations.</td>
+ <td>Required</td>
+ </tr>
+ </table>
+ <p><strong>Examples:</strong></p>
+ <source>
+@FractalComponent
+@Provides(interfaces=@Interface(name="r",signature=java.lang.Runnable.class))
+ public class Client implements Runnable {
+ (...)
+ }
+ </source>
+ <p>
+ ...will generate the following
Fractal ADL abstract definition:
+ </p>
+ <source>
+<definition name="primitive.Client">
+ <interface name="r" signature="java.lang.Runnable" role="server"
+ cardinality="singleton"
contingency="mandatory"/>
+ <content class="primitive.Client"/>
+</definition>
+ </source>
+
+ <subtitle anchor="alifecycle">@LifeCycle</subtitle>
+ <p><strong>Details:</strong></p>
+ <p>This method annotation provides a way to define a
<strong>lifecycle handler</strong> supported by the controller part of the
associated Fractal component.</p>
+ <p><strong>Parameters:</strong></p>
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Description</th>
+ <th>Contingency</th>
+ </tr>
+ <tr>
+ <td>on</td>
+ <td>the lifecyle transition to handle
(<code>LifeCycleType.START</code> | <code>LifeCycleType.STOP</code>).</td>
+ <td>Required</td>
+ </tr>
+ </table>
+ <p><strong>Example:</strong></p>
+ <source>
+@FractalComponent
+public class Client implements Runnable {
+ @LifeCycle(on=LifeCycleType.START)
+ private void init() {
+ System.out.println("Starting the component Client...");
+ }
+ (...)
+}
+ </source>
+
<subtitle anchor="service">@Service</subtitle>
+ <p><strong>Details:</strong></p>
+ <p>This field annotation provides a way to get a component
service. So far, only one service is implemented: "component". This service
gives the reference of the <strong>Component part</strong>.</p>
+ <p><strong>Parameters:</strong></p>
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Description</th>
+ <th>Contingency</th>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>The name of the service.</td>
+ <td>Optional (default value is "component")</td>
+ </tr>
+ </table>
+ <p><strong>Example:</strong></p>
+ <source>
+public class Client implements Runnable {
+ @Service("component")
+ private Component c;
+}
+ </source>
+
+
+ <subtitle
anchor="annmonologHandler">@MonologHandler</subtitle>
+ <p><strong>Details:</strong></p>
+ <p>This class annotation allows the developer to describe a
<strong><a href="http://monolog.objectweb.org/";>Monolog</a> handler</strong>
specific to the Fractal component.
+ The available annotation attributes support the various
properties that can be defined in a <a
href="http://monolog.objectweb.org/";>Monolog</a> configuration file.</p>
+ <p><strong>Parameters:</strong></p>
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Description</th>
+ <th>Contingency</th>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>the identifier of the handler.</td>
+ <td>Required</td>
+ </tr>
+ <tr>
+ <td>type</td>
+ <td>the type of the handler.</td>
+ <td>Optional<br/>(default value is
<code>Console</code>)</td>
+ </tr>
+ <tr>
+ <td>output</td>
+ <td>the output flow of the handler.</td>
+ <td>Optional<br/>(default value is
<code>System.out</code>)</td>
+ </tr>
+ <tr>
+ <td>pattern</td>
+ <td>the output pattern of the handler.</td>
+ <td>Optional<br/>(default value is <code>%l:
%m%n</code>)</td>
+ </tr>
+ <tr>
+ <td>max-size</td>
+ <td>the maximal size of the output file.</td>
+ <td>Optional</td>
+ </tr>
+ <tr>
+ <td>file-number</td>
+ <td>the number of files used by the handler.</td>
+ <td>Optional</td>
+ </tr>
+ <tr>
+ <td>append-mode</td>
+ <td>tag to use the handler in append mode
(<code>true</code>|<code>false</code>).</td>
+ <td>Optional<br/>(default value is
<code>false</code>)</td>
+ </tr>
+ </table>
+ <p><strong>Example:</strong></p>
+ <source>
+@MonologHandler(name="clientHandler", output="System.err", pattern="%-5l
[%h] <%t> %m%n")
+public class Client implements Runnable { ... }
+ </source>
+
+ <subtitle
anchor="annmonolog">@Monolog</subtitle>
+ <p><strong>Details:</strong></p>
+ <p>This field annotation provides a way to define a
<strong>Monolog logger</strong> to log the execution of the Fractal
component.</p>
+ <p><strong>Parameters:</strong></p>
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Description</th>
+ <th>Contingency</th>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>the name of the <a
href="http://monolog.objectweb.org/";>Monolog</a> logger.</td>
+ <td>Mandatory<br/>(default value is the Class
name)</td>
+ </tr>
+ <tr>
+ <td>level</td>
+ <td>the level of the <a
href="http://monolog.objectweb.org/";>Monolog</a> logger.</td>
+ <td>Optional<br/>(default value is
<code>INFO</code>)</td>
+ </tr>
+ <tr>
+ <td>additivity</td>
+ <td>the additivity tag for the <a
href="http://monolog.objectweb.org/";>Monolog</a> logger
(<code>true</code>|<code>false</code>).</td>
+ <td>Optional<br/>(default value is
<code>true</code>)</td>
+ </tr>
+ <tr>
+ <td>clean-handlers</td>
+ <td>the clean-handlers tag for the <a
href="http://monolog.objectweb.org/";>Monolog</a> logger
(<code>true</code>|<code>false</code>).</td>
+ <td>Optional<br/>(default value is
<code>true</code>)</td>
+ </tr>
+ </table>
+ <p><strong>Example:</strong></p>
+ <source>
+public class Client implements Runnable {
+ @Monolog (name="c", handler="clientHandler,fileHandler")
+ private Logger log;
+
+ @Monolog
+ private Logger log2;
+
+ ...
+}
+ </source>
+ <p><strong>Julia Configuration:</strong></p>
+ <p>To enable the Monolog support in Julia, the
<code>julia.cfg</code> configuration file should be modified to override the
<code>lifecycle-controller-impl</code> definition as follows:</p>
+ <source>
+...
+
+# 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)
+ )
+)
+
+...
+ </source>
+ <p><strong>AOKell Configuration:</strong></p>
+ <p>To enable the Monolog support in AOKell, the
<code>build.properties</code> configuration file should be modified to
activate the <code>feature.loggable.on</code> property as follows:</p>
+ <source>
+...
+
+# 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
+
+...
+ </source>
+ </s2>
+
+
+
+ <s2 name="1.2 Revisiting the HelloWorld Example"
anchor="fraclet-example">
+ <p>This 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.</p>
+ <subtitle anchor="architecture">HelloWorld Architecture
Overview</subtitle>
+ <p>The figure below introduces the well-known HelloWorld
example implemented with Fractal components.</p>
+ <p><img src="helloworld.png" alt="" height="123" width="254"
border="0"/></p>
+ <subtitle anchor="source">HelloWorld
Implementation</subtitle>
+ <p>The source code below represents the Java code and the
Fraclet annotations written to implement the <code>Client</code> and the
<code>Server</code> Fractal components:</p>
+ <source>
+@FractalComponent
+@Provides(interfaces=@Interface(name="r",signature=java.lang.Runnable.class))
+public class Client implements Runnable {
+
+ @Requires(name = "s")
+ private Service defaut;
+
+ @Attribute(value="Hello !")
+ protected String message;
+
+ public void run() {
+ this.defaut.print(this.message);
+ }
+}
+ </source>
+ <p>The <code>Client</code> class defines the
<code>Runnable</code> interface as a Fractal interface using the
<code>@Provides</code> annotation.
+ The field <code>default</code> is annoted as a client
interface (using <code>@Requires</code>), and will be named "s".
+ The attribute <code>message</code> is annoted as a Fractal
attribute (using <code>@Attribute</code>), which will be automatically
initialized to <code>"Hello !"</code>.</p>
+ <source>
+@Interface(name="s")
+public interface Service {
+ void print(String message);
+}
+ </source>
+ <p>The <code>Service</code> interface is annoted with
<code>@fractalItf</code> to define the name of the Fractal interface as
<code>s</code>.</p>
+ <source>
+@FractalComponent
+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);
+ }
+}
+ </source>
+ <p>The <code>Server</code> class inherits automatically from
the <code>Service</code> annotations.
+ The <code>header</code> and the <code>counter</code>
attributes are defined as Fractal attributes (using <code>@FractalAC</code>),
whose initial value will be defined when the component will be created.</p>
+ <subtitle anchor="source">HelloWorld Architecture
Definition</subtitle>
+ <p>The assembly definition below represents the FractalADL
assembly defined to describe the <code>HelloWorld</code> Fractal
component:</p>
+ <source>
+<definition name="HelloWorld">
+ <component name="client" definition="Client";
+ <component name="server" definition="Server('>>',2)"/>
+ <binding client="this.r" server="client.r"/>
+ <binding client="client.s" server="server.s"/>
+</definition>
+ </source>
+ <p>This definition creates a composite component
<code>HelloWorld</code>.
+ Then it specifies that the definition of the component
named <code>server</code> is <code>Server</code> and that the values of the
<code>header</code> and the <code>counter</code> attributes are
<code>'>>'</code> and <code>2</code>, respectively.</p>
+
+
+
+ <subtitle anchor="artifacts">Directory Structure</subtitle>
+ <p>The directory structure below presents the list of
compiled, generated and written files when using Fraclet to implement the
HelloWorld example:</p>
+ <source>
+%example%
+ * build/
+ - Client.class
+ - Client.fractal
+ - ClientAttributeController.class
+ - Server.class
+ - Server.fractal
+ - ServerAttributeController.class
+ - Service.class
+ - Service.fractal
+ - HelloWorld.fractal
+ * generated/
+ - Client.java
+ - Client.fractal
+ - ClientAttributeController.java
+ - Server.java
+ - Server.fractal
+ - ServerAttributeController.java
+ - Service.java
+ - Service.fractal
+ * src/
+ - Client.java
+ - HelloWorld.fractal
+ - Server.java
+ - Service.java
+ </source>
+
+ </s2>
+
+ </s1>
+
+ <s1 name="2. Fraclet Availability" anchor="availability">
+ <p>Fraclet is freely available under an LGPL licence at the
following URLs:</p>
+ <ul>
+ <li>CVS repository: you can checkout Fractal Annotation
from the <a href="http://forge.objectweb.org/cvs/?group_id=22";>Fractal CVS
repository</a> by specifying <code>fraclet-annotation</code>as module
name.</li>
+ <li>Download: you can download Fraclet Annotation archives
from the <a
href="http://forge.objectweb.org/project/showfiles.php?group_id=22";>Fractal
GForge interface</a>.</li>
+ </ul>
+ </s1>
+
+
+
+
+ <s1 name="3. Dissemination" anchor="publication">
+ <ul>
+ <li><a href="http://www.lifl.fr/~rouvoy/";>R. Rouvoy</a>, <a
href="http://www.lifl.fr/~pessemie/";>N. Pessemier</a>, <a
href="http://www.lifl.fr/~pawlak/";>R. Pawlak</a>, <a
href="http://www.lifl.fr/~merle/";>P. Merle</a>, <strong>Apports de la
programmation par attributs pour le modèle de composants Fractal</strong>, at
the 5th French speaking days on Component-Oriented Progamming, October 2006
[slides]</li>
+ <li><a href="http://www.lifl.fr/~rouvoy/";>R. Rouvoy</a>, <a
href="http://www.lifl.fr/~pessemie/";>N. Pessemier</a>, <a
href="http://www.lifl.fr/~pawlak/";>R. Pawlak</a>, <a
href="http://www.lifl.fr/~merle/";>P. Merle</a>, <strong>Using
Attribute-Oriented Programming to Leverage Fractal-Based
Developments</strong>, at the <a href="../../doc/ecoop06/index.html">5th
Fractal workshop</a> at <a href="http://2006.ecoop.org/";>ECOOP 2006</a>, July
2006 [<a href="../../doc/ecoop06/talks/rouvoy.pdf">slides</a>]</li>
+ <li><a href="http://www.lifl.fr/~rouvoy/";>R. Rouvoy</a>,
<strong>Fraclet: Making Fractal Developments Easier!</strong>, at the
Jacquard Research Meeting, January 2006 [<a
href="../../current/rouvoy-fraclet-06.pdf">slides</a>]</li>
+ </ul>
+ </s1>
+
+ </body>
+</document>
\ No newline at end of file
Index: web/xml/root/tutorials/fraclet/fracletxdoc.xml
diff -u /dev/null web/xml/root/tutorials/fraclet/fracletxdoc.xml:1.1
--- /dev/null Wed Jan 17 11:21:41 2007
+++ web/xml/root/tutorials/fraclet/fracletxdoc.xml Wed Jan 17 11:21:41
2007
@@ -0,0 +1,763 @@
+<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
+<!DOCTYPE document SYSTEM '../../../../common/dtd/objectweb.dtd'>
+
+<document>
+ <properties>
+ <author email="fractal@xxxxxxxxxxxxx">Fractal Team</author>
+ <title>Fraclet</title>
+ <filename>fracletxdoc.xml</filename>
+ <pathtoroot>../..</pathtoroot>
+ </properties>
+
+ <body>
+ <s1 name="About the Fraclet Annotation Framework">
+ <table border="0" width="100%">
+ <tr>
+ <td align="center" valign="middle">
+ <a href="Bransleys_fern.png"><img
src="Bransleys_fern.png" alt="" height="125" width="75" border="0"/></a>
+ </td>
+ <td align="left" valign="bottom">
+ <ul>
+ <li><strong>Title:</strong>
Fraclet Tutorial</li>
+ <li><strong>Author:</strong>
<em>Romain Rouvoy</em> (INRIA)</li>
+ <li><strong>Version:</strong>
<em>2.0</em> (Fraclet-xdoc)</li>
+
<li><strong>Released:</strong> <em>August 30<sup>th</sup>, 2006</em></li>
+ </ul>
+ </td>
+ </tr>
+ </table>
+ <p>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.</p>
+
+ <p>This approach has several benefits:</p>
+ <ul>
+ <li>You don't have to worry about out dating deployment
meta-data whenever you touch the code. The deployment <strong>meta-data is
continuously integrated</strong>.</li>
+ <li>Working with only one file per component gives you a
better overview of what you're doing. If your component consists of several
files, it's easy to lose track. If you have ever written an Enterprise Java
Bean, you know what we mean. A single EJB can typically consists of 7 or more
files. With Fraclet you only <strong>maintain one of them, and the rest is
generated</strong>.</li>
+ <li>You dramatically reduce development time, and can
concentrate on business logic, while Fraclet <strong>generates 60% of the
code</strong> for you.</li>
+ </ul>
+ <p> Two implementations of the Fraclet annotation framework
exist: <strong>Fraclet XDoc</strong> and <strong>Fraclet Annotation</strong>.
</p>
+ <ul>
+ <li> <strong>Fraclet XDoc</strong> uses the
XDoclet generation engine to produce the various artifacts required by the
Fractal component model.</li>
+ <li> <strong>Fraclet-Annotation</strong> uses
the Spoon transformation tool to enhance the handwritten program code with
the non-functional properties of the component model.</li>
+ </ul>
+ <p>This tutorial describes the <strong>Fraclet Xdoc</strong>
implementation. </p>
+ </s1>
+ <s1 name="Table of Contents">
+ <ol>
+
+ <li><connect href="fracletxdoc.xml#xdoc">Fraclet XDoc: An
XDoclet2 plugin for Fractal</connect></li>
+ <li><connect
href="fracletxdoc.xml#availability">Fraclet Availability</connect></li>
+ <li><connect
href="fracletxdoc.xml#publication">Dissemination</connect></li>
+ </ol>
+
+ </s1>
+
+ <s1 name="1. Fraclet XDoc: An XDoclet2 plugin for Fractal"
anchor="xdoc">
+ <p>Fraclet uses the <a
href="http://xdoclet.codehaus.org/";>XDoclet2</a> as annotation parser and
generation engine.</p>
+ <table
border="0" width="100%">
+ <tr>
+ <td align="center" valign="middle">
+ <a
href="http://xdoclet.codehaus.org/";><img
src="http://xdoclet.codehaus.org/logos/XDocletLogo1.gif"; alt="" height="73"
width="120" border="0"/></a>
+ </td>
+ <td align="left" valign="bottom">
+ <p>XDoclet is an open source code generation engine.
+ It enables <strong>Attribute-Oriented Programming</strong>
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.</p>
+ <p>XDoclet2 is the next generation of this technology.
+ Based on <a
href="http://generama.codehaus.org/";>Generama</a>, it uses standard template
engines such as <a href="http://jakarta.apache.org/velocity/";>Velocity</a>
and <a href="http://freemarker.sourceforge.net/";>Freemarker</a> for
generation of text-oriented output, and <a
href="http://jakarta.apache.org/commons/jelly/";>Jelly</a> for XML output.
+ The function of XDoclet2 is to seed the generation contexts
for these template engines.</p>
+ </td>
+ </tr>
+ </table>
+ <p>XDoclet2 is supported by <a
href="http://xdoclet.codehaus.org/XDoclet+Plugins";>XDoclet2 plugins</a>,
which provide task-specific generation functionality.</p>
+ <p> This part describes the features of this XDoclet2 plugin for
Fractal, and the way to use them. </p>
+ <ol>
+ <li><connect
href="fracletxdoc.xml#xdoc-annotations">Available Annotations</connect></li>
+ <li><connect href="fracletxdoc.xml#xdoc-plugins">Available
Plugins</connect></li>
+ <li><connect href="fracletxdoc.xml#example">Revisiting the
HelloWorld Example</connect></li>
+
+ </ol>
+ <!--</s2>-->
+ <s2 name="1.1 Available Annotations" anchor="xdoc-annotations">
+ <p>Some annotations have been defined in order to describe
the component meta-information.
+ The list below describes these annotations.</p>
+ <table border="1">
+ <tr>
+ <th>Annotation</th>
+ <th>Location</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><connect
href="fracletxdoc.xml#itf"><code>@provides</code></connect></td>
+ <td>Class</td>
+ <td>Annotation to describe a Fractal server
interface.</td>
+ </tr>
+ <tr>
+ <td><connect
href="fracletxdoc.xml#ctrl"><code>@component</code></connect></td>
+ <td>Class</td>
+ <td>Annotation to describe the controller part of a
Fractal component.</td>
+ </tr>
+ <tr>
+ <td><connect
href="fracletxdoc.xml#data"><code>@data</code></connect></td>
+ <td>Class</td>
+ <td>Annotation to describe a data used by a Fractal
component.</td>
+ </tr>
+ <tr>
+ <td><connect
href="fracletxdoc.xml#handler"><code>@monolog.handler</code></connect></td>
+ <td>Class</td>
+ <td>Annotation to describe a custom Monolog
handler.</td>
+ </tr>
+ <tr>
+ <td><connect
href="fracletxdoc.xml#ac"><code>@attribute</code></connect></td>
+ <td>Field</td>
+ <td>Annotation to describe an attribute of a Fractal
component.</td>
+ </tr>
+ <tr>
+ <td><connect
href="fracletxdoc.xml#bc"><code>@requires</code></connect></td>
+ <td>Field</td>
+ <td>Annotation to describe a binding of a Fractal
component.</td>
+ </tr>
+ <tr>
+ <td><connect
href="fracletxdoc.xml#rc"><code>@control</code></connect></td>
+ <td>Field</td>
+ <td>Annotation to provide a reflective control to
the content of a Fractal component.</td>
+ </tr>
+ <tr>
+ <td><connect
href="fracletxdoc.xml#log"><code>@logger</code></connect></td>
+ <td>Field</td>
+ <td>Annotation to define a logger for a Fractal
component.</td>
+ </tr>
+ <tr>
+ <td><connect
href="fracletxdoc.xml#lcc"><code>@lifecycle</code></connect></td>
+ <td>Method</td>
+ <td>Annotation to handle the lifecycle in a Fractal
component.</td>
+ </tr>
+ </table>
+
+ <subtitle anchor="itf">The @provides annotation</subtitle>
+ <p><strong>Details:</strong></p>
+ <p>This class annotation adds the name information to the
<strong>definition of a Fractal interface</strong>.
+ 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.</p>
+ <p><strong>Parameters:</strong></p>
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Description</th>
+ <th>Contingency</th>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>the name of the Fractal interface.</td>
+ <td>Optional<br/>(default value is the signature
short name)</td>
+ </tr>
+ <tr>
+ <td>signature</td>
+ <td>the signature of the Fractal interface.</td>
+ <td>Optional<br/>(default value is the Class
signature)</td>
+ </tr>
+ </table>
+ <p><strong>Examples:</strong></p>
+ <source>
+/** @provides name=m */
+public interface Main { ... }
+
+/** @provides name=r signature=java.lang.Runnable */
+public class Client implements Runnable { ... }
+ </source>
+
+ <subtitle anchor="ctrl">The @component annotation</subtitle>
+ <p><strong>Details:</strong></p>
+ <p>This class annotation allows the developer to describe
the <strong>description of the controller part</strong> that should be
associated to the content part of the Fractal component.</p>
+ <p><strong>Parameters:</strong></p>
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Description</th>
+ <th>Contingency</th>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>the Fractal component fullname.</td>
+ <td>Optional</td>
+ </tr>
+ <tr>
+ <td>controller</td>
+ <td>the definition name of the controller part of
the Fractal component.</td>
+ <td>Optional</td>
+ </tr>
+ <tr>
+ <td>template</td>
+ <td>the definition name of the controller part of
the Fractal template component.</td>
+ <td>Optional</td>
+ </tr>
+ </table>
+ <p>Example:</p>
+ <source>
+/** @component name=fc.client controller=primitive */
+public class Client implements Runnable { ... }
+
+/** @component controller=primitive template=primitiveTemplate */
+public class Client implements Runnable { ... }
+ </source>
+
+ <subtitle anchor="data">The @data annotation</subtitle>
+ <p><strong>Details:</strong></p>
+ <p>This class annotation provides a way to define a
<strong>data</strong> used by a Fractal component.</p>
+ <p><strong>Example:</strong></p>
+ <source>
+/** @data */
+public class Message {
+ ...
+}
+ </source>
+
+ <subtitle anchor="handler">The @monolog.handler
annotation</subtitle>
+ <p><strong>Details:</strong></p>
+ <p>This class annotation allows the developer to describe a
<strong><a href="http://monolog.objectweb.org/";>Monolog</a> handler</strong>
specific to the Fractal component.
+ The available annotation attributes support the various
properties that can be defined in a <a
href="http://monolog.objectweb.org/";>Monolog</a> configuration file.</p>
+ <p><strong>Parameters:</strong></p>
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Description</th>
+ <th>Contingency</th>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>the identifier of the handler.</td>
+ <td>Required</td>
+ </tr>
+ <tr>
+ <td>type</td>
+ <td>the type of the handler.</td>
+ <td>Optional<br/>(default value is
<code>Console</code>)</td>
+ </tr>
+ <tr>
+ <td>output</td>
+ <td>the output flow of the handler.</td>
+ <td>Optional<br/>(default value is
<code>System.out</code>)</td>
+ </tr>
+ <tr>
+ <td>pattern</td>
+ <td>the output pattern of the handler.</td>
+ <td>Optional<br/>(default value is <code>%l:
%m%n</code>)</td>
+ </tr>
+ <tr>
+ <td>max-size</td>
+ <td>the maximal size of the output file.</td>
+ <td>Optional</td>
+ </tr>
+ <tr>
+ <td>file-number</td>
+ <td>the number of files used by the handler.</td>
+ <td>Optional</td>
+ </tr>
+ <tr>
+ <td>append-mode</td>
+ <td>tag to use the handler in append mode
(<code>true</code>|<code>false</code>).</td>
+ <td>Optional<br/>(default value is
<code>false</code>)</td>
+ </tr>
+ </table>
+ <p><strong>Example:</strong></p>
+ <source>
+/** @monolog.handler name=clientHandler output=System.err pattern="%-5l [%h]
<%t> %m%n" */
+public class Client implements Runnable { ... }
+ </source>
+
+ <subtitle anchor="ac">The @attribute annotation</subtitle>
+ <p><strong>Details:</strong></p>
+ <p>This field annotation describes a <strong>Fractal
attribute</strong>.
+ A Fractal attribute is a Java attribute whose value can be
configured and introspected from the Fractal component.
+ Fractal attributes are managed by the <a
href="../../specification/index.html#tth_sEc4.2">attribute control</a>
feature of the Fractal component model.</p>
+ <p><strong>Parameters:</strong></p>
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Description</th>
+ <th>Contingency</th>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>the name of the Fractal attribute.</td>
+ <td>Optional<br/>(default value is the Field
name)</td>
+ </tr>
+ <tr>
+ <td>value</td>
+ <td>the default value of the Fractal attribute.</td>
+ <td>Optional</td>
+ </tr>
+ </table>
+ <p><strong>Example:</strong></p>
+ <source>
+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;
+
+ ...
+}
+ </source>
+
+ <subtitle anchor="bc">The @requires annotation</subtitle>
+ <p><strong>Details:</strong></p>
+ <p>This field annotation describes a <strong>Fractal
binding</strong>.
+ A Fractal binding is a Java attribute representing a
client interface.
+ Fractal bindings are managed by the <a
href="../../specification/index.html#tth_sEc4.3">binding control</a> feature
of the Fractal component model.</p>
+ <p><strong>Parameters:</strong></p>
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Description</th>
+ <th>Contingency</th>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>the name of the Fractal binding.</td>
+ <td>Optional<br/>(default value is the Field
name)</td>
+ </tr>
+ <tr>
+ <td>signature</td>
+ <td>the signature of the Fractal binding.</td>
+ <td>Optional<br/>(default value is the Field
signature)</td>
+ </tr>
+ <tr>
+ <td>contingency</td>
+ <td>the contingency of the Fractal binding
(<code>mandatory</code>|<code>optional</code>).</td>
+ <td>Optional<br/>(default value is
<code>mandatory</code>)</td>
+ </tr>
+ <tr>
+ <td>cardinality</td>
+ <td>the cardinality of the Fractal binding
(<code>singleton</code>|<code>collection</code>).</td>
+ <td>Optional<br/>(default value is
<code>singleton</code>)</td>
+ </tr>
+ </table>
+ <p><strong>Example:</strong></p>
+ <source>
+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;
+
+ ...
+}
+ </source>
+
+ <subtitle anchor="rc">The @control annotation</subtitle>
+ <p><strong>Details:</strong></p>
+ <p>This field annotation provides a way to refer a
<strong>control interface</strong> provided by the controller part of the
associated Fractal component.</p>
+ <p><strong>Parameters:</strong></p>
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Description</th>
+ <th>Contingency</th>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>the name of the Fractal controller.</td>
+ <td>Optional<br/>(default value is
<code>component</code>)</td>
+ </tr>
+ </table>
+ <p><strong>Example:</strong></p>
+ <source>
+public class Client implements Runnable {
+ /** @control name=name-controller */
+ protected NameController nc; // field should be declared as protected or
public.
+
+ /** @control */
+ protected Component self;
+
+ ...
+}
+ </source>
+
+ <subtitle anchor="log">The @logger annotation</subtitle>
+ <p><strong>Details:</strong></p>
+ <p>This field annotation provides a way to define a
<strong>Monolog logger</strong> to log the execution of the Fractal
component.</p>
+ <p><strong>Parameters:</strong></p>
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Description</th>
+ <th>Contingency</th>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>the name of the <a
href="http://monolog.objectweb.org/";>Monolog</a> logger.</td>
+ <td>Optional<br/>(default value is the Class
name)</td>
+ </tr>
+ <tr>
+ <td>level</td>
+ <td>the level of the <a
href="http://monolog.objectweb.org/";>Monolog</a> logger.</td>
+ <td>Optional<br/>(default value is
<code>INFO</code>)</td>
+ </tr>
+ <tr>
+ <td>additivity</td>
+ <td>the additivity tag for the <a
href="http://monolog.objectweb.org/";>Monolog</a> logger
(<code>true</code>|<code>false</code>).</td>
+ <td>Optional<br/>(default value is
<code>true</code>)</td>
+ </tr>
+ <tr>
+ <td>clean-handlers</td>
+ <td>the clean-handlers tag for the <a
href="http://monolog.objectweb.org/";>Monolog</a> logger
(<code>true</code>|<code>false</code>).</td>
+ <td>Optional<br/>(default value is
<code>true</code>)</td>
+ </tr>
+ </table>
+ <p><strong>Example:</strong></p>
+ <source>
+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;
+
+ ...
+}
+ </source>
+ <p><strong>Julia Configuration:</strong></p>
+ <p>To enable the Monolog support in Julia, the
<code>julia.cfg</code> configuration file should be modified to override the
<code>lifecycle-controller-impl</code> definition as follows:</p>
+ <source>
+...
+
+# 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)
+ )
+)
+
+...
+ </source>
+ <p><strong>AOKell Configuration:</strong></p>
+ <p>To enable the Monolog support in AOKell, the
<code>build.properties</code> configuration file should be modified to
activate the <code>feature.loggable.on</code> property as follows:</p>
+ <source>
+...
+
+# 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
+
+...
+ </source>
+
+ <subtitle anchor="lcc">The @lifecycle annotation</subtitle>
+ <p><strong>Details:</strong></p>
+ <p>This method annotation provides a way to define a
<strong>lifecycle handler</strong> supported by the controller part of the
associated Fractal component.</p>
+ <p><strong>Parameters:</strong></p>
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Description</th>
+ <th>Contingency</th>
+ </tr>
+ <tr>
+ <td>when</td>
+ <td>the lifecyle transition to handle
(<code>create</code>|<code>start</code>|<code>stop</code>|<code>destroy</code>).</td>
+ <td>Required</td>
+ </tr>
+ </table>
+ <p><strong>Example:</strong></p>
+ <source>
+public class Client implements Runnable {
+ /** @lifecycle when=start */
+ protected void init() {
+ System.out.println("Starting the component Client...");
+ }
+
+ ...
+}
+ </source>
+ </s2>
+
+ <s2 name="1.2 Available Plugins" anchor="xdoc-plugins">
+ <p>Some plugins have been defined in order to generate the
component artifacts.
+ The list below describes these plugins:</p>
+ <table border="1">
+ <tr>
+ <th>Plugin</th>
+ <th>Dependency</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><connect
href="fracletxdoc.xml#attribute"><code>AttributeControllerPlugin</code></connect></td>
+ <td> - </td>
+ <td>Plugin to generate the AttributeController
interface of a Fractal component.</td>
+ </tr>
+ <tr>
+ <td><connect
href="fracletxdoc.xml#primitive"><code>PrimitiveComponentPlugin</code></connect></td>
+ <td><code>AttributeControllerPlugin</code></td>
+ <td>Plugin to generate the component glue class of a
Fractal component.</td>
+ </tr>
+ <tr>
+ <td><connect
href="fracletxdoc.xml#adl"><code>PrimitiveDefinitionPlugin</code></connect></td>
+ <td> - </td>
+ <td>Plugin to generate the FractalADL definition
associated to the Fractal component.</td>
+ </tr>
+ <tr>
+ <td><connect
href="fracletxdoc.xml#compositeadl"><code>CompositeDefinitionPlugin</code></connect></td>
+ <td><code>PrimitiveDefinitionPlugin</code></td>
+ <td>Plugin to generate the FractalADL assembly
definition containing the Fractal component.</td>
+ </tr>
+ <tr>
+ <td><connect
href="fracletxdoc.xml#monolog"><code>MonologConfigurationPlugin</code></connect></td>
+ <td> - </td>
+ <td>Plugin to generate the <a
href="http://monolog.objectweb.org/";>Monolog</a> configuration file
associated to the Fractal components.</td>
+ </tr>
+ </table>
+
+ <subtitle anchor="attribute">The AttributeControllerPlugin
generator</subtitle>
+ <p><strong>Details:</strong></p>
+ <p>Generates the <code><CLASS>Attributes</code>
interface associated to a <code><CLASS></code>
+ class if it defines at least an attribute using the
+ <connect
href="fracletxdoc.xml#ac"><code>@attribute</code></connect> annotation.</p>
+ <p><strong>Usage:</strong></p>
+ <source>
+<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>
+ </source>
+
+ <subtitle anchor="primitive">The PrimitiveComponentPlugin
generator</subtitle>
+ <p><strong>Details:</strong></p>
+ <p>Generates the <code>Fc<CLASS></code> class
associated to a <code><CLASS></code> class.
+ class if it defines either a <connect
href="fracletxdoc.xml#ac"><code>@attribute</code></connect>,
+ <connect
href="fracletxdoc.xml#bc"><code>@requires</code></connect>,
+ <connect
href="fracletxdoc.xml#rc"><code>@control</code></connect> or/and
+ <connect
href="fracletxdoc.xml#log"><code>@logger</code></connect> annotation.</p>
+ <p><strong>Usage:</strong></p>
+ <source>
+<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>
+ </source>
+
+ <subtitle anchor="adl">The PrimitiveDefinitionPlugin
generator</subtitle>
+ <p>Generates the <code><CLASS>.fractal</code>
definition associated to a <code><CLASS></code> class (or
interface).</p>
+ <p><strong>Usage:</strong></p>
+ <source>
+<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>
+ </source>
+
+ <subtitle anchor="compositeadl">The
CompositeDefinitionPlugin generator</subtitle>
+ <p><strong>Details:</strong></p>
+ <p>Generates the <code><CLASS>Composite.fractal</code>
definition associated to a <code><CLASS></code> class if it
+ defines at least a <connect
href="fracletxdoc.xml#bc"><code>@requires</code></connect>
+ annotation.</p>
+ <p><strong>Usage:</strong></p>
+ <source>
+<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>
+ </source>
+
+ <subtitle anchor="monolog">The MonologConfigurationPlugin
generator</subtitle>
+ <p><strong>Details:</strong></p>
+ <p>Generates the <code>monolog.properties</code>
configuration file for the <a
href="http://monolog.objectweb.org/";>Monolog</a> tool.</p>
+ <p><strong>Usage:</strong></p>
+ <source>
+<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>
+ </source>
+ </s2>
+
+ <s2 name="1.3 Revisiting the HelloWorld Example with Fraclet"
anchor="example">
+ <p>This 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.</p>
+ <subtitle anchor="architecture">HelloWorld Architecture
Overview</subtitle>
+ <p>The figure below introduces the well-known HelloWorld
example implemented with Fractal components.</p>
+ <p><img src="helloworld.png" alt="" height="123" width="254"
border="0"/></p>
+ <subtitle anchor="source">HelloWorld
Implementation</subtitle>
+ <p>The source code below represents the Java code and the
Fraclet annotations written to implement the <code>Client</code> and the
<code>Server</code> Fractal components:</p>
+ <source>
+/** @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);
+ }
+}
+ </source>
+ <p>The <code>Client</code> class defines the
<code>Runnable</code> interface as a Fractal interface using the
<code>@provides</code> annotation.
+ The attribute <code>s</code> is annoted as a client
interface (using <code>@requires</code>), which will be named <code>s</code>
as no <code>name</code> parameter is defined.
+ The attribute <code>message</code> is annoted as a Fractal
attribute (using <code>@attribute</code>), which will be automatically
initialized to <code>"Hello !"</code>.</p>
+ <source>
+/** @provides name=s */
+public interface Service {
+ void print(String message);
+}
+ </source>
+ <p>The <code>Service</code> interface is annoted with
<code>@provides</code> to define the name of the Fractal interface as
<code>s</code>.</p>
+ <source>
+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);
+ }
+}
+ </source>
+ <p>The <code>Server</code> class inherits automatically from
the <code>Service</code> annotations.
+ The <code>header</code> and the <code>counter</code>
attributes are defined as Fractal attributes (using <code>@attribute</code>),
whose initial value will be defined when the component will be created.</p>
+ <subtitle anchor="source">HelloWorld Architecture
Definition</subtitle>
+ <p>The assembly definition below represents the FractalADL
assembly defined to describe the <code>HelloWorld</code> Fractal
component:</p>
+ <source>
+<definition name="HelloWorld" extends="ClientComposite">
+ <component name="s" definition="Server(>>,2)"/>
+</definition>
+ </source>
+ <p>This definition creates a composite component
<code>HelloWorld</code> extending the generated <code>Client</code> abstract
definition.
+ Then it specifies that the definition of the component
named <code>s</code> is <code>Server</code> and that the values of the
<code>header</code> and the <code>counter</code> attributes are
<code>>></code> and <code>2</code>, respectively.</p>
+ <subtitle anchor="compilation">Compilation with
Ant</subtitle>
+ <p>The following piece of XML presents the compilation
process enhanced with the Fractal plugins.</p>
+ <source>
+<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>
+ </source>
+ <subtitle anchor="artifacts">Directory Structure</subtitle>
+ <p>The directory structure below presents the list of
compiled, generated and written files when using Fraclet to implement the
HelloWorld example:</p>
+ <source>
+%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
+ </source>
+ </s2>
+ </s1>
+
+ <s1 name="2. Fraclet Availability" anchor="availability">
+ <p>Fraclet is freely available under an LGPL licence at the
following URLs:</p>
+ <ul>
+ <li>CVS repository: you can checkout Fraclet XDoc from the
<a href="http://forge.objectweb.org/cvs/?group_id=22";>Fractal CVS
repository</a> by specifying <code>fraclet-xdoc</code> as module name.</li>
+ <li>Download: you can download Fraclet XDoc archives from
the <a
href="http://forge.objectweb.org/project/showfiles.php?group_id=22";>Fractal
GForge interface</a>.</li>
+ </ul>
+ </s1>
+
+ <s1 name="3. Dissemination" anchor="publication">
+ <ul>
+ <li><a href="http://www.lifl.fr/~rouvoy/";>R. Rouvoy</a>, <a
href="http://www.lifl.fr/~pessemie/";>N. Pessemier</a>, <a
href="http://www.lifl.fr/~pawlak/";>R. Pawlak</a>, <a
href="http://www.lifl.fr/~merle/";>P. Merle</a>, <strong>Apports de la
programmation par attributs pour le modèle de composants Fractal</strong>, at
the 5th French speaking days on Component-Oriented Progamming, October 2006
[slides]</li>
+ <li><a href="http://www.lifl.fr/~rouvoy/";>R. Rouvoy</a>, <a
href="http://www.lifl.fr/~pessemie/";>N. Pessemier</a>, <a
href="http://www.lifl.fr/~pawlak/";>R. Pawlak</a>, <a
href="http://www.lifl.fr/~merle/";>P. Merle</a>, <strong>Using
Attribute-Oriented Programming to Leverage Fractal-Based
Developments</strong>, at the <a href="../../doc/ecoop06/index.html">5th
Fractal workshop</a> at <a href="http://2006.ecoop.org/";>ECOOP 2006</a>, July
2006 [<a href="../../doc/ecoop06/talks/rouvoy.pdf">slides</a>]</li>
+ <li><a href="http://www.lifl.fr/~rouvoy/";>R. Rouvoy</a>,
<strong>Fraclet: Making Fractal Developments Easier!</strong>, at the
Jacquard Research Meeting, January 2006 [<a
href="../../current/rouvoy-fraclet-06.pdf">slides</a>]</li>
+ </ul>
+ </s1>
+
+ </body>
+</document>
\ No newline at end of file
Index: web/xml/root/tutorials/fraclet/index.xml
diff -u web/xml/root/tutorials/fraclet/index.xml:1.17
web/xml/root/tutorials/fraclet/index.xml:1.18
--- web/xml/root/tutorials/fraclet/index.xml:1.17 Fri Oct 27 14:25:30
2006
+++ web/xml/root/tutorials/fraclet/index.xml Wed Jan 17 11:21:41 2007
@@ -45,1552 +45,20 @@
</ul>
</s1>
- <s1 name="Table of Contents">
- <ol>
-
- <li><connect href="index.xml#xdoc">Fraclet XDoc: An XDoclet2
plugin for Fractal</connect></li>
- <li><connect
href="index.xml#fracletannotation">Fraclet Annotation: A Java 5 annotation
support for Fractal</connect></li>
- <li><connect
href="index.xml#availability">Fraclet Availability</connect></li>
- <li><connect
href="index.xml#publication">Dissemination</connect></li>
- </ol>
-
- </s1>
-
- <s1 name="1. Fraclet XDoc: An XDoclet2 plugin for Fractal"
anchor="xdoc">
- <p>Fraclet uses the <a
href="http://xdoclet.codehaus.org/";>XDoclet2</a> as annotation parser and
generation engine.</p>
- <table
border="0" width="100%">
- <tr>
- <td align="center" valign="middle">
- <a
href="http://xdoclet.codehaus.org/";><img
src="http://xdoclet.codehaus.org/logos/XDocletLogo1.gif"; alt="" height="73"
width="120" border="0"/></a>
- </td>
- <td align="left" valign="bottom">
- <p>XDoclet is an open source code generation engine.
- It enables <strong>Attribute-Oriented Programming</strong>
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.</p>
- <p>XDoclet2 is the next generation of this technology.
- Based on <a
href="http://generama.codehaus.org/";>Generama</a>, it uses standard template
engines such as <a href="http://jakarta.apache.org/velocity/";>Velocity</a>
and <a href="http://freemarker.sourceforge.net/";>Freemarker</a> for
generation of text-oriented output, and <a
href="http://jakarta.apache.org/commons/jelly/";>Jelly</a> for XML output.
- The function of XDoclet2 is to seed the generation contexts
for these template engines.</p>
- </td>
- </tr>
- </table>
- <p>XDoclet2 is supported by <a
href="http://xdoclet.codehaus.org/XDoclet+Plugins";>XDoclet2 plugins</a>,
which provide task-specific generation functionality.</p>
- <p> This part describes the features of this XDoclet2 plugin for
Fractal, and the way to use them. </p>
- <ol>
- <li><connect href="index.xml#xdoc-annotations">Available
Annotations</connect></li>
- <li><connect href="index.xml#xdoc-plugins">Available
Plugins</connect></li>
- <li><connect href="index.xml#example">Revisiting the
HelloWorld Example</connect></li>
-
- </ol>
- <!--</s2>-->
- <s2 name="1.1 Available Annotations" anchor="xdoc-annotations">
- <p>Some annotations have been defined in order to describe
the component meta-information.
- The list below describes these annotations.</p>
- <table border="1">
- <tr>
- <th>Annotation</th>
- <th>Location</th>
- <th>Description</th>
- </tr>
- <tr>
- <td><connect
href="index.xml#itf"><code>@provides</code></connect></td>
- <td>Class</td>
- <td>Annotation to describe a Fractal server
interface.</td>
- </tr>
- <tr>
- <td><connect
href="index.xml#ctrl"><code>@component</code></connect></td>
- <td>Class</td>
- <td>Annotation to describe the controller part of a
Fractal component.</td>
- </tr>
- <tr>
- <td><connect
href="index.xml#data"><code>@data</code></connect></td>
- <td>Class</td>
- <td>Annotation to describe a data used by a Fractal
component.</td>
- </tr>
- <tr>
- <td><connect
href="index.xml#handler"><code>@monolog.handler</code></connect></td>
- <td>Class</td>
- <td>Annotation to describe a custom Monolog
handler.</td>
- </tr>
- <tr>
- <td><connect
href="index.xml#ac"><code>@attribute</code></connect></td>
- <td>Field</td>
- <td>Annotation to describe an attribute of a Fractal
component.</td>
- </tr>
- <tr>
- <td><connect
href="index.xml#bc"><code>@requires</code></connect></td>
- <td>Field</td>
- <td>Annotation to describe a binding of a Fractal
component.</td>
- </tr>
- <tr>
- <td><connect
href="index.xml#rc"><code>@control</code></connect></td>
- <td>Field</td>
- <td>Annotation to provide a reflective control to
the content of a Fractal component.</td>
- </tr>
- <tr>
- <td><connect
href="index.xml#log"><code>@logger</code></connect></td>
- <td>Field</td>
- <td>Annotation to define a logger for a Fractal
component.</td>
- </tr>
- <tr>
- <td><connect
href="index.xml#lcc"><code>@lifecycle</code></connect></td>
- <td>Method</td>
- <td>Annotation to handle the lifecycle in a Fractal
component.</td>
- </tr>
- </table>
-
- <subtitle anchor="itf">The @provides annotation</subtitle>
- <p><strong>Details:</strong></p>
- <p>This class annotation adds the name information to the
<strong>definition of a Fractal interface</strong>.
- 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.</p>
- <p><strong>Parameters:</strong></p>
- <table>
- <tr>
- <th>Parameter</th>
- <th>Description</th>
- <th>Contingency</th>
- </tr>
- <tr>
- <td>name</td>
- <td>the name of the Fractal interface.</td>
- <td>Optional<br/>(default value is the signature
short name)</td>
- </tr>
- <tr>
- <td>signature</td>
- <td>the signature of the Fractal interface.</td>
- <td>Optional<br/>(default value is the Class
signature)</td>
- </tr>
- </table>
- <p><strong>Examples:</strong></p>
- <source>
-/** @provides name=m */
-public interface Main { ... }
-
-/** @provides name=r signature=java.lang.Runnable */
-public class Client implements Runnable { ... }
- </source>
-
- <subtitle anchor="ctrl">The @component annotation</subtitle>
- <p><strong>Details:</strong></p>
- <p>This class annotation allows the developer to describe
the <strong>description of the controller part</strong> that should be
associated to the content part of the Fractal component.</p>
- <p><strong>Parameters:</strong></p>
- <table>
- <tr>
- <th>Parameter</th>
- <th>Description</th>
- <th>Contingency</th>
- </tr>
- <tr>
- <td>name</td>
- <td>the Fractal component fullname.</td>
- <td>Optional</td>
- </tr>
- <tr>
- <td>controller</td>
- <td>the definition name of the controller part of
the Fractal component.</td>
- <td>Opti