Some (a lot of) cosmetic bug fix : format the javadoc.
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@697862 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/ComponentFactory.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/ComponentFactory.java
index a353bc3..a9d1319 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/ComponentFactory.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/ComponentFactory.java
@@ -40,51 +40,54 @@
/**
* The component factory manages component instance objects. This management
- * consist in creating and managing component instance build with the component
- * factory. This class could export Factory and ManagedServiceFactory services.
- *
+ * consists to create and manage component instances build with the current
+ * component factory. This class could export Factory and ManagedServiceFactory
+ * services.
+ * @see IPojoFactory
+ * @see TrackerCustomizer
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
public class ComponentFactory extends IPojoFactory implements TrackerCustomizer {
/**
- * Tracker used to track required handler factories.
+ * The tracker used to track required handler factories.
* Immutable once set.
*/
protected Tracker m_tracker;
/**
- * Class loader to delegate loading.
+ * The class loader to delegate classloading.
* Immutable once set.
*/
private FactoryClassloader m_classLoader;
/**
- * Component Implementation class.
+ * The component implementation class.
+ * (manipulated byte array)
*/
private byte[] m_clazz;
/**
- * Component Implementation Class Name.
+ * The component implementation qualified class name.
* Immutable once set.
- * This attribute is set during the construction of the factory.
+ * This attribute is set during the creation of the factory.
*/
private String m_classname;
/**
- * Manipulation Metadata of the internal POJO.
+ * The manipulation metadata of the implementation class.
* Immutable once set.
- * This attribute is set during the construction of the factory.
+ * This attribute is set during the creation of the factory.
*/
private PojoMetadata m_manipulation;
/**
- * Create a instance manager factory. The class is given in parameter. The
- * component type is not a composite.
- * @param context : bundle context
- * @param clazz : the component class
- * @param element : metadata of the component
- * @throws ConfigurationException occurs when the element describing the factory is malformed.
+ * Creates a instance manager factory.
+ * The class is given in parameter. The component type is not a composite.
+ * @param context the bundle context
+ * @param clazz the component class
+ * @param element the metadata of the component
+ * @throws ConfigurationException if the element describing the factory is malformed.
*/
public ComponentFactory(BundleContext context, byte[] clazz, Element element) throws ConfigurationException {
this(context, element);
@@ -93,25 +96,30 @@
/**
* Create a instance manager factory.
- * @param context : bundle context
- * @param element : metadata of the component to create
- * @throws ConfigurationException occurs when the element describing the factory is malformed.
+ * @param context the bundle context
+ * @param element the metadata of the component to create
+ * @throws ConfigurationException if element describing the factory is malformed.
*/
public ComponentFactory(BundleContext context, Element element) throws ConfigurationException {
super(context, element);
check(element); // NOPMD. This invocation is normal.
}
+ /**
+ * Gets the component type description of the current factory.
+ * @return the description of the component type attached to this factory.
+ * @see org.apache.felix.ipojo.IPojoFactory#getComponentTypeDescription()
+ */
public ComponentTypeDescription getComponentTypeDescription() {
return new PrimitiveTypeDescription(this);
}
/**
- * Check method : allows a factory to check if given element is well-formed.
- * A component factory metadata are correct if they contain the 'classname' attribute.
- * As this method is called from the (single-thread) constructor, no synchronization is needed.
- * @param element : the metadata
- * @throws ConfigurationException occurs when the element describing the factory is malformed.
+ * Allows a factory to check if the given element is well-formed.
+ * A component factory metadata is correct if they contain the 'classname' attribute.
+ * As this method is called from the (single-threaded) constructor, no synchronization is needed.
+ * @param element the metadata describing the component
+ * @throws ConfigurationException if the element describing the factory is malformed.
*/
public void check(Element element) throws ConfigurationException {
m_classname = element.getAttribute("classname");
@@ -132,11 +140,11 @@
/**
* Creates a primitive instance.
* This method is called when holding the lock.
- * @param config : instance configuration
- * @param context : service context.
- * @param handlers : handler to use
+ * @param config the instance configuration
+ * @param context the service context (null if the instance has to be created in the global space).
+ * @param handlers the handlers to attach to the instance
* @return the created instance
- * @throws org.apache.felix.ipojo.ConfigurationException : if the configuration process failed.
+ * @throws org.apache.felix.ipojo.ConfigurationException if the configuration process failed.
* @see org.apache.felix.ipojo.IPojoFactory#createInstance(java.util.Dictionary, org.apache.felix.ipojo.IPojoContext, org.apache.felix.ipojo.HandlerManager[])
*/
public ComponentInstance createInstance(Dictionary config, IPojoContext context, HandlerManager[] handlers) throws org.apache.felix.ipojo.ConfigurationException {
@@ -167,10 +175,13 @@
/**
* Defines a class.
- * This method need to be synchronized to avoid that the classloader is created twice.
- * @param name : qualified name of the class
- * @param clazz : byte array of the class
- * @param domain : protection domain of the class
+ * This method needs to be synchronized to avoid that the classloader
+ * is created twice.
+ * This method delegate the <code>define</code> method invocation to the
+ * factory classloader.
+ * @param name the qualified name of the class
+ * @param clazz the byte array of the class
+ * @param domain the protection domain of the class
* @return the defined class object
*/
public synchronized Class defineClass(String name, byte[] clazz, ProtectionDomain domain) {
@@ -182,20 +193,25 @@
/**
* Returns the URL of a resource.
- * @param resName : resource name
+ * This methods delegates the invocation to the
+ * {@link Bundle#getResource(String)} method.
+ * @param resName the resource name
* @return the URL of the resource
*/
public URL getResource(String resName) {
- //No synchronization needed, the context is immutable and the call is managed by the underlying framework.
+ //No synchronization needed, the context is immutable and
+ //the call is managed by the underlying framework.
return m_context.getBundle().getResource(resName);
}
/**
- * Loads a class.
- * @param className : name of the class to load
+ * Loads a class. This method checks if the class
+ * to load is the implementation class or not.
+ * If it is, the factory classloader is used, else
+ * the {@link Bundle#loadClass(String)} is called.
+ * @param className the name of the class to load
* @return the resulting Class object
- * @throws ClassNotFoundException
- * @throws ClassNotFoundException : happen when the class is not found
+ * @throws ClassNotFoundException if the class is not found
*/
public Class loadClass(String className) throws ClassNotFoundException {
if (m_clazz != null && m_classname.equals(className)) { // Immutable fields.
@@ -206,7 +222,7 @@
/**
* Starts the factory.
- * This method is called with the lock.
+ * This method is called when holding the monitor lock.
*/
public void starting() {
if (m_tracker != null) {
@@ -227,7 +243,7 @@
/**
* Stops all the instance managers.
- * This method is called with the lock.
+ * This method is called when holding the lock.
*/
public void stopping() {
if (m_tracker != null) {
@@ -237,8 +253,10 @@
}
/**
- * Computes the factory name.
- * This method does not manipulate any non-immutable fields, so does not need to be synchronized.
+ * Computes the factory name. The factory name is computed from
+ * the 'name' and 'classname' attributes.
+ * This method does not manipulate any non-immutable fields,
+ * so does not need to be synchronized.
* @return the factory name.
*/
public String getFactoryName() {
@@ -252,7 +270,8 @@
/**
* Computes required handlers.
- * This method does not manipulate any non-immutable fields, so does not need to be synchronized.
+ * This method does not manipulate any non-immutable fields,
+ * so does not need to be synchronized.
* @return the required handler list.
*/
public List getRequiredHandlerList() {
@@ -302,11 +321,12 @@
}
/**
- * A new handler factory is detected.
+ * This method is called when a new handler factory is detected.
* Test if the factory can be used or not.
- * This method need to be synchronized as it accesses to the content of required handlers.
- * @param reference : the new service reference.
- * @return true if the given factory reference match with a required handler.
+ * This method need to be synchronized as it accesses to the content
+ * of required handlers.
+ * @param reference the new service reference.
+ * @return <code>true</code> if the given factory reference matches with a required handler.
* @see org.apache.felix.ipojo.util.TrackerCustomizer#addingService(org.osgi.framework.ServiceReference)
*/
public synchronized boolean addingService(ServiceReference reference) {
@@ -327,9 +347,10 @@
}
/**
- * A matching service has been added to the tracker, we can no compute the factory state. This method is synchronized to avoid concurrent calls to
- * method modifying the factory state.
- * @param reference : added reference.
+ * This method is called when a matching service has been added to the tracker,
+ * we can no compute the factory state. This method is synchronized to avoid
+ * concurrent calls to method modifying the factory state.
+ * @param reference the added service reference.
* @see org.apache.felix.ipojo.util.TrackerCustomizer#addedService(org.osgi.framework.ServiceReference)
*/
public synchronized void addedService(ServiceReference reference) {
@@ -339,10 +360,11 @@
}
/**
- * A used factory disappears.
- * This method is synchronized to avoid concurrent calls to method modifying the factory state.
- * @param reference : service reference.
- * @param service : factory object.
+ * This method is called when a used handler factory disappears.
+ * This method is synchronized to avoid concurrent calls to method modifying
+ * the factory state.
+ * @param reference the leaving service reference.
+ * @param service the handler factory object.
* @see org.apache.felix.ipojo.util.TrackerCustomizer#removedService(org.osgi.framework.ServiceReference, java.lang.Object)
*/
public synchronized void removedService(ServiceReference reference, Object service) {
@@ -358,9 +380,11 @@
}
/**
- * A used handler factory is modified.
- * @param reference : the service reference
- * @param service : the Factory object (if already get)
+ * This method is called when a used handler factory is modified.
+ * However, handler factory modification is not possible, so this method
+ * is never called.
+ * @param reference the service reference
+ * @param service the Factory object (if already get)
* @see org.apache.felix.ipojo.util.TrackerCustomizer#modifiedService(org.osgi.framework.ServiceReference, java.lang.Object)
*/
public void modifiedService(ServiceReference reference, Object service) {
@@ -376,21 +400,25 @@
}
/**
- * FactoryClassloader.
+ * this class defines the classloader attached to a factory.
+ * This class loader is used to load the implementation (e.g. manipulated)
+ * class.
+ * @see ClassLoader
+ * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
private class FactoryClassloader extends ClassLoader {
/**
- * Map of defined classes [Name, Class Object].
+ * The map of defined classes [Name, Class Object].
*/
private final Map m_definedClasses = new HashMap();
/**
* The defineClass method.
- * @param name : name of the class
- * @param clazz : the byte array of the class
- * @param domain : the protection domain
- * @return : the defined class.
+ * @param name name of the class
+ * @param clazz the byte array of the class
+ * @param domain the protection domain
+ * @return the defined class.
*/
public Class defineClass(String name, byte[] clazz, ProtectionDomain domain) {
if (m_definedClasses.containsKey(name)) { return (Class) m_definedClasses.get(name); }
@@ -400,8 +428,8 @@
}
/**
- * Return the URL of the asked resource.
- * @param arg : the name of the resource to find.
+ * Returns the URL of the required resource.
+ * @param arg the name of the resource to find.
* @return the URL of the resource.
* @see java.lang.ClassLoader#getResource(java.lang.String)
*/
@@ -410,31 +438,38 @@
}
/**
- * Load the class.
+ * Loads the given class.
* @see java.lang.ClassLoader#loadClass(java.lang.String, boolean)
- * @param name : the name of the class
- * @param resolve : should be the class resolve now ?
- * @return : the loaded class
- * @throws ClassNotFoundException : the class to load is not found
+ * @param name the name of the class
+ * @param resolve should be the class resolve now ?
+ * @return the loaded class object
+ * @throws ClassNotFoundException if the class to load is not found
+ * @see java.lang.ClassLoader#loadClass(String, boolean)
*/
protected synchronized Class loadClass(String name, boolean resolve) throws ClassNotFoundException {
return m_context.getBundle().loadClass(name);
}
}
+ /**
+ * This class defines the description of primitive (non-composite) component
+ * types. An instance of this class will be returned when invoking the
+ * {@link ComponentFactory#getComponentDescription()} method.
+ * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
+ */
private final class PrimitiveTypeDescription extends ComponentTypeDescription {
/**
- * Constructor.
- * @param factory : the represented factory.
+ * Creates a PrimitiveTypeDescription object.
+ * @param factory the factory attached to this component type description.
*/
public PrimitiveTypeDescription(Factory factory) {
super(factory);
}
/**
- * Compute the properties to publish :
- * component.class contains the pojo class name.
+ * Computes the properties to publish.
+ * The <code>component.class</code> property contains the implementation class name.
* @return the dictionary of properties to publish
* @see org.apache.felix.ipojo.architecture.ComponentTypeDescription#getPropertiesToPublish()
*/
@@ -447,7 +482,7 @@
}
/**
- * Add the "implementation-class" attribute to the type description.
+ * Adds the "implementation-class" attribute to the type description.
* @return the component type description.
* @see org.apache.felix.ipojo.architecture.ComponentTypeDescription#getDescription()
*/
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/ComponentInstance.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/ComponentInstance.java
index 9b6c574..4f2ca74 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/ComponentInstance.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/ComponentInstance.java
@@ -24,13 +24,13 @@
import org.osgi.framework.BundleContext;
/**
- * The component instance class manages one instance of a component type.
+ * This class defines the iPOJO's component instance concept.
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
public interface ComponentInstance {
/**
- * Component Instance State : DISPOSED. The instance was destroyed.
+ * Component Instance State : DISPOSED. The component instance was disposed.
*/
int DISPOSED = -1;
@@ -41,87 +41,87 @@
int STOPPED = 0;
/**
- * Component Instance State : INVALID. The component is invalid when it
- * start or when a component dependency is invalid.
+ * Component Instance State : INVALID. The component instance is invalid when it
+ * starts or when a component dependency is invalid.
*/
int INVALID = 1;
/**
- * Component Instance State : VALID. The component is resolved when it is
- * running and all its component dependencies are valid.
+ * Component Instance State : VALID. The component instance is resolved when it is
+ * running and all its attached handlers are valid.
*/
int VALID = 2;
/**
- * Start the component instance.
+ * Starts the component instance.
*/
void start();
/**
- * Stop the component instance.
+ * Stops the component instance.
* A stopped instance can be re-started.
*/
void stop();
/**
- * Dispose the component instance.
+ * Disposes the component instance.
* A disposed instance cannot be re-started.
*/
void dispose();
/**
- * Return the actual state of the instance.
+ * Returns the actual state of the instance.
* @return the actual state of the component instance.
*/
int getState();
/**
- * Return the instance description.
+ * Returns the instance description.
* @return the instance description of the current instance
*/
InstanceDescription getInstanceDescription();
/**
- * Return the factory which create this instance.
+ * Returns the factory who created this instance.
* @return the factory of the component instance.
*/
ComponentFactory getFactory();
/**
- * Return the bundle context of this instance.
+ * Returns the bundle context of this instance.
* @return the context of the component instance
*/
BundleContext getContext();
/**
- * Return the name of the instance.
+ * Returns the name of the instance.
* @return the name of the component instance
*/
String getInstanceName();
/**
- * Check if the instance is started.
- * @return true if getState returns INVALID or VALID.
+ * Checks if the instance is started.
+ * @return <code>true</code> if {@link ComponentInstance#getState()}
+ * returns {@link ComponentInstance#INVALID} or {@link ComponentInstance#VALID}.
*/
boolean isStarted();
/**
- * Re-configure an instance. Do nothing if the instance does not support
+ * Re-configures an instance. Do nothing if the instance does not support
* dynamic reconfiguration. The reconfiguration does not stop the instance.
- *
- * @param configuration : the new configuration.
+ * @param configuration the new configuration.
*/
void reconfigure(Dictionary configuration);
/**
- * Add an instance state listener on the current instance.
- * @param listener : the listener to add.
+ * Adds an instance state listener on the current instance.
+ * @param listener the listener to add.
*/
void addInstanceStateListener(InstanceStateListener listener);
/**
- * Remove an instance state listener on the current instance.
- * @param listener : the listener to remove.
+ * Removes an instance state listener on the current instance.
+ * @param listener the listener to remove.
*/
void removeInstanceStateListener(InstanceStateListener listener);
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/ConfigurationException.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/ConfigurationException.java
index cde3140..0bed6f4 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/ConfigurationException.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/ConfigurationException.java
@@ -19,8 +19,9 @@
package org.apache.felix.ipojo;
/**
- * Configuration Exception.
+ * This class defines the exception thrown when an instance cannot be configured correctly.
* This exception occurs when component metadata are not correct.
+ * @see Exception
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
public class ConfigurationException extends Exception {
@@ -31,14 +32,16 @@
private static final long serialVersionUID = 1L;
/**
- * Component Type on which the error occurs.
+ * The component type on which the error occurs.
+ * Uses the factory name.
*/
private String m_type;
/**
- * Constructor.
- * @param mes : message
- * @param typ : component type
+ * Creates a new configuration exception.
+ * @param mes the error message
+ * @param typ the component type
+ * @see Exception#Exception(String)
*/
ConfigurationException(String mes, String typ) {
super(mes);
@@ -46,15 +49,16 @@
}
/**
- * Constructor.
- * @param mes : message
+ * Creates a new configuration exception.
+ * @param mes the error message
+ * @see Exception#Exception(String)
*/
public ConfigurationException(String mes) {
super(mes);
}
/**
- * Get the error message.
+ * Gets the error message.
* @return the error message.
* @see java.lang.Throwable#getMessage()
*/
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/ContextListener.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/ContextListener.java
index d592c5c..a2d0fa0 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/ContextListener.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/ContextListener.java
@@ -20,16 +20,18 @@
/**
- * Context Source Listener.
+ * Context Source Listener interface.
+ * A context source listener is notified when a monitored context
+ * property value changed.
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
public interface ContextListener {
/**
* A monitored value has been modified.
- * @param source : context source containing the property
- * @param property : modified property name
- * @param value : new value of the property
+ * @param source the context source containing the property
+ * @param property the modified property name
+ * @param value the new value of the property
*/
void update(ContextSource source, String property, Object value);
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/ContextSource.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/ContextSource.java
index e55f163..de9a8eb 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/ContextSource.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/ContextSource.java
@@ -23,34 +23,35 @@
/**
* Context Source service interface.
+ * A context source advertises of context changes.
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
public interface ContextSource {
/**
- * Get the current value of the given property.
- * @param property : property name
- * @return the property value, null if unknown
+ * Gets the current value of the given property.
+ * @param property property name
+ * @return the property value (<code>null</code> if unknown)
*/
Object getProperty(String property);
/**
- * Get the whole context.
+ * Gets the entire context.
* @return the dictionary [Property, Value]
*/
Dictionary getContext();
/**
- * Register a context listener on the given set of properties.
- * The listener will be notified of every change made on these properties.
- * @param listener : the context listener to register.
- * @param properties : property set monitored by the listener.
+ * Registers a context listener on the given set of properties.
+ * The listener will be notified of every changes made on monitored properties.
+ * @param listener the context listener to register.
+ * @param properties property set monitored by the listener.
*/
void registerContextListener(ContextListener listener, String[] properties);
/**
- * Unregister the given context listener.
- * @param listener : the listener to unregister.
+ * Unregisters the given context listener.
+ * @param listener the listener to unregister.
*/
void unregisterContextListener(ContextListener listener);
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/Factory.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/Factory.java
index a8bff35..84ccf65 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/Factory.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/Factory.java
@@ -32,108 +32,118 @@
public interface Factory {
/**
- * Factory State. A valid factory is a factory where all required handlers are available.
+ * Factory State.
+ * A valid factory is a factory where all required handlers are available.
*/
int VALID = 1;
/**
- * Factory State. An invalid factory is a factory where at least one required handler is unavailable. Creating an instance with an invalid factory failed.
+ * Factory State.
+ * An invalid factory is a factory where at least one required handler is
+ * unavailable. Creating an instance with an invalid factory failed.
*/
int INVALID = 0;
/**
- * Create an instance manager (i.e. component type instance).
- * @param configuration : the configuration properties for this component.
+ * Creates an instance manager (i.e. component type instance).
+ * @param configuration the configuration properties for this component.
* @return the created instance manager.
- * @throws UnacceptableConfiguration : when a given configuration is not valid.
- * @throws MissingHandlerException : when an handler is missing.
- * @throws ConfigurationException : when the instance configuration failed.
+ * @throws UnacceptableConfiguration if the given configuration is not valid.
+ * @throws MissingHandlerException if an handler is missing.
+ * @throws ConfigurationException if the instance configuration failed.
*/
ComponentInstance createComponentInstance(Dictionary configuration) throws UnacceptableConfiguration, MissingHandlerException, ConfigurationException;
/**
- * Create an instance manager (i.e. component type instance). This has these service interaction in the scope given in argument.
- * @param configuration : the configuration properties for this component.
- * @param serviceContext : the service context of the component.
+ * Creates an instance manager (i.e. component type instance).
+ * The instance is created in the scope given in argument.
+ * @param configuration the configuration properties for this component.
+ * @param serviceContext the service context of the component.
* @return the created instance manager.
- * @throws UnacceptableConfiguration : when the given configuration is not valid.
- * @throws MissingHandlerException : when an handler is missing.
- * @throws ConfigurationException : when the instance configuration failed.
+ * @throws UnacceptableConfiguration if the given configuration is not valid.
+ * @throws MissingHandlerException if an handler is missing.
+ * @throws ConfigurationException if the instance configuration failed.
*/
ComponentInstance createComponentInstance(Dictionary configuration, ServiceContext serviceContext) throws UnacceptableConfiguration, MissingHandlerException, ConfigurationException;
/**
- * Get the component type information containing provided service, configuration properties ...
+ * Gets the component type information containing provided service,
+ * configuration properties ...
* @return the component type information.
*/
Element getDescription();
/**
- * Get the component type description.
+ * Gets the component type description.
* @return the component type description object
*/
ComponentTypeDescription getComponentDescription();
/**
- * Check if the given configuration is acceptable as a configuration of a component instance.
- * @param conf : the configuration to test
- * @return true if the configuration is acceptable
+ * Checks if the given configuration is acceptable as a configuration
+ * of a component instance.
+ * @param conf the configuration to test
+ * @return <code>true</code> if the configuration is acceptable
*/
boolean isAcceptable(Dictionary conf);
/**
- * Return the factory name.
+ * Returns the factory name.
* @return the name of the factory.
*/
String getName();
/**
- * Reconfigure an instance already created. This configuration need to have the name property to identify the instance.
- * @param conf : the configuration to reconfigure the instance.
- * @throws UnacceptableConfiguration : if the given configuration is not consistent for the targeted instance.
- * @throws MissingHandlerException : when an handler is missing.
+ * Reconfigures an instance already created. This configuration needs to
+ * have the name property to identify the instance.
+ * @param conf the configuration to reconfigure the instance.
+ * @throws UnacceptableConfiguration if the given configuration is not consistent for the targeted instance.
+ * @throws MissingHandlerException if an handler is missing.
*/
void reconfigure(Dictionary conf) throws UnacceptableConfiguration, MissingHandlerException;
/**
- * Add a factory state listener on the current factory.
- * @param listener : the listener to add
+ * Adds a factory state listener on the current factory.
+ * @param listener the listener to add
*/
void addFactoryStateListener(FactoryStateListener listener);
/**
- * Remove the given factory state listener from the listener list.
- * @param listener : the listener to remove
+ * Removes the given factory state listener from the listener list.
+ * @param listener the listener to remove
*/
void removeFactoryStateListener(FactoryStateListener listener);
/**
- * Get the list of missing handlers.
- * @return the list containing the name of missing handlers (Name : namespace:name)
+ * Gets the list of missing handlers.
+ * The handlers are given under the form namespace:name
+ * @return the list containing the name of missing handlers
*/
List getMissingHandlers();
/**
* Get the list of required handlers.
- * @return the list containing the name of required handlers (Name : namespace:name)
+ * The handlers are given under the form namespace:name
+ * @return the list containing the name of required handlers
*/
List getRequiredHandlers();
/**
- * Return the classname of the component type.
+ * Returns the class name of the component type.
* For factories which does not contains a class, return "composite"
* @return the class name of the component type or "composite"
+ * @deprecated
*/
String getClassName();
/**
- * Return the state of the factory.
+ * Returns the state of the factory.
* @return the state of the factory
*/
int getState();
/**
- * Get the bundle context of the factory.
+ * Gets the bundle context of the factory.
* @return the bundle context of the factory.
*/
BundleContext getBundleContext();
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/FactoryStateListener.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/FactoryStateListener.java
index 1d3fb59..3d9dadd 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/FactoryStateListener.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/FactoryStateListener.java
@@ -19,17 +19,18 @@
package org.apache.felix.ipojo;
/**
- * Factory state listener.
+ * A factory state listener received notification about monitored factory state changes.
* This listener allows anyone to be notified when the listened factory state changes.
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
public interface FactoryStateListener {
/**
- * State change listener.
- * Each time an instance state change, this method is called.
- * @param factory : changing factory
- * @param newState : new instance state
+ * Notification listener.
+ * Each time an instance state changes, this method is called
+ * with the new factory state.
+ * @param factory the changing factory
+ * @param newState the new factory state
*/
void stateChanged(Factory factory, int newState);
}
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/FieldInterceptor.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/FieldInterceptor.java
index d8d4823..22e308d 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/FieldInterceptor.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/FieldInterceptor.java
@@ -19,28 +19,30 @@
package org.apache.felix.ipojo;
/**
-* Field interceptor.
-* A class implementing this interface is able to be notified of field accesses.
-* The listener need to be register on the instance manager.
-*
+* A field interceptor is notified when a monitored field asks for a value or
+* receives a new value. A class implementing this interface is able to be
+* notified of field accesses, and is able to inject a value to this field.
+* The listener needs to be register on the instance manager.
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
public interface FieldInterceptor {
/**
- * 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
+ * This method is called when a PUTFIELD operation is detected,
+ * e.g. an assignation.
+ * @param pojo the pojo object setting the value
+ * @param fieldName the field name
+ * @param value the value passed to the field
*/
void onSet(Object pojo, String fieldName, Object value);
/**
* 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
+ * This method allows to inject a value to the field.
+ * @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
*/
Object onGet(Object pojo, String fieldName, Object value);
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/Handler.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/Handler.java
index 42107af..5d96c33 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/Handler.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/Handler.java
@@ -27,50 +27,51 @@
/**
* Handler Abstract Class.
- *
+ * A handler is a 'piece' of
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
public abstract class Handler {
/**
- * Handler namespace property.
+ * The handler namespace property.
*/
public static final String HANDLER_NAMESPACE_PROPERTY = "handler.namespace";
/**
- * Handler name property.
+ * The handler name property.
*/
public static final String HANDLER_NAME_PROPERTY = "handler.name";
/**
- * Handler type property.
+ * The handler type property.
*/
public static final String HANDLER_TYPE_PROPERTY = "handler.type";
/**
- * Handler priority.
+ * The handler priority.
*/
public static final String HANDLER_LEVEL_PROPERTY = "handler.level";
/**
- * Handler validity.
+ * The current handler validity.
+ * This impacts directly the instance state.
*/
protected boolean m_isValid = true;
/**
- * HandlerManager managing the current handler.
+ * The HandlerManager managing the current handler.
*/
protected HandlerManager m_instance;
/**
- * Set the factory attached to this handler object.
+ * Sets the factory attached to this handler object.
* This method must be override to depend on each component factory type.
- * @param factory : the factory.
+ * @param factory the factory to attach.
*/
public abstract void setFactory(Factory factory);
/**
- * Get the logger to use in the handler.
+ * Gets the logger to use in the handler.
* This method must be override to depend on each component factory type logging policy.
* @return the logger.
*/
@@ -78,7 +79,8 @@
/**
* Log method (warning).
- * @param message : message to log
+ * Log a warning message to the handler logger.
+ * @param message the message to log
*/
public final void warn(String message) {
getLogger().log(Logger.WARNING, message);
@@ -86,15 +88,17 @@
/**
* Log method (error).
- * @param message : message to log
+ * Log an error message to the handler logger.
+ * @param message the message to log
*/
public final void error(String message) {
getLogger().log(Logger.ERROR, message);
}
/**
- * Log method (info).
- * @param message : message to log
+ * Log method (info).
+ * Log an info message to the handler logger.
+ * @param message the message to log
*/
public final void info(String message) {
getLogger().log(Logger.INFO, message);
@@ -102,8 +106,10 @@
/**
* Log method (warning).
- * @param message : message to log
- * @param exception : exception to attach to the message
+ * Log a warning message to the handler logger.
+ * The message is sent with an attached exception.
+ * @param message the message to log
+ * @param exception the exception to attach with the message
*/
public final void warn(String message, Throwable exception) {
getLogger().log(Logger.WARNING, message, exception);
@@ -111,8 +117,10 @@
/**
* Log method (error).
- * @param message : message to log
- * @param exception : exception to attach to the message
+ * Log an error message to the handler logger.
+ * The message is sent with an attached exception.
+ * @param message the message to log
+ * @param exception the exception to attach to the message
*/
public final void error(String message, Throwable exception) {
getLogger().log(Logger.ERROR, message, exception);
@@ -129,25 +137,25 @@
public abstract Handler getHandler(String name);
/**
- * Attach the current handler object to the given component instance.
+ * Attaches the current handler object to the given component instance.
* An attached handler becomes a part of the instance container.
- * @param instance : the component instance on which the current handler will be attached.
+ * @param instance the component instance on which the current handler will be attached.
*/
protected abstract void attach(ComponentInstance instance);
/**
- * Check if the current handler is valid.
- * This check test the handlers validity.
+ * Checks if the current handler is valid.
+ * This check tests the handler validity.
* This method must not be override.
- * @return true if the handler is valid.
+ * @return <code>true</code> if the handler is valid.
*/
public final boolean isValid() {
return ((Pojo) this).getComponentInstance().getState() == ComponentInstance.VALID;
}
/**
- * Set the validity of the current handler.
- * @param isValid : if true the handler becomes valid, else it becomes invalid.
+ * Sets the validity of the current handler.
+ * @param isValid if <code>true</code> the handler becomes valid, else it becomes invalid.
*/
public final void setValidity(boolean isValid) {
if (m_isValid != isValid) {
@@ -161,13 +169,17 @@
}
}
+ /**
+ * Is the current handler valid.
+ * @return <code>true</code> if the handler is valid, <code>false</code> otherwise.
+ */
public final boolean getValidity() {
return m_isValid;
}
/**
- * Get the component instance of the current handler.
- * @return : the component instance.
+ * Gets the component instance of the current handler.
+ * @return the component instance.
*/
public final HandlerManager getHandlerManager() {
if (m_instance != null) { return m_instance; }
@@ -176,55 +188,66 @@
}
/**
- * Initialize component factory.
- * This method aims to gather component factory properties. Each handler wanting to contribute need to override this
- * method and add properties to the given component description.
- * @param typeDesc : component description.
- * @param metadata : component type metadata.
- * @throws ConfigurationException : if the metadata are not correct (early detection).
+ * Initializes the component factory.
+ * This method aims to collect component factory properties.
+ * Each handler wanting to contribute needs to override this
+ * method and adds properties to the given component description.
+ * By default, this method does nothing.
+ * @param typeDesc the component description.
+ * @param metadata the component type metadata.
+ * @throws ConfigurationException if the metadata are not correct (early detection).
*/
public void initializeComponentFactory(ComponentTypeDescription typeDesc, Element metadata) throws ConfigurationException {
// The default implementation does nothing.
}
/**
- * Configure the handler.
- * @param metadata : the metadata of the component
- * @param configuration : the instance configuration
- * @throws ConfigurationException : if the metadata are not correct.
+ * Configures the handler.
+ * @param metadata the metadata of the component
+ * @param configuration the instance configuration
+ * @throws ConfigurationException if the metadata are not correct.
*/
public abstract void configure(Element metadata, Dictionary configuration) throws ConfigurationException;
/**
- * Stop the handler : stop the management.
+ * Stops the handler
+ * This method stops the management.
*/
public abstract void stop();
/**
- * Start the handler : start the management.
+ * Starts the handler
+ * This method starts the management.
*/
public abstract void start();
/**
* This method is called when the component state changed.
- * @param state : the new state
+ * By default, this method does nothing.
+ * @param state the new instance state {@link ComponentInstance}
*/
public void stateChanged(int state) {
// The default implementation does nothing.
}
/**
- * Return the current handler description.
+ * Returns the current handler description.
* The simplest description contains only the name and the validity of the handler.
- * @return the description of the handler..
+ * If the handler override this method, it can customize the description.
+ * By default, this method returns the simplest description.
+ * @return the description of the handler.
*/
public HandlerDescription getDescription() {
return new HandlerDescription(this);
}
/**
- * The instance is reconfiguring.
- * @param configuration : New instance configuration.
+ * Reconfigures the instance.
+ * This method is called, when the instance is under reconfiguration.
+ * The reconfiguration does not stops the instance, and so the handler supporting
+ * the reconfiguration must override this method and handles this case.
+ * By default, this method does nothing.
+ * @param configuration the new instance configuration.
*/
public void reconfigure(Dictionary configuration) {
// The default implementation does nothing.
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerFactory.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerFactory.java
index 1c30774..c4a969c 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerFactory.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerFactory.java
@@ -20,13 +20,16 @@
/**
- * Service interface published by handler factory.
+ * Service interface published by handler factory.
+ * This interface allows interacting the the handler factory to create
+ * {@link Handler} objects.
+ * @see Factory
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
public interface HandlerFactory extends Factory {
/**
- * iPOJO Default Namespace.
+ * The iPOJO Default Namespace.
*/
String IPOJO_NAMESPACE = "org.apache.felix.ipojo";
@@ -43,15 +46,15 @@
String getHandlerName();
/**
- * Gets the type of created handler.
+ * Gets the type of the handler factory.
* The handler can only be plugged on instance container with the same type.
- * Basically, types are primitive and composite.
- * @return the types of the handler
+ * Basically, types are <code>primitive</code> and <code>composite</code>.
+ * @return the type of the handler
*/
String getType();
/**
- * Gets the start level of the handlers created by this factory.
+ * Gets the start level of the handler objects created by this factory.
* Handlers with a low start level are configured and started before
* handlers with an higher start level. Moreover, these handlers are
* stopped and disposed after.
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerManager.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerManager.java
index b0f0c09..261055e 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerManager.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerManager.java
@@ -27,29 +27,28 @@
/**
* The handler manager manages an handler instance.
- *
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
public class HandlerManager extends InstanceManager {
/**
- * Handler object (contained).
+ * The internal handler object.
* Immutable once set.
*/
private Handler m_handler;
/**
- * Constructor.
- * @param factory : handler factory
- * @param context : bundle context
- * @param handlers : handler array
+ * Creates a handler manager.
+ * @param factory the handler factory
+ * @param context the bundle context
+ * @param handlers the handler array
*/
public HandlerManager(ComponentFactory factory, BundleContext context, HandlerManager[] handlers) {
super(factory, context, handlers);
}
/**
- * Get the contained handler object.
+ * Gets the contained handler object.
* If not already created it creates the object.
* @return the handler object.
*/
@@ -61,10 +60,10 @@
}
/**
- * Create and initialize the handler object.
- * @param instance : component instance on which the handler will be attached.
- * @param metadata : component metadata.
- * @param configuration : instance configuration.
+ * Creates and initializes the handler object.
+ * @param instance the component instance on which the handler will be attached.
+ * @param metadata the component metadata.
+ * @param configuration the instance configuration.
* @throws ConfigurationException if the handler configuration failed.
*/
public void init(ComponentInstance instance, Element metadata, Dictionary configuration) throws ConfigurationException {
@@ -75,7 +74,7 @@
}
/**
- * Create the handler object.
+ * Creates the handler object.
* This method does nothing if the object is already created.
* This method does not need locking protocol as only one thread (the creator thread) can create an instance.
*/
@@ -85,7 +84,7 @@
}
/**
- * Start the instance manager.
+ * Starts the instance manager.
*/
public void start() {
synchronized (this) {
@@ -119,7 +118,7 @@
}
/**
- * Stop the instance manager.
+ * Stops the instance manager.
*/
public void stop() {
synchronized (this) {
@@ -158,7 +157,7 @@
}
/**
- * Dispose the instance.
+ * Disposes the instance.
* @see org.apache.felix.ipojo.ComponentInstance#dispose()
*/
public void dispose() {
@@ -167,7 +166,7 @@
}
/**
- * Kill the current instance.
+ * Kills the current instance.
* Only the factory of this instance can call this method.
*/
protected void kill() {
@@ -178,8 +177,8 @@
/**
* State Change listener callback.
* This method is notified at each time a plugged handler becomes invalid.
- * @param instance : changing instance
- * @param newState : new state
+ * @param instance the changing instance
+ * @param newState the new state
* @see org.apache.felix.ipojo.InstanceStateListener#stateChanged(org.apache.felix.ipojo.ComponentInstance, int)
*/
public void stateChanged(ComponentInstance instance, int newState) {
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerManagerFactory.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerManagerFactory.java
index a0ba2fa..153ad66 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerManagerFactory.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerManagerFactory.java
@@ -35,27 +35,28 @@
public class HandlerManagerFactory extends ComponentFactory implements HandlerFactory {
/**
- * Handler type (composite|primitive).
+ * The Handler type (<code>composite</code> or <code>primitive</code>).
*/
private final String m_type;
/**
- * iPOJO Handler Namespace.
- * (Set the the iPOJO default namespace is not specified)
+ * The iPOJO Handler Namespace.
+ * (Uses the iPOJO default namespace is not specified)
*/
private final String m_namespace;
/**
- * Handler start level.
- * Lower level are priority are configured and started before higher level, and are stopped after.
+ * The handler start level.
+ * Lower levels are priority and so are configured and started
+ * before higher levels, and are stopped after.
*/
private final int m_level;
/**
* Creates a handler factory.
- * @param context : bundle context
- * @param metadata : metadata of the component to create
- * @throws ConfigurationException occurs when the element describing the factory is malformed.
+ * @param context the bundle context
+ * @param metadata the metadata of the component to create
+ * @throws ConfigurationException if the element describing the factory is malformed.
*/
public HandlerManagerFactory(BundleContext context, Element metadata) throws ConfigurationException {
super(context, metadata);
@@ -124,12 +125,11 @@
/**
* Creates an instance. The given configuration needs to contain the 'name'
* property. This method is called when holding the lock.
- * @param configuration : configuration of the created instance.
- * @param context : the service context to push for this instance.
- * @param handlers : handler array to used.
- * @return the created component instance.
- * not consistent with the component type of this factory.
- * @throws org.apache.felix.ipojo.ConfigurationException : when the instance configuration failed.
+ * @param configuration the configuration of the created instance.
+ * @param context the service context to push for this instance.
+ * @param handlers the handler array to attach to the instance.
+ * @return the created {@link HandlerManager}.
+ * @throws org.apache.felix.ipojo.ConfigurationException if the instance configuration failed.
* @see org.apache.felix.ipojo.Factory#createComponentInstance(java.util.Dictionary)
*/
public ComponentInstance createInstance(Dictionary configuration, IPojoContext context, HandlerManager[] handlers) throws ConfigurationException {
@@ -142,9 +142,9 @@
/**
* Computes required handlers. This method does not manipulate any
* non-immutable fields, so does not need to be synchronized.
- * This method is overridden to avoid to use the same detection rules
- * than atomic components. Indeed, architecture is disable by default,
- * and an handler is never immediate.
+ * This method is overridden to avoid using the same detection rules
+ * than 'primitive' components. Indeed, architecture is disable by default,
+ * and a handler is never immediate.
* @return the required handler list.
*/
public List getRequiredHandlerList() {
@@ -171,20 +171,28 @@
return list;
}
+ /**
+ * Defines the handler type description.
+ * @see ComponentDescription
+ */
private class HandlerTypeDescription extends ComponentTypeDescription {
/**
- * Constructor.
- * @param factory : factory.
+ * Creates the HandlerTypeDescription.
+ * @param factory the factory.
+ * @see ComponentTypeDescription#ComponentTypeDescription(Factory)
*/
public HandlerTypeDescription(Factory factory) {
super(factory);
}
/**
- * Add properties to publish :
- * handler.name, handler.namespace, handler.type and handler.level if the level is not Integer.MAX.
- * @return return the dictionary to publish.
+ * Add properties to publish.
+ * <li>handler.name</li>
+ * <li>handler.namespace</li>
+ * <li>handler.type</li>
+ * <li>handler.level if the level is not Integer.MAX</li>
+ * @return returns the dictionary to publish.
* @see org.apache.felix.ipojo.architecture.ComponentTypeDescription#getPropertiesToPublish()
*/
public Dictionary getPropertiesToPublish() {
diff --git a/ipojo/plugin/src/main/java/org/apache/felix/ipojo/plugin/ManipulatorMojo.java b/ipojo/plugin/src/main/java/org/apache/felix/ipojo/plugin/ManipulatorMojo.java
index a7391e1..a09e942 100644
--- a/ipojo/plugin/src/main/java/org/apache/felix/ipojo/plugin/ManipulatorMojo.java
+++ b/ipojo/plugin/src/main/java/org/apache/felix/ipojo/plugin/ManipulatorMojo.java
@@ -29,7 +29,7 @@
import org.apache.maven.project.MavenProjectHelper;
/**
- * Package an OSGi jar "bundle" as an "iPOJO bundle".
+ * Packages an OSGi jar "bundle" as an "iPOJO bundle".
*
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
* @version $Rev$, $Date$
@@ -66,7 +66,7 @@
private String m_jarName;
/**
- * Metadata file location.
+ * Location of the metadata file.
* @parameter alias="metadata" default-value="metadata.xml"
*/
private String m_metadata;
@@ -111,7 +111,7 @@
}
/**
- * Execute method : launch the pojoization.
+ * Execute method : this method launches the pojoization.
* @throws MojoExecutionException : an exception occurs during the manipulation.
* @see org.apache.maven.plugin.AbstractMojo#execute()
*/