felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From clem...@apache.org
Subject svn commit: r701012 [3/4] - in /felix/trunk/ipojo: core/src/main/java/org/apache/felix/ipojo/ core/src/main/java/org/apache/felix/ipojo/architecture/ core/src/main/java/org/apache/felix/ipojo/parser/ core/src/main/java/org/apache/felix/ipojo/util/ meta...
Date Thu, 02 Oct 2008 06:30:34 GMT
Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ManifestMetadataParser.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ManifestMetadataParser.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ManifestMetadataParser.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ManifestMetadataParser.java Wed Oct  1 23:30:33 2008
@@ -29,21 +29,24 @@
 import org.apache.felix.ipojo.metadata.Element;
 
 /**
- * Manifest Metadata parser. Read a manifest file and construct metadata
+ * The Manifest Metadata parser reads a manifest file and builds
+ * the iPOJO metadata ({@link Element} / {@link Attribute} ) structure.
  * 
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class ManifestMetadataParser {
 
     /**
-     * Element list.
+     * The element list.
+     * Contains the element found in the parsed header.
      */
     private Element[] m_elements = new Element[0];
 
     /**
-     * Get the array of component type metadata.
+     * Gets the array of component type metadata.
      * @return the component metadata (composite & component).
-     * @throws ParseException when a parsing error occurs
+     * An empty array is returned if no component type declaration.
+     * @throws ParseException if a parsing error occurs
      */
     public Element[] getComponentsMetadata() throws ParseException {
         Element[] elems = m_elements[0].getElements();
@@ -57,9 +60,9 @@
     }
 
     /**
-     * Get the array of instance configuration described in the metadata.
-     * @return the instances list.
-     * @throws ParseException : if the metadata cannot be parsed successfully
+     * Gets the array of instance configuration described in the metadata.
+     * @return the instances list or <code>null</code> if no instance configuration.
+     * @throws ParseException if the metadata cannot be parsed successfully
      */
     public Dictionary[] getInstances() throws ParseException {
         Element[] configs = m_elements[0].getElements("instance");
@@ -74,11 +77,12 @@
     }
 
     /**
-     * Parse an Element to get a dictionary.
-     * 
-     * @param instance : the Element describing an instance.
-     * @return : the resulting dictionary
-     * @throws ParseException : occurs when a configuration cannot be parse correctly.
+     * Parses an Element to create an instance configuration dictionary.
+     * The 'name' attribute of the instance declaration is mapped
+     * to the 'instance.name' property. 
+     * @param instance the Element describing an instance.
+     * @return the resulting dictionary
+     * @throws ParseException if a configuration cannot be parse correctly.
      */
     private Dictionary parseInstance(Element instance) throws ParseException {
         Dictionary dict = new Properties();
@@ -103,10 +107,11 @@
     }
 
     /**
-     * Parse a property.
-     * @param prop : the current element to parse
-     * @param dict : the dictionary to populate
-     * @throws ParseException : occurs if the property cannot be parsed correctly
+     * Parses an instance property.
+     * This method is recursive to handle complex properties.
+     * @param prop the current element to parse
+     * @param dict the dictionary to populate (the future instance configuration)
+     * @throws ParseException if the property cannot be parsed correctly
      */
     private void parseProperty(Element prop, Dictionary dict) throws ParseException {
         // Check that the property has a name
@@ -148,10 +153,11 @@
     }
     
     /**
-     * Parses a complex property. This property will be build as a Dictionary.
-     * @param prop Element to parse.
+     * Parses a complex property. 
+     * This property will be built as a {@link Dictionary}.
+     * @param prop the Element to parse.
      * @return the resulting dictionary
-     * @throws ParseException occurs when an internal property is incorrect. 
+     * @throws ParseException if an internal property is incorrect. 
      */
     private Dictionary parseDictionary(Element prop) throws ParseException {
      // Check if there is 'property' elements
@@ -169,11 +175,12 @@
     }
     
     /**
-     * Parses a complex property. This property will be built as a Map.
-     * The used Map implementation is HashMap.
+     * Parses a complex property. 
+     * This property will be built as a {@link Map}.
+     * The used {@link Map} implementation is {@link HashMap}.
      * @param prop the property to parse
      * @return the resulting Map
-     * @throws ParseException occurs when an internal property is incorrect.
+     * @throws ParseException if an internal property is incorrect.
      */
     private Map parseMap(Element prop) throws ParseException {
         // Check if there is 'property' elements
@@ -190,11 +197,12 @@
     }
     
     /**
-     * Parses a complex property. This property will be built as a List.
-     * The used Map implementation is ArrayList. The order or element is kept.
+     * Parses a complex property. This property will be built as a {@link List}.
+     * The used {@link List} implementation is {@link ArrayList}. 
+     * The order of elements is kept.
      * @param prop the property to parse
      * @return the resulting List
-     * @throws ParseException occurs when an internal property is incorrect.
+     * @throws ParseException if an internal property is incorrect.
      */
     private List parseList(Element prop) throws ParseException {
         Element[] subProps = prop.getElements("property");
@@ -212,9 +220,10 @@
     
     /**
      * Parse a property.
-     * @param prop : the current element to parse
-     * @param map : the map to populate
-     * @throws ParseException : occurs if the property cannot be parsed correctly
+     * This methods handles complex properties.
+     * @param prop the current element to parse
+     * @param map the map to populate
+     * @throws ParseException if the property cannot be parsed correctly
      */
     private void parseProperty(Element prop, Map map) throws ParseException {
         // Check that the property has a name
@@ -255,12 +264,13 @@
     }
 
     /**
-     * Parse an anonymous property. An anonymous property is a property with no name.
+     * Parse an anonymous property.
+     * An anonymous property is a property with no name.
      * An anonymous property can be simple (just a value) or complex (i.e. a map, a dictionary 
      * a list or an array).
      * @param prop the property to parse
      * @param list the list to populate with the resulting property
-     * @throws ParseException occurs when an internal property cannot be parse correctly
+     * @throws ParseException if an internal property cannot be parse correctly
      */
     private void parseAnonymousProperty(Element prop, List list) throws ParseException {
         // Check that the property has a name
@@ -336,9 +346,8 @@
     }
 
     /**
-     * Add an element to the list.
-     * 
-     * @param elem : the element to add
+     * Adds an element to the {@link ManifestMetadataParser#m_elements} list.
+     * @param elem the the element to add
      */
     private void addElement(Element elem) {
         if (m_elements == null) {
@@ -352,8 +361,7 @@
     }
 
     /**
-     * Remove an element to the list.
-     * 
+     * Removes an element from the {@link ManifestMetadataParser#m_elements} list.
      * @return an element to remove
      */
     private Element removeLastElement() {
@@ -375,10 +383,13 @@
     }
 
     /**
-     * Parse the given dictionary and create the instance managers.
-     * 
-     * @param dict : the given headers of the manifest file
-     * @throws ParseException : if any error occurs
+     * Looks for the <code>iPOJO-Components</code> header
+     * in the given dictionary. Then, initializes the 
+     * {@link ManifestMetadataParser#m_elements} list (adds the
+     * <code>iPOJO</code> root element) and parses the contained
+     * component type declarations and instance configurations.
+     * @param dict the given headers of the manifest file
+     * @throws ParseException if any error occurs
      */
     public void parse(Dictionary dict) throws ParseException {
         String componentClassesStr = (String) dict.get("iPOJO-Components");
@@ -388,10 +399,12 @@
     }
 
     /**
-     * Parse the given header and create the instance managers.
-     * 
-     * @param header : the given header of the manifest file
-     * @throws ParseException : if any error occurs
+     * Parses the given header, initialized the 
+     * {@link ManifestMetadataParser#m_elements} list 
+     * (adds the <code>iPOJO</code> element) and parses 
+     * contained component type declarations and instance configurations.
+     * @param header the given header of the manifest file
+     * @throws ParseException if any error occurs
      */
     public void parseHeader(String header) throws ParseException {
         // Add the ipojo element inside the element list
@@ -400,11 +413,13 @@
     }
 
     /**
-     * Parse the metadata from the string given in argument.
-     * 
-     * @param metadata : the metadata to parse
-     * @return Element : the root element resulting of the parsing
-     * @throws ParseException : if any error occurs
+     * Parses the metadata from the string given in argument.
+     * This methods creates a new {@link ManifestMetadataParser} object
+     * and calls the {@link ManifestMetadataParser#parseElements(String)}
+     * method. The parsing must result as a tree (only one root element).
+     * @param metadata the metadata to parse
+     * @return Element the root element resulting of the parsing
+     * @throws ParseException if any error occurs
      */
     public static Element parse(String metadata) throws ParseException {
         ManifestMetadataParser parser = new ManifestMetadataParser();
@@ -416,10 +431,15 @@
     }
     
     /**
-     * Parse the metadata from the given header string.
-     * @param header : the header to parse
-     * @return Element : the root element resulting of the parsing
-     * @throws ParseException : if any error occurs
+     * Parses the metadata from the given header string.
+     * This method creates a new {@link ManifestMetadataParser} object and then
+     * creates the <code>iPOJO</code> root element, parses content elements
+     * (component types and instances declarations), and returns the resulting 
+     * {@link Element} / {@link Attribute} structure. The parsed string
+     * must be a tree (only one root element).
+     * @param header the header to parse
+     * @return Element the root element resulting of the parsing
+     * @throws ParseException if any error occurs
      */
     public static Element parseHeaderMetadata(String header) throws ParseException {
         ManifestMetadataParser parser = new ManifestMetadataParser();
@@ -432,9 +452,10 @@
     }
 
     /**
-     * Parse the given string.
-     * 
-     * @param elems : the string to parse
+     * Parses the given string.
+     * This methods populates the {@link ManifestMetadataParser#m_elements}
+     * list.
+     * @param elems the string to parse
      */
     private void parseElements(String elems) {
         char[] string = elems.toCharArray();

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/MethodMetadata.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/MethodMetadata.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/MethodMetadata.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/MethodMetadata.java Wed Oct  1 23:30:33 2008
@@ -23,31 +23,30 @@
 import org.apache.felix.ipojo.metadata.Element;
 
 /**
- * A Method Metadata represent a method from the implementation class.
- * This class allow to get information about a method : name, arguments, return type...
- * 
+ * A Method Metadata represents a method from the implementation class.
+ * This class allows getting information about a method : name, arguments, return type...
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class MethodMetadata {
 
     /**
-     * Name of the method.
+     * The name of the method.
      */
     private String m_name;
 
     /**
-     * Argument type array. 
+     * The argument type array. 
      */
     private String[] m_arguments = new String[0];
 
     /**
-     * Returned type. 
+     * The returned type. 
      */
     private String m_return = "void";
 
     /**
-     * Constructor.
-     * @param metadata : method manipulation element.
+     * Creates a Method Metadata.
+     * @param metadata the method manipulation element.
      */
     MethodMetadata(Element metadata) {
         m_name = metadata.getAttribute("name");
@@ -74,7 +73,9 @@
     }
 
     /**
-     * Get the method unique identifier. For internal usage only.
+     * Gets the method unique identifier. For internal usage only.
+     * A method identifier is a unique string that can be a java field
+     * that identify the method.
      * @return the method identifier.
      */
     public String getMethodIdentifier() {
@@ -94,8 +95,8 @@
     }
 
     /**
-     * Compute the method id for the given method. 
-     * @param method : Method object.
+     * Computes the method id for the given Method object. 
+     * @param method the Method object.
      * @return the method id.
      */
     public static String computeMethodId(Method method) {

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ParseException.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ParseException.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ParseException.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ParseException.java Wed Oct  1 23:30:33 2008
@@ -19,7 +19,7 @@
 package org.apache.felix.ipojo.parser;
 
 /**
- * Exceptions thrown by parsers.
+ * Exception thrown by parsers.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class ParseException extends Exception {

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ParseUtils.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ParseUtils.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ParseUtils.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ParseUtils.java Wed Oct  1 23:30:33 2008
@@ -23,16 +23,16 @@
 import java.util.StringTokenizer;
 
 /**
- * Parse Utility Methods.
- * 
+ * Parser Utility Methods.
+ * This class contains helper method to parse iPOJO metadata.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public final class ParseUtils {
 
     /**
-     * Parse the string form of an array as {a, b, c}.
-     * 
-     * @param str : the string form
+     * Parses the iPOJO string form of an array as {a, b, c}
+     * or [a, b, c].
+     * @param str the string form
      * @return the resulting string array
      */
     public static String[] parseArrays(String str) {
@@ -55,10 +55,10 @@
     }
     
     /**
-     * Parse the string form of an array as {a, b, c}.
-     * 
-     * @param str : the string form
-     * @return the resulting string array
+     * Parses the string form of an array as {a, b, c}
+     * or [a, b, c] as a list.
+     * @param str the string form
+     * @return the resulting list
      */
     public static List parseArraysAsList(String str) {
         return Arrays.asList(parseArrays(str));
@@ -68,9 +68,9 @@
      * Split method. 
      * This method is equivalent of the String.split in java 1.4
      * The result array contains 'trimmed' String
-     * @param toSplit : String to split
-     * @param separator : separator
-     * @return the token array 
+     * @param toSplit the String to split
+     * @param separator the separator
+     * @return the split array 
      */
     public static String[] split(String toSplit, String separator) {
         StringTokenizer tokenizer = new StringTokenizer(toSplit, separator);

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/PojoMetadata.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/PojoMetadata.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/PojoMetadata.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/PojoMetadata.java Wed Oct  1 23:30:33 2008
@@ -23,39 +23,41 @@
 
 /**
  * Manipulation Metadata allows getting information about the implementation class
- * without doing reflection. 
- * 
+ * without using reflection such as implemented interfaces, super class,
+ * methods and fields. 
+ * This method allows getting object to register {@link org.apache.felix.ipojo.FieldInterceptor} and
+ * {@link org.apache.felix.ipojo.MethodInterceptor}.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class PojoMetadata {
     
     /**
-     * List of implemented interfaces.
+     * The list of implemented interfaces.
      */
     private String[] m_interfaces = new String[0];
     
     /**
-     * List of fields.
+     * The list of fields.
      */
     private FieldMetadata[] m_fields = new FieldMetadata[0];
     
     /**
-     * List of methods. 
+     * The list of methods. 
      */
     private MethodMetadata[] m_methods = new MethodMetadata[0];
 
     /**
-     * Super class (if not java.lang.object).
+     * The Super class (if <code>null</code> for {@link Object}).
      */
     private String m_super;
     
     
     /**
-     * Constructor.
+     * Creates Pojo metadata.
      * Manipulation Metadata object are created from component type metadata by
      * parsing manipulation metadata.
-     * @param metadata : component type metadata
-     * @throws ConfigurationException : the manipulation metadata cannot be found
+     * @param metadata the component type metadata
+     * @throws ConfigurationException if the manipulation metadata cannot be found
      */
     public PojoMetadata(Element metadata) throws ConfigurationException {
         Element[] elems = metadata.getElements("manipulation", "");
@@ -87,9 +89,9 @@
     public String[] getInterfaces() { return m_interfaces; }
     
     /**
-     * Get the field metadata for the given name. 
-     * @param name : name of the field
-     * @return the corresponding field metadata or null if not found
+     * Gets the field metadata for the given name. 
+     * @param name : the name of the field
+     * @return the corresponding field metadata or <code>null</code> if not found
      */
     public FieldMetadata getField(String name) { 
         for (int i = 0; i < m_fields.length; i++) {
@@ -99,10 +101,10 @@
     }
     
     /**
-     * Get the field metadata for the given name and type. 
-     * @param name : name of the field
-     * @param type : type of the field
-     * @return the corresponding field metadata or null if not found
+     * Gets the field metadata for the given name and type. 
+     * @param name : the name of the field
+     * @param type : the type of the field
+     * @return the corresponding field metadata or <code>null</code> if not found
      */
     public FieldMetadata getField(String name, String type) { 
         for (int i = 0; i < m_fields.length; i++) {
@@ -112,9 +114,12 @@
     }
     
     /**
-     * Check if the given interface name is implemented.
-     * @param itf : interface to check.
-     * @return true if the implementation class implement the given interface.
+     * Checks if the given interface name is implemented.
+     * This methods checks on interface directly implemented
+     * by the implementation class.
+     * @param itf the interface to check.
+     * @return <code>true</code> if the implementation class implements
+     * the given interface.
      */
     public boolean isInterfaceImplemented(String itf) {
         for (int i = 0; i < m_interfaces.length; i++) {
@@ -124,11 +129,12 @@
     }
     
     /**
-     * Get the MethodMetadata corresponding to the method
-     * (contained in the implementation class) to given name.
-     * If several method match, the first one is returned.
-     * @param name : name of the method to look for.
-     * @return the Method Metadate or null if not found
+     * Gets the MethodMetadata corresponding to the method
+     * (contained in the implementation class) with
+     * the given name.
+     * If several methods match, the first one is returned.
+     * @param name the name of the method to find.
+     * @return the method metadata object or <code>null</code> if not found
      */
     public MethodMetadata getMethod(String name) {
         for (int i = 0; i < m_methods.length; i++) {
@@ -138,11 +144,11 @@
     }
     
     /**
-     * Get the MethodMetadata list corresponding to the method
+     * Gets the MethodMetadata list corresponding to the method
      * (contained in the implementation class) to given name.
      * All methods contained in the implementation class matching 
      * with the name are in the returned list.
-     * @param name : name of the method to look for.
+     * @param name the name of the method to look for.
      * @return the Method Metadata array or an empty array if not found
      */
     public MethodMetadata[] getMethods(String name) {
@@ -163,12 +169,12 @@
     }
     
     /**
-     * Get the MethodMetadata corresponding to the method
+     * Gets the MethodMetadata corresponding to the method
      * (contained in the implementation class) to given name 
      * and argument types.
-     * @param name : name of the method to look for.
-     * @param types : array of the argument types of the method 
-     * @return the Method Metadate or null if not found
+     * @param name the name of the method to look for.
+     * @param types the array of the argument types of the method 
+     * @return the Method Metadata or <code>null</code> if not found
      */
     public MethodMetadata getMethod(String name, String[] types) {
         for (int i = 0; i < m_methods.length; i++) {
@@ -186,8 +192,10 @@
     }
         
      /**
-      * Add a method to the list.
-     * @param method : Method Metadata to add.
+     * Adds a method to the list.
+     * This method is used during the creation of the {@link PojoMetadata}
+     * object.
+     * @param method the Method Metadata to add.
      */
     private void addMethod(MethodMetadata method) {
         for (int i = 0; (m_methods != null) && (i < m_methods.length); i++) {
@@ -207,8 +215,10 @@
     }
         
      /**
-      * Add a field to the list.
-     * @param field : the Field Metadata to add.
+     * Adds a field to the list.
+     * This method is used during the creation of the {@link PojoMetadata}
+     * object.
+     * @param field the Field Metadata to add.
      */
     private void addField(FieldMetadata field) {
         for (int i = 0; (m_fields != null) && (i < m_fields.length); i++) {
@@ -228,8 +238,10 @@
     }
         
     /**
-     * Add the interface to the list.
-     * @param itf : the interface name to add.
+     * Adds the interface to the list.
+     * This method is used during the creation of the {@link PojoMetadata}
+     * object.
+     * @param itf the interface name to add.
      */
     private void addInterface(String itf) {
         for (int i = 0; (m_interfaces != null) && (i < m_interfaces.length); i++) {

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Callback.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Callback.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Callback.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Callback.java Wed Oct  1 23:30:33 2008
@@ -26,42 +26,52 @@
 import org.apache.felix.ipojo.parser.MethodMetadata;
 
 /**
- * A callback allows calling a method on the component instances.
+ * A callback allows invoking a method on a POJO.
+ * This class supports both public, protected and private methods of the
+ * implementation class. This class also supports public method from super class.
+ * The {@link Method} object is computed once and this computation is delayed
+ * to the first invocation.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class Callback {
 
     /**
-     * Method object.
+     * The method object.
+     * Computed at the first call.
      */
     protected Method m_methodObj;
 
     /**
-     * Name of the method to call.
+     * The name of the method to call.
      */
     private String m_method;
 
     /**
      * Is the method a static method ?
+     * This implies calling the method on <code>null</code>
      */
     private boolean m_isStatic;
 
     /**
-     * Reference on the instance manager.
+     * The reference on the instance manager.
+     * Used to get POJO objects.
      */
     private InstanceManager m_manager;
 
     /**
-     * Argument classes.
+     * The argument classes.
+     * This array contains the list of argument class names.
      */
     private String[] m_args;
 
     /**
-     * Callback constructor.
-     * @param method : the name of the method to call
-     * @param args : argument type name
-     * @param isStatic : is the method a static method
-     * @param manager : the instance manager of the component containing the method
+     * Creates a Callback.
+     * If the argument array is not null the reflection type are computed.
+     * @see {@link Callback#computeArguments(String[])}
+     * @param method the name of the method to call
+     * @param args the argument type name, or <code>null</code> if no arguments
+     * @param isStatic is the method a static method
+     * @param manager the instance manager of the component containing the method
      */
     public Callback(String method, String[] args, boolean isStatic, InstanceManager manager) {
         m_method = method;
@@ -73,11 +83,11 @@
     }
 
     /**
-     * Callback constructor.
-     * @param method : the name of the method to call
-     * @param args : argument classes
-     * @param isStatic : is the method a static method
-     * @param manager : the instance manager of the component containing the method
+     * Creates a Callback.
+     * @param method the the name of the method to call
+     * @param args the argument classes
+     * @param isStatic the is the method a static method
+     * @param manager the the instance manager of the component containing the method
      */
     public Callback(String method, Class[] args, boolean isStatic, InstanceManager manager) {
         m_method = method;
@@ -90,9 +100,10 @@
     }
 
     /**
-     * Constructor.
-     * @param method : Method Metadata obtain form manipulation metadata.
-     * @param manager : instance manager.
+     * Creates a Callback.
+     * @param method the {@link MethodMetadata} obtained from manipulation
+     * metadata ({@link PojoMetadata}).
+     * @param manager the instance manager.
      */
     public Callback(MethodMetadata method, InstanceManager manager) {
         m_isStatic = false;
@@ -102,8 +113,10 @@
     }
 
     /**
-     * Compute arguments of the method.
-     * @param args : arguments of the method.
+     * Computes arguments of the method.
+     * This method computes "reflection type" from given argument.
+     * @see FieldMetadata#getReflectionType(String)
+     * @param args the arguments of the method.
      */
     private void computeArguments(String[] args) {
         m_args = new String[args.length];
@@ -113,9 +126,9 @@
     }
 
     /**
-     * Search the looked method in the given method arrays.
-     * @param methods : method array in which we need to look
-     * @return the method object or null if not found
+     * Searches the {@link Method} in the given method arrays.
+     * @param methods the method array in which the method should be found
+     * @return the method object or <code>null</code> if not found
      */
     private Method searchMethodInMethodArray(Method[] methods) {
         for (int i = 0; i < methods.length; i++) {
@@ -140,8 +153,10 @@
     }
 
     /**
-     * Search the method object in the POJO by analyzing present method. The name of the method and the argument type are checked.
-     * @throws NoSuchMethodException : occurs when the method cannot be found either in the pojo class either in parent classes.
+     * Searches the {@link Method} object in the POJO by analyzing implementation
+     * class methods. The name of the method and the argument type are checked.
+     * @throws NoSuchMethodException if the method cannot be found either in the
+     * implementation class or in parent classes.
      */
     protected void searchMethod() throws NoSuchMethodException {
         Method[] methods = m_manager.getClazz().getDeclaredMethods();
@@ -163,35 +178,43 @@
     }
 
     /**
-     * Call the method.
-     * @return the result of the invocation, null for void method, the last result for multi-object instance
-     * @throws NoSuchMethodException : Method is not found in the class
-     * @throws InvocationTargetException : The method is not static
-     * @throws IllegalAccessException : The method can not be invoked
+     * Invokes the method without arguments.
+     * If several the instance contains several objects, the method is invoked
+     * on every objects.
+     * @return the result of the invocation, <code>null</code> for <code>void</code>
+     * method, the last result for multi-object instance
+     * @throws NoSuchMethodException if Method is not found in the class
+     * @throws InvocationTargetException if the method throws an exception
+     * @throws IllegalAccessException if the method can not be invoked
      */
     public Object call() throws NoSuchMethodException, IllegalAccessException, InvocationTargetException {
         return call(new Object[0]);
     }
 
     /**
-     * Call the current callback method on the instance given in parameter.
-     * @param instance : instance on which call the callback
-     * @return the result of the invocation, null for void method
-     * @throws NoSuchMethodException : the method was not found
-     * @throws IllegalAccessException : the method cannot be called
-     * @throws InvocationTargetException : an error happens in the method
+     * Invokes the method without arguments.
+     * The method is invokes on the specified object.
+     * @param instance the instance on which call the callback
+     * @return the result of the invocation, <code>null</code> for
+     * <code>void</code> method
+     * @throws NoSuchMethodException if the method was not found
+     * @throws IllegalAccessException if the method cannot be called
+     * @throws InvocationTargetException if an error happens in the method
      */
     public Object call(Object instance) throws NoSuchMethodException, IllegalAccessException, InvocationTargetException {
         return call(instance, new Object[0]);
     }
 
     /**
-     * Call the callback on the method with the argument given in parameter.
-     * @param arg : the parameters
-     * @return the result of the invocation, null for void method, the last result for multi-object instance
-     * @throws NoSuchMethodException : the callback method is not found
-     * @throws IllegalAccessException : the callback method cannot be called
-     * @throws InvocationTargetException : an error occurs inside the called method
+     * Invokes the method on every created objects with the specified
+     * arguments.
+     * @param arg the method arguments
+     * @return the result of the invocation, <code>null</code> for 
+     * <code>void</code> method, the last result for instance containing
+     * several objects.
+     * @throws NoSuchMethodException if the callback method is not found
+     * @throws IllegalAccessException if the callback method cannot be called
+     * @throws InvocationTargetException if an error is thrown by the called method
      */
     public Object call(Object[] arg) throws NoSuchMethodException, IllegalAccessException, InvocationTargetException {
         if (m_methodObj == null) {
@@ -218,13 +241,15 @@
     }
 
     /**
-     * Call the callback on the method with the argument given in parameter and with the arguments given in parameter too.
-     * @param instance : instance on which call the callback
-     * @param arg : the argument array
-     * @return the result of the invocation, null for void method
-     * @throws NoSuchMethodException : the callback method is not found
-     * @throws IllegalAccessException : the callback method cannot be called
-     * @throws InvocationTargetException : an error occurs inside the called method
+     * Invokes the method on the given object with the specified
+     * arguments.
+     * @param instance the instance on which call the method
+     * @param arg the argument array
+     * @return the result of the invocation, <code>null</code> for 
+     * <code>void</code> method
+     * @throws NoSuchMethodException if the callback method is not found
+     * @throws IllegalAccessException if the callback method cannot be called
+     * @throws InvocationTargetException if an error is thrown by the called method
      */
     public Object call(Object instance, Object[] arg) throws NoSuchMethodException, IllegalAccessException, InvocationTargetException {
         if (m_methodObj == null) {
@@ -234,6 +259,10 @@
         return m_methodObj.invoke(instance, arg);
     }
 
+    /**
+     * Gets the method name.
+     * @return the method name
+     */
     public String getMethod() {
         return m_method;
     }

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/DependencyModel.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/DependencyModel.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/DependencyModel.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/DependencyModel.java Wed Oct  1 23:30:33 2008
@@ -24,6 +24,7 @@
 import java.util.List;
 
 import org.apache.felix.ipojo.ConfigurationException;
+import org.apache.felix.ipojo.ServiceContext;
 import org.apache.felix.ipojo.context.ServiceReferenceImpl;
 import org.apache.felix.ipojo.metadata.Element;
 import org.osgi.framework.BundleContext;
@@ -31,41 +32,53 @@
 import org.osgi.framework.ServiceReference;
 
 /**
- * Abstract dependency model. This class is the parent class of every service dependency. It manages the most part of dependency management. This
- * class creates an interface between the service tracker and the concrete dependency.
+ * Abstract dependency model.
+ * This class is the parent class of every service dependency. It manages the most 
+ * part of dependency management. This class creates an interface between the service
+ * tracker and the concrete dependency.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public abstract class DependencyModel implements TrackerCustomizer {
 
     /**
-     * Dependency state : BROKEN. A broken dependency cannot be fulfilled anymore. The dependency becomes broken when a used service disappears in the
-     * static binding policy.
+     * Dependency state : BROKEN.
+     * A broken dependency cannot be fulfilled anymore. The dependency becomes
+     * broken when a used service disappears in the static binding policy.
      */
     public static final int BROKEN = -1;
 
     /**
-     * Dependency state : UNRESOLVED. A dependency is unresolved if the dependency is not valid and no service providers are available.
+     * Dependency state : UNRESOLVED.
+     * A dependency is unresolved if the dependency is not valid and no service
+     * providers are available.
      */
     public static final int UNRESOLVED = 0;
 
     /**
-     * Dependency state : RESOLVED. A dependency is resolved if the dependency is optional or at least one provider is available.
+     * Dependency state : RESOLVED. 
+     * A dependency is resolved if the dependency is optional or at least one
+     * provider is available.
      */
     public static final int RESOLVED = 1;
 
     /**
-     * Binding policy : Dynamic. In this policy, services can appears and departs without special treatment.
+     * Binding policy : Dynamic. 
+     * In this policy, services can appears and departs without special treatment.
      */
     public static final int DYNAMIC_BINDING_POLICY = 0;
 
     /**
-     * Binding policy : Static. Once a service is used, if this service disappears the dependency becomes BROKEN. The instance needs to be recreated.
+     * Binding policy : Static. 
+     * Once a service is used, if this service disappears the dependency becomes
+     * {@link DependencyModel#BROKEN}. The instance needs to be recreated.
      */
     public static final int STATIC_BINDING_POLICY = 1;
 
     /**
-     * Binding policy : Dynamic-Priority. In this policy, services can appears and departs. However, once a service with a highest ranking (according
-     * to the used comparator) appears, this new service is re-injected.
+     * Binding policy : Dynamic-Priority. 
+     * In this policy, services can appears and departs. However, once a service
+     * with a highest ranking (according to the used comparator) appears, this 
+     * new service is re-injected.
      */
     public static final int DYNAMIC_PRIORITY_BINDING_POLICY = 2;
 
@@ -80,61 +93,71 @@
     private boolean m_optional;
 
     /**
-     * Required specification. Cannot change once set.
+     * The required specification.
+     * Cannot change once set.
      */
     private Class m_specification;
 
     /**
-     * Comparator to sort service references.
+     * The comparator to sort service references.
      */
     private Comparator m_comparator;
 
     /**
-     * LDAP filter object selecting service references form the set of providers providing the required specification.
+     * The LDAP filter object selecting service references 
+     * from the set of providers providing the required specification.
      */
     private Filter m_filter;
 
     /**
-     * Bundle context used by the dependency. (could be a service context).
+     * Bundle context used by the dependency.
+     * (may be a {@link ServiceContext}).
      */
     private BundleContext m_context;
 
     /**
-     * Listener object on which invoking the validate and invalidate methods.
+     * Listener object on which invoking the {@link DependencyStateListener#validate(DependencyModel)} 
+     * and {@link DependencyStateListener#invalidate(DependencyModel)} methods.
      */
     private final DependencyStateListener m_listener;
 
     /**
-     * Actual state of the dependency.
+     * The actual state of the dependency.
+     * {@link DependencyModel#UNRESOLVED} at the beginning.
      */
     private int m_state;
 
     /**
-     * Binding policy of the dependency.
+     * The Binding policy of the dependency.
      */
     private int m_policy = DYNAMIC_BINDING_POLICY;
 
     /**
-     * Service tracker used by this dependency.
+     * The tracker used by this dependency to track providers.
      */
     private Tracker m_tracker;
 
     /**
-     * List of matching service references. This list is a subset of tracked references. This set is compute according to the filter and the match
-     * method.
+     * The list of matching service references. This list is a 
+     * subset of tracked references. This set is computed according 
+     * to the filter and the {@link DependencyModel#match(ServiceReference)} method.
      */
     private final List m_matchingRefs = new ArrayList();
 
     /**
-     * Constructor.
-     * @param specification : required specification
-     * @param aggregate : is the dependency aggregate ?
-     * @param optional : is the dependency optional ?
-     * @param filter : LDAP filter
-     * @param comparator : comparator object to sort references
-     * @param policy : binding policy
-     * @param context : bundle context (or service context)
-     * @param listener : dependency lifecycle listener to notify from dependency state changes.
+     * Creates a DependencyModel.
+     * If the dependency has no comparator and follows the
+     * {@link DependencyModel#DYNAMIC_PRIORITY_BINDING_POLICY} policy
+     * the OSGi Service Reference Comparator is used. 
+     * @param specification the required specification
+     * @param aggregate is the dependency aggregate ?
+     * @param optional is the dependency optional ?
+     * @param filter the LDAP filter
+     * @param comparator the comparator object to sort references
+     * @param policy the binding policy
+     * @param context the bundle context (or service context)
+     * @param listener the dependency lifecycle listener to notify from dependency
+     * state changes.
      */
     public DependencyModel(Class specification, boolean aggregate, boolean optional, Filter filter, Comparator comparator, int policy,
             BundleContext context, DependencyStateListener listener) {
@@ -154,7 +177,9 @@
     }
 
     /**
-     * Open the tracking.
+     * Opens the tracking.
+     * This method computes the dependency state
+     * @see DependencyModel#computeDependencyState()
      */
     public void start() {
         m_tracker = new Tracker(m_context, m_specification.getName(), this);
@@ -163,7 +188,9 @@
     }
 
     /**
-     * Close the tracking.
+     * Closes the tracking.
+     * The dependency becomes {@link DependencyModel#UNRESOLVED}
+     * at the end of this method.
      */
     public void stop() {
         if (m_tracker != null) {
@@ -174,26 +201,33 @@
     }
 
     /**
-     * Is the reference set frozen (cannot change anymore) ? This method must be override by concrete dependency to support the static binding policy.
-     * This method is just used by default. The method must always return false for non-static dependency.
-     * @return true if the reference set is frozen.
+     * Is the reference set frozen (cannot change anymore)? 
+     * This method must be override by concrete dependency to support
+     * the static binding policy. In fact, this method allows optimizing
+     * the static dependencies to become frozen only when needed.
+     * This method returns <code>false</code> by default. 
+     * The method must always return <code>false</code> for non-static dependencies.
+     * @return <code>true</code> if the reference set is frozen.
      */
     public boolean isFrozen() {
         return false;
     }
 
     /**
-     * Does the service reference match ? This method must be override by concrete dependency if they need to advanced testing on service reference
-     * (that cannot be express in the LDAP filter). By default this method return true.
-     * @param ref : tested reference.
-     * @return true
+     * Does the service reference match ? This method must be override by
+     * concrete dependencies if they need advanced testing on service reference
+     * (that cannot be expressed in the LDAP filter). By default this method 
+     * returns <code>true</code>.
+     * @param ref the tested reference.
+     * @return <code>true</code> if the service reference matches.
      */
     public boolean match(ServiceReference ref) {
         return true;
     }
 
     /**
-     * Compute the actual dependency state.
+     * Computes the actual dependency state.
+     * This methods invokes the {@link DependencyStateListener}.
      */
     private void computeDependencyState() {
         if (m_state == BROKEN) { return; } // The dependency is broken ...
@@ -226,9 +260,10 @@
     }
 
     /**
-     * Service tracker adding service callback. We accept the service only if we aren't broken or frozen.
-     * @param ref : the new dependency.
-     * @return true if the reference must be tracked.
+     * Service tracker adding service callback. 
+     * It accepts the service only if the dependency isn't broken or frozen.
+     * @param ref the arriving service reference.
+     * @return <code>true</code> if the reference must be tracked.
      * @see org.apache.felix.ipojo.util.TrackerCustomizer#addingService(org.osgi.framework.ServiceReference)
      */
     public boolean addingService(ServiceReference ref) {
@@ -236,7 +271,9 @@
     }
 
     /**
-     * Service Tracker added service callback. If the service matches, manage the arrival.
+     * Service Tracker added service callback. 
+     * If the service matches (against the filter and the {@link DependencyModel#match(ServiceReference)},
+     * manages the provider arrival.
      * @param ref : new references.
      * @see org.apache.felix.ipojo.util.TrackerCustomizer#addedService(org.osgi.framework.ServiceReference)
      */
@@ -248,12 +285,12 @@
     }
     
     /**
-     * Check if the given service reference match the current filter.
+     * Checks if the given service reference match the current filter.
      * This method aims to avoid calling {@link Filter#match(ServiceReference)} 
-     * method when manipulating a composite reference. In fact, this method throws
+     * method when manipulating a composite reference. In fact, this method thrown
      * a {@link ClassCastException} on Equinox.
-     * @param ref : the service reference to check.
-     * @return true if the service reference matches.
+     * @param ref the service reference to check.
+     * @return <code>true</code> if the service reference matches.
      */
     private boolean matchAgainstFilter(ServiceReference ref) {
         boolean match = true;
@@ -269,9 +306,10 @@
     }
 
     /**
-     * Manage the arrival of a new service reference. The reference is valid and match the filter and the match method. This method has different
-     * behavior according to the binding policy.
-     * @param ref : the new reference
+     * Manages the arrival of a new service reference. 
+     * The reference is valid and matches the filter and the {@link DependencyModel#match(ServiceReference)}
+     * method. This method has different behavior according to the binding policy.
+     * @param ref the new reference
      */
     private void manageArrival(ServiceReference ref) {
 
@@ -314,9 +352,11 @@
     }
 
     /**
-     * Service tracker removed service callback. A service goes away. The depart need to be managed only if the reference was used.
-     * @param ref : leaving service reference
-     * @param arg1 : service object if the service was get
+     * Service tracker removed service callback. 
+     * A service provider goes away. The depart needs to be managed only if the 
+     * reference was used.
+     * @param ref the leaving service reference
+     * @param arg1 the service object if the service was already get
      * @see org.apache.felix.ipojo.util.TrackerCustomizer#removedService(org.osgi.framework.ServiceReference, java.lang.Object)
      */
     public void removedService(ServiceReference ref, Object arg1) {
@@ -326,9 +366,9 @@
     }
 
     /**
-     * Manage the departure of a used service.
-     * @param ref : leaving service reference
-     * @param obj : service object if the service was get
+     * Manages the departure of a used service.
+     * @param ref the leaving service reference
+     * @param obj the service object if the service was get
      */
     private void manageDeparture(ServiceReference ref, Object obj) {
         // If we already get this service and the binding policy is static, the dependency becomes broken
@@ -359,10 +399,13 @@
     }
 
     /**
-     * Service tracker modified service callback. This method must handle if the modified service should be considered as a depart or an arrival.
-     * According to the dependency filter, a service can now match or can no match anymore.
-     * @param ref : modified reference
-     * @param arg1 : service object if already get.
+     * Service tracker modified service callback. 
+     * This method must handle if the modified service should be considered as 
+     * a depart or an arrival.
+     * According to the dependency filter, a service can now match or can no match 
+     * anymore.
+     * @param ref the modified reference
+     * @param arg1 the service object if already get.
      * @see org.apache.felix.ipojo.util.TrackerCustomizer#modifiedService(org.osgi.framework.ServiceReference, java.lang.Object)
      */
     public void modifiedService(ServiceReference ref, Object arg1) {
@@ -384,8 +427,9 @@
     }
 
     /**
-     * Get the next matching service reference.
-     * @return null if no more provider is available, else return the first reference from the matching set.
+     * Gets the next matching service reference.
+     * @return <code>null</code> if no more provider is available, 
+     * else returns the first reference from the matching set.
      */
     public ServiceReference getServiceReference() {
         synchronized (this) {
@@ -398,8 +442,9 @@
     }
 
     /**
-     * Get matching service references.
-     * @return the sorted (if a comparator is used) array of matching service references, null if no references are available.
+     * Gets matching service references.
+     * @return the sorted (if a comparator is used) array of matching service 
+     * references, <code>null</code> if no references are available.
      */
     public ServiceReference[] getServiceReferences() {
         synchronized (this) {
@@ -409,7 +454,8 @@
     }
 
     /**
-     * Get the list of currently used service references.
+     * Gets the list of currently used service references.
+     * If no service references, returns <code>null</code>
      * @return the list of used reference (according to the service tracker).
      */
     public List getUsedServiceReferences() {
@@ -435,7 +481,7 @@
     }
 
     /**
-     * Get the number of actual matching references.
+     * Gets the number of actual matching references.
      * @return the number of matching references
      */
     public int getSize() {
@@ -443,21 +489,25 @@
     }
 
     /**
-     * Concrete dependency callback. This method is called when a new service need to be re-injected in the underlying concrete dependency.
-     * @param ref : service reference to inject.
+     * Concrete dependency callback. 
+     * This method is called when a new service needs to be 
+     * re-injected in the underlying concrete dependency.
+     * @param ref the service reference to inject.
      */
     public abstract void onServiceArrival(ServiceReference ref);
 
     /**
-     * Concrete dependency callback. This method is called when a used service (already injected) is leaving.
-     * @param ref : the leaving service reference.
+     * Concrete dependency callback. 
+     * This method is called when a used service (already injected) is leaving.
+     * @param ref the leaving service reference.
      */
     public abstract void onServiceDeparture(ServiceReference ref);
 
     /**
-     * This method can be override by the concrete dependency to be notified of service modification. This modification is not an arrival or a
-     * departure.
-     * @param ref : modified service reference.
+     * This method can be override by the concrete dependency to be notified
+     * of service modification.
+     * This modification is not an arrival or a departure.
+     * @param ref the modified service reference.
      */
     public void onServiceModification(ServiceReference ref) {
         if (m_policy == DYNAMIC_PRIORITY_BINDING_POLICY) {
@@ -474,37 +524,41 @@
     }
 
     /**
-     * Concrete dependency callback. This method is called when the dependency is reconfigured and when this reconfiguration implies changes on the
-     * matching service set ( and by the way on the injected service).
-     * @param departs : service leaving the matching set.
-     * @param arrivals : service arriving in the matching set.
+     * Concrete dependency callback. 
+     * This method is called when the dependency is reconfigured and when this
+     * reconfiguration implies changes on the matching service set ( and by the
+     * way on the injected service).
+     * @param departs the service leaving the matching set.
+     * @param arrivals the service arriving in the matching set.
      */
     public abstract void onDependencyReconfiguration(ServiceReference[] departs, ServiceReference[] arrivals);
 
     /**
-     * Call the listener callback to notify the new state of the current dependency.
+     * Calls the listener callback to notify the new state of the current 
+     * dependency.
      */
     private void invalidate() {
         m_listener.invalidate(this);
     }
 
     /**
-     * Call the listener callback to notify the new state of the current dependency.
+     * Calls the listener callback to notify the new state of the current 
+     * dependency.
      */
     private void validate() {
         m_listener.validate(this);
     }
 
     /**
-     * Get the actual state of the dependency.
-     * @return : the state of the dependency.
+     * Gets the actual state of the dependency.
+     * @return the state of the dependency.
      */
     public int getState() {
         return m_state;
     }
 
     /**
-     * Get the tracked specification.
+     * Gets the tracked specification.
      * @return the Class object tracked by the dependency.
      */
     public Class getSpecification() {
@@ -512,8 +566,9 @@
     }
 
     /**
-     * Set the required specification of this service dependency. This operation is not supported if the dependency tracking has already begun.
-     * @param specification : required specification.
+     * Sets the required specification of this service dependency. 
+     * This operation is not supported if the dependency tracking has already begun.
+     * @param specification the required specification.
      */
     public void setSpecification(Class specification) {
         if (m_tracker == null) {
@@ -524,8 +579,9 @@
     }
 
     /**
-     * Set the filter of the dependency. This method recompute the matching set and call the onDependencyReconfiguration callback.
-     * @param filter : new LDAP filter.
+     * Sets the filter of the dependency. This method recomputes the
+     * matching set and call the onDependencyReconfiguration callback.
+     * @param filter the new LDAP filter.
      */
     public void setFilter(Filter filter) { //NOPMD
         m_filter = filter;
@@ -641,8 +697,9 @@
     }
 
     /**
-     * Return the dependency filter (String form).
-     * @return the String form of the LDAP filter used by this dependency, null if not set.
+     * Returns the dependency filter (String form).
+     * @return the String form of the LDAP filter used by this dependency, 
+     * <code>null</code> if not set.
      */
     public String getFilter() {
         if (m_filter == null) {
@@ -653,8 +710,9 @@
     }
 
     /**
-     * Set the aggregate attribute of the current dependency. If the tracking is open, it will call arrival and departure callbacks.
-     * @param isAggregate : new aggregate attribute value.
+     * Sets the aggregate attribute of the current dependency. 
+     * If the tracking is opened, it will call arrival and departure callbacks.
+     * @param isAggregate the new aggregate attribute value.
      */
     public synchronized void setAggregate(boolean isAggregate) {
         if (m_tracker == null) { // Not started ...
@@ -688,8 +746,8 @@
     }
 
     /**
-     * Set the optionality attribute of the current dependency.
-     * @param isOptional : the new optional attribute value.
+     * Sets the optionality attribute of the current dependency.
+     * @param isOptional the new optional attribute value.
      */
     public void setOptionality(boolean isOptional) {
         if (m_tracker == null) { // Not started ...
@@ -704,7 +762,7 @@
     }
 
     /**
-     * Return the used binding policy.
+     * Gets the used binding policy.
      * @return the current binding policy.
      */
     public int getBindingPolicy() {
@@ -712,7 +770,8 @@
     }
 
     /**
-     * Set the binding policy. Not yet supported.
+     * Sets the binding policy. 
+     * Not yet supported.
      */
     public void setBindingPolicy() {
         throw new UnsupportedOperationException("Binding Policy change is not yet supported");
@@ -726,8 +785,8 @@
     
     /**
      * Gets the used comparator name.
-     * Null if no comparator (i.e. OSGi one is used).
-     * @return the comparator class name or null if the dependency doesn't use a comparator.
+     * <code>Null</code> if no comparator (i.e. the OSGi one is used).
+     * @return the comparator class name or <code>null</code> if the dependency doesn't use a comparator.
      */
     public String getComparator() {
         if (m_comparator != null) {
@@ -738,8 +797,9 @@
     }
 
     /**
-     * Set the bundle context used by this dependency. This operation is not supported if the tracker is already opened.
-     * @param context : bundle context or service context to use
+     * Sets the bundle context used by this dependency.
+     * This operation is not supported if the tracker is already opened.
+     * @param context the bundle context or service context to use
      */
     public void setBundleContext(BundleContext context) {
         if (m_tracker == null) { // Not started ...
@@ -750,30 +810,33 @@
     }
 
     /**
-     * Get a service object for the given reference.
-     * @param ref : wanted service reference
-     * @return : the service object attached to the given reference
+     * Gets a service object for the given reference.
+     * @param ref the wanted service reference
+     * @return the service object attached to the given reference
      */
     public Object getService(ServiceReference ref) {
         return m_tracker.getService(ref);
     }
 
     /**
-     * Unget a used service reference.
-     * @param ref : reference to unget.
+     * Ungets a used service reference.
+     * @param ref the reference to unget.
      */
     public void ungetService(ServiceReference ref) {
         m_tracker.ungetService(ref);
     }
 
     /**
-     * Helper method parsing the comparator attribute and returning the comparator object. If the 'comparator' attribute is not set, this method
-     * returns null. If the 'comparator' attribute is set to 'osgi', this method returns the normal OSGi comparator. In other case, it tries to create
+     * Helper method parsing the comparator attribute and returning the
+     * comparator object. If the 'comparator' attribute is not set, this method
+     * returns null. If the 'comparator' attribute is set to 'osgi', this method 
+     * returns the normal OSGi comparator. In other case, it tries to create
      * an instance of the declared comparator class.
-     * @param dep : Element describing the dependency
-     * @param context : bundle context (to load the comparator class)
-     * @return the comparator object, null if not set.
-     * @throws ConfigurationException the comparator class cannot be load or the comparator cannot be instantiated correctly.
+     * @param dep the Element describing the dependency
+     * @param context the bundle context (to load the comparator class)
+     * @return the comparator object, <code>null</code> if not set.
+     * @throws ConfigurationException the comparator class cannot be load or the
+     * comparator cannot be instantiated correctly.
      */
     public static Comparator getComparator(Element dep, BundleContext context) throws ConfigurationException {
         Comparator cmp = null;
@@ -798,11 +861,11 @@
     }
 
     /**
-     * Load the given specification class.
-     * @param specification : specification class name to load
-     * @param context : bundle context
-     * @return : the class object for the given specification
-     * @throws ConfigurationException : the class cannot be loaded correctly.
+     * Loads the given specification class.
+     * @param specification the specification class name to load
+     * @param context the bundle context
+     * @return the class object for the given specification
+     * @throws ConfigurationException if the class cannot be loaded correctly.
      */
     public static Class loadSpecification(String specification, BundleContext context) throws ConfigurationException {
         Class spec = null;
@@ -815,11 +878,13 @@
     }
 
     /**
-     * Helper method parsing the binding policy. If the 'policy' attribute is not set in the dependency, the method returns the 'DYNAMIC BINDING
-     * POLICY'. Accepted policy values are : dynamic, dynamic-priority and static.
-     * @param dep : Element describing the dependency
-     * @return : the policy attached to this dependency
-     * @throws ConfigurationException : an unknown biding policy was described.
+     * Helper method parsing the binding policy. 
+     * If the 'policy' attribute is not set in the dependency, the method returns 
+     * the 'DYNAMIC BINDING POLICY'. Accepted policy values are : dynamic, 
+     * dynamic-priority and static.
+     * @param dep the Element describing the dependency
+     * @return the policy attached to this dependency
+     * @throws ConfigurationException if an unknown binding policy was described.
      */
     public static int getPolicy(Element dep) throws ConfigurationException {
         String policy = dep.getAttribute("policy");

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/DependencyStateListener.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/DependencyStateListener.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/DependencyStateListener.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/DependencyStateListener.java Wed Oct  1 23:30:33 2008
@@ -20,20 +20,20 @@
 
 
 /**
- * This interface allows a class to be notified of dependency state changes.
+ * This interface allows a class to be notified of service dependency state changes.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public interface DependencyStateListener {
 
     /**
      * The given dependency becomes valid.
-     * @param dependency : dependency becoming valid.
+     * @param dependency the dependency becoming valid.
      */
     void validate(DependencyModel dependency);
     
     /**
      * The given dependency becomes invalid.
-     * @param dependency : dependency becoming invalid.
+     * @param dependency the dependency becoming invalid.
      */
     void invalidate(DependencyModel dependency);
 }

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Logger.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Logger.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Logger.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Logger.java Wed Oct  1 23:30:33 2008
@@ -23,58 +23,60 @@
 import org.osgi.service.log.LogService;
 
 /**
- * iPOJO Logger. This logger send log message to a log service if presents.
+ * iPOJO Logger.
+ * This class is an helper class implementing a simple log system. 
+ * This logger sends log messages to a log service if available.
  * 
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class Logger {
     
     /**
-     * Ipojo default log level property.
+     * The iPOJO default log level property.
      */
     public static final String IPOJO_LOG_LEVEL = "ipojo.log.level";
 
     /**
-     * Log Level ERROR.
+     * The Log Level ERROR.
      */
     public static final int ERROR = 1;
 
     /**
-     * Log Level WARNING.
+     * The Log Level WARNING.
      */
     public static final int WARNING = 2;
 
     /**
-     * Log Level INFO.
+     * The Log Level INFO.
      */
     public static final int INFO = 3;
 
     /**
-     * Log Level DEBUG.
+     * The Log Level DEBUG.
      */
     public static final int DEBUG = 4;
 
     /**
-     * Bundle Context.
+     * The Bundle Context used to get the
+     * log service.
      */
     private BundleContext m_context;
 
     /**
-     * Name of the logger.
+     * The name of the logger.
      */
     private String m_name;
 
     /**
-     * trace level of this logger.
+     * The trace level of this logger.
      */
     private int m_level;
 
     /**
-     * Constructor.
-     * 
-     * @param context : bundle context
-     * @param name : name of the logger
-     * @param level : trace level
+     * Creates a logger.
+     * @param context the bundle context
+     * @param name the name of the logger
+     * @param level the trace level
      */
     public Logger(BundleContext context, String name, int level) {
         m_name = name;
@@ -83,20 +85,19 @@
     }
     
     /**
-     * Constructor.
-     * 
-     * @param context : bundle context
-     * @param name : name of the logger
+     * Create a logger.
+     * Uses the default logger level.
+     * @param context the bundle context
+     * @param name the name of the logger
      */
     public Logger(BundleContext context, String name) {
         this(context, name, getDefaultLevel(context));
     }
 
     /**
-     * Log a message.
-     * 
-     * @param level : level of the message
-     * @param msg : the message to log
+     * Logs a message.
+     * @param level the level of the message
+     * @param msg the the message to log
      */
     public void log(int level, String msg) {
         if (m_level >= level) {
@@ -105,11 +106,10 @@
     }
 
     /**
-     * Log a message with an exception.
-     * 
-     * @param level : level of the message
-     * @param msg : message to log
-     * @param exception : exception attached to the message
+     * Logs a message with an exception.
+     * @param level the level of the message
+     * @param msg the message to log
+     * @param exception the exception attached to the message
      */
     public void log(int level, String msg, Throwable exception) {
         if (m_level >= level) {
@@ -118,10 +118,9 @@
     }
     
     /**
-     * Internal log method.
-     * 
-     * @param level : level of the message.
-     * @param msg : message to log
+     * Internal log method. 
+     * @param level the level of the message.
+     * @param msg the message to log
      */
     private void dispatch(int level, String msg) {
         
@@ -173,10 +172,9 @@
 
     /**
      * Internal log method.
-     * 
-     * @param level : level of the message.
-     * @param msg : message to log
-     * @param exception : exception attached to the message
+     * @param level the level of the message.
+     * @param msg the message to log
+     * @param exception the exception attached to the message
      */
     private void dispatch(int level, String msg, Throwable exception) {
         
@@ -232,10 +230,11 @@
     }
     
     /**
-     * Get the default logger level.
-     * The property is searched inside the framework properties, the system properties,
-     * and in the manifest from the given bundle context. By default, set the level to WARNING. 
-     * @param context : bundle context.
+     * Gets the default logger level.
+     * The property is searched inside the framework properties, 
+     * the system properties, and in the manifest from the given 
+     * bundle context. By default, set the level to {@link Logger#WARNING}. 
+     * @param context the bundle context.
      * @return the default log level.
      */
     private static int getDefaultLevel(BundleContext context) {

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Property.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Property.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Property.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Property.java Wed Oct  1 23:30:33 2008
@@ -31,60 +31,62 @@
 import org.osgi.framework.BundleContext;
 
 /**
- * Property class managing a property.
- * This class allows storing property value and calling setter method too.
+ * Property class managing a managed value.
+ * This class managed the method invocation as well as field injection.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class Property implements FieldInterceptor {
 
     /**
-     * Name of the property (filed name if not set).
+     * The name of the property (field name if not set).
+     * Cannot change once set.
      */
     private final String m_name;
 
     /**
-     * Field of the property.
+     * The field of the property.
      * Cannot change once set.
      */
     private final String m_field;
 
     /**
-     * Setter method of the property.
+     * The setter method of the property.
+     * Cannot change once set.
      */
     private final Callback m_method;
 
     /**
-     * Value of the property.
+     * The value of the property.
      */
     private Object m_value;
 
     /**
-     * Type of the property.
+     * The type of the property.
      */
     private final Class m_type;
 
     /**
-     * Handler object on to use the logger.
+     * The handler object to get the logger.
      */
     private final Handler m_handler;
     
     /**
-     * Instance Manager.
+     * The instance manager.
      */
     private final InstanceManager m_manager;
 
     /**
-     * Configurable Property Constructor. At least the method or the field need
-     * to be referenced.
-     * 
-     * @param name : name of the property (optional)
-     * @param field : name of the field
-     * @param method : method name
-     * @param value : initial value of the property (optional)
-     * @param type : the type of the property
-     * @param manager : instance manager
-     * @param handler : handler object which manage this property.
-     * @throws ConfigurationException : occurs when the property value cannot be set.
+     * Creates a property. 
+     * At least the method or the field need
+     * to be specified.
+     * @param name the name of the property (optional)
+     * @param field the name of the field
+     * @param method the method name
+     * @param value the initial value of the property (optional)
+     * @param type the the type of the property
+     * @param manager the instance manager
+     * @param handler the handler object which manage this property.
+     * @throws ConfigurationException if the property value cannot be set.
      */
     public Property(String name, String field, String method, String value, String type, InstanceManager manager, Handler handler) throws ConfigurationException {
         m_handler = handler;
@@ -115,9 +117,9 @@
     }
 
     /**
-     * The set type method computes and returns the property type according to the given type name.
-     * @param type : the type name
-     * @param context : bundle context (used to load classes)
+     * Computes and returns the property type according to the given type name.
+     * @param type the the type name
+     * @param context the bundle context (used to load classes)
      * @return the class of the given type
      * @throws ConfigurationException if an error occurs when loading the type class for non-primitive types.
      */
@@ -161,11 +163,11 @@
     }
 
     /**
-     * Get the Class object of a type array.
-     * @param type : the string descriptor of the type (must end by [] )
-     * @param context : bundle context (used to load classes)
+     * Gets the Class object of a type array.
+     * @param type the string descriptor of the type (must end by [] )
+     * @param context the bundle context (used to load classes)
      * @return the Class object of the given type array.
-     * @throws ConfigurationException : if the class cannot be loaded
+     * @throws ConfigurationException if the class cannot be loaded
      */
     private static Class computeArrayType(String type, BundleContext context) throws ConfigurationException {
         String internalType = type.substring(0, type.length() - 2);
@@ -220,7 +222,8 @@
     }
 
     /**
-     * Get method name, null if no method.
+     * Gets the method name, 
+     * <code>null</code> if no method.
      * @return the method name.
      */
     public String getMethod() {
@@ -229,16 +232,16 @@
     }
 
     /**
-     * Check if the property has a method callback.
-     * @return true if the property has a method.
+     * Checks if the property has a method callback.
+     * @return <code>true</code> if the property has a method.
      */
     public boolean hasMethod() {
         return m_method != null;
     }
 
     /**
-     * Check if the property has a field.
-     * @return true if the property has a field.
+     * Checks if the property has a field.
+     * @return <code>true</code> if the property has a field.
      */
     public boolean hasField() {
         return m_field != null;
@@ -249,8 +252,8 @@
     }
 
     /**
-     * Fix the value of the property.
-     * @param value : the new value.
+     * Sets the value of the property.
+     * @param value the new value.
      */
     public void setValue(Object value) {
         synchronized (this) {
@@ -275,10 +278,10 @@
     }
 
     /**
-     * Test if the given value is assignable to the given type.
-     * @param type : class of the type
-     * @param value : object to check
-     * @return true if the object is assignable in the property of type 'type'.
+     * Checks if the given value is assignable to the given type.
+     * @param type the class of the type
+     * @param value the object to check
+     * @return <code>true</code> if the object is assignable in the property of type 'type'.
      */
     public static boolean isAssignable(Class type, Object value) {
         if (value == null || type.isInstance(value)) { // When the value is null, the assign works necessary.
@@ -301,11 +304,11 @@
     }
 
     /**
-     * Create an object of the given type with the given String value.
-     * @param type : type of the returned object
-     * @param strValue : String value.
+     * Creates an object of the given type with the given String value.
+     * @param type the type of the returned object
+     * @param strValue the String value.
      * @return the object of type 'type' created from the String 'value'
-     * @throws ConfigurationException occurs when the object cannot be created.
+     * @throws ConfigurationException if the object cannot be created.
      */
     public static Object create(Class type, String strValue) throws ConfigurationException {
         if (Boolean.TYPE.equals(type)) { return new Boolean(strValue); }
@@ -343,11 +346,12 @@
     }
 
     /**
-     * Create an array object containing the type 'interntype' from the String array 'values'.
-     * @param interntype : internal type of the array.
-     * @param values : String array
+     * Creates an array object containing the type component type from 
+     * the String array 'values'.
+     * @param interntype the internal type of the array.
+     * @param values the String array
      * @return the array containing objects created from the 'values' array
-     * @throws ConfigurationException occurs when the array cannot be created correctly
+     * @throws ConfigurationException if the array cannot be created correctly
      */
     public static Object createArrayObject(Class interntype, String[] values) throws ConfigurationException {
         if (Boolean.TYPE.equals(interntype)) {
@@ -430,8 +434,9 @@
     }
 
     /**
-     * Invoke the setter method on the given pjo object. If no specified pojo object, will call on each created pojo object.
-     * @param instance : the created object (could be null
+     * Invokes the setter method on the given pojo object. 
+     * If no specified pojo object, it calls on each created pojo object.
+     * @param instance the created object (could be <code>null</code>)
      * @see org.apache.felix.ipojo.Handler#onCreation(java.lang.Object)
      */
     public synchronized void invoke(Object instance) {
@@ -455,9 +460,9 @@
 
     /**
      * A field value is required by the object 'pojo'.
-     * @param pojo : POJO object
-     * @param fieldName : field
-     * @param value : last value
+     * @param pojo the POJO object
+     * @param fieldName the field
+     * @param value the last value
      * @return the value if the handler want to inject this value.
      * @see org.apache.felix.ipojo.FieldInterceptor#onGet(java.lang.Object, java.lang.String, java.lang.Object)
      */
@@ -467,9 +472,9 @@
 
     /**
      * The field 'field' receives a new value.
-     * @param pojo : pojo
-     * @param fieldName : field name
-     * @param value : new value
+     * @param pojo the pojo
+     * @param fieldName the field name
+     * @param value the new value
      * @see org.apache.felix.ipojo.FieldInterceptor#onSet(java.lang.Object, java.lang.String, java.lang.Object)
      */
     public void onSet(Object pojo, String fieldName, Object value) {

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/ServiceReferenceRankingComparator.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/ServiceReferenceRankingComparator.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/ServiceReferenceRankingComparator.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/ServiceReferenceRankingComparator.java Wed Oct  1 23:30:33 2008
@@ -25,16 +25,18 @@
 
 /**
  * Service Reference Comparator.
- * This comparator follow OSGi Ranking policy.
+ * This comparator follows OSGi Ranking policy.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class ServiceReferenceRankingComparator implements Comparator {
 
     /**
-     * Compare two service reference.
-     * @param ref1 : reference 1
-     * @param ref2 : reference 2
-     * @return -1 if the reference 1 is 'higher' than the reference 2, 1 otherwise. (higher is term of ranking means a lower index)
+     * Compares two service reference.
+     * @param ref1 the reference 1
+     * @param ref2 the reference 2
+     * @return <code>-1</code> if the reference 1 
+     * is 'higher' than the reference 2, <code>1</code> otherwise. 
+     * (higher is term of ranking means a lower index)
      * @see java.util.Comparator#compare(java.lang.Object, java.lang.Object)
      */
     public int compare(Object ref1, Object ref2) {



Mime
View raw message