added a "changed" attribute in the ResourceAdapterService annotation. Fixed some javadocs
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@960272 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 2d7e273..7bfdb8f 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
@@ -26,42 +26,39 @@
/**
* Annotates an Adapater Service. The adapter will be applied to any service that
- * matches the implemented interface and filter. For each matching service
- * an adapter will be created based on the adapter implementation class.
- * 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.
+ * 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.
*/
@Retention(RetentionPolicy.CLASS)
@Target(ElementType.TYPE)
public @interface AdapterService
{
/**
- * Returns the adapter service interface(s). By default, the directly implemented interface(s) is (are) used.
- * @return The service interface(s) provided by this adapter.
+ * Sets the adapter service interface(s). By default, the directly implemented interface(s) is (are) used.
*/
Class<?>[] adapterService() default {};
/**
- * The adapter service properites. They will be added to the adapted service properties.
- * @return additional properties to use with the adapter service registration
+ * Sets some additional properties to use with the adapter service registration. By default,
+ * the adapter will inherit all adaptee service properties.
*/
Property[] adapterProperties() default {};
/**
- * The adapted service interface
+ * Sets the adaptee service interface this adapter is applying to.
*/
Class<?> adapteeService();
/**
- * the filter condition to use with the adapted service interface.
- * @return the filter condition to use with the adapted ervice interface
+ * Sets the filter condition to use with the adapted service interface.
*/
String adapteeFilter() default "";
/**
- * Sets the static method used to create the AdapterService implementation instance.
+ * Sets the static method used to create the adapter service implementation instance.
+ * By default, the default constructor of the annotated class is used.
*/
String factoryMethod() default "";
}
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 7ebfde5..fe0bacb 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
@@ -25,52 +25,47 @@
/**
* Annotates an Aspect Service. The aspect will be applied to any service that
- * matches the specified interface and filter. For each matching service
- * an aspect will be created based on the aspect implementation class.
- * 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 declare the original
- * service as a member it will be injected.
+ * 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.
*/
@Retention(RetentionPolicy.CLASS)
@Target(ElementType.TYPE)
public @interface AspectService
{
/**
- * Returns the service interface to apply the aspect to. By default, the directly implemented interface is used.
- * @return The service interface to apply the aspect to.
+ * Sets the service interface to apply the aspect to. By default, the directly implemented interface is used.
*/
Class<?> service() default Object.class;
/**
- * the filter condition to use with the service interface this aspect is applying to.
- * @return the filter condition to use with the service interface
+ * Sets the filter condition to use with the service interface this aspect is applying to.
*/
String filter() default "";
/**
- * Additional properties to use with the aspect service registration
- * @return additional properties to use with the aspect service registration
+ * Sets Additional properties to use with the aspect service registration
*/
Property[] properties() default {};
/**
- * Ranking of this aspect. Since aspects are chained, the ranking defines the order in which they are chained.
+ * Sets the ranking of this aspect. Since aspects are chained, the ranking defines the order in which they are chained.
* Chain ranking is implemented as a service ranking so service lookups automatically retrieve the top of the
* chain.
- *
- * @return the ranking of this aspect
*/
int ranking();
/**
- * Specifies the field name where to inject the original service. By default, the original service is injected
+ * Sets the field name where to inject the original service. By default, the original service is injected
* in any attributes in the aspect implementation that are of the same type as the aspect interface.
*/
String field() default "";
/**
- * Sets the static method used to create the AspectService implementation instance.
+ * Sets the static method used to create the AspectService implementation instance. By default, the
+ * default constructor of the annotated class is used. The factoryMethod can be used to provide a specific
+ * aspect implements, like a DynamicProxy.
*/
String factoryMethod() default "";
}
diff --git a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/ResourceAdapterService.java b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/ResourceAdapterService.java
index e4a3171..3875038 100644
--- a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/ResourceAdapterService.java
+++ b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/ResourceAdapterService.java
@@ -58,6 +58,11 @@
boolean propagate() default false;
/**
+ * The callback method to be invoked when the Resource has changed.
+ */
+ String changed() default "";
+
+ /**
* Sets the static method used to create the AdapterService implementation instance.
*/
String factoryMethod() default "";
diff --git a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Service.java b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Service.java
index 739be75..ce16e40 100644
--- a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Service.java
+++ b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Service.java
@@ -28,9 +28,9 @@
* By default, all directly implemented interfaces are registered into the OSGi registry,
* and the Service is instantiated automatically, when the Service' bundle is started and
* when the Service dependencies are available. If you need to take control of when and how
- * much Service instance must be created, then you can use the <code>factory</code>
+ * much Service instances must be created, then you can use the <code>factorySet</code>
* Service attribute.<p>
- * If a <code>factory</code> attribute is set, the Service is not started automatically
+ * If a <code>factorySet</code> attribute is set, the Service is not started automatically
* during bundle startup, and a <code>java.util.Set<Dictionary></code>
* object is registered into the OSGi registry on behalf of the Service. This Set will act
* as a Factory API, and another component may use this Set and add some configuration
@@ -58,11 +58,12 @@
* @Start
* void start() {
* // Our Service is starting and is about to be registered in the OSGi registry as a Z service.
- * }
+ * }
*
- * public void doService() {
+ * public void doService() {
* // ...
- * }
+ * }
+ * }
* </pre>
* </blockquote>
*
@@ -151,10 +152,11 @@
* So, basically, another component may then be injected with this set in order to dynamically instantiate some Service instances:
* <ul>
* <li> Each time a new Dictionary is added into the Set, then a new instance of the annotated service will be instantiated.</li>
- * <li> Each time an existing Dictionary is updated from the Set, then the corresponding Service instance will be updated.</li>
+ * <li> Each time an existing Dictionary is re-added into the Set, then the corresponding Service instance will be updated.</li>
* <li> Each time an existing Dictionary is removed from the Set, then the corresponding Service instance will be destroyed.</li>
* </ul>
- * The dictionary registered in the Set will be provided to the created Service instance using a callback method that you can
+ *
+ * <p>The dictionary registered in the Set will be provided to the created Service instance using a callback method that you can
* optionally specify in the {@link Service#factoryConfigure()} attribute. Each public properties from that dictionary
* (which don't start with a dot) will be propagated along with the annotated Service properties.
*/
diff --git a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/ServiceDependency.java b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/ServiceDependency.java
index a040810..4a8270d 100644
--- a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/ServiceDependency.java
+++ b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/ServiceDependency.java
@@ -32,7 +32,8 @@
public @interface ServiceDependency
{
/**
- * The type if the service this dependency is applying on. By default, the type is method parameter or the class field type.
+ * The type if the service this dependency is applying on. By default, the method parameter
+ * (or the class field) is used as the type.
*/
Class<?> service() default Object.class;
@@ -131,6 +132,12 @@
* m_config = config;
* }
*
+ * // This named dependency will be configured by our init method (see below).
+ * @ServiceDependency(name="dependency1")
+ * void bindOtherService(OtherService other) {
+ * // the filter and required flag will be configured from our init method.
+ * }
+
* // The returned Map will be used to configure our "dependency1" Dependency.
* @Init
* Map init() {
@@ -139,11 +146,6 @@
* put("dependency1.required", m_config.get("required"));
* }};
* }
- *
- * @ServiceDependency(name="dependency1")
- * void bindOtherService(OtherService other) {
- * // the filter and required flag will be configured from our init method.
- * }
* }
* </pre></blockquote>
*/
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 324fb92..13d43b6 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
@@ -574,6 +574,9 @@
// Parse propagate attribute
writer.putString(annotation, EntryParam.propagate, Boolean.FALSE.toString());
+
+ // Parse changed attribute
+ writer.putString(annotation, EntryParam.changed, null);
}
/**
diff --git a/dependencymanager/runtime/src/main/java/org/apache/felix/dm/runtime/ResourceAdapterServiceBuilder.java b/dependencymanager/runtime/src/main/java/org/apache/felix/dm/runtime/ResourceAdapterServiceBuilder.java
index bbddb88..601925e 100644
--- a/dependencymanager/runtime/src/main/java/org/apache/felix/dm/runtime/ResourceAdapterServiceBuilder.java
+++ b/dependencymanager/runtime/src/main/java/org/apache/felix/dm/runtime/ResourceAdapterServiceBuilder.java
@@ -44,7 +44,8 @@
String[] service = srvMeta.getStrings(Params.service, null);
Dictionary<String, Object> properties = srvMeta.getDictionary(Params.properties, null);
boolean propagate = "true".equals(srvMeta.getString(Params.propagate, "false"));
- Service srv = dm.createResourceAdapterService(filter, propagate, null, "changed")
+ String changed = srvMeta.getString(Params.changed, null /* no change callback if not specified explicitly */);
+ Service srv = dm.createResourceAdapterService(filter, propagate, null, changed)
.setInterface(service, properties);
String factoryMethod = srvMeta.getString(Params.factoryMethod, null);
if (factoryMethod == null)