felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From guilla...@apache.org
Subject svn commit: r1489150 - in /felix/site/trunk: content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ templates/
Date Mon, 03 Jun 2013 20:20:03 GMT
Author: guillaume
Date: Mon Jun  3 20:20:03 2013
New Revision: 1489150

URL: http://svn.apache.org/r1489150
FELIX-4095 Add CDI-like @Stereotype

* Add documentation


Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics.mdtext?rev=1489150&r1=1489149&r2=1489150&view=diff
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics.mdtext
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics.mdtext
Mon Jun  3 20:20:03 2013
@@ -11,6 +11,7 @@ Title: iPOJO Advanced Topics
 * [Constructing POJO objects with factory methods]({{ refs.constructing-pojo-objects-with-factory-methods.path
 * [How-to use iPOJO factories]({{ refs.how-to-use-ipojo-factories.path }})
 * [iPOJO Hierarchical Composition Overview]({{ refs.ipojo-hierarchical-composition-overview.path
+* [Using @Stereotype]({{ refs.using-stereotypes.path }})

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/using-stereotypes.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/using-stereotypes.mdtext?rev=1489150&view=auto
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/using-stereotypes.mdtext
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/using-stereotypes.mdtext
Mon Jun  3 20:20:03 2013
@@ -0,0 +1,86 @@
+translation_pending: true
+Title: How-to use @Stereotype
+# Stereotypes
+*Stereotypes are user-defined marker annotations allowing to group other annotations together.
iPOJO recognize these annotations and act as if all the grouped annotations were directly
decorating the stereotyped annotation support.*
+## Example
+The `@AutoComponent` is a stereotyped annotation (notice the `@Stereotype`) that will act
as a 'container' for `@Component` and `@Instantiate`.
+    :::java
+    @Component
+    @Instantiate
+    @Stereotype
+    @Target(TYPE)
+    public @interface AutoComponent {}
+The `MyComponent` class will be considered as a component with an instance.
+    :::java
+    @AutoComponent
+    public class MyComponent {
+        // ...
+    }
+## When using a stereotype ?
+Stereotypes are useful when writing extension of the iPOJO programming model. Sometimes,
to keep things simple for the user, its necessary to hide some parts of iPOJO.
+For example, a new programming model could mandates to have one-to-one factory/instance relationship.
With iPOJO's programming model, writing `@Component` and `@Instantiate` (if using annotation)
is required, this may be error prone when writing the new components: the developer could
miss one annotation or the other.
+Another example is to simplify annotation declaration when an annotation pattern appears
(the same annotations group on many places of the code). Typically, introducing a stereotype
defines a 'kind' that can be reused (code factorisation).
+# Defining a Stereotype
+Stereotyped annotations, unlike custom handler annotations, do not need to be in a package
containing either `ipojo` or `handler`. They just need to be annotated with `@Stereotype`
(since iPOJO annotations 1.10.1) and have a class level rentention policy (the default when
`@Retention` is missing). Any `@Target` can be specified (`TYPE`, `METHOD`, `FIELD`, `CONSTRUCTOR`
and `ANNOTATION_TYPE` are supported), dependeding on the stereotype's semantic.
+A stereotyped annotation can support all of the regular iPOJO's annotations plus all other
externally supported types (custom handler, manipulator binding extensions, ...).
+    :::java
+    import com.acme.app.ipojo.Custom; // Import a custom handler annotation
+    @Component                        // Use standard iPOJO annotation
+    @Custom                           // Use the custome annotation
+    @HandlerDeclaration("<ns:handler xmlns:ns='com.acme.app'/>")
+    @Stereotype
+    @Target(TYPE)
+    public @interface AutoComponent {}
+The stereotype developer needs to declare a compile time dependency on the ipojo annotations
+    :::xml
+    <dependency>
+        <groupId>org.apache.felix</groupId>
+        <artifactId>org.apache.felix.ipojo.annotations</artifactId>
+        <version>${ipojo.version}</version> <!-- Since 1.10.1 -->
+        <scope>provided</scope>
+    </dependency>
+<div class="alert alert-info info" markdown="1">
+<h4>Type and manipulation</h4>
+<p>The artifact containing the stereotyped annotation *does not need* to be a bundle
and it does not need to be manipulated.</p>
+# Using the new stereotype
+Using a stereotyped annotation does not differ from using any annotation: it has decorate
some type, method, field, ...
+## Manipulation
+Stereotype support needs iPOJO manipulator 1.10.1 (at least).
+During the manipulation, the system search for all annotation definitions to find if they
are @Stereotype annotated or not.
+If the stereotyped annotation is directly in the manipulated module, no problems: any front-end
will work as expected.
+If not, the different manipulator's front-end have variable support for the stereotype feature.
+### With bnd-ipojo-plugin
+The more advanced support for stereotypes.
+The plugin inspect *maven project's dependencies* provided to Bnd as its classpath to find
stereotyped annotations definition.
+### With others
+No dependencies are analyzed at the moment.
\ No newline at end of file

Modified: felix/site/trunk/templates/ipojo.html
URL: http://svn.apache.org/viewvc/felix/site/trunk/templates/ipojo.html?rev=1489150&r1=1489149&r2=1489150&view=diff
--- felix/site/trunk/templates/ipojo.html (original)
+++ felix/site/trunk/templates/ipojo.html Mon Jun  3 20:20:03 2013
@@ -106,6 +106,7 @@
                                         <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/constructing-pojo-objects-with-factory-methods.html">Constructing
service objects with factory methods</a></li>
                                         <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/using-ipojo-introspection-api.html">Using
the introspection API</a></li>
                                         <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-testing-components.html">Testing
+                                        <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/using-stereotypes.html">Using
                                         <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-eclipse-integration.html">Eclipse
                                         <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-faq.html">FAQ</a></li>
                                         <li><a href="{{ refs.ipojo-reference-card.path
}}">Reference Card</a></li>

View raw message