You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by cl...@apache.org on 2008/10/02 08:30:34 UTC
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...
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) {