Fixed javadoc. Cleaned imports.
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@1064323 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/AdapterService.java b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/AdapterService.java
index 5f1f816..d21f627 100644
--- a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/AdapterService.java
+++ b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/AdapterService.java
@@ -23,13 +23,37 @@
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
-
/**
* Annotates an Adapater Service. The adapter will be applied to any service that
* matches the implemented interface and filter. The adapter will be registered
* with the specified interface and existing properties from the original service
* plus any extra properties you supply here. It will also inherit all dependencies,
* and if you declare the original service as a member it will be injected.
+ *
+ * <h3>Usage Examples</h3>
+ *
+ * <p> Here, the AdapterService is registered into the OSGI registry each time an AdapteeService
+ * is found from the registry. The AdapterImpl class adapts the AdapteeService to the AdapterService.
+ * The AdapterService will also have a service property (param=value), and will also include eventual
+ * service properties found from the AdapteeService:<p>
+ * <blockquote>
+ * <pre>
+ *
+ * @AdapterService(adapteeService = AdapteeService.class,
+ * properties={@Property(name="param", value="value")})
+ * class AdapterImpl implements AdapterService
+ * {
+ * // The service we are adapting (injected by reflection)
+ * protected AdapteeService adaptee;
+ *
+ * public void doWork()
+ * {
+ * adaptee.mehod1();
+ * adaptee.method2();
+ * }
+ * }
+ * </pre>
+ * </blockquote>
*/
@Retention(RetentionPolicy.CLASS)
@Target(ElementType.TYPE)
diff --git a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/AspectService.java b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/AspectService.java
index fe0bacb..55c6600 100644
--- a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/AspectService.java
+++ b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/AspectService.java
@@ -28,7 +28,32 @@
* matches the specified interface and filter. The aspect will be registered
* with the same interface and properties as the original service, plus any
* extra properties you supply here. It will also inherit all dependencies,
- * and if you can declare the original service as a member it will be injected.
+ * and if you can declare the original service as a member it will be injected.<p>
+ *
+ * <h3>Usage Examples</h3>
+ *
+ * <p> Here, the AspectService is registered into the OSGI registry each time an InterceptedService
+ * is found from the registry. The AspectService class intercepts the InterceptedService, and decorates
+ * its "doWork()" method. This aspect uses a rank with value "10", meaning that it will intercept some
+ * other eventual aspects with lower ranks. The Aspect also uses a service property (param=value), and
+ * include eventual service properties found from the InterceptedService:<p>
+ * <blockquote>
+ * <pre>
+ *
+ * @AspectService(ranking=10),
+ * properties={@Property(name="param", value="value")})
+ * class AspectService implements InterceptedService
+ * {
+ * // The service we are intercepting (injected by reflection)
+ * protected InterceptedService intercepted;
+ *
+ * public void doWork()
+ * {
+ * intercepted.doWork();
+ * }
+ * }
+ * </pre>
+ * </blockquote>
*/
@Retention(RetentionPolicy.CLASS)
@Target(ElementType.TYPE)
@@ -63,7 +88,7 @@
String field() default "";
/**
- * Sets the static method used to create the AspectService implementation instance. By default, the
+ * Sets the static method used to create the AspectService implementation instance. The
* default constructor of the annotated class is used. The factoryMethod can be used to provide a specific
* aspect implements, like a DynamicProxy.
*/
diff --git a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/BundleAdapterService.java b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/BundleAdapterService.java
index bf7d93c..04e2d47 100644
--- a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/BundleAdapterService.java
+++ b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/BundleAdapterService.java
@@ -60,7 +60,7 @@
int stateMask() default Bundle.INSTALLED | Bundle.RESOLVED | Bundle.ACTIVE;
/**
- * Specifies if manifest headers from the bundle should be propagated to the service.
+ * Specifies if manifest headers from the bundle should be propagated to the service properties.
*/
boolean propagate() default true;
diff --git a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Composition.java b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Composition.java
index 3abbead..7996920 100644
--- a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Composition.java
+++ b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Composition.java
@@ -25,7 +25,45 @@
/**
* Annotates a method returning the list of objects which are part of the Service implementation.
- * Each instances will be injected with Service dependencies.
+ * Each instances will be injected with Service dependencies (attributes or callbacks), and if the
+ * service has some annotated lifecycle callbacks (@Init/@Start/@Stop/@Destroy), then the same callbacks
+ * will be invoked on the objects which are part of the composition.<p>
+ *
+ * <h3>Usage Examples</h3>
+ *
+ * <p> Here, the "MyComponent" component is composed of the Helper class, which is also injected with
+ * service dependencies. The lifecycle callbacks are also invoked in the Helper (if the Helper defines
+ * them):<p>
+ * <blockquote>
+ * <pre>
+ *
+ * class Helper {
+ * LogService logService; // Injected
+ * void start() {} // lifecycle callback
+ * void bind(OtherService otherService) {} // injected
+ * }
+ *
+ * @Component
+ * class MyComponent {
+ * // Helper which will also be injected with our service dependencies
+ * private Helper helper = new Helper();
+ *
+ * @Composition
+ * Object[] getComposition() {
+ * return new Object[] { this, helper };
+ * }
+ *
+ * @ServiceDependency
+ * private LogService logService; // Helper.logService will be also be injected, if defined.
+ *
+ * @Start
+ * void start() {} // the Helper.start() method will also be called, if defined
+ *
+ * @ServiceDependency
+ * void bind(OtherService otherService) {} // the Helper.bind() method will also be called, if defined
+ * }
+ * </pre>
+ * </blockquote>
*/
@Retention(RetentionPolicy.CLASS)
@Target(ElementType.METHOD)
diff --git a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/plugin/bnd/AnnotationCollector.java b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/plugin/bnd/AnnotationCollector.java
index ec5fd7d..274eb87 100644
--- a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/plugin/bnd/AnnotationCollector.java
+++ b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/plugin/bnd/AnnotationCollector.java
@@ -31,6 +31,7 @@
import org.apache.felix.dm.annotation.api.AspectService;
import org.apache.felix.dm.annotation.api.BundleAdapterService;
import org.apache.felix.dm.annotation.api.BundleDependency;
+import org.apache.felix.dm.annotation.api.Component;
import org.apache.felix.dm.annotation.api.Composition;
import org.apache.felix.dm.annotation.api.ConfigurationDependency;
import org.apache.felix.dm.annotation.api.Destroy;
@@ -39,7 +40,6 @@
import org.apache.felix.dm.annotation.api.LifecycleController;
import org.apache.felix.dm.annotation.api.ResourceAdapterService;
import org.apache.felix.dm.annotation.api.ResourceDependency;
-import org.apache.felix.dm.annotation.api.Component;
import org.apache.felix.dm.annotation.api.ServiceDependency;
import org.apache.felix.dm.annotation.api.Start;
import org.apache.felix.dm.annotation.api.Stop;
diff --git a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/plugin/bnd/DescriptorGenerator.java b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/plugin/bnd/DescriptorGenerator.java
index 6801024..6b301cc 100644
--- a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/plugin/bnd/DescriptorGenerator.java
+++ b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/plugin/bnd/DescriptorGenerator.java
@@ -27,8 +27,6 @@
import java.util.HashMap;
import java.util.Map;
-import org.apache.felix.dm.annotation.api.Component;
-
import aQute.lib.osgi.Analyzer;
import aQute.lib.osgi.Clazz;
import aQute.lib.osgi.EmbeddedResource;
diff --git a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/plugin/mvn/AnnotationMojo.java b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/plugin/mvn/AnnotationMojo.java
index 126bcc2..f65d5ac 100644
--- a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/plugin/mvn/AnnotationMojo.java
+++ b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/plugin/mvn/AnnotationMojo.java
@@ -19,7 +19,6 @@
package org.apache.felix.dm.annotation.plugin.mvn;
import java.io.File;
-import java.io.IOException;
import java.util.Iterator;
import java.util.Map;