Added several bits of javadoc to the public API methods.
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@1435086 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/dependencymanager/core/src/main/java/org/apache/felix/dm/Component.java b/dependencymanager/core/src/main/java/org/apache/felix/dm/Component.java
index 81b0f0f..50d1e28 100644
--- a/dependencymanager/core/src/main/java/org/apache/felix/dm/Component.java
+++ b/dependencymanager/core/src/main/java/org/apache/felix/dm/Component.java
@@ -39,6 +39,13 @@
* @return this component
*/
public Component add(Dependency dependency);
+
+ /**
+ * Adds a list of new dependencies to this component.
+ *
+ * @param dependencies the dependencies to add
+ * @return this component
+ */
public Component add(List dependencies);
/**
@@ -255,6 +262,18 @@
*/
public Object[] getCompositionInstances();
+ /**
+ * Invokes a callback method on an array of instances. The method, whose name
+ * and signatures you provide, along with the values for the parameters, is
+ * invoked on all the instances where it exists.
+ *
+ * @see InvocationUtil#invokeCallbackMethod(Object, String, Class[][], Object[][])
+ *
+ * @param instances an array of instances to invoke the method on
+ * @param methodName the name of the method
+ * @param signatures the signatures of the method
+ * @param parameters the parameter values
+ */
public void invokeCallbackMethod(Object[] instances, String methodName, Class[][] signatures, Object[][] parameters);
/**
diff --git a/dependencymanager/core/src/main/java/org/apache/felix/dm/ConfigurationDependency.java b/dependencymanager/core/src/main/java/org/apache/felix/dm/ConfigurationDependency.java
index d00dcf0..02aed1e 100644
--- a/dependencymanager/core/src/main/java/org/apache/felix/dm/ConfigurationDependency.java
+++ b/dependencymanager/core/src/main/java/org/apache/felix/dm/ConfigurationDependency.java
@@ -29,46 +29,68 @@
*
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
-public interface ConfigurationDependency extends Dependency, ComponentDependencyDeclaration
-{
- ConfigurationDependency setCallback(String callback);
+public interface ConfigurationDependency extends Dependency, ComponentDependencyDeclaration {
+ /**
+ * Sets the name of the callback method that should be invoked when a configuration
+ * is available. The contract for this method is identical to that of
+ * <code>ManagedService.updated(Dictionary) throws ConfigurationException</code>.
+ *
+ * @param callback the name of the callback method
+ */
+ ConfigurationDependency setCallback(String callback);
- /**
- * Sets the <code>service.pid</code> of the configuration you are depending on.
- */
- ConfigurationDependency setPid(String pid);
+ /**
+ * Sets the <code>service.pid</code> of the configuration you are depending
+ * on.
+ */
+ ConfigurationDependency setPid(String pid);
- /**
- * Sets propagation of the configuration properties to the service properties. Any additional
- * service properties specified directly are merged with these.
- */
- ConfigurationDependency setPropagate(boolean propagate);
-
- /**
- * The label used to display the tab name (or section) where the properties are displayed. Example: "Printer Service".
- * @return The label used to display the tab name where the properties are displayed (may be localized)
- */
- ConfigurationDependency setHeading(String heading);
+ /**
+ * Sets propagation of the configuration properties to the service
+ * properties. Any additional service properties specified directly are
+ * merged with these.
+ */
+ ConfigurationDependency setPropagate(boolean propagate);
- /**
- * A human readable description of the PID this configuration is associated with. Example: "Configuration for the PrinterService bundle".
- * @return A human readable description of the PID this configuration is associated with (may be localized)
- */
- ConfigurationDependency setDescription(String description);
+ /**
+ * The label used to display the tab name (or section) where the properties
+ * are displayed. Example: "Printer Service".
+ *
+ * @return The label used to display the tab name where the properties are
+ * displayed (may be localized)
+ */
+ ConfigurationDependency setHeading(String heading);
- /**
- * Points to the basename of the Properties file that can localize the Meta Type informations.
- * The default localization base name for the properties is OSGI-INF/l10n/bundle, but can
- * be overridden by the manifest Bundle-Localization header (see core specification, in section Localization on page 68).
- * You can specify a specific localization basename file using this method (e.g. <code>setLocalization("person")</code>
- * will match person_du_NL.properties in the root bundle directory.
- */
- ConfigurationDependency setLocalization(String path);
+ /**
+ * A human readable description of the PID this configuration is associated
+ * with. Example: "Configuration for the PrinterService bundle".
+ *
+ * @return A human readable description of the PID this configuration is
+ * associated with (may be localized)
+ */
+ ConfigurationDependency setDescription(String description);
- /**
- * Adds a MetaData regarding a given configuration property.
- */
- ConfigurationDependency add(PropertyMetaData properties);
-
- ConfigurationDependency setInstanceBound(boolean isInstanceBound);
+ /**
+ * Points to the basename of the Properties file that can localize the Meta
+ * Type informations. The default localization base name for the properties
+ * is OSGI-INF/l10n/bundle, but can be overridden by the manifest
+ * Bundle-Localization header (see core specification, in section
+ * Localization on page 68). You can specify a specific localization
+ * basename file using this method (e.g.
+ * <code>setLocalization("person")</code> will match person_du_NL.properties
+ * in the root bundle directory.
+ */
+ ConfigurationDependency setLocalization(String path);
+
+ /**
+ * Adds a MetaData regarding a given configuration property.
+ */
+ ConfigurationDependency add(PropertyMetaData properties);
+
+ /**
+ * Sets this dependency to be instance bound or not.
+ *
+ * @param isInstanceBound <code>true</code> if this dependency should be instance bound
+ */
+ ConfigurationDependency setInstanceBound(boolean isInstanceBound);
}
diff --git a/dependencymanager/core/src/main/java/org/apache/felix/dm/Dependency.java b/dependencymanager/core/src/main/java/org/apache/felix/dm/Dependency.java
index 804b4c1..332348c 100644
--- a/dependencymanager/core/src/main/java/org/apache/felix/dm/Dependency.java
+++ b/dependencymanager/core/src/main/java/org/apache/felix/dm/Dependency.java
@@ -105,7 +105,23 @@
*/
public void invokeRemoved(DependencyService service);
+ /**
+ * Determines if the properties associated with this dependency should be propagated to
+ * the properties of the service registered by the component they belong to.
+ *
+ * @see Dependency#getProperties()
+ *
+ * @return <code>true</code> if the properties should be propagated
+ */
public boolean isPropagated();
+
+ /**
+ * Returns the properties associated with this dependency.
+ *
+ * @see Dependency#isPropagated()
+ *
+ * @return the properties
+ */
public Dictionary getProperties();
/**
diff --git a/dependencymanager/core/src/main/java/org/apache/felix/dm/DependencyActivation.java b/dependencymanager/core/src/main/java/org/apache/felix/dm/DependencyActivation.java
index f0649ff..3138c95 100644
--- a/dependencymanager/core/src/main/java/org/apache/felix/dm/DependencyActivation.java
+++ b/dependencymanager/core/src/main/java/org/apache/felix/dm/DependencyActivation.java
@@ -19,9 +19,24 @@
package org.apache.felix.dm;
/**
+ * Dependency activation interface that must be implemented by any
+ * new dependency and is used by the dependency manager to start and
+ * stop the dependency after it has been associated with a component.
+ *
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
public interface DependencyActivation {
- public void start(DependencyService service);
- public void stop(DependencyService service);
+ /**
+ * Invoked when the dependency should start.
+ *
+ * @param service the component this dependency belongs to
+ */
+ public void start(DependencyService service);
+
+ /**
+ * Invoked when the dependency should stop.
+ *
+ * @param service the component this dependency belongs to
+ */
+ public void stop(DependencyService service);
}
diff --git a/dependencymanager/core/src/main/java/org/apache/felix/dm/DependencyActivatorBase.java b/dependencymanager/core/src/main/java/org/apache/felix/dm/DependencyActivatorBase.java
index e0b5d3e..fdb9d3a 100644
--- a/dependencymanager/core/src/main/java/org/apache/felix/dm/DependencyActivatorBase.java
+++ b/dependencymanager/core/src/main/java/org/apache/felix/dm/DependencyActivatorBase.java
@@ -313,5 +313,4 @@
public Component createFactoryConfigurationAdapterService(String factoryPid, String update, boolean propagate, String heading, String desc, String localization, PropertyMetaData[] propertiesMetaData) {
return m_manager.createFactoryConfigurationAdapterService(factoryPid, update, propagate, heading, desc, localization, propertiesMetaData);
}
-
}
diff --git a/dependencymanager/core/src/main/java/org/apache/felix/dm/DependencyManager.java b/dependencymanager/core/src/main/java/org/apache/felix/dm/DependencyManager.java
index 60b5781..7a148fe 100644
--- a/dependencymanager/core/src/main/java/org/apache/felix/dm/DependencyManager.java
+++ b/dependencymanager/core/src/main/java/org/apache/felix/dm/DependencyManager.java
@@ -105,7 +105,8 @@
for (int i = 0; i < props.length; i++) {
if (props[i].equals("*aspect*")) {
m_serviceRegistryCache.addFilterIndex(new AspectFilterIndex());
- } else if (props[i].equals("*adapter*")) {
+ }
+ else if (props[i].equals("*adapter*")) {
m_serviceRegistryCache.addFilterIndex(new AdapterFilterIndex());
}
else {
@@ -431,6 +432,7 @@
return new AdapterServiceImpl(this, serviceInterface, serviceFilter, null, add, change, remove, swap);
}
+ /** @see DependencyManager#createAdapterService(Class, String, String, String, String, String) */
public Component createAdapterService(Class serviceInterface, String serviceFilter, String add, String change, String remove) {
return new AdapterServiceImpl(this, serviceInterface, serviceFilter, null, add, change, remove);
}
@@ -457,8 +459,8 @@
* @param resourceFilter the filter condition to use with the resource
* @param resourcePropertiesFilter the filter condition on the resource properties to use with the resource
* @param propagate <code>true</code> if properties from the resource should be propagated to the service
- * @param callbackInstance
- * @param callbackChanged
+ * @param callbackInstance instance to invoke the callback on
+ * @param callbackChanged the name of the callback method
* @return a service that acts as a factory for generating resource adapters
* @see Resource
*/
@@ -466,14 +468,17 @@
return new ResourceAdapterServiceImpl(this, resourceFilter, propagate, callbackInstance, null, callbackChanged);
}
+ /** @see DependencyManager#createResourceAdapterService(String, boolean, Object, String) */
public Component createResourceAdapterService(String resourceFilter, boolean propagate, Object callbackInstance, String callbackSet, String callbackChanged) {
return new ResourceAdapterServiceImpl(this, resourceFilter, propagate, callbackInstance, callbackSet, callbackChanged);
}
+ /** @see DependencyManager#createResourceAdapterService(String, boolean, Object, String) */
public Component createResourceAdapterService(String resourceFilter, Object propagateCallbackInstance, String propagateCallbackMethod, Object callbackInstance, String callbackChanged) {
return new ResourceAdapterServiceImpl(this, resourceFilter, propagateCallbackInstance, propagateCallbackMethod, callbackInstance, null, callbackChanged);
}
+ /** @see DependencyManager#createResourceAdapterService(String, boolean, Object, String) */
public Component createResourceAdapterService(String resourceFilter, Object propagateCallbackInstance, String propagateCallbackMethod, Object callbackInstance, String callbackSet, String callbackChanged) {
return new ResourceAdapterServiceImpl(this, resourceFilter, propagateCallbackInstance, propagateCallbackMethod, callbackInstance, callbackSet, callbackChanged);
}
@@ -582,12 +587,8 @@
* @param propertiesMetaData Array of MetaData regarding configuration properties
* @return a service that acts as a factory for generating the managed service factory configuration adapter
*/
- public Component createFactoryConfigurationAdapterService(String factoryPid, String update, boolean propagate,
- String heading, String desc, String localization,
- PropertyMetaData[] propertiesMetaData)
- {
- return new FactoryConfigurationAdapterServiceImpl(this, factoryPid, update, propagate, m_context, m_logger,
- heading, desc, localization, propertiesMetaData);
+ public Component createFactoryConfigurationAdapterService(String factoryPid, String update, boolean propagate, String heading, String desc, String localization, PropertyMetaData[] propertiesMetaData) {
+ return new FactoryConfigurationAdapterServiceImpl(this, factoryPid, update, propagate, m_context, m_logger, heading, desc, localization, propertiesMetaData);
}
/**
diff --git a/dependencymanager/core/src/main/java/org/apache/felix/dm/DependencyService.java b/dependencymanager/core/src/main/java/org/apache/felix/dm/DependencyService.java
index 100b9a9..182993d 100644
--- a/dependencymanager/core/src/main/java/org/apache/felix/dm/DependencyService.java
+++ b/dependencymanager/core/src/main/java/org/apache/felix/dm/DependencyService.java
@@ -18,7 +18,11 @@
*/
package org.apache.felix.dm;
+import org.osgi.framework.BundleContext;
+
/**
+ * Interface to the component, so dependencies can interact with it.
+ *
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
public interface DependencyService {
@@ -42,18 +46,51 @@
* @param dependency the dependency
*/
public void dependencyChanged(Dependency dependency);
-
+
+ /**
+ * Returns the component instance.
+ *
+ * @return component instance
+ */
public Object getService(); // is also defined on the Service interface
+
+ /**
+ * Initializes the component. Instantiates it and injects the default injectables such
+ * as {@link BundleContext} and {@link DependencyManager}.
+ */
public void initService(); // was an implementation method TODO we use it in ConfDepImpl but should not (probably)
+
+ /**
+ * Returns <code>true</code> if this component is registered. In other words, all
+ * its required dependencies are available.
+ *
+ * @return <code>true</code> if the component is registered
+ */
public boolean isRegistered(); // impl method
+
+ /**
+ * Returns a list of all instances that are part of the composition for this component.
+ *
+ * @return an array of instances
+ */
public Object[] getCompositionInstances(); // impl method
+ /**
+ * Returns <code>true</code> if this component is instantiated.
+ *
+ * @return <code>true</code> if this component is instantiated
+ */
public boolean isInstantiated();
/**
* Can be called by the dependency whenever it wants to invoke callback methods.
*/
public void invokeCallbackMethod(Object[] instances, String methodName, Class[][] signatures, Object[][] parameters);
-
+
+ /**
+ * Returns the component interface.
+ *
+ * @return the component interface
+ */
public Component getServiceInterface();
}
diff --git a/dependencymanager/core/src/main/java/org/apache/felix/dm/InvocationUtil.java b/dependencymanager/core/src/main/java/org/apache/felix/dm/InvocationUtil.java
index 9435c7f..46ddf60 100644
--- a/dependencymanager/core/src/main/java/org/apache/felix/dm/InvocationUtil.java
+++ b/dependencymanager/core/src/main/java/org/apache/felix/dm/InvocationUtil.java
@@ -27,6 +27,8 @@
import java.util.Map;
/**
+ * Utility methods for invoking callbacks. Lookups of callbacks are accellerated by using a LRU cache.
+ *
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
public class InvocationUtil {
@@ -43,6 +45,20 @@
m_methodCache = new LRUMap(Math.max(size, 64));
}
+ /**
+ * Invokes a callback method on an instance. The code will search for a callback method with
+ * the supplied name and any of the supplied signatures in order, invoking the first one it finds.
+ *
+ * @param instance the instance to invoke the method on
+ * @param methodName the name of the method
+ * @param signatures the ordered list of signatures to look for
+ * @param parameters the parameter values to use for each potential signature
+ * @return whatever the method returns
+ * @throws NoSuchMethodException when no method could be found
+ * @throws IllegalArgumentException when illegal values for this methods arguments are supplied
+ * @throws IllegalAccessException when the method cannot be accessed
+ * @throws InvocationTargetException when the method that was invoked throws an exception
+ */
public static Object invokeCallbackMethod(Object instance, String methodName, Class[][] signatures, Object[][] parameters) throws NoSuchMethodException, IllegalArgumentException, IllegalAccessException, InvocationTargetException {
Class currentClazz = instance.getClass();
while (currentClazz != null && currentClazz != Object.class) {
@@ -57,6 +73,21 @@
throw new NoSuchMethodException(methodName);
}
+ /**
+ * Invoke a method on an instance.
+ *
+ * @param object the instance to invoke the method on
+ * @param clazz the class of the instance
+ * @param name the name of the method
+ * @param signatures the signatures to look for in order
+ * @param parameters the parameter values for the signatures
+ * @param isSuper <code>true</code> if this is a superclass and we should therefore not look for private methods
+ * @return whatever the method returns
+ * @throws NoSuchMethodException when no method could be found
+ * @throws IllegalArgumentException when illegal values for this methods arguments are supplied
+ * @throws IllegalAccessException when the method cannot be accessed
+ * @throws InvocationTargetException when the method that was invoked throws an exception
+ */
public static Object invokeMethod(Object object, Class clazz, String name, Class[][] signatures, Object[][] parameters, boolean isSuper) throws NoSuchMethodException, InvocationTargetException, IllegalArgumentException, IllegalAccessException {
if (object == null) {
throw new IllegalArgumentException("Instance cannot be null");
diff --git a/dependencymanager/core/src/main/java/org/apache/felix/dm/PropertyMetaData.java b/dependencymanager/core/src/main/java/org/apache/felix/dm/PropertyMetaData.java
index 5dbc675..902f293 100644
--- a/dependencymanager/core/src/main/java/org/apache/felix/dm/PropertyMetaData.java
+++ b/dependencymanager/core/src/main/java/org/apache/felix/dm/PropertyMetaData.java
@@ -19,12 +19,14 @@
public interface PropertyMetaData {
/**
* The label used to display the property. Example: "Log Level".
+ *
* @return The label used to display the property (may be localized)
*/
public PropertyMetaData setHeading(String heading);
/**
* The key of a ConfigurationAdmin property. Example: "printer.logLevel"
+ *
* @return The Configuration Admin property name
*/
public PropertyMetaData setId(String id);
@@ -56,6 +58,7 @@
/**
* Returns the property description. The description may be localized and must describe the semantics of this type and any
* constraints. Example: "Select the log level for the Printer Service".
+ *
* @return a localizable description of the property.
*/
public PropertyMetaData setDescription(String description);
@@ -81,6 +84,7 @@
/**
* Return a list of valid options for this property (the labels may be localized).
+ *
* @return the list of valid options for this property.
*/
public PropertyMetaData addOption(String optionLabel, String optionValue);
diff --git a/dependencymanager/core/src/main/java/org/apache/felix/dm/ResourceDependency.java b/dependencymanager/core/src/main/java/org/apache/felix/dm/ResourceDependency.java
index d5ab781..b837262 100644
--- a/dependencymanager/core/src/main/java/org/apache/felix/dm/ResourceDependency.java
+++ b/dependencymanager/core/src/main/java/org/apache/felix/dm/ResourceDependency.java
@@ -21,6 +21,11 @@
import java.net.URL;
/**
+ * A resource dependency is a dependency on a resource. A resource in this context is an object that is
+ * identified by a URL. Resources should somehow be provided by an external component, the resource
+ * provider. These dependencies then react on them becoming available or not. Use cases for such dependencies
+ * are resources that are embedded in bundles, in a workspace or some remote or local repository, etc.
+ *
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
public interface ResourceDependency extends Dependency, ComponentDependencyDeclaration, ResourceHandler {
@@ -34,7 +39,7 @@
* @param removed the method to call when a service was removed
* @return this service dependency
*/
- public ResourceDependency setCallbacks(String added, String removed) ;
+ public ResourceDependency setCallbacks(String added, String removed);
/**
* Sets the callbacks for this service. These callbacks can be used as hooks whenever a
@@ -95,16 +100,47 @@
* @return this service dependency
*/
public ResourceDependency setAutoConfig(String instanceName);
-
+
+ /**
+ * Sets the resource for this dependency.
+ *
+ * @param resource the URL of the resource
+ */
public ResourceDependency setResource(URL resource);
-
+
+ /**
+ * Determines if this is a required dependency or not.
+ *
+ * @param required <code>true</code> if the dependency is required
+ */
public ResourceDependency setRequired(boolean required);
+ /**
+ * Sets the filter condition for this resource dependency.
+ *
+ * @param resourceFilter the filter condition
+ */
public ResourceDependency setFilter(String resourceFilter);
-
+
+ /** @see ResourceDependency#setPropagate(Object, String) */
public ResourceDependency setPropagate(boolean propagate);
-
+
+ /**
+ * Sets an Object instance and a callback method used to propagate some properties to the provided service properties.
+ * The method will be invoked on the specified object instance and must have one of the following signatures:<p>
+ * <ul><li>Dictionary callback(ServiceReference, Object service)
+ * <li>Dictionary callback(ServiceReference)
+ * </ul>
+ * @param instance the Object instance which is used to retrieve propagated service properties
+ * @param method the method to invoke for retrieving the properties to be propagated to the service properties.
+ * @return this service dependency.
+ */
public ResourceDependency setPropagate(Object instance, String method);
-
+
+ /**
+ * Sets this dependency to be instance bound or not.
+ *
+ * @param isInstanceBound <code>true</code> if this dependency should be instance bound
+ */
public ResourceDependency setInstanceBound(boolean isInstanceBound);
}
diff --git a/dependencymanager/core/src/main/java/org/apache/felix/dm/ResourceUtil.java b/dependencymanager/core/src/main/java/org/apache/felix/dm/ResourceUtil.java
index 564ec52..88d9c88 100644
--- a/dependencymanager/core/src/main/java/org/apache/felix/dm/ResourceUtil.java
+++ b/dependencymanager/core/src/main/java/org/apache/felix/dm/ResourceUtil.java
@@ -23,9 +23,17 @@
import java.util.Properties;
/**
+ * Utility class for resource handling.
+ *
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
public class ResourceUtil {
+ /**
+ * Creates a set of properties for a resource based on its URL.
+ *
+ * @param url the URL
+ * @return a set of properties
+ */
public static Dictionary createProperties(URL url) {
Properties props = new Properties();
props.setProperty(ResourceHandler.PROTOCOL, url.getProtocol());
diff --git a/dependencymanager/core/src/main/java/org/apache/felix/dm/ServiceDependency.java b/dependencymanager/core/src/main/java/org/apache/felix/dm/ServiceDependency.java
index be9f8d5..aa9400a 100644
--- a/dependencymanager/core/src/main/java/org/apache/felix/dm/ServiceDependency.java
+++ b/dependencymanager/core/src/main/java/org/apache/felix/dm/ServiceDependency.java
@@ -208,5 +208,10 @@
*/
public ServiceDependency setPropagate(Object instance, String method);
+ /**
+ * Sets this dependency to be instance bound or not.
+ *
+ * @param isInstanceBound <code>true</code> if this dependency should be instance bound
+ */
public ServiceDependency setInstanceBound(boolean isInstanceBound);
}