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 [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...
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)) {