Complement annotations javadoc with code samples
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@1564827 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Component.java b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Component.java
index 40f77e3..a38245d 100644
--- a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Component.java
+++ b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Component.java
@@ -22,8 +22,32 @@
import java.lang.annotation.Target;
/**
- * This annotation declares a component.
+ * Declares a component type (needed to create instances of the component).
* This annotation is mandatory to declares an iPOJO component.
+ *
+ * Its usual to find it on top of class definition:
+ * <pre>
+ * {@code @Component}
+ * public class MyComponent {
+ * // ...
+ * }
+ * </pre>
+ *
+ * But, it is also possible to have it associated to a
+ * {@linkplain org.apache.felix.ipojo.annotations.Stereotype stereotyped} annotation definition:
+ * <pre>
+ * {@code @Component}
+ * {@linkplain org.apache.felix.ipojo.annotations.Instantiate @Instantiate}
+ * {@linkplain org.apache.felix.ipojo.annotations.Stereotype @Stereotype}
+ * public @interface AutoInstantiatedComponent {
+ * // ...
+ * }
+ * </pre>
+ *
+ * <h2>See also</h2>
+ * <ul>
+ * <li><a href="http://felix.apache.org/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/how-to-use-ipojo-factories.html">Use iPOJO Factories</a></li>
+ * </ul>
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
@Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE})
@@ -31,44 +55,86 @@
/**
* Set if the component type is public.
- * Default: true
+ * @see #publicFactory()
* @deprecated renamed to publicFactory.
*/
boolean public_factory() default true;
/**
- * Set if the component type is public.
- * Default: true
+ * Set if the component type is public or private (defaults to public).
+ * A private factory does not expose a {@code Factory} service.
+ * Only instances declared in the same bundle are created.
+ * <pre>
+ * {@code @Component(publicFactory = false)}
+ * public class MyComponent {
+ * // ...
+ * }
+ * </pre>
+ * Default: {@literal true}
*/
boolean publicFactory() default true;
/**
* Set the component type name.
+ * <pre>
+ * {@code @Component(name = "my-component")}
+ * public class MyComponent {
+ * // ...
+ * }
+ * </pre>
* Default : implementation class name.
*/
String name() default "";
/**
- * Enable / Disable the architecture exposition.
- * Default : true
+ * Enable / Disable the architecture exposition (no {@code Architecture}
+ * service will be exposed for component's instances).
+ * <pre>
+ * {@code @Component(architecture = false)}
+ * public class MyComponent {
+ * // ...
+ * }
+ * </pre>
+ * Default : {@literal true}
*/
boolean architecture() default true;
/**
* Set if the component is immediate.
- * Default : false
+ * By default, iPOJO tries to be as lazy as possible and will create the POJO instance at the last possible time.
+ * Notice this setting is only effective when the component provides a service ({@linkplain org.apache.felix.ipojo.annotations.Provides @Provides}).
+ * <pre>
+ * {@code @Component(immediate = true)}
+ * {@linkplain org.apache.felix.ipojo.annotations.Provides @Provides}
+ * public class MyComponent implements MyService {
+ * // ...
+ * }
+ * </pre>
+ * Default : {@literal false}
*/
boolean immediate() default false;
/**
- * Set if the component must propagate received configuration to provided services.
- * default: true
+ * Enable or disable the configuration propagation to service properties.
+ * <pre>
+ * {@code @Component(propagation = false)}
+ * public class MyComponent {
+ * // ...
+ * }
+ * </pre>
+ * default: {@literal true}
*/
boolean propagation() default true;
/**
- * Set the Managed Service PID.
+ * Set the Managed Service PID for Configuration Admin.
* default no PID (i.e. the managed service will not be exposed).
+ * <pre>
+ * {@code @Component(managedservice = "my.Pid")}
+ * public class MyComponent {
+ * // ...
+ * }
+ * </pre>
*/
String managedservice() default "";
@@ -77,6 +143,7 @@
* from a static method. The specified method must be a static
* method and return a pojo object.
* By default, iPOJO uses the 'regular' constructor.
+ * @see #factoryMethod()
* @deprecated now is called <tt>factoryMethod</tt>.
*/
String factory_method() default "";
@@ -86,11 +153,26 @@
* from a static method. The specified method must be a static
* method and return a pojo object.
* By default, iPOJO uses the 'regular' constructor.
+ * <pre>
+ * {@code @Component(factoryMethod = "createInstance")}
+ * public class MyComponent {
+ * // ...
+ * public static MyComponent createInstance() {
+ * return new MyComponent("some static configuration");
+ * }
+ * }
+ * </pre>
*/
String factoryMethod() default "";
/**
* Set the version of the component type.
+ * <pre>
+ * {@code @Component(version = "1.3")}
+ * public class MyComponent {
+ * // ...
+ * }
+ * </pre>
*/
String version() default "";
}
diff --git a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Controller.java b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Controller.java
index 4f3dc92..babcf01 100644
--- a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Controller.java
+++ b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Controller.java
@@ -22,7 +22,27 @@
import java.lang.annotation.Target;
/**
- * This annotation declares a lifecycle controller.
+ * This annotation declares a <a href="http://felix.apache.org/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/instance-vs-service-controller.html">lifecycle controller</a>.
+ *
+ * <pre>
+ * {@code @Component}
+ * public class MyComponent {
+ * // ...
+ * {@code @Controller}
+ * private boolean controller;
+ *
+ * public void aMethod() {
+ * // Invalidate the instance
+ * controller = false;
+ * }
+ *
+ * public void anotherMethod() {
+ * // Validate the instance again
+ * controller = true;
+ * }
+ * }
+ * </pre>
+
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
@Target({ElementType.FIELD, ElementType.ANNOTATION_TYPE})
diff --git a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Handler.java b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Handler.java
index b921267..b3fa777 100644
--- a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Handler.java
+++ b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Handler.java
@@ -24,6 +24,16 @@
/**
* This annotation declares a handler.
* This annotation is mandatory to declares an iPOJO handler.
+ * <pre>
+ * {@code @Handler}(
+ * name = "my-handler",
+ * namespace = "com.acme.foo"
+ * )
+ * public class MyHandler extends PrimitiveHandler {
+ * // ...
+ * }
+ * </pre>
+
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
@Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE})
@@ -47,7 +57,7 @@
/**
* Enable / Disable the architecture exposition.
- * Default : false
+ * Default : {@literal false}
*/
boolean architecture() default false;
}
diff --git a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/HandlerDeclaration.java b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/HandlerDeclaration.java
index 608b6bf..1191d47 100644
--- a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/HandlerDeclaration.java
+++ b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/HandlerDeclaration.java
@@ -22,7 +22,14 @@
import java.lang.annotation.Target;
/**
- * This annotation is used to configure a handler.
+ * This annotation is used to configure a handler through XML (as in {@literal metadata.xml}).
+ * <pre>
+ * {@linkplain org.apache.felix.ipojo.annotations.Component @Component}
+ * {@code @HandlerDeclaration("<ns:my-handler attribute='value' xmlns:ns='http://www.acme.com/ipojo/ns'/>")}
+ * public class MyComponent {
+ * // ...
+ * }
+ * </pre>
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
@Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE})
@@ -31,6 +38,7 @@
/**
* The content of this attribute represents the XML
* that would be used in the metadata.xml.
+ * It must be a root XML Element, namespaces are allowed and so for child elements.
*/
String value();
}
diff --git a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Instantiate.java b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Instantiate.java
index 90b0b7b..87d9201 100644
--- a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Instantiate.java
+++ b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Instantiate.java
@@ -24,6 +24,17 @@
/**
* This annotation is used to create an 'empty' instance of the
* current component type.
+ *
+ * Notice that all mandatory properties should have a default value, otherwise
+ * configuration is declared unacceptable and the instance creation fails.
+ *
+ * <pre>
+ * {@linkplain org.apache.felix.ipojo.annotations.Component @Component}
+ * {@code @Instantiate}
+ * public class MyComponent {
+ * // ...
+ * }
+ * </pre>
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
@Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE})
@@ -31,7 +42,14 @@
/**
* Optional attribute to set the instance name.
- * Default: no name
+ * Default: unique generated name
+ * <pre>
+ * {@linkplain org.apache.felix.ipojo.annotations.Component @Component}
+ * {@code @Instantiate("my-default-component")}
+ * public class MyComponent {
+ * // ...
+ * }
+ * </pre>
*/
String name() default "";
}
diff --git a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Invalidate.java b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Invalidate.java
index 01b0c66..0dfac8c 100644
--- a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Invalidate.java
+++ b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Invalidate.java
@@ -23,6 +23,13 @@
/**
* This annotation declares an invalidate callback.
+ *
+ * <pre>
+ * {@code @Invalidate}
+ * public void stop() {
+ * // Code executed when instances are becoming invalid
+ * }
+ * </pre>
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
diff --git a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/PostRegistration.java b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/PostRegistration.java
index e4a65c6..0319439 100644
--- a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/PostRegistration.java
+++ b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/PostRegistration.java
@@ -23,8 +23,16 @@
/**
- * This annotation declares a post-service-registration method.
+ * Declares a method to be <a href="http://felix.apache.org/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/providing-osgi-services.html#being-notified-of-the-service-registration-and-unregistration">notified after service registration</a> is effective.
+ *
+ * <pre>
+ * {@code @PostRegistration}
+ * public void registered(ServiceReference<?> reference) {
+ * // Called after the service publication
+ * }
+ * </pre>
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
+ * @see org.apache.felix.ipojo.annotations.Provides
*/
@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
public @interface PostRegistration {
diff --git a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/PostUnregistration.java b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/PostUnregistration.java
index ce9208e..50f7040 100644
--- a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/PostUnregistration.java
+++ b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/PostUnregistration.java
@@ -23,8 +23,16 @@
/**
- * This annotation declares a post-service-unregistration method.
+ * Declares a method to be <a href="http://felix.apache.org/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/providing-osgi-services.html#being-notified-of-the-service-registration-and-unregistration">notified after service un-registration</a> is effective.
+ *
+ * <pre>
+ * {@code @PostUnregistration}
+ * public void unregistered(ServiceReference<?> reference) {
+ * // Called after the service un-publication
+ * }
+ * </pre>
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
+ * @see org.apache.felix.ipojo.annotations.Provides
*/
@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
public @interface PostUnregistration {
diff --git a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Provides.java b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Provides.java
index 1db18f5..d0f06ee 100644
--- a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Provides.java
+++ b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Provides.java
@@ -22,36 +22,71 @@
import java.lang.annotation.Target;
/**
-* This annotation declares that the component instances will provide a service.
-* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
+ * This annotation declares that the component instances will provide a service.
+ *
+ * <pre>
+ * {@linkplain org.apache.felix.ipojo.annotations.Component @Component}
+ * {@code @Provides}
+ * public class MyComponent implements Service {
+ * // ...
+ * }
+ * </pre>
+ * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
@Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE})
public @interface Provides {
/**
* Set the provided specifications.
+ * It can be used to force the exposed service to use an implementation class
+ * (not an interface) as specification.
* Default : all implemented interfaces
+ *
+ * <pre>
+ * {@linkplain org.apache.felix.ipojo.annotations.Component @Component}
+ * {@code @Provides(specifications = AbsComponent.class)}
+ * public class MyComponent extends AbsComponent {
+ * // ...
+ * }
+ * </pre>
*/
Class[] specifications() default { };
/**
* Set the service object creation strategy.
- * Two value are possible: SINGLETON, SERVICE, METHOD, INSTANCE or the strategy class name.
- * SERVICE means OSGi Service Factory.
- * METHOD delegates the creation to the factory-method of the component
- * INSTANCE creates one service object per requiring instance
- * for other strategies, specify the qualified name of the CreationStrategy class.
- * Default : SINGLETON
+ * Multiple values are possible: {@literal SINGLETON}, {@literal SERVICE},
+ * {@literal METHOD}, {@literal INSTANCE} or the strategy fully qualified class name:
+ * <ul>
+ * <li>{@literal SINGLETON}: Default strategy</li>
+ * <li>{@literal SERVICE}: OSGi Service Factory style, 1 POJO instance per consumer bundle</li>
+ * <li>{@literal METHOD}: Delegates the creation to the factory-method of the component, method will be called every time the service reference is get.</li>
+ * <li>{@literal INSTANCE}: Creates one service object per requiring instance</li>
+ * <li>Any other value is interpreted as the qualified name of a {@code CreationStrategy} implementation</li>
+ * </ul>
*/
String strategy() default "SINGLETON";
/**
* Allows adding static properties to the service.
- * Nested properties are static service properties,
- * so <b>must</b> contain the name and the value as
- * they are not attached to a field.
+ * Nested properties are static service properties, so <b>must</b> contain the name,
+ * value and type as they are not attached to a field (cannot discover type through
+ * introspection).
* The array contains {@link StaticServiceProperty} elements.
* Default : No service properties
+
+ * <pre>
+ * {@linkplain org.apache.felix.ipojo.annotations.Component @Component}
+ * {@code @Provides}(
+ * properties = {
+ * {@code @StaticServiceProperty}(name = "size", type = "int", value = "5"),
+ * {@code @StaticServiceProperty}(name = "name", type = "java.lang.String", value = "OSGi")
+ * }
+ * )
+ * public class MyComponent implements Service {
+ * // ...
+ * }
+ * </pre>
+
*/
StaticServiceProperty[] properties() default {};
}
diff --git a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Updated.java b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Updated.java
index 8abff5e..5fa9270 100644
--- a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Updated.java
+++ b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Updated.java
@@ -23,7 +23,22 @@
/**
* This annotation declares an updated callback.
- * Updated callback are called after a reconfiguration.
+ * Updated callback are called after a <a href="http://felix.apache.org/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/configuration-handler.html#being-notified-when-a-reconfiguration-is-completed">reconfiguration</a>.
+ *
+ * Methods annotated with {@code @Updated} must have one of the 2 following signatures:
+ * <pre>
+ * {@code @Updated}
+ * public void updated() {
+ * // The instance was reconfigured
+ * }
+ * </pre>
+ *
+ * <pre>
+ * {@code @Updated}
+ * public void updated(Dictionary conf) {
+ * // The instance was reconfigured, conf is the new configuration.
+ * }
+ * </pre>
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
diff --git a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Validate.java b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Validate.java
index aaaa321..3a6517e 100644
--- a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Validate.java
+++ b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Validate.java
@@ -23,6 +23,13 @@
/**
* This annotation declares a validate callback.
+ *
+ * <pre>
+ * {@code @Validate}
+ * public void start() {
+ * // Code executed when instances are becoming valid
+ * }
+ * </pre>
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})