felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From clem...@apache.org
Subject svn commit: r701012 [2/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/InstanceManager.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/InstanceManager.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/InstanceManager.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/InstanceManager.java Wed Oct  1 23:30:33 2008
@@ -37,70 +37,78 @@
 import org.osgi.framework.BundleContext;
 
 /**
- * The instance manager class manages one instance of a component type. It manages component lifecycle, component instance creation and handlers.
+ * This class defines the container of primitive instances. It manages content initialization 
+ * and handlers cooperation.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class InstanceManager implements ComponentInstance, InstanceStateListener {
     /**
-     * Name of the component instance.
+     * The name of the component instance.
      */
     protected String m_name;
 
     /**
-     * Name of the component type implementation class.
+     * The name of the component type implementation class.
      */
     protected String m_className;
 
     /**
-     * Handler list.
+     * The handler object list.
      */
     protected final HandlerManager[] m_handlers;
 
     /**
-     * Component state (STOPPED at the beginning).
+     * The current instance state ({@link ComponentInstance#STOPPED} at the beginning).
+     * Possible value are 
+     * <li>{@link ComponentInstance#INVALID}</li>
+     * <li>{@link ComponentInstance#VALID}</li>
+     * <li>{@link ComponentInstance#DISPOSED}</li>
+     * <li>{@link ComponentInstance#STOPPED}</li>
      */
     protected int m_state = STOPPED;
 
     /**
-     * Instance State Listener List.
+     * The instance state listener list.
+     * @see InstanceStateListener
      */
     protected List m_listeners = null;
 
     /**
-     * Parent factory (ComponentFactory).
+     * The instance factory.
      */
     private final ComponentFactory m_factory;
 
     /**
-     * The context of the component.
+     * The bundle context of the instance.
      */
     private final BundleContext m_context;
 
     /**
-     * Map [field, field interceptor list] storing handlers interested by the field.
+     * The map [field, {@link FieldInterceptor} list] storing interceptors monitoring fields.
      * Once configured, this map can't change.
      */
     private Map m_fieldRegistration;
 
     /**
-     * Map [method identifier, method interceptor list] storing handlers interested by the method.
+     * the map [method identifier, {@link MethodInterceptor} list] storing handlers interested by the method.
      * Once configure this map can't change.
      */
     private Map m_methodRegistration;
 
     /**
-     * Manipulated class.
+     * The manipulated class.
      * Once set, this field doesn't change.
      */
     private Class m_clazz;
 
     /**
-     * Instances of the components.
+     * The content of the current instance.
      */
     private List m_pojoObjects;
 
     /**
-     * Factory method. Contains the name of the static method used to create POJO objects.
+     * The factory method used to create content objects.
+     * If <code>null</code>, the regular constructor is used. 
      * Once set, this field is immutable.
      */
     private String m_factoryMethod = null;
@@ -111,25 +119,28 @@
     private boolean m_inTransition = false;
 
     /**
-     * Queue of stored state changed.
+     * The queue of stored state changed.
      */
     private List m_stateQueue = new ArrayList();
 
     /**
-     * Map of [field, value], storing POJO field value.
+     * The map of [field, value], storing POJO managed 
+     * field value.
      */
     private Map m_fields = new HashMap();
 
     /**
-     * Map method [id=>method].
+     * The Map storing the Method objects by ids.
+     * [id=>{@link Method}].
      */
     private Map m_methods = new HashMap();
 
     /**
-     * Construct a new Component Manager.
-     * @param factory : the factory managing the instance manager
-     * @param context : the bundle context to give to the instance
-     * @param handlers : handlers array
+     * Creates a new Component Manager.
+     * The instance is not initialized.
+     * @param factory  the factory managing the instance manager
+     * @param context  the bundle context to give to the instance
+     * @param handlers handler object array
      */
     public InstanceManager(ComponentFactory factory, BundleContext context, HandlerManager[] handlers) {
         m_factory = factory;
@@ -138,10 +149,12 @@
     }
 
     /**
-     * Configure the instance manager. Stop the existing handler, clear the handler list, change the metadata, recreate the handlers
-     * @param metadata : the component type metadata
-     * @param configuration : the configuration of the instance
-     * @throws ConfigurationException : occurs if the metadata are not correct
+     * Configures the instance manager.
+     * Sets the class name, and the instance name as well as the factory method.
+     * Initializes handlers.
+     * @param metadata the component type metadata
+     * @param configuration the configuration of the instance
+     * @throws ConfigurationException if the metadata are not correct
      */
     public void configure(Element metadata, Dictionary configuration) throws ConfigurationException {
         m_className = metadata.getAttribute("classname");
@@ -159,7 +172,7 @@
     }
 
     /**
-     * Get the description of the current instance.
+     * Gets the description of the current instance.
      * @return the instance description.
      * @see org.apache.felix.ipojo.ComponentInstance#getInstanceDescription()
      */
@@ -186,7 +199,7 @@
     }
 
     /**
-     * Get the list of handlers plugged on the instance.
+     * Gets the list of handlers plugged (i.e. attached) on the instance.
      * This method does not need a synchronized block as the handler set is constant.
      * @return the handler array of plugged handlers.
      */
@@ -199,10 +212,11 @@
     }
 
     /**
-     * Return a specified handler.
+     * Returns a specified handler.
+     * This method allows cross-handler interactions.
      * This must does not need a synchronized block as the handler set is constant.
-     * @param name : class name of the handler to find or its qualified name (namespace:name)
-     * @return : the handler, or null if not found
+     * @param name the class name of the handler to find or its qualified name (namespace:name)
+     * @return the handler, or null if not found
      */
     public Handler getHandler(String name) {
         for (int i = 0; i < m_handlers.length; i++) {
@@ -215,11 +229,11 @@
     }
 
     /**
-     * Give access to a field value to the first created pojo.
-     * This method process by analyzing both managed fields and pojo fields (by reflection).
+     * Gives access to a field value of the first created pojo.
+     * This method processes by analyzing both managed fields and pojo fields (by reflection).
      * If no pojo were already created try only on managed fields.
-     * @param fieldName : field name.
-     * @return the field value, null is returned if the value is managed and not already set.
+     * @param fieldName the field name.
+     * @return the field value, <code>null</code> is returned if the value is managed and not already set.
      */
     public synchronized Object getFieldValue(String fieldName) {
         if (m_pojoObjects == null) {
@@ -230,12 +244,12 @@
     }
 
     /**
-     * Give access to a field value to the given created pojo.
-     * This method process by analyzing both managed fields and pojo fields (by reflection).
-     * If the given pojo is null, try only on managed fields.
-     * @param fieldName : field name.
-     * @param pojo : the pojo on which computing field value.
-     * @return the field value, null is returned if the value is managed and not already set.
+     * Gives access to a field value to the given created pojo.
+     * This method processes by analyzing both managed fields and pojo fields (by reflection).
+     * If the given pojo is <code>null</code>, tries only on managed fields.
+     * @param fieldName the field name.
+     * @param pojo  the pojo on which computing field value.
+     * @return the field value, <code>null</code> is returned if the value is managed and not already set.
      */
     public synchronized Object getFieldValue(String fieldName, Object pojo) {
         Object setByContainer = null;
@@ -268,7 +282,9 @@
     }
 
     /**
-     * Start the instance manager.
+     * Starts the instance manager.
+     * This method activates plugged handlers,
+     * and computes the initial instance state.
      */
     public void start() {
         synchronized (this) {
@@ -300,7 +316,10 @@
     }
 
     /**
-     * Stop the instance manager.
+     * Stops the instance manager.
+     * This methods sets the instance state to {@link ComponentInstance#STOPPED},
+     * disables attached handlers, and notifies listeners ({@link InstanceStateListener})
+     * of the instance stopping process.
      */
     public void stop() {
         List listeners = null;
@@ -336,12 +355,17 @@
     }
 
     /**
-     * Dispose the instance.
+     * Disposes the instance.
+     * This method does the following process:
+     * <li>Stop the instance is not {@link ComponentInstance#STOPPED}</li>
+     * <li>Notifies listeners {@link InstanceStateListener} of the destruction</li>
+     * <li>Disposes attached handlers</li>
+     * <li>Clears structures</li>
      * @see org.apache.felix.ipojo.ComponentInstance#dispose()
      */
     public void dispose() {
         List listeners = null;
-        int state = -2;
+        int state = -2; // Temporary state
         synchronized (this) {
             state = m_state; // Stack confinement
             if (m_listeners != null) {
@@ -376,10 +400,11 @@
     }
 
     /**
-     * Set the state of the component instance. if the state changed call the stateChanged(int) method on the handlers. This method has a reentrant
-     * mechanism. If in the flow of the first call the method is called another times, the second call is stored and executed after the first one is
-     * finished.
-     * @param state : the new state
+     * Sets the state of the component instance. 
+     * If the state changes, calls the {@link PrimitiveHandler#stateChanged(int)} method on the attached handlers.
+     * This method has a reentrant mechanism. If in the flow of the first call the method is called another times, 
+     * the second call is stored and executed after the first one finished.
+     * @param state the new state
      */
     public void setState(int state) {
         int originalState = -2;
@@ -443,7 +468,12 @@
     }
 
     /**
-     * Get the actual state of the instance.
+     * Gets the actual state of the instance.
+     * Possible values are:
+     * <li>{@link ComponentInstance#INVALID}</li>
+     * <li>{@link ComponentInstance#VALID}</li>
+     * <li>{@link ComponentInstance#DISPOSED}</li>
+     * <li>{@link ComponentInstance#STOPPED}</li>
      * @return the actual state of the component instance.
      * @see org.apache.felix.ipojo.ComponentInstance#getState()
      */
@@ -452,8 +482,10 @@
     }
 
     /**
-     * Check if the instance if started.
-     * @return true if the instance is started.
+     * Checks if the instance is started.
+     * An instance is started if the state is either 
+     * {@link ComponentInstance#VALID} or {@link ComponentInstance#INVALID}.
+     * @return <code>true</code> if the instance is started.
      * @see org.apache.felix.ipojo.ComponentInstance#isStarted()
      */
     public synchronized boolean isStarted() {
@@ -461,8 +493,8 @@
     }
 
     /**
-     * Register an instance state listener.
-     * @param listener : listener to register.
+     * Registers an instance state listener.
+     * @param listener the listener to register.
      * @see org.apache.felix.ipojo.ComponentInstance#addInstanceStateListener(org.apache.felix.ipojo.InstanceStateListener)
      */
     public synchronized void addInstanceStateListener(InstanceStateListener listener) {
@@ -473,8 +505,8 @@
     }
 
     /**
-     * Unregister an instance state listener.
-     * @param listener : listener to unregister.
+     * Unregisters an instance state listener.
+     * @param listener the listener to unregister.
      * @see org.apache.felix.ipojo.ComponentInstance#removeInstanceStateListener(org.apache.felix.ipojo.InstanceStateListener)
      */
     public synchronized void removeInstanceStateListener(InstanceStateListener listener) {
@@ -487,7 +519,7 @@
     }
 
     /**
-     * Get the factory which create the current instance.
+     * Gets the factory which has created the current instance.
      * @return the factory of the component
      * @see org.apache.felix.ipojo.ComponentInstance#getFactory()
      */
@@ -496,7 +528,7 @@
     }
 
     /**
-     * Load the manipulated class.
+     * Loads the manipulated class.
      */
     private void load() {
         try {
@@ -509,8 +541,8 @@
     }
 
     /**
-     * Get the array of object created by the instance.
-     * @return the created instance of the component instance.
+     * Gets the object array created by the instance.
+     * @return the created content objects of the component instance.
      */
     public synchronized Object[] getPojoObjects() {
         if (m_pojoObjects == null) {
@@ -519,6 +551,17 @@
         return m_pojoObjects.toArray(new Object[m_pojoObjects.size()]);
     }
     
+    /**
+     * Creates a POJO objects.
+     * This method is not synchronized and does require any locks.
+     * If a {@link InstanceManager#m_factoryMethod} is specified,
+     * this method called this static method to creates the object.
+     * Otherwise, the methods uses the regular constructor.
+     * All those methods can receive the {@link BundleContext} in
+     * argument.
+     * @return the created object or <code>null</code> if an error
+     * occurs during the creation.
+     */
     private Object createObject() {
         if (m_clazz == null) {
             load();
@@ -662,13 +705,18 @@
     }
 
     /**
-     * Create an instance of the component. 
-     * This method need to be called one time only for singleton provided service.
-     * @return a new instance
+     * Creates an instance of the content. 
+     * This method needs to be called once only for singleton provided service.
+     * This methods call the {@link InstanceManager#createObject()} method, and adds
+     * the created object to the {@link InstanceManager#m_pojoObjects} list. Then,
+     * it calls the {@link PrimitiveHandler#onCreation(Object)} methods on attached 
+     * handlers.
+     * @return a new instance or <code>null</code> if an error occurs during the
+     * creation.
      */
     public Object createPojoObject() {
         Object instance = createObject();
-
+        
         // Add the new instance in the instance list.
         synchronized (this) {
             if (m_pojoObjects == null) {
@@ -678,6 +726,7 @@
         }
         // Call createInstance on Handlers :
         for (int i = 0; i < m_handlers.length; i++) {
+            // This methods must be call without the monitor lock.
             ((PrimitiveHandler) m_handlers[i].getHandler()).onCreation(instance);
         }
         
@@ -685,8 +734,20 @@
     }
 
     /**
-     * Get the first object created by the instance. If no object created, create and return one object.
-     * @return the instance of the component instance to use for singleton component
+     * Gets the first object created by the instance. 
+     * If no object created, creates and returns a POJO object.
+     * This methods call the {@link InstanceManager#createObject()} method, and adds
+     * the created object to the {@link InstanceManager#m_pojoObjects} list. Then,
+     * it calls the {@link PrimitiveHandler#onCreation(Object)} methods on attached 
+     * handlers.
+     * <br/>
+     * <p>
+     * <b>TODO</b> this method has a potential race condition if two threads require a pojo
+     * object at the same time. Only one object will be created, but the second thread
+     * can receive the created object before the {@link PrimitiveHandler#onCreation(Object)}
+     * calls.
+     * </p>
+     * @return the pojo object of the component instance to use for singleton component
      */
     public Object getPojoObject() {
         Object pojo = null;
@@ -714,7 +775,7 @@
     }
 
     /**
-     * Get the manipulated class.
+     * Gets the manipulated class.
      * The method does not need to be synchronized.
      * Reassigning the internal class will use the same class object.
      * @return the manipulated class
@@ -727,11 +788,14 @@
     }
 
     /**
-     * Register an handler. The handler will be notified of event on each field given in the list.
-     * @param handler : the handler to register
-     * @param fields : the field metadata list
-     * @param methods : the method metadata list
-     * @deprecated use register(FieldMetadata fm, FieldInterceptor fi) and register(MethodMetadata mm, MethodInterceptor mi) instead. 
+     * Registers an handler.
+     * This methods is called by handler wanting to monitor
+     * fields and/or methods of the implementation class.  
+     * @param handler the handler to register
+     * @param fields the field metadata list
+     * @param methods the method metadata list
+     * @deprecated use {@link InstanceManager#register(FieldMetadata, FieldInterceptor)}
+     * and {@link InstanceManager#register(FieldMetadata, MethodInterceptor)} instead. 
      */
     public void register(PrimitiveHandler handler, FieldMetadata[] fields, MethodMetadata[] methods) {
         for (int i = 0; fields != null && i < fields.length; i++) {
@@ -744,9 +808,11 @@
     }
     
     /**
-     * Register a field interceptor.
-     * @param field : intercepted field
-     * @param interceptor : interceptor
+     * Registers a field interceptor.
+     * A field interceptor will be notified of field access of the
+     * implementation class. Note that handlers are field interceptors.
+     * @param field the field to monitor
+     * @param interceptor the field interceptor object
      */
     public void register(FieldMetadata field, FieldInterceptor interceptor) {
         if (m_fieldRegistration == null) {
@@ -771,9 +837,11 @@
     }
     
     /**
-     * Register a method interceptor.
-     * @param method : intercepted method
-     * @param interceptor : interceptor
+     * Registers a method interceptor.
+     * A method interceptor will be notified of method entries, exits
+     * and errors. Note that handlers are method interceptors.
+     * @param method the field to monitor
+     * @param interceptor the field interceptor object
      */
     public void register(MethodMetadata method, MethodInterceptor interceptor) {
         if (m_methodRegistration == null) {
@@ -798,11 +866,14 @@
     }
 
     /**
-     * This method is called by the manipulated class each time that a GETFIELD instruction is found. The method ask to each handler which value need
-     * to be returned.
-     * @param pojo : the pojo object on which the field was get
-     * @param fieldName : the field name on which the GETFIELD instruction is called
-     * @return the value decided by the last asked handler (throw a warning if two fields decide two different values)
+     * This method is called by the manipulated class each time that a GETFIELD instruction is executed.
+     * The method asks to each attached handler monitoring this field which value need
+     * to be injected (i.e. returned) by invoking the {@link PrimitiveHandler#onGet(Object, String, Object)}
+     * method. If the field value changes, this method call the {@link PrimitiveHandler#onSet(Object, String, Object)}
+     * method on each field interceptor monitoring the field in order to advertize the new value.
+     * @param pojo the pojo object on which the field was get
+     * @param fieldName the field name on which the GETFIELD instruction is called
+     * @return the value decided by the last asked handler (throws a warning if two fields decide two different values)
      */
     public Object  onGet(Object pojo, String fieldName) {
         Object initialValue = null;
@@ -850,10 +921,12 @@
     }
 
     /**
-     * Dispatch entry method event on registered handler.
-     * @param pojo : the pojo object on which method is invoked.
-     * @param methodId : method id
-     * @param args : argument array
+     * Dispatches entry method events on registered method interceptors.
+     * This method calls the {@link PrimitiveHandler#onEntry(Object, Method, Object[])}
+     * methods on method interceptors monitoring the method.
+     * @param pojo the pojo object on which method is invoked.
+     * @param methodId the method id used to compute the {@link Method} object.
+     * @param args the argument array
      */
     public void onEntry(Object pojo, String methodId, Object[] args) {
         if (m_methodRegistration == null) { // Immutable field.
@@ -867,11 +940,15 @@
     }
 
     /**
-     * Dispatch exit method event on registered handler. The given returned object is an instance of Exception if the method has launched an
-     * exception. If the given object is null, either the method returns void, either the method has returned null.
-     * @param pojo : the pojo object on which the method was invoked
-     * @param methodId : method id
-     * @param result : returned object.
+     * Dispatches exit method events on registered method interceptors.
+     * The given returned object is an instance of {@link Exception} if the method thrown an
+     * exception. If the given object is <code>null</code>, either the method returns <code>void</code>,
+     * or the method has returned <code>null</code>
+     * This method calls the {@link PrimitiveHandler#onExit(Object, Method, Object[])} and the 
+     * {@link PrimitiveHandler#onFinally(Object, Method)} methods on method interceptors monitoring the method.
+     * @param pojo the pojo object on which method was invoked.
+     * @param methodId the method id used to compute the {@link Method} object.
+     * @param result the returned object.
      */
     public void onExit(Object pojo, String methodId, Object result) {
         if (m_methodRegistration == null) {
@@ -888,11 +965,14 @@
     }
 
     /**
-     * Dispatch error method event on registered handler. The given returned object is an instance of Exception if the method has thrown an exception.
-     * If the given object is null, either the method returns void, either the method has returned null.
-     * @param pojo : the pojo object on which the method was invoked
-     * @param methodId : method id
-     * @param error : throwable object.
+     * Dispatches error method events on registered method interceptors.
+     * or the method has returned <code>null</code>
+     * This method calls the {@link PrimitiveHandler#onExit(Object, Method, Object[])} and the 
+     * {@link PrimitiveHandler#onFinally(Object, Method)} methods on method interceptors monitoring 
+     * the method.
+     * @param pojo the pojo object on which the method was invoked
+     * @param methodId the method id used to compute the {@link Method} object.
+     * @param error the Throwable object.
      */
     public void onError(Object pojo, String methodId, Throwable error) {        
         if (m_methodRegistration == null) {
@@ -909,9 +989,11 @@
     }
 
     /**
-     * Get method object by id.
-     * @param methodId : method id
-     * @return : the method object or null if the method cannot be found.
+     * Computes the {@link Method} object from the given id.
+     * Once computes, a map is used as a cache to avoid to recompute for
+     * the same id.
+     * @param methodId the method id
+     * @return the method object or <code>null</code> if the method cannot be found.
      */
     private Method getMethodById(String methodId) {
         // Not necessary synchronized as recomputing the methodID will give the same Method twice.
@@ -940,10 +1022,14 @@
     }
 
     /**
-     * This method is called by the manipulated class each time that a PUTFILED instruction is found. the method send to each handler the new value.
-     * @param pojo : the pojo object on which the field was set
-     * @param fieldName : the field name on which the PUTFIELD instruction is called
-     * @param objectValue : the value of the field
+     * This method is called by the manipulated class each time that a PUTFILED instruction is executed. 
+     * The method calls the {@link PrimitiveHandler#onSet(Object, String, Object)} method on each field
+     * interceptors monitoring this field.
+     * This method can be invoked with a <code>null</code> pojo argument when the changes comes from another
+     * handler.
+     * @param pojo the pojo object on which the field was set
+     * @param fieldName the field name on which the PUTFIELD instruction is called
+     * @param objectValue the new value of the field
      */
     public void onSet(Object pojo, String fieldName, Object objectValue) {
         Object value = null; // Stack confinement
@@ -961,8 +1047,9 @@
         }
     }
 
+    
     /**
-     * Get the bundle context used by this component instance.
+     * Gets the bundle context used by this component instance.
      * @return the context of the component.
      * @see org.apache.felix.ipojo.ComponentInstance#getContext()
      */
@@ -970,16 +1057,31 @@
         return m_context; // Immutable
     }
 
+    /**
+     * Gets the global bundle context. This is the bundle context
+     * of the bundle declaring the component type.
+     * @return the bundle context of the bundle declaring the component
+     * type.
+     */
     public BundleContext getGlobalContext() {
         return ((IPojoContext) m_context).getGlobalContext(); // Immutable
     }
-
+    
+    
+    /**
+     * Gets the local service context. This service context gives
+     * access to the 'local' service registry (the composite one).
+     * If the instance lives in the global (i.e. OSGi) context,
+     * this method returns <code>null</code>
+     * @return the local service context or <code>null</code> if the
+     * instance doesn't live in a composite.
+     */
     public ServiceContext getLocalServiceContext() {
         return ((IPojoContext) m_context).getServiceContext(); // Immutable
     }
 
     /**
-     * Get the instance name.
+     * Gets the instance name.
      * @return the instance name.
      * @see org.apache.felix.ipojo.ComponentInstance#getInstanceName()
      */
@@ -988,8 +1090,15 @@
     }
 
     /**
-     * Reconfigure the current instance.
-     * @param configuration : the new configuration to push
+     * Reconfigures the current instance.
+     * Reconfiguring an instance means re-injecting a new
+     * instance configuration. Some properties are immutable
+     * such as the instance name.
+     * This methods calls the {@link PrimitiveHandler#reconfigure(Dictionary)}
+     * methods on each attached handler, and then recompute the instance
+     * state. Note that the reconfiguration process does not deactivate the 
+     * instance. 
+     * @param configuration the new configuration to push
      * @see org.apache.felix.ipojo.ComponentInstance#reconfigure(java.util.Dictionary)
      */
     public void reconfigure(Dictionary configuration) {
@@ -1011,19 +1120,22 @@
     }
 
     /**
-     * Get the implementation class of the component type.
+     * Gets the implementation class of the component type.
      * This method does not need to be synchronized as the
      * class name is constant once set. 
-     * @return the class name of the component type.
+     * @return the class name of the component implementation.
      */
     public String getClassName() {
         return m_className;
     }
 
     /**
-     * State Change listener callback. This method is notified at each time a plugged handler becomes invalid.
-     * @param instance : changing instance
-     * @param newState : new state
+     * State Change listener callback.
+     * This method is called every time that a plugged handler becomes valid or invalid.
+     * This method computes the new instance state and applies it (by calling the
+     * {@link InstanceManager#setState(int)} method.
+     * @param instance the handler becoming valid or invalid
+     * @param newState the new state of the handler
      * @see org.apache.felix.ipojo.InstanceStateListener#stateChanged(org.apache.felix.ipojo.ComponentInstance, int)
      */
     public void stateChanged(ComponentInstance instance, int newState) {
@@ -1055,7 +1167,9 @@
     }
 
     /**
-     * Get the list of registered fields. This method is invoked by the POJO itself.
+     * Gets the list of registered fields (containing field names). 
+     * This method is invoked by the POJO itself during
+     * its initialization.
      * @return the set of registered fields.
      */
     public Set getRegistredFields() {
@@ -1066,7 +1180,9 @@
     }
 
     /**
-     * Get the list of registered methods. This method is invoked by the POJO itself.
+     * Gets the list of registered methods (containing method ids). 
+     * This method is invoked by the POJO itself during its
+     * initialization.
      * @return the set of registered methods.
      */
     public Set getRegistredMethods() {

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/InstanceStateListener.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/InstanceStateListener.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/InstanceStateListener.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/InstanceStateListener.java Wed Oct  1 23:30:33 2008
@@ -19,17 +19,25 @@
 package org.apache.felix.ipojo;
 
 /**
- * Instance state listener.
- * This listener allows anyone to be notified when the listened instance state changes. 
+ * This class defines instance state listeners.
+ * An instance state listener is notified of instance state changes. It needs to be
+ * registered on the instance by invoking the ({@link ComponentInstance#addInstanceStateListener(InstanceStateListener)}
+ * method. Once registered, the listener can track instance state changes. 
+ * Received states are:
+ * <li>{@link ComponentInstance#VALID}</li>
+ * <li>{@link ComponentInstance#INVALID}</li>
+ * <li>{@link ComponentInstance#STOPPED}</li>
+ * <li>{@link ComponentInstance#DISPOSED}</li> 
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public interface InstanceStateListener {
     
     /**
-     * State change listener.
-     * Each time an instance state change, this method is called.
-     * @param instance : changing instance
-     * @param newState : new instance state
+     * State change listener callback method.
+     * Every time that a monitored instance's state changes,
+     * this method is called with the instance and the new state.
+     * @param instance the changing instance
+     * @param newState the new instance state
      */
     void stateChanged(ComponentInstance instance, int newState);
 }

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/MethodInterceptor.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/MethodInterceptor.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/MethodInterceptor.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/MethodInterceptor.java Wed Oct  1 23:30:33 2008
@@ -22,47 +22,52 @@
 
 /**
 * Method interceptor.
-* A class implementing this interface is able to be notified of method invocation.
-* The listener need to be register on the instance manager. 
-* For event are send to the listener : before the method entry, after the method returns, 
-* when an error is thrown by the method, and before the after either a returns or an error (finally) 
-* 
+* A class implementing this interface is able to be notified of method invocations (
+* i.e. entries, exits, and errors).
+* The listener needs to be register on the instance manager with the 
+* {@link InstanceManager#register(org.apache.felix.ipojo.parser.MethodMetadata, MethodInterceptor)}
+* method. 
+* Events are sent before the method entry (onEntry), after the method returns (onExit), 
+* when an error is thrown by the method (onError), and before the after either a returns or an error (onFinally)
 * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
 */
 public interface MethodInterceptor {
     
     /**
-     * This method is called when the execution enter in a method.
-     * @param pojo : pojo on which the method is called.
-     * @param method : method invoked.
-     * @param args arguments array.
+     * This method is called when the execution enters in a method.
+     * @param pojo the pojo on which the method is called.
+     * @param method the invoked method.
+     * @param args the arguments array.
      */
     void onEntry(Object pojo, Method method, Object[] args);
 
     /**
-     * This method is called when the execution exit a method (before a return or a throw).
-     * If the given returned object is null, either the method is void, either it returns null.
+     * This method is called when the execution exits a method :
+     * before a <code>return</code>.
+     * If the given returned object is <code>null</code>, either the method is 
+     * <code>void</code>, or it returns <code>null</code>.
      * You must not modified the returned object.
-     * @param pojo : the pojo on which the method exits.
-     * @param method : exiting method.
-     * @param returnedObj : the returned object (boxed for primitive type)
+     * @param pojo the pojo on which the method exits.
+     * @param method the exiting method.
+     * @param returnedObj the the returned object (boxed for primitive type)
      */
     void onExit(Object pojo, Method method, Object returnedObj);
     
     /**
-     * This method is called when the execution throw an exception in the given method.
-     * @param pojo : the pojo on which the method was accessed.
-     * @param method : invoked method.
-     * @param throwable : the thrown exception
+     * This method is called when the execution throws an exception in the given 
+     * method.
+     * @param pojo the pojo on which the method was accessed.
+     * @param method the invoked method.
+     * @param throwable the thrown exception
      */
     void onError(Object pojo, Method method, Throwable throwable);
     
     /**
-     * This method is called when the execution of a method will terminate : 
+     * This method is called when the execution of a method is going to terminate : 
      * just before to throw an exception or before to return.
-     * OnError or OnExit was already called.
-     * @param pojo : the pojo on which the method was accessed.
-     * @param method : invoked method.
+     * (onError or onExit was already called).
+     * @param pojo the pojo on which the method was accessed.
+     * @param method the invoked method.
      */
     void onFinally(Object pojo, Method method);
 

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/MissingHandlerException.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/MissingHandlerException.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/MissingHandlerException.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/MissingHandlerException.java Wed Oct  1 23:30:33 2008
@@ -22,7 +22,9 @@
 
 /**
  * Missing Handler Exception.
- * This exception occurs when an handler is missing to build an instance.
+ * This exception occurs when an handler factory is missing to create an instance.
+ * In fact, when a required handler factory is not avialable or valid, the {@link Handler}
+ * object cannot be created, and so the instance container cannot be completed.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class MissingHandlerException extends Exception {
@@ -33,13 +35,15 @@
     private static final long serialVersionUID = 5047792897590881478L;
     
     /**
-     * Message. 
+     * The message. 
      */
     private String m_message;
     
     /**
-     * Constructor.
-     * @param missing : list of missing handlers.
+     * Creates a MissingHandlerException.
+     * This methods computes the message from
+     * the given list.
+     * @param missing the list of missing handlers.
      */
     public MissingHandlerException(List missing) {
         super();
@@ -50,8 +54,8 @@
     }
     
     /**
-     * Get the error message.
-     * @return : the error message
+     * Gets the error message.
+     * @return the error message
      * @see java.lang.Throwable#getMessage()
      */
     public String getMessage() {

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/Nullable.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/Nullable.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/Nullable.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/Nullable.java Wed Oct  1 23:30:33 2008
@@ -20,7 +20,12 @@
 
 /**
  * A Nullable object must implement this interface.
- * 
+ * This allows to the code checking if the injected object is
+ * a Nullable object or not such as in:<br/>
+ * <code>if(foo instanceof Nullable){...}</code>
+ * <br/>
+ * This interface does not define any methods. Nullable objects owns
+ * the same methods than the 'real' object.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public interface Nullable {

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/Pojo.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/Pojo.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/Pojo.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/Pojo.java Wed Oct  1 23:30:33 2008
@@ -19,16 +19,16 @@
 package org.apache.felix.ipojo;
 
 /**
- * Interface implemented by each object created through an manipulated class.
- * This interface allow to get the component instance from the object.
+ * Interface implemented by each manipulated class. 
+ * This interface allows getting the component instance from the object.
  * 
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public interface Pojo {
 
     /**
-     * Get the instance container which create the current object.
-     * @return the component instance who create this object.
+     * Gets the instance container which creates the current object.
+     * @return the component instance which creates this object.
      */
     ComponentInstance getComponentInstance();
 

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/PolicyServiceContext.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/PolicyServiceContext.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/PolicyServiceContext.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/PolicyServiceContext.java Wed Oct  1 23:30:33 2008
@@ -34,52 +34,65 @@
 import org.osgi.framework.ServiceRegistration;
 
 /**
- * The policy service context is a service context aiming to solve service requirement.
- * It's parameterized by a resolving policy. Three policies are managed : 
- * - Local : services are only solve un the local service registry
- * - Global : services are resolved only in the global (i.e. OSGi) service registry
- * - Local and Global : services are resolved inside the local registry and the global registry  
+ * The policy service context is a service context aiming to resolve service dependencies
+ * inside different service context according to a policy.
+ * So, the policy service context behavior follows one of the three following policy:
+ * <li> Local : services are only resolved in the local service context.</li>
+ * <li> Global : services are only resolved in the global context (hte OSGi one)</li>
+ * <li> Local and Global : services are resolved inside the local context and inside
+ * the global context</li>
+ *    
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class PolicyServiceContext implements ServiceContext {
     
     /**
-     * Resolving policy, look only in the composite.
+     * Resolving policy, resolves services only in the composite
+     * context (local).
+     * This policy is the default one for services inherited from
+     * service-level dependencies.
      */
     public static final int LOCAL = 0;
     
     /**
-     * Resolving policy, look inside the composite and in the global scope.
+     * Resolving policy, resolves services only in the composite
+     * (local) and in the global context.
      * This policy is the default one for implementation dependency.
      */
     public static final int LOCAL_AND_GLOBAL = 1;
     
     /**
-     * Resolving policy, look inside the global only.
+     * Resolving policy, resolves services inside the global context
+     * only.
      */
     public static final int GLOBAL = 2;
     
     /**
-     * Global service registry.
+     * The global service registry.
+     * Targets the OSGi service registry.
      */
     public BundleContext m_global;
     
     /**
-     * Local (Composite) Service Registry.
+     * The local (Composite) Service Registry.
      */
     public ServiceContext m_local;
     
     /**
-     * Resolving policy.
+     * The resolving policy to use to resolve
+     * dependencies.
      */
     private int m_policy = LOCAL_AND_GLOBAL;
     
     
     /**
-     * Create a new PolicyServiceContext.
-     * @param global : global bundle context
-     * @param local : parent (local) service context
-     * @param policy : resolution policy
+     * Creates a PolicyServiceContext.
+     * If the local context is null, sets the policy to
+     * {@link PolicyServiceContext#GLOBAL}, else use the 
+     * given policy.
+     * @param global the global bundle context
+     * @param local the parent (local) service context
+     * @param policy the resolution policy
      */
     public PolicyServiceContext(BundleContext global, ServiceContext local, int policy) {
         m_global = global;
@@ -92,10 +105,12 @@
     }
 
     /**
-     * Add a service listener according to the policy.
-     * @param listener : the listener to add
-     * @param filter : LDAP filter
-     * @throws InvalidSyntaxException occurs when the filter is malformed.
+     * Adds a service listener according to the policy.
+     * Be aware, that the listener can be registered both in the local and in the global context
+     * if the {@link PolicyServiceContext#LOCAL_AND_GLOBAL} is used.
+     * @param listener the listener to add
+     * @param filter the LDAP filter
+     * @throws InvalidSyntaxException if the filter is malformed.
      * @see org.apache.felix.ipojo.ServiceContext#addServiceListener(org.osgi.framework.ServiceListener, java.lang.String)
      */
     public void addServiceListener(ServiceListener listener, String filter) throws InvalidSyntaxException {
@@ -109,8 +124,10 @@
     }
 
     /**
-     * Add a service listener according to the policy.
-     * @param listener : the listener to add
+     * Adds a service listener according to the policy.
+     * Be aware, that the listener can be registered both in the local and in the global context
+     * if the {@link PolicyServiceContext#LOCAL_AND_GLOBAL} is used.
+     * @param listener the listener to add
      * @see org.apache.felix.ipojo.ServiceContext#addServiceListener(org.osgi.framework.ServiceListener)
      */
     public void addServiceListener(ServiceListener listener) {
@@ -123,11 +140,13 @@
     }
 
     /**
-     * Get all service references. These reference are found inside the local registry, global registry or both according to the policy.
-     * @param clazz : required service specification.
-     * @param filter : LDAP filter
-     * @return the array of service reference, null if no service available
-     * @throws InvalidSyntaxException occurs when the LDAP filter is malformed 
+     * Gets all service references.
+     * These references are found inside the local registry, global registry or both according to the policy.
+     * The returned array can contain service references from both context.
+     * @param clazz the required service specification.
+     * @param filter the LDAP filter
+     * @return the array of service reference, <code>null</code> if no service available
+     * @throws InvalidSyntaxException if the LDAP filter is malformed 
      * @see org.apache.felix.ipojo.ServiceContext#getAllServiceReferences(java.lang.String, java.lang.String)
      */
     public ServiceReference[] getAllServiceReferences(String clazz,
@@ -147,8 +166,9 @@
     }
 
     /**
-     * Get the service object for the given reference.
-     * @param ref : the service reference
+     * Gets the service object for the given references.
+     * The service is get inside the context according to the policy.
+     * @param ref the service reference
      * @return the service object
      * @see org.apache.felix.ipojo.ServiceContext#getService(org.osgi.framework.ServiceReference)
      */
@@ -172,9 +192,10 @@
     }
 
     /**
-     * Get a service reference for the required service specification.
-     * @param clazz : the required service specification
-     * @return a service reference or null if not consistent service available
+     * Gets a service reference for the required service specification.
+     * The service is looked inside the context according to the policy.
+     * @param clazz the required service specification
+     * @return a service reference or <code>null</code> if no matching service available
      * @see org.apache.felix.ipojo.ServiceContext#getServiceReference(java.lang.String)
      */
     public ServiceReference getServiceReference(String clazz) {
@@ -197,10 +218,11 @@
 
     /**
      * Get a service reference for the required service specification.
-     * @param clazz : the required service specification
-     * @param filter : LDAP filter
-     * @return a service reference array or null if not consistent service available
-     * @throws InvalidSyntaxException occurs when the LDAP filter is malformed 
+     * The services are looked inside the context according to the policy.
+     * @param clazz the required service specification
+     * @param filter the LDAP filter
+     * @return a service reference array or <code>null</code> if not consistent service available
+     * @throws InvalidSyntaxException if the LDAP filter is malformed 
      * @see org.apache.felix.ipojo.ServiceContext#getServiceReference(java.lang.String)
      */
     public ServiceReference[] getServiceReferences(String clazz, String filter) throws InvalidSyntaxException {
@@ -220,10 +242,11 @@
     }
     
     /**
-     * Compute the service reference array from the two given set of service references.
-     * @param refLocal : local references
-     * @param refGlobal : global references
-     * @return the set of service reference
+     * Computes the service reference array from the two given set of service references
+     * according to the policy.
+     * @param refLocal the set of local references
+     * @param refGlobal the set of global references
+     * @return the set of service references
      */
     private ServiceReference[] computeServiceReferencesFromBoth(ServiceReference[] refLocal, ServiceReference[] refGlobal) {
         if (refLocal == null) {
@@ -240,31 +263,33 @@
 
     /**
      * This method is not supported.
-     * @param clazzes : specifications
-     * @param service : service object
-     * @param properties : service properties
-     * @return : the service registration object
+     * This context can only be used to resolve service dependencies.
+     * @param clazzes the specifications
+     * @param service the service object
+     * @param properties the service properties
+     * @return the service registration object
      * @see org.apache.felix.ipojo.ServiceContext#registerService(java.lang.String[], java.lang.Object, java.util.Dictionary)
      */
     public ServiceRegistration registerService(String[] clazzes, Object service, Dictionary properties) {
-        throw new UnsupportedOperationException("PolicyServiceContext can only be used for service dependency and not service providing");
+        throw new UnsupportedOperationException("PolicyServiceContext can only be used for service dependency and not to provide services");
     }
 
     /**
      * This method is not supported.
-     * @param clazz : specification
-     * @param service : service object
-     * @param properties : service properties
-     * @return : the service registration object
+     * This context can only be used to resolve service dependencies.
+     * @param clazz the specification
+     * @param service the service object
+     * @param properties the service properties to publish
+     * @return the service registration object
      * @see org.apache.felix.ipojo.ServiceContext#registerService(java.lang.String, java.lang.Object, java.util.Dictionary)
      */
     public ServiceRegistration registerService(String clazz, Object service, Dictionary properties) {
-        throw new UnsupportedOperationException("PolicyServiceContext can only be used for service dependency and not service providing");
+        throw new UnsupportedOperationException("PolicyServiceContext can only be used for service dependency and not to provide services");
     }
 
     /**
-     * Remove a service listener.
-     * @param listener : the service listener to remove
+     * Removes a service listener.
+     * @param listener the service listener to remove
      * @see org.apache.felix.ipojo.ServiceContext#removeServiceListener(org.osgi.framework.ServiceListener)
      */
     public void removeServiceListener(ServiceListener listener) {
@@ -277,9 +302,9 @@
     }
 
     /**
-     * Unget the service reference.
-     * @param reference : the service reference to unget.
-     * @return true if the unget is successful.
+     * Ungets the service reference.
+     * @param reference the service reference to unget.
+     * @return <code>true</code> if the service release if the reference is no more used.
      * @see org.apache.felix.ipojo.ServiceContext#ungetService(org.osgi.framework.ServiceReference)
      */
     public boolean ungetService(ServiceReference reference) {
@@ -291,7 +316,7 @@
     }
 
     /**
-     * Add a bundle listener.
+     * Adds a bundle listener.
      * Delegate on the global bundle context.
      * @param arg0 : bundle listener to add
      * @see org.osgi.framework.BundleContext#addBundleListener(org.osgi.framework.BundleListener)
@@ -301,8 +326,8 @@
     }
 
     /**
-     * Add a framework listener.
-     * Delegate on the global bundle context.
+     * Adds a framework listener.
+     * Delegates on the global bundle context.
      * @param arg0 : framework listener to add.
      * @see org.osgi.framework.BundleContext#addFrameworkListener(org.osgi.framework.FrameworkListener)
      */
@@ -311,10 +336,10 @@
     }
 
     /**
-     * Create a LDAP filter.
-     * @param arg0 : String-form of the filter
+     * Creates a LDAP filter.
+     * @param arg0 the String-form of the filter
      * @return the created filter object
-     * @throws InvalidSyntaxException : if the given argument is not a valid against the LDAP grammar.
+     * @throws InvalidSyntaxException if the given argument is not a valid against the LDAP grammar.
      * @see org.osgi.framework.BundleContext#createFilter(java.lang.String)
      */
     public Filter createFilter(String arg0) throws InvalidSyntaxException {
@@ -322,7 +347,7 @@
     }
 
     /**
-     * Get the current bundle.
+     * Gets the current bundle.
      * @return the current bundle
      * @see org.osgi.framework.BundleContext#getBundle()
      */
@@ -331,8 +356,8 @@
     }
 
     /**
-     * Get the bundle object with the given id.
-     * @param bundleId : bundle id
+     * Gets the bundle object with the given id.
+     * @param bundleId the bundle id
      * @return the bundle object
      * @see org.osgi.framework.BundleContext#getBundle(long)
      */
@@ -341,7 +366,7 @@
     }
 
     /**
-     * Get installed bundles.
+     * Gets installed bundles.
      * @return the list of installed bundles
      * @see org.osgi.framework.BundleContext#getBundles()
      */
@@ -351,8 +376,8 @@
 
 
     /**
-     * Get a data file.
-     * @param filename : File name.
+     * Gets a data file.
+     * @param filename the File name.
      * @return the File object
      * @see org.osgi.framework.BundleContext#getDataFile(java.lang.String)
      */
@@ -361,9 +386,10 @@
     }
 
     /**
-     * Get a property value.
-     * @param key : key of the asked property
-     * @return the property value (object) or null if no property are associated with the given key
+     * Gets a property value.
+     * @param key the key of the asked property
+     * @return the property value (object) or <code>null</code> if no property
+     * are associated with the given key
      * @see org.osgi.framework.BundleContext#getProperty(java.lang.String)
      */
     public String getProperty(String key) {
@@ -371,10 +397,10 @@
     }
 
     /**
-     * Install a bundle.
-     * @param location : URL of the bundle to install
+     * Installs a bundle.
+     * @param location the URL of the bundle to install
      * @return the installed bundle
-     * @throws BundleException : if the bundle cannot be installed correctly
+     * @throws BundleException if the bundle cannot be installed correctly
      * @see org.osgi.framework.BundleContext#installBundle(java.lang.String)
      */
     public Bundle installBundle(String location) throws BundleException {
@@ -382,11 +408,11 @@
     }
 
     /**
-     * Install a bundle.
-     * @param location : URL of the bundle to install
-     * @param input : 
+     * Installs a bundle.
+     * @param location the URL of the bundle to install
+     * @param input the input stream to load the bundle content
      * @return the installed bundle
-     * @throws BundleException : if the bundle cannot be installed correctly
+     * @throws BundleException if the bundle cannot be installed correctly
      * @see org.osgi.framework.BundleContext#installBundle(java.lang.String, java.io.InputStream)
      */
     public Bundle installBundle(String location, InputStream input) throws BundleException {
@@ -394,8 +420,8 @@
     }
 
     /**
-     * Remove a bundle listener.
-     * @param listener : the listener to remove
+     * Removes the bundle listener.
+     * @param listener the listener to remove
      * @see org.osgi.framework.BundleContext#removeBundleListener(org.osgi.framework.BundleListener)
      */
     public void removeBundleListener(BundleListener listener) {
@@ -403,8 +429,8 @@
     }
 
     /**
-     * Remove a framework listener.
-     * @param listener : the listener to remove
+     * Removes a framework listener.
+     * @param listener the listener to remove
      * @see org.osgi.framework.BundleContext#removeFrameworkListener(org.osgi.framework.FrameworkListener)
      */
     public void removeFrameworkListener(FrameworkListener listener) {

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/PrimitiveHandler.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/PrimitiveHandler.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/PrimitiveHandler.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/PrimitiveHandler.java Wed Oct  1 23:30:33 2008
@@ -20,148 +20,195 @@
 
 import java.lang.reflect.Method;
 
-import org.apache.felix.ipojo.metadata.Element;
 import org.apache.felix.ipojo.parser.PojoMetadata;
 import org.apache.felix.ipojo.util.Logger;
 
 
-
 /**
-* Abstract class to extends for primitive handler.
-* 
+* This class defines common mechanisms of primitive handlers.
+* Primitive handlers are handler composing the container of primitive
+* component instances (declared by the 'component' element inside the
+* iPOJO descriptor).
+* Note that this class also defines default method implementation.
+* Classes overriding this class can change the behavior of those methods.
 * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
 */
 public abstract class PrimitiveHandler extends Handler implements FieldInterceptor, MethodInterceptor {
     
     /**
-     * "Primitive" Handler type (value).
+     * The "Primitive" Handler type (value).
      */
     public static final String HANDLER_TYPE = "primitive";
     
     /**
-     * Reference on the instance manager.
+     * The reference on the instance manager.
      */
     private InstanceManager m_manager;
     
     
     /**
-     * Factory of the instance manager. 
+     * The factory of the instance manager. 
      */
     private ComponentFactory m_factory;
     
     /**
-     * Attach the current handler to the given instance.
-     * @param manager ! the instance on which the current handler will be attached.
+     * Attaches the current handler to the given instance.
+     * @param manager the instance on which the current handler will be attached.
      * @see org.apache.felix.ipojo.Handler#attach(org.apache.felix.ipojo.ComponentInstance)
      */
     protected final void attach(ComponentInstance manager) {
         m_manager = (InstanceManager) manager;
     }
     
+    /**
+     * Sets the factory of the managed instance.
+     * @param factory the factory 
+     * @see org.apache.felix.ipojo.Handler#setFactory(org.apache.felix.ipojo.Factory)
+     */
     public final void setFactory(Factory factory) {
         m_factory = (ComponentFactory) factory;
     }
     
+    /**
+     * gets the logger of the managed instance.
+     * @return the logger to use to log messages.
+     * @see org.apache.felix.ipojo.Handler#getLogger()
+     */
     public Logger getLogger() {
         return m_factory.getLogger();
     }
     
+    /**
+     * Gets the instance manager managing the instance.
+     * @return the instance manager
+     */
     public InstanceManager getInstanceManager() {
         return m_manager;
     }
     
+    /**
+     * Gets the factory which creates the managed instance.
+     * @return the factory which creates the managed instance.
+     */
     public ComponentFactory getFactory() {
         return m_factory;
     }
     
-    public Element[] getMetadata() {
-        return null;
-    }
-    
+    /**
+     * Gets the PojoMetadata of the content of the managed
+     * instance. This method allows getting manipulation
+     * metadata.
+     * @return the information about the content of the
+     * managed instance.
+     */
     public PojoMetadata getPojoMetadata() {
         return m_factory.getPojoMetadata();
     }
     
     /**
-     * Get a plugged handler of the same container.
-     * This method must be call only in the start method (or after). 
-     * In the configure method, this method can not return a consistent
-     * result as all handlers are not plugged. 
-     * @param name : name of the handler to find (class name or qualified handler name (ns:name)). 
-     * @return the handler object or null if the handler is not found.
+     * Gets a plugged handler of the same container.
+     * This method must be called only in the start method (or after). 
+     * In the configure method, this method can be inconsistent
+     * as all handlers are not initialized. 
+     * @param name the name of the handler to find (class name or qualified
+     * handler name (<code>ns:name</code>)). 
+     * @return the handler object or <code>null</code> if the handler is not found.
      */
     public final Handler getHandler(String name) {
         return m_manager.getHandler(name);
     }
     
     /**
-     * This method is called when a PUTFIELD operation is detected.
-     * @param pojo : the pojo object setting the value
-     * @param fieldName : the field name
-     * @param value : the value passed to the field
+     * Callback method called when a managed field 
+     * receives a new value. The given pojo can be
+     * null if the new value is set by another handler.
+     * This default implementation does nothing. 
+     * @param pojo the pojo object setting the value
+     * @param fieldName the field name
+     * @param value the value received by the field
+     * @see FieldInterceptor#onSet(Object, String, Object)
      */
     public void onSet(Object pojo, String fieldName, Object value) {
         // Nothing to do in the default implementation
     }
 
     /**
-     * This method is called when a GETFIELD operation is detected.
-     * @param pojo : the pojo object getting the value
-     * @param fieldName : the field name
-     * @param value : the value passed to the field (by the previous call)
-     * @return : the managed value of the field
+     * Callback method called when a managed field
+     * asks for a value.
+     * The default implementation returned the previously
+     * injected value.
+     * @param pojo the pojo object requiring the value
+     * @param fieldName the field name
+     * @param value the value passed to the field (by the previous call)
+     * @return the value to inject, of the previous value if the handler
+     * don't want to inject a value.
+     * @see FieldInterceptor#onGet(Object, String, Object)
      */
     public Object onGet(Object pojo, String fieldName, Object value) {
         return value;
     }
     
     /**
-     * This method is called when the execution enter in a method.
-     * @param pojo : pojo on which the method is called.
-     * @param method : method invoked.
-     * @param args arguments array.
+     * Callback method called when a method will be invoked.
+     * This default implementation does nothing. 
+     * @param pojo the pojo on which the method is called.
+     * @param method the method invoked.
+     * @param args the arguments array.
+     * @see MethodInterceptor#onEntry(Object, Method, Object[])
      */
     public void onEntry(Object pojo, Method method, Object[] args) { 
         // Nothing to do in the default implementation
     }
 
     /**
-     * This method is called when the execution exit a method (before a return or a throw).
-     * If the given returned object is null, either the method is void, either it returns null.
+     * Callback method called when a method ends.
+     * This method is called when a thread exits a method (before a return or a throw).
+     * If the given returned object is <code>null</code>, either the method is 
+     * <code>void</code>, or it returns <code>null</code>.
      * You must not modified the returned object.
-     * @param pojo : the pojo on which the method exits.
-     * @param method : exiting method.
-     * @param returnedObj : the returned object (boxed for primitive type)
+     * The default implementation does nothing.
+     * @param pojo the pojo on which the method exits.
+     * @param method the exiting method.
+     * @param returnedObj the returned object (boxed for primitive type)
+     * @see MethodInterceptor#onExit(Object, Method, Object)
      */
     public void onExit(Object pojo, Method method, Object returnedObj) { 
         // Nothing to do in the default implementation
     }
     
     /**
-     * This method is called when the execution throw an exception in the given method.
-     * @param pojo : the pojo on which the method was accessed.
-     * @param method : invoked method.
-     * @param throwable : the thrown exception
+     * Callback method called when an error occurs.
+     * This method is called when the execution throws an exception 
+     * in the given method.
+     * The default implementation does nothing.
+     * @param pojo the pojo on which the method was accessed.
+     * @param method the invoked method.
+     * @param throwable the thrown exception
+     * @see org.apache.felix.ipojo.MethodInterceptor#onError(java.lang.Object, java.lang.reflect.Method, java.lang.Throwable)
      */
     public void onError(Object pojo, Method method, Throwable throwable) {
         // Nothing to do in the default implementation
     }
     
     /**
-     * This method is called when the execution of a method will terminate : 
+     * Callback method called when the execution of a method will terminate : 
      * just before to throw an exception or before to return.
-     * OnError or OnExit was already called.
-     * @param pojo : the pojo on which the method was accessed.
-     * @param method : invoked method.
+     * {@link MethodInterceptor#onExit(Object, Method, Object)} or
+     * {@link MethodInterceptor#onError(Object, Method, Throwable)} 
+     * were already called.
+     * This default implementation does nothing.
+     * @param pojo the pojo on which the method was accessed.
+     * @param method the invoked method.
      */
     public void onFinally(Object pojo, Method method) {
         // Nothing to do in the default implementation
     }
     
     /**
-     * This method is called when an instance of the component is created, but
+     * Callback method called when an instance of the component is created, but
      * before someone can use it.
-     * @param instance : the created instance
+     * The default implementation does nothing.
+     * @param instance the created instance
      */
     public void onCreation(Object instance) { 
         // Nothing to do in the default implementation

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/ServiceContext.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/ServiceContext.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/ServiceContext.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/ServiceContext.java Wed Oct  1 23:30:33 2008
@@ -27,99 +27,123 @@
 import org.osgi.framework.ServiceRegistration;
 
 /**
- * A service context give the access the a service broker. All service
- * interaction should use this service context.
- * 
+ * A service context is the facade of a service registry. 
+ * It gives the access to a service broker. All service
+ * interactions should use a service context to garanty
+ * the service isolation.
+ * This class is a subset of {@link BundleContext} methods.
+ * (methods implying interactions with the service registry).
+ * So, refer to this class for further information.
+ * @see BundleContext
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public interface ServiceContext extends BundleContext {
 
     /**
-     * Add a service listener.
-     * @param listener : the service listener to add.
-     * @param filter : the LDAP filter
-     * @throws InvalidSyntaxException : occurs when the LDAP filter is malformed
+     * Adds a service listener.
+     * The listener is added to this service context.
+     * So only services from this context will be tracked.
+     * @param listener the service listener to add.
+     * @param filter the LDAP filter
+     * @throws InvalidSyntaxException if the LDAP filter is malformed
      * @see org.osgi.framework.BundleContext#addServiceListener(org.osgi.framework.ServiceListener, java.lang.String)
      */
     void addServiceListener(ServiceListener listener, String filter) throws InvalidSyntaxException;
 
     /**
-     * Add a service listener.
-     * @param listener : the service listener to add.
+     * Adds a service listener.
+     * The listener is added to this service context.
+     * So only services from this context will be tracked.
+     * @param listener the service listener to add.
      * @see org.osgi.framework.BundleContext#addServiceListener(org.osgi.framework.ServiceListener)
      */
     void addServiceListener(ServiceListener listener);
 
     /**
-     * Get the service references matching with the given query.
-     * @param clazz : Required interface
-     * @param filter : LDAP filter
-     * @return the array of available service reference
-     * @throws InvalidSyntaxException : occurs if the LDAP filter is malformed
+     * Gets the service references matching with the given query.
+     * The query is executed inside this service context.
+     * @param clazz the required interface
+     * @param filter a LDAP filter
+     * @return the array of available service references or <code>null</code>
+     * if no providers are available.
+     * @throws InvalidSyntaxException if the LDAP filter is malformed
      * @see org.osgi.framework.BundleContext#getAllServiceReferences(java.lang.String, java.lang.String)
      */
     ServiceReference[] getAllServiceReferences(String clazz, String filter) throws InvalidSyntaxException;
 
     /**
-     * Get a service object.
-     * @param reference : the required service reference 
+     * Gets a service object.
+     * The given service reference must comes from this
+     * service context.
+     * @param reference the required service reference 
      * @return the service object or null if the service reference is no more valid or if the service object is not accessible
      * @see org.osgi.framework.BundleContext#getService(org.osgi.framework.ServiceReference)
      */
     Object getService(ServiceReference reference);
 
     /**
-     * Get a service reference for the given interface.
-     * @param clazz : the required interface name
-     * @return a service reference on a available provider or null if no provider available
+     * Gets a service reference for the given interface.
+     * The query is executed inside this service context.
+     * @param clazz the required interface name
+     * @return a service reference on a available provider or 
+     * <code>null</code> if no providers are available
      * @see org.osgi.framework.BundleContext#getServiceReference(java.lang.String)
      */
     ServiceReference getServiceReference(String clazz);
 
     /**
-     * Get service reference list for the given query.
+     * Gets service reference list for the given query.
+     * The query is executed inside this service context.
      * @param clazz : the name of the required service interface
      * @param filter : LDAP filter to apply on service provider
-     * @return : the array of consistent service reference or null if no available provider
-     * @throws InvalidSyntaxException : occurs if the LDAP filter is malformed
+     * @return : the array of consistent service reference or <code>null</code>
+     * if no available providers
+     * @throws InvalidSyntaxException if the LDAP filter is malformed
      * @see org.osgi.framework.BundleContext#getServiceReferences(java.lang.String, java.lang.String)
      */
     ServiceReference[] getServiceReferences(String clazz, String filter) throws InvalidSyntaxException;
 
     /**
-     * Register a service.
-     * @param clazzes : interfaces provided by the service.
-     * @param service : the service object.
-     * @param properties : service properties.
+     * Registers a service inside this service context.
+     * This service is then isolated inside this context.
+     * @param clazzes the interfaces provided by the service.
+     * @param service the service object.
+     * @param properties service properties to publish
      * @return the service registration for this service publication.
+     * This service registration is attached to the current service context,
+     * and does not have any meaning in other contexts.
      * @see org.apache.felix.ipojo.ServiceContext#registerService(java.lang.String[], java.lang.Object, java.util.Dictionary)
      */
     ServiceRegistration registerService(String[] clazzes, Object service, Dictionary properties);
 
     /**
-     * Register a service.
-     * @param clazz : interface provided by the service.
-     * @param service : the service object.
-     * @param properties : service properties.
-     * @return the service registration for this service publication.
+     * Registers a service inside this service context.
+     * This service is then isolated inside this context.
+     * @param clazz the interface provided by the service.
+     * @param service the service object.
+     * @param properties service properties to publish.
+     * @return the service registration for this service publication. 
+     * This service registration is attached to the current service context,
+     * and does not have any meaning in other contexts.
      * @see org.osgi.framework.BundleContext#registerService(java.lang.String, java.lang.Object, java.util.Dictionary)
      */
     ServiceRegistration registerService(String clazz, Object service, Dictionary properties);
 
     /**
-     * Remove a service listener.
-     * @param listener : the listener to remove
+     * Removes a service listener.
+     * The listener must be registered inside this service context.
+     * @param listener the listener to remove
      * @see org.osgi.framework.BundleContext#removeServiceListener(org.osgi.framework.ServiceListener)
      */
     void removeServiceListener(ServiceListener listener);
 
     /**
-     * Unget the service reference.
-     * @param reference : the reference to unget
-     * @return true if you are the last user of the reference
+     * Ungets the service reference.
+     * The service reference must comes from this service context.
+     * @param reference the reference to unget
+     * @return <code>true</code> if you are the last user of the reference.
      * @see org.osgi.framework.BundleContext#ungetService(org.osgi.framework.ServiceReference)
      */
     boolean ungetService(ServiceReference reference);
 
-
 }

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/UnacceptableConfiguration.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/UnacceptableConfiguration.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/UnacceptableConfiguration.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/UnacceptableConfiguration.java Wed Oct  1 23:30:33 2008
@@ -20,7 +20,9 @@
 
 /**
  * UnacceptableConfiguration occurs when a factory refuses to create an
- * instance.
+ * instance. This exception is thrown when the instance configuration does not
+ * specify a value for a required property or when the configuration tries to override
+ * the value of an immutable property
  * 
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
@@ -32,8 +34,8 @@
     private static final long serialVersionUID = 2998931848886223965L;
 
     /**
-     * Constructor.
-     * @param message : message indicating the error.
+     * Creates an UnacceptableConfiguration.
+     * @param message : message about the error.
      */
     public UnacceptableConfiguration(String message) {
         super(message);

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/architecture/Architecture.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/architecture/Architecture.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/architecture/Architecture.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/architecture/Architecture.java Wed Oct  1 23:30:33 2008
@@ -20,14 +20,15 @@
 
 /**
  * Architecture service.
- * Allows to have information on the component.
+ * This service allows collecting information on the component instance,
+ * such as its state, plugged handlers ...
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public interface Architecture {
 
     /**
-     * Return the description of the instance.
-     * @return : the current component instance description
+     * Returns the description of the instance.
+     * @return the current component instance description
      */
     InstanceDescription getInstanceDescription();
 

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/FieldMetadata.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/FieldMetadata.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/FieldMetadata.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/FieldMetadata.java Wed Oct  1 23:30:33 2008
@@ -21,26 +21,29 @@
 import org.apache.felix.ipojo.metadata.Element;
 
 /**
- * A Field Metadata represent a field of an implementation class.
- * This class allow to avoid reflection to get the type and the name of a field.
+ * A Field Metadata represents a field of the implementation class.
+ * This class avoids using reflection to get the type and the name of a field.
  * 
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class FieldMetadata {
     
     /**
-     * Name of the field.
+     * The name of the field.
      */
     private String m_name;
     
     /**
-     * Type of the field. 
+     * The yype of the field. 
      */
     private String m_type;
     
     /**
-     * Constructor.
-     * @param metadata : field manipulation element.
+     * Creates a field metadata.
+     * This constructor is used when creating the {@link PojoMetadata}
+     * object.
+     * @param metadata the field manipulation element from Manipulation
+     * Metadata.
      */
     FieldMetadata(Element metadata) {
         m_name = metadata.getAttribute("name");
@@ -48,9 +51,12 @@
     }
     
     /**
-     * Constructor.
-     * @param field : field name.
-     * @param type : type of the field.
+     * Creates a field metadata.
+     * This constructor can be used to avoid using {@link PojoMetadata}.
+     * Be care that creating such {@link FieldMetadata} does not assert its 
+     * presence in the implementation class.
+     * @param field the field name.
+     * @param type the type of the field.
      */
     public FieldMetadata(String field, String type) {
         m_name = field;
@@ -62,10 +68,11 @@
     public String getFieldType() { return m_type; }
     
     /**
-     * Get the 'reflective' type of the given type.
+     * Gets the 'reflective' type of the given type.
      * The reflective type is the type used by the Java Reflection API.
-     * @param type : the type to analyze to find the Java reflective type.
-     * @return : the reflective type corresponding to this field.
+     * More precisely this method handles the array cases 
+     * @param type the type to analyze to find the Java reflective type.
+     * @return the reflective type corresponding to this field.
      */
     public static String getReflectionType(String type) {
         // Primitive Array 
@@ -83,9 +90,9 @@
     }
     
     /**
-     * Get the internal notation for primitive type.
-     * @param string : String form of the type
-     * @return the internal notation or null if not found
+     * Gets the internal notation for primitive type.
+     * @param string the String form of the type
+     * @return the internal notation or <code>null</code> if not found
      */
     public static String getInternalPrimitiveType(String string) {
         if (string.equalsIgnoreCase("boolean")) {
@@ -116,9 +123,10 @@
     }
     
     /**
-     * Get the iPOJO primitive type from the given primitive class.
-     * @param clazz : a primitive class
-     * @return the primitive type.
+     * Gets the iPOJO primitive type from the given primitive class.
+     * @param clazz the class of the primitive type
+     * @return the iPOJO primitive type name or <code>null</code> if
+     * not found.
      */
     public static String getPrimitiveTypeByClass(Class clazz) {
         if (clazz.equals(Boolean.TYPE)) {



Mime
View raw message