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.

@Component
@Instantiate
@Stereotype
@Target(TYPE)
public @interface AutoComponent {}

The MyComponent class will be considered as a component with an instance.

@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, ...).

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 module:

<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>

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.