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);    
 }