felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From clem...@apache.org
Subject svn commit: r701012 [1/4] - in /felix/trunk/ipojo: core/src/main/java/org/apache/felix/ipojo/ core/src/main/java/org/apache/felix/ipojo/architecture/ core/src/main/java/org/apache/felix/ipojo/parser/ core/src/main/java/org/apache/felix/ipojo/util/ meta...
Date Thu, 02 Oct 2008 06:30:34 GMT
Author: clement
Date: Wed Oct  1 23:30:33 2008
New Revision: 701012

URL: http://svn.apache.org/viewvc?rev=701012&view=rev
Log:
Improves javadoc and fixes some cosmetic bugs

Modified:
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/Extender.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/IPojoContext.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/IPojoFactory.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/InstanceManager.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/InstanceStateListener.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/MethodInterceptor.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/MissingHandlerException.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/Nullable.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/Pojo.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/PolicyServiceContext.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/PrimitiveHandler.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/ServiceContext.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/UnacceptableConfiguration.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/architecture/Architecture.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/FieldMetadata.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ManifestMetadataParser.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/MethodMetadata.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ParseException.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ParseUtils.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/PojoMetadata.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Callback.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/DependencyModel.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/DependencyStateListener.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Logger.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Property.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/ServiceReferenceRankingComparator.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Tracker.java
    felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/util/TrackerCustomizer.java
    felix/trunk/ipojo/metadata/src/main/java/org/apache/felix/ipojo/metadata/Attribute.java
    felix/trunk/ipojo/metadata/src/main/java/org/apache/felix/ipojo/metadata/Element.java

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/Extender.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/Extender.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/Extender.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/Extender.java Wed Oct  1 23:30:33 2008
@@ -43,12 +43,22 @@
 
 /**
  * iPOJO Extender.
- * Looks for iPOJO Bundle and start the management of these bundles if needed.
+ * This class listens bundle arrivals and departures in order to detect and manage
+ * iPOJO powered bundles. This class creates factories and ask for instance creation.
+ * @see SynchronousBundleListener
+ * @see BundleActivator
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class Extender implements SynchronousBundleListener, BundleActivator {
 
     /**
+     * Enables the iPOJO internal dispatcher.
+     * This internal dispatcher helps the OSGi framework to support large
+     * scale applications. The internal dispatcher is disabled by default.
+     */
+    protected static final boolean DISPATCHER_ENABLED = false;
+    
+    /**
      * iPOJO Component Type and Instance declaration header.
      */
     private static final String IPOJO_HEADER = "iPOJO-Components";
@@ -59,46 +69,53 @@
     private static final String IPOJO_EXTENSION = "IPOJO-Extension";
 
     /**
-     * iPOJO Extender logger.
+     * The iPOJO Extender logger.
      */
     private Logger m_logger;
 
     /**
-     * iPOJO Bundle Context.
+     * The Bundle Context of the iPOJO Core bundle.
      */
     private BundleContext m_context;
 
     /**
-     * Declared instance manager.
+     * The instance creator used to create instances.
+     * (Singleton)
      */
     private InstanceCreator m_creator;
 
     /**
-     * iPOJO Bundle.
+     * The iPOJO Bundle.
      */
     private Bundle m_bundle;
 
     /**
-     * List of factory types.
+     * The list of factory types.
      */
     private List m_factoryTypes = new ArrayList();
 
     /**
-     * List of unbound types.
+     * The list of unbound types.
+     * A type is unbound if the matching extension is not deployed.
      */
     private final List m_unboundTypes = new ArrayList();
     
     /**
-     * Thread analyzing arriving bundles and creating iPOJO contributions.
+     * The thread analyzing arriving bundles and creating iPOJO contributions.
      */
     private final CreatorThread m_thread = new CreatorThread();
+    
+    /**
+     * The internal iPOJO dispatcher.
+     */
+    private EventDispatcher m_dispatcher;
 
     /**
      * Bundle Listener Notification.
-     * @param event : the bundle event.
+     * @param event the bundle event.
      * @see org.osgi.framework.BundleListener#bundleChanged(org.osgi.framework.BundleEvent)
      */
-    public synchronized void bundleChanged(BundleEvent event) {
+    public synchronized void bundleChanged(final BundleEvent event) {
         if (event.getBundle() == m_bundle) { return; }
 
         switch (event.getType()) {
@@ -117,8 +134,11 @@
     }
 
     /**
-     * Ends the iPOJO Management for the given bundle.
-     * @param bundle : the bundle.
+     * Ends the iPOJO Management for the given bundle. 
+     * Generally the bundle is leaving. This method
+     * stops every factories declared is the bundle and 
+     * disposed every declared instances.
+     * @param bundle the bundle.
      */
     private void closeManagementFor(Bundle bundle) {
         List toRemove = new ArrayList();
@@ -168,8 +188,9 @@
     }
 
     /**
-     * Check if the given bundle is an iPOJO bundle, and begin the iPOJO management is true.
-     * @param bundle : the bundle to check.
+     * Checks if the given bundle is an iPOJO bundle, and begin 
+     * the iPOJO management is true.
+     * @param bundle the bundle to check.
      */
     private void startManagementFor(Bundle bundle) {
         Dictionary dict = bundle.getHeaders();
@@ -193,9 +214,10 @@
     }
 
     /**
-     * Parse an IPOJO-Extension manifest header.
-     * @param bundle : bundle containing the header.
-     * @param header : header to parse.
+     * Parses an IPOJO-Extension manifest header and then creates
+     * iPOJO extensions (factory types).
+     * @param bundle the bundle containing the header.
+     * @param header the header to parse.
      */
     private void parseAbstractFactoryType(Bundle bundle, String header) {
         String[] arr = ParseUtils.split(header, ",");
@@ -224,11 +246,13 @@
     }
 
     /**
-     * Parse the internal metadata (from the manifest (in the iPOJO-Components property)).
-     * @param bundle : the owner bundle.
-     * @param components : iPOJO Header String.
-     * @throws IOException : the manifest could not be found
-     * @throws ParseException : the parsing process failed
+     * Parses the internal metadata (from the manifest 
+     * (in the iPOJO-Components property)). This methods
+     * creates factories and add instances to the instance creator.
+     * @param bundle the owner bundle.
+     * @param components The iPOJO Header String.
+     * @throws IOException if the manifest can not be found
+     * @throws ParseException if the parsing process failed
      */
     private void parse(Bundle bundle, String components) throws IOException, ParseException {
         ManifestMetadataParser parser = new ManifestMetadataParser();
@@ -246,8 +270,8 @@
     }
 
     /**
-     * iPOJO Starting method.
-     * @param context : iPOJO bundle context.
+     * iPOJO Start method.
+     * @param context the iPOJO bundle context.
      * @see org.osgi.framework.BundleActivator#start(org.osgi.framework.BundleContext)
      */
     public void start(BundleContext context) {
@@ -256,6 +280,9 @@
         m_creator = new InstanceCreator(context);
 
         m_logger = new Logger(m_context, "IPOJO-Extender");
+        
+        m_dispatcher = new EventDispatcher(context);
+        m_dispatcher.start();
 
         // Begin by initializing core handlers
         startManagementFor(m_bundle);
@@ -275,13 +302,14 @@
     }
 
     /**
-     * Stop the iPOJO Management.
-     * @param context : bundle context.
+     * Stops the iPOJO Bundle.
+     * @param context the bundle context.
      * @see org.osgi.framework.BundleActivator#stop(org.osgi.framework.BundleContext)
      */
     public void stop(BundleContext context) {
         m_thread.stop(); // Stop the thread processing bundles.
         m_context.removeBundleListener(this);
+        m_dispatcher.stop();
 
         for (int k = 0; k < m_factoryTypes.size(); k++) {
             ManagedAbstractFactoryType mft = (ManagedAbstractFactoryType) m_factoryTypes.get(k);
@@ -305,9 +333,9 @@
     }
 
     /**
-     * Add a component factory to the factory list.
-     * @param metadata : the new component metadata.
-     * @param bundle : the bundle.
+     * Adds a component factory to the factory list.
+     * @param metadata the new component metadata.
+     * @param bundle the bundle.
      */
     private void createAbstractFactory(Bundle bundle, Element metadata) {
         ManagedAbstractFactoryType factoryType = null;
@@ -376,30 +404,30 @@
      */
     private final class ManagedAbstractFactoryType {
         /**
-         * Type (i.e.) name of the extension.
+         * The type (i.e.) name of the extension.
          */
         String m_type;
 
         /**
-         * Abstract Factory class.
+         * The abstract Factory class.
          */
         Class m_clazz;
 
         /**
-         * Bundle object containing the declaration of the extension.
+         * The bundle object containing the declaration of the extension.
          */
         Bundle m_bundle;
 
         /**
-         * Factories created by this extension. 
+         * The factories created by this extension. 
          */
         private Map m_created;
 
         /**
-         * Constructor.
-         * @param factory : abstract factory class.
-         * @param type : name of the extension.
-         * @param bundle : bundle declaring the extension.
+         * Creates a ManagedAbstractFactoryType.
+         * @param factory the abstract factory class.
+         * @param type the name of the extension.
+         * @param bundle the bundle declaring the extension.
          */
         protected ManagedAbstractFactoryType(Class factory, String type, Bundle bundle) {
             m_bundle = bundle;
@@ -409,30 +437,30 @@
     }
 
     /**
-     * Structure storing unbound component type declaration.
-     * Unbound means that there is no extension able to manage it.
+     * Structure storing unbound component type declarations.
+     * Unbound means that there is no extension able to manage the extension.
      */
     private final class UnboundComponentType {
         /**
-         * Component type description.
+         * The component type description.
          */
         private final Element m_description;
 
         /**
-         * Bundle declaring this type.
+         * The bundle declaring this type.
          */
         private final Bundle m_bundle;
 
         /**
-         * Required extension name.
+         * The required extension name.
          */
         private final String m_type;
 
         /**
-         * Constructor.
-         * @param description : description of the component type.
-         * @param bundle : bundle declaring this type.
-         * @param type : required extension name.
+         * Creates a UnboundComponentType.
+         * @param description the description of the component type.
+         * @param bundle the bundle declaring this type.
+         * @param type the required extension name.
          */
         protected UnboundComponentType(String type, Element description, Bundle bundle) {
             m_type = type;
@@ -442,8 +470,8 @@
     }
 
     /**
-     * Compute the bundle context from the bundle class by introspection.
-     * @param bundle : bundle.
+     * Computes the bundle context from the bundle class by introspection.
+     * @param bundle the bundle.
      * @return the bundle context object or null if not found.
      */
     public BundleContext getBundleContext(Bundle bundle) {
@@ -513,7 +541,7 @@
     
 
     /**
-     * The creator thread analyze arriving bundle to create iPOJO contribution.
+     * The creator thread analyzes arriving bundles to create iPOJO contribution.
      */
     private class CreatorThread implements Runnable {
 
@@ -523,14 +551,14 @@
         private boolean m_started = true;
         
         /**
-         * List of bundle that are going to be analyzed.
+         * The list of bundle that are going to be analyzed.
          */
         private List m_bundles = new ArrayList();
         
         /**
-         * A bundle is arrived.
+         * A bundle is arriving.
          * This method is synchronized to avoid concurrent modification of the waiting list.
-         * @param bundle : new bundle
+         * @param bundle the new bundle
          */
         public synchronized void addBundle(Bundle bundle) {
             m_bundles.add(bundle);
@@ -542,14 +570,14 @@
          * A bundle is leaving.
          * If the bundle was not already processed, the bundle is remove from the waiting list.
          * This method is synchronized to avoid concurrent modification of the waiting list.
-         * @param bundle : the leaving bundle.
+         * @param bundle the leaving bundle.
          */
         public synchronized void removeBundle(Bundle bundle) {
             m_bundles.remove(bundle);
         }
         
         /**
-         * Stop the creator thread.
+         * Stops the creator thread.
          */
         public synchronized void stop() {
             m_started = false;
@@ -558,10 +586,10 @@
         }
 
         /**
-         * Creator thread run method.
-         * While the waiting list is not empty, the thread launch the bundle analyzing.
+         * Creator thread's run method.
+         * While the list is not empty, the thread launches the bundle analyzing on the next bundle.
          * When the list is empty, the thread sleeps until the arrival of a new bundle 
-         * or that iPOJO stops.
+         * or until iPOJO stops.
          * @see java.lang.Runnable#run()
          */
         public void run() {

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/IPojoContext.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/IPojoContext.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/IPojoContext.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/IPojoContext.java Wed Oct  1 23:30:33 2008
@@ -26,6 +26,7 @@
 import org.osgi.framework.BundleContext;
 import org.osgi.framework.BundleException;
 import org.osgi.framework.BundleListener;
+import org.osgi.framework.Constants;
 import org.osgi.framework.Filter;
 import org.osgi.framework.FrameworkListener;
 import org.osgi.framework.InvalidSyntaxException;
@@ -36,45 +37,61 @@
 /**
  * The iPOJO Context is a BundleContext implementation allowing the separation
  * between Bundle context and Service (Bundle) Context.
- * 
+ * This is used inside composition to differentiate the classloading context (i.e.
+ * Bundle) and the service registry access.
+ * This class delegates calls to the good internal context (either the BundleContext
+ * or the ServiceContext) according to the method. If the instance does not have a valid
+ * service context, the bundle context is always used. 
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class IPojoContext implements BundleContext, ServiceContext {
 
     /**
-     * BundleContext used to access bundle method.
+     * The bundleContext used to access bundle methods.
      */
     private BundleContext m_bundleContext;
 
     /**
-     * Service Context used to access service interaction.
+     * The service context used to access to the service registry.
      */
     private ServiceContext m_serviceContext;
+    
+    /**
+     * The internal event dispatcher used to avoid the multiplication
+     * of service listeners. The dispatcher is only used when the service context is
+     * not specified and if the internal dispatching is enabled ({@link Extender#DISPATCHER_ENABLED}
+     */
+    private EventDispatcher m_dispatcher;
 
     /**
-     * Constructor. Used when the service context = the bundle context
-     * 
-     * @param context : bundle context
+     * Creates an iPOJO Context.
+     * No service context is specified.
+     * This constructor is used when the
+     * instance lives in the global context.
+     * @param context the bundle context
      */
     public IPojoContext(BundleContext context) {
         m_bundleContext = context;
+        m_dispatcher = EventDispatcher.getDispatcher();
     }
 
     /**
-     * Constructor. Used when the service context and the bundle context are
-     * different
-     * 
-     * @param bundleContext : bundle context
-     * @param serviceContext : service context
+     * Creates an iPOJO Context.
+     * A service context is used to refer to the
+     * service registry. The service context will be 
+     * used for all service accesses.
+     * @param bundleContext the bundle context
+     * @param serviceContext the service context
      */
     public IPojoContext(BundleContext bundleContext, ServiceContext serviceContext) {
         m_bundleContext = bundleContext;
         m_serviceContext = serviceContext;
+        m_dispatcher = EventDispatcher.getDispatcher();
     }
 
     /**
-     * Add a bundle listener.
-     * @param listener : the listener to add
+     * Adds a bundle listener.
+     * @param listener the listener to add
      * @see org.osgi.framework.BundleContext#addBundleListener(org.osgi.framework.BundleListener)
      */
     public void addBundleListener(BundleListener listener) {
@@ -82,8 +99,8 @@
     }
 
     /**
-     * Add a framework listener.
-     * @param listener : the listener object to add
+     * Adds a framework listener.
+     * @param listener the listener object to add
      * @see org.osgi.framework.BundleContext#addFrameworkListener(org.osgi.framework.FrameworkListener)
      */
     public void addFrameworkListener(FrameworkListener listener) {
@@ -91,15 +108,30 @@
     }
 
     /**
-     * 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.
+     * This methods registers the listener on the service context
+     * if it specified. Otherwise, if the internal dispatcher is enabled,
+     * it registers the listener inside the internal dispatcher (if
+     * the filter match against the iPOJO Filter format 
+     * {@link IPojoContext#match(String)}). Finally, if the internal 
+     * dispatcher is disabled, it uses the "regular" bundle context.
+     * @param listener the service listener to add.
+     * @param filter the LDAP filter
+     * @throws InvalidSyntaxException if LDAP filter is malformed
      * @see org.osgi.framework.BundleContext#addServiceListener(org.osgi.framework.ServiceListener, java.lang.String)
      */
     public void addServiceListener(ServiceListener listener, String filter) throws InvalidSyntaxException {
         if (m_serviceContext == null) {
-            m_bundleContext.addServiceListener(listener, filter);
+            if (Extender.DISPATCHER_ENABLED) {
+                String itf = match(filter);
+                if (itf != null) {
+                    m_dispatcher.addListener(itf, listener);
+                } else {
+                    m_bundleContext.addServiceListener(listener, filter);
+                }
+            } else {
+                m_bundleContext.addServiceListener(listener, filter);
+            }
         } else {
             m_serviceContext.addServiceListener(listener, filter);
         }
@@ -107,7 +139,9 @@
 
     /**
      * Add a service listener.
-     * @param listener : the service listener to add.
+     * This methods registers the listener on the service context
+     * if it specified. Otherwise, it uses the "regular" bundle context.
+     * @param listener the service listener to add.
      * @see org.osgi.framework.BundleContext#addServiceListener(org.osgi.framework.ServiceListener)
      */
     public void addServiceListener(ServiceListener listener) {
@@ -117,12 +151,31 @@
             m_serviceContext.addServiceListener(listener);
         }
     }
+    
+    /**
+     * This method checks if the filter matches with the iPOJO
+     * filter format: <code>(OBJECTCLASS=$ITF)</code>. It tries
+     * to extract the required interface (<code>$ITF</code>).
+     * @param filter the filter to analyze
+     * @return the required interface or <code>null</code>
+     * if the filter doesn't match with the iPOJO format.
+     */
+    private String match(String filter) {
+        if (filter != null && filter.startsWith("(" + Constants.OBJECTCLASS + "=") // check the beginning (OBJECTCLASS
+            && filter.lastIndexOf(')') == filter.indexOf(')')) { // check that there is only one )
+            return filter.substring(("(" + Constants.OBJECTCLASS + "=").length(), filter.length() - 1);
+        }
+        return null;
+    }
+    
+    
 
     /**
-     * Create a Filter object.
-     * @param filter : the string form of the LDAP filter to create
-     * @return the Filter object.
-     * @throws InvalidSyntaxException : occurs when the given filter is malformed
+     * Creates a filter objects.
+     * This method always uses the bundle context.
+     * @param filter the string form of the LDAP filter to create
+     * @return the filter object.
+     * @throws InvalidSyntaxException if the given filter is malformed
      * @see org.osgi.framework.BundleContext#createFilter(java.lang.String)
      */
     public Filter createFilter(String filter) throws InvalidSyntaxException {
@@ -130,11 +183,13 @@
     }
 
     /**
-     * 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.
+     * Uses the service context if specified, used the bundle context
+     * otherwise.
+     * @param clazz the required interface
+     * @param filter the LDAP filter
+     * @return the array of available service references
+     * @throws InvalidSyntaxException if the LDAP filter is malformed
      * @see org.osgi.framework.BundleContext#getAllServiceReferences(java.lang.String, java.lang.String)
      */
     public ServiceReference[] getAllServiceReferences(String clazz, String filter) throws InvalidSyntaxException {
@@ -146,8 +201,9 @@
     }
 
     /**
-     * Get the current bundle.
-     * @return the current bundle
+     * Gets the current bundle object.
+     * @return the bundle declaring the component type of the instance
+     * using the current IPojoContext.
      * @see org.osgi.framework.BundleContext#getBundle()
      */
     public Bundle getBundle() {
@@ -155,8 +211,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)
      */
@@ -165,7 +221,7 @@
     }
 
     /**
-     * Get installed bundles.
+     * Gets installed bundles.
      * @return the list of installed bundles
      * @see org.osgi.framework.BundleContext#getBundles()
      */
@@ -174,8 +230,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)
      */
@@ -184,9 +240,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) {
@@ -194,9 +251,14 @@
     }
 
     /**
-     * Get a service object.
-     * @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
+     * Gets a service object.
+     * The given service reference must come from the same context than
+     * where the service is get.
+     * This method uses the service context if specified, the bundle
+     * context otherwise.
+     * @param reference the required service reference 
+     * @return the service object or <code>null</code> 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)
      */
     public Object getService(ServiceReference reference) {
@@ -208,9 +270,12 @@
     }
 
     /**
-     * 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.
+     * This method uses the service context if specified, the bundle
+     * context otherwise.
+     * @param clazz the required interface name
+     * @return a service reference on a available provider or <code>null</code>
+     * if no providers available
      * @see org.osgi.framework.BundleContext#getServiceReference(java.lang.String)
      */
     public ServiceReference getServiceReference(String clazz) {
@@ -222,11 +287,14 @@
     }
 
     /**
-     * Get service reference list for the given query.
-     * @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
+     * Gets service reference list for the given query.
+     * This method uses the service context if specified, the bundle
+     * context otherwise.
+     * @param clazz the name of the required service interface
+     * @param filter the LDAP filter to apply on service provider
+     * @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)
      */
     public ServiceReference[] getServiceReferences(String clazz, String filter) throws InvalidSyntaxException {
@@ -238,10 +306,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 {
@@ -249,11 +317,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.
      * @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 {
@@ -261,10 +329,13 @@
     }
 
     /**
-     * Register a service.
-     * @param clazzes : interfaces provided by the service.
-     * @param service : the service object.
-     * @param properties : service properties.
+     * Registers a service.
+     * This method uses the service context if specified (and so, registers
+     * the service in this service registry), the bundle context otherwise (the
+     * service will be available to every global instances).
+     * @param clazzes the interfaces provided by the service.
+     * @param service the service object.
+     * @param properties the service properties to publish
      * @return the service registration for this service publication.
      * @see org.apache.felix.ipojo.ServiceContext#registerService(java.lang.String[], java.lang.Object, java.util.Dictionary)
      */
@@ -277,10 +348,13 @@
     }
 
     /**
-     * Register a service.
-     * @param clazz : interface provided by the service.
-     * @param service : the service object.
-     * @param properties : service properties.
+     * Registers a service.
+     * This method uses the service context if specified (and so, registers
+     * the service in this service registry), the bundle context otherwise (the
+     * service will be available to every global instances).
+     * @param clazz the interface provided by the service.
+     * @param service the the service object.
+     * @param properties the service properties to publish.
      * @return the service registration for this service publication.
      * @see org.osgi.framework.BundleContext#registerService(java.lang.String, java.lang.Object, java.util.Dictionary)
      */
@@ -293,8 +367,8 @@
     }
 
     /**
-     * Remove a bundle listener.
-     * @param listener : the listener to remove
+     * Removes a bundle listener.
+     * @param listener the listener to remove
      * @see org.osgi.framework.BundleContext#removeBundleListener(org.osgi.framework.BundleListener)
      */
     public void removeBundleListener(BundleListener listener) {
@@ -302,8 +376,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) {
@@ -311,23 +385,29 @@
     }
 
     /**
-     * Remove a service listener.
-     * @param listener : the service listener to remove
+     * Removes a service listener.
+     * Removes the service listener from where it was registered so either in
+     * the global context, or in the service context or in the internal dispatcher.
+     * @param listener the service listener to remove
      * @see org.apache.felix.ipojo.ServiceContext#removeServiceListener(org.osgi.framework.ServiceListener)
      * @see org.osgi.framework.BundleContext#removeServiceListener(org.osgi.framework.ServiceListener)
      */
     public void removeServiceListener(ServiceListener listener) {
         if (m_serviceContext == null) {
-            m_bundleContext.removeServiceListener(listener);
+            if (! Extender.DISPATCHER_ENABLED || ! m_dispatcher.removeListener(listener)) {
+                m_bundleContext.removeServiceListener(listener);
+            }
         } else {
             m_serviceContext.removeServiceListener(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.
+     * This method uses the service context if specified, 
+     * the bundle context otherwise.
+     * @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)
      */
     public boolean ungetService(ServiceReference reference) {
@@ -339,7 +419,7 @@
     }
 
     /**
-     * Get the global context, i.e. the bundle context of the factory.
+     * Gets the global context, i.e. the bundle context of the factory.
      * @return the global bundle context.
      */
     public BundleContext getGlobalContext() {
@@ -347,8 +427,10 @@
     }
 
     /**
-     * Get the service context, i.e. the composite context.
-     * @return the service context.
+     * Gets the service context, i.e. the composite context.
+     * Returns <code>null</code> if the instance does not live
+     * inside a composite.
+     * @return the service context or <code>null</code>.
      */
     public ServiceContext getServiceContext() {
         return m_serviceContext;

Modified: felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/IPojoFactory.java
URL: http://svn.apache.org/viewvc/felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/IPojoFactory.java?rev=701012&r1=701011&r2=701012&view=diff
==============================================================================
--- felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/IPojoFactory.java (original)
+++ felix/trunk/ipojo/core/src/main/java/org/apache/felix/ipojo/IPojoFactory.java Wed Oct  1 23:30:33 2008
@@ -37,7 +37,10 @@
 import org.osgi.service.cm.ManagedServiceFactory;
 
 /**
- * This class abstracts iPOJO factories.
+ * This class defines common mechanisms of iPOJO component factories
+ * (i.e. component type).
+ * This class implements both the Factory and ManagedServiceFactory
+ * services.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public abstract class IPojoFactory implements Factory, ManagedServiceFactory {
@@ -47,22 +50,25 @@
      */
 
     /**
-     * List of the managed instance name. This list is shared by all factories.
+     * The list of the managed instance name.
+     * This list is shared by all factories and is
+     * used to assert name unicity.
      */
     protected static List m_instancesName = new ArrayList();
 
     /**
-     * Component-Type description exposed by the factory service.
+     * The component type description exposed by the {@link Factory} service.
      */
     protected ComponentTypeDescription m_componentDesc;
 
     /**
-     * List of the managed instance managers. The key of this map is the name (i.e. instance names) of the created instance
+     * The list of the managed instance managers. 
+     * The key of this map is the name (i.e. instance names) of the created instance
      */
     protected final Map m_componentInstances = new HashMap();
 
     /**
-     * Component Type provided by this factory.
+     * The component type metadata.
      */
     protected final Element m_componentMetadata;
 
@@ -72,56 +78,69 @@
     protected final BundleContext m_context;
 
     /**
-     * Factory Name. Could be the component class name if the factory name is not set.
+     * The factory name. 
+     * Could be the component class name if the factory name is not set.
      * Immutable once set.
      */
     protected String m_factoryName;
 
     /**
-     * List of required handler.
+     * The list of required handlers.
      */
     protected List m_requiredHandlers = new ArrayList();
 
     /**
-     * List of listeners.
+     * The list of factory state listeners.
+     * @see FactoryStateListener
      */
     protected List m_listeners = new ArrayList(1);
 
     /**
-     * Logger for the factory (and all component instance).
+     * The logger for the factory (and all component instances).
      */
     protected final Logger m_logger;
 
     /**
-     * Is the factory public (expose as a service).
+     * Is the factory public (exposed as services).
      */
     protected final boolean m_isPublic;
 
     /**
-     * Service Registration of this factory (Factory & ManagedServiceFactory).
+     * The service registration of this factory (Factory & ManagedServiceFactory).
+     * @see ManagedServiceFactory
+     * @see Factory
      */
     protected ServiceRegistration m_sr;
 
     /**
-     * Factory state.
+     * The factory state.
+     * Can be:
+     * <li>{@link Factory#INVALID}</li>
+     * <li>{@link Factory#VALID}</li>
+     * The factory is invalid at the beginning.
+     * A factory becomes valid if every required handlers
+     * are available (i.e. can be created).
      */
     protected int m_state = Factory.INVALID;
 
     /**
-     * Index used to generate instance name if not set.
+     * The index used to generate instance name if not set.
      */
     private long m_index = 0;
 
     /**
-     * Flag indicating if this factory has already a computed description or not.
+     * The flag indicating if this factory has already a 
+     * computed description or not.
      */
     private boolean m_described;
 
     /**
-     * Constructor.
-     * @param context : bundle context of the bundle containing the factory.
-     * @param metadata : description of the component type.
-     * @throws ConfigurationException occurs when the element describing the factory is malformed.
+     * Creates an iPOJO Factory.
+     * At the end of this method, the required set of handler is computed.
+     * But the result is computed by a sub-class.
+     * @param context the bundle context of the bundle containing the factory.
+     * @param metadata the description of the component type.
+     * @throws ConfigurationException if the element describing the factory is malformed.
      */
     public IPojoFactory(BundleContext context, Element metadata) throws ConfigurationException {
         m_context = context;
@@ -133,13 +152,17 @@
         m_requiredHandlers = getRequiredHandlerList(); // Call sub-class to get the list of required handlers.
     }
 
+    /**
+     * Gets the component type description.
+     * @return the component type description
+     */
     public ComponentTypeDescription getComponentTypeDescription() {
         return new ComponentTypeDescription(this);
     }
 
     /**
      * Adds a factory listener.
-     * @param listener : the factory listener to add.
+     * @param listener the factory listener to add.
      * @see org.apache.felix.ipojo.Factory#addFactoryStateListener(org.apache.felix.ipojo.FactoryStateListener)
      */
     public void addFactoryStateListener(FactoryStateListener listener) {
@@ -149,7 +172,7 @@
     }
 
     /**
-     * Gets the logger used by instances of he current factory.
+     * Gets the logger used by instances created by the current factory.
      * @return the factory logger.
      */
     public Logger getLogger() {
@@ -158,35 +181,38 @@
 
     /**
      * Computes the factory name.
+     * Each sub-type must override this method. 
      * @return the factory name.
      */
     public abstract String getFactoryName();
 
     /**
      * Computes the required handler list.
+     * Each sub-type must override this method.
      * @return the required handler list
      */
     public abstract List getRequiredHandlerList();
 
     /**
      * Creates an instance.
-     * This method is called with the lock.
-     * @param config : instance configuration
-     * @param context : ipojo context to use
-     * @param handlers : handler array to use
+     * This method is called with the monitor lock.
+     * @param config the instance configuration
+     * @param context the iPOJO context to use
+     * @param handlers the handler array to use
      * @return the new component instance.
-     * @throws ConfigurationException : occurs when the instance creation failed during the configuration process.
+     * @throws ConfigurationException if the instance creation failed during the configuration process.
      */
     public abstract ComponentInstance createInstance(Dictionary config, IPojoContext context, HandlerManager[] handlers)
             throws ConfigurationException;
 
     /**
-     * Creates an instance. The given configuration needs to contain the 'name' property.
-     * @param configuration : configuration of the created instance.
+     * Creates an instance.
+     * This method creates the instance in the global context.
+     * @param configuration the configuration of the created instance.
      * @return the created component instance.
-     * @throws UnacceptableConfiguration : occurs if the given configuration is not consistent with the component type of this factory.
-     * @throws MissingHandlerException : occurs if an handler is unavailable when the instance is created.
-     * @throws org.apache.felix.ipojo.ConfigurationException : occurs when the instance or type configuration are not correct.
+     * @throws UnacceptableConfiguration if the given configuration is not consistent with the component type of this factory.
+     * @throws MissingHandlerException if an handler is unavailable when the instance is created.
+     * @throws org.apache.felix.ipojo.ConfigurationException if the instance or type configuration are not correct.
      * @see org.apache.felix.ipojo.Factory#createComponentInstance(java.util.Dictionary)
      */
     public ComponentInstance createComponentInstance(Dictionary configuration) throws UnacceptableConfiguration, MissingHandlerException,
@@ -195,15 +221,17 @@
     }
 
     /**
-     * Creates an instance. The given configuration needs to contain the 'name' property.
+     * Creates an instance in the specified service context.
      * This method is synchronized to assert the validity of the factory during the creation.
-     * Callbacks to sub-class and to create instance need to be aware that they are holding the lock.
-     * @param configuration : configuration of the created instance.
-     * @param serviceContext : the service context to push for this instance.
+     * Callbacks to sub-class and  created instances need to be aware that they are holding the monitor lock.
+     * This method call the override {@link IPojoFactory#createInstance(Dictionary, IPojoContext, HandlerManager[])
+     * method.
+     * @param configuration the configuration of the created instance.
+     * @param serviceContext the service context to push for this instance.
      * @return the created component instance.
-     * @throws UnacceptableConfiguration : occurs if the given configuration is not consistent with the component type of this factory.
-     * @throws MissingHandlerException : occurs when an handler is unavailable when creating the instance.
-     * @throws org.apache.felix.ipojo.ConfigurationException : when the instance configuration failed.
+     * @throws UnacceptableConfiguration if the given configuration is not consistent with the component type of this factory.
+     * @throws MissingHandlerException if an handler is unavailable when creating the instance.
+     * @throws org.apache.felix.ipojo.ConfigurationException if the instance configuration failed.
      * @see org.apache.felix.ipojo.Factory#createComponentInstance(java.util.Dictionary)
      */
     public synchronized ComponentInstance createComponentInstance(Dictionary configuration, ServiceContext serviceContext) throws UnacceptableConfiguration, // NOPMD
@@ -262,6 +290,11 @@
         }
     }
 
+    /**
+     * Gets the bundle context of the factory.
+     * @return the bundle context of the factory.
+     * @see org.apache.felix.ipojo.Factory#getBundleContext()
+     */
     public BundleContext getBundleContext() {
         return m_context;
     }
@@ -275,7 +308,7 @@
 
     /**
      * Gets the component type description.
-     * @return the component type description object. Null if not already computed.
+     * @return the component type description object. <code>Null</code> if not already computed.
      */
     public synchronized ComponentTypeDescription getComponentDescription() {
         return m_componentDesc;
@@ -295,8 +328,8 @@
     }
 
     /**
-     * Computes the list of missing handlers. This method is called with the lock.
-     * @return list of missing handlers.
+     * Computes the list of missing handlers. This method is called with the monitor lock.
+     * @return the list of missing handlers.
      * @see org.apache.felix.ipojo.Factory#getMissingHandlers()
      */
     public List getMissingHandlers() {
@@ -324,7 +357,7 @@
      * Gets the list of required handlers.
      * This method is synchronized to avoid the concurrent modification
      * of the required handlers.
-     * @return list of required handlers.
+     * @return the list of required handlers.
      * @see org.apache.felix.ipojo.Factory#getRequiredHandlers()
      */
     public synchronized List getRequiredHandlers() {
@@ -348,8 +381,8 @@
 
     /**
      * Checks if the configuration is acceptable.
-     * @param conf : the configuration to test.
-     * @return true if the configuration is acceptable.
+     * @param conf the configuration to test.
+     * @return <code>true</code> if the configuration is acceptable.
      * @see org.apache.felix.ipojo.Factory#isAcceptable(java.util.Dictionary)
      */
     public boolean isAcceptable(Dictionary conf) {
@@ -365,9 +398,13 @@
 
     /**
      * Checks if the configuration is acceptable.
-     * @param conf : the configuration to test.
-     * @throws UnacceptableConfiguration occurs if the configuration is unacceptable.
-     * @throws MissingHandlerException occurs if an handler is missing.
+     * This method checks the following assertions:
+     * <li>All handlers can be creates</li>
+     * <li>The configuration does not override immutable properties</li>
+     * <li>The configuration contains a value for every unvalued property</li>
+     * @param conf the configuration to test.
+     * @throws UnacceptableConfiguration if the configuration is unacceptable.
+     * @throws MissingHandlerException if an handler is missing.
      */
     public void checkAcceptability(Dictionary conf) throws UnacceptableConfiguration, MissingHandlerException {
         PropertyDescription[] props;
@@ -395,10 +432,13 @@
 
     /**
      * Reconfigures an existing instance.
+     * The acceptability of the configuration is checked before the reconfiguration. Moreover,
+     * the configuration must contain the 'instance.name' property specifying the instance 
+     * to reconfigure.
      * This method is synchronized to assert the validity of the factory during the reconfiguration.
-     * @param properties : the new configuration to push.
-     * @throws UnacceptableConfiguration : occurs if the new configuration is not consistent with the component type.
-     * @throws MissingHandlerException : occurs if the current factory is not valid.
+     * @param properties the new configuration to push.
+     * @throws UnacceptableConfiguration if the new configuration is not consistent with the component type.
+     * @throws MissingHandlerException if the current factory is not valid.
      * @see org.apache.felix.ipojo.Factory#reconfigure(java.util.Dictionary)
      */
     public synchronized void reconfigure(Dictionary properties) throws UnacceptableConfiguration, MissingHandlerException {
@@ -422,7 +462,7 @@
 
     /**
      * Removes a factory listener.
-     * @param listener : the factory listener to remove.
+     * @param listener the factory listener to remove.
      * @see org.apache.felix.ipojo.Factory#removeFactoryStateListener(org.apache.felix.ipojo.FactoryStateListener)
      */
     public void removeFactoryStateListener(FactoryStateListener listener) {
@@ -432,13 +472,18 @@
     }
 
     /**
-     * Stopping method. This method is call when the factory is stopping.
+     * Stopping method. 
+     * This method is call when the factory is stopping.
      * This method is called when holding the lock on the factory.
      */
     public abstract void stopping();
 
     /**
      * Stops all the instance managers.
+     * This method calls the {@link IPojoFactory#stopping()} method,
+     * notifies listeners, and disposes created instances. Moreover,
+     * if the factory is public, services are also unregistered.
+     *  
      */
     public synchronized void stop() {
         ComponentInstance[] instances;
@@ -482,7 +527,8 @@
     }
 
     /**
-     * Destroys the factory. The factory cannot be restarted. Only the extender can call this method.
+     * Destroys the factory. 
+     * The factory cannot be restarted. Only the {@link Extender} can call this method.
      */
     synchronized void dispose() {
         stop(); // Does not hold the lock.
@@ -491,12 +537,17 @@
     }
 
     /**
-     * Starting method. This method is called when the factory is starting. This method is called when holding the lock on the factory.
+     * Starting method. 
+     * This method is called when the factory is starting.
+     * This method is called when holding the lock on the factory.
      */
     public abstract void starting();
 
     /**
      * Starts the factory.
+     * Tries to compute the component type description,
+     * calls the {@link IPojoFactory#starting()} method,
+     * and published services if the factory is public.
      */
     public synchronized void start() {
         if (m_described) { // Already started.
@@ -519,9 +570,9 @@
 
     /**
      * Creates or updates an instance.
-     * @param name : name of the instance
-     * @param properties : configuration of the instance
-     * @throws org.osgi.service.cm.ConfigurationException : if the configuration is not consistent for this component type
+     * @param name the name of the instance
+     * @param properties the new configuration of the instance
+     * @throws org.osgi.service.cm.ConfigurationException if the configuration is not consistent for this component type
      * @see org.osgi.service.cm.ManagedServiceFactory#updated(java.lang.String, java.util.Dictionary)
      */
     public void updated(String name, Dictionary properties) throws org.osgi.service.cm.ConfigurationException {
@@ -561,7 +612,7 @@
 
     /**
      * Deletes an instance.
-     * @param name : name of the instance to delete
+     * @param name the name of the instance to delete
      * @see org.osgi.service.cm.ManagedServiceFactory#deleted(java.lang.String)
      */
     public synchronized void deleted(String name) {
@@ -574,7 +625,7 @@
 
     /**
      * Callback called by instance when disposed.
-     * @param instance : the destroyed instance
+     * @param instance the destroyed instance
      */
     public void disposed(ComponentInstance instance) {
         String name = instance.getInstanceName();
@@ -585,7 +636,11 @@
     }
 
     /**
-     * Computes the component type description. The factory must be valid when calling this method.
+     * Computes the component type description.
+     * To do this, it creates a 'ghost' instance of the handler 
+     * and calls the {@link Handler#initializeComponentFactory(ComponentTypeDescription, Element)}
+     * method. The handler instance is then deleted. 
+     * The factory must be valid when calling this method.
      * This method is called with the lock.
      */
     protected void computeDescription() {
@@ -607,7 +662,10 @@
 
     /**
      * Computes factory state.
-     * This method is call when holding the lock on the current factory.
+     * The factory is valid if every required handler are available.
+     * If the factory becomes valid for the first time, the component
+     * type description is computed.
+     * This method is called when holding the lock on the current factory.
      */
     protected void computeFactoryState() {
         boolean isValid = true;
@@ -669,11 +727,11 @@
     }
 
     /**
-     * Checks if the given handler identifier and the service reference can match.
+     * Checks if the given handler identifier and the service reference match.
      * Does not need to be synchronized as the method does not use any fields.
-     * @param req : the handler identifier.
-     * @param ref : the service reference.
-     * @return true if the service reference can fulfill the handler requirement
+     * @param req the handler identifier.
+     * @param ref the service reference.
+     * @return <code>true</code> if the service reference can fulfill the handler requirement
      */
     protected boolean match(RequiredHandler req, ServiceReference ref) {
         String name = (String) ref.getProperty(Handler.HANDLER_NAME_PROPERTY);
@@ -685,11 +743,12 @@
     }
 
     /**
-     * Returns the handler object for the given required handler. The handler is instantiated in the given service context.
+     * Returns the handler object for the given required handler.
+     * The handler is instantiated in the given service context.
      * This method is called with the lock.
-     * @param req : handler to create.
-     * @param context : service context in which create the handler (instance context).
-     * @return the Handler object.
+     * @param req the handler to create.
+     * @param context the service context in which the handler is created (same as the instance context).
+     * @return the handler object.
      */
     protected HandlerManager getHandler(RequiredHandler req, ServiceContext context) {
         try {
@@ -716,9 +775,9 @@
     }
 
     /**
-     * Helping method generating a new unique name.
+     * Helper method generating a new unique name.
      * This method is call when holding the lock to assert generated name unicity.
-     * @return an non already used name
+     * @return a non already used name
      */
     protected String generateName() {
         String name = m_factoryName + "-" + m_index;
@@ -736,34 +795,34 @@
      */
     protected class RequiredHandler implements Comparable {
         /**
-         * Factory to create this handler.
+         * The factory to create this handler.
          */
         private HandlerFactory m_factory;
 
         /**
-         * Handler name.
+         * The handler name.
          */
         private final String m_name;
 
         /**
-         * Handler start level.
+         * The handler start level.
          */
         private int m_level = Integer.MAX_VALUE;
 
         /**
-         * Handler namespace.
+         * The handler namespace.
          */
         private final String m_namespace;
 
         /**
-         * Service Reference of the handler factory.
+         * The Service Reference of the handler factory.
          */
         private ServiceReference m_reference;
 
         /**
-         * Constructor.
-         * @param name : handler name.
-         * @param namespace : handler namespace.
+         * Crates a Required Handler.
+         * @param name the handler name.
+         * @param namespace the handler namespace.
          */
         public RequiredHandler(String name, String namespace) {
             m_name = name;
@@ -771,9 +830,10 @@
         }
 
         /**
-         * Equals method. Two handlers are equals if they have same name and namespace or they share the same service reference.
-         * @param object : object to compare to the current object.
-         * @return : true if the two compared object are equals
+         * Equals method.
+         * Two handlers are equals if they have same name and namespace or they share the same service reference.
+         * @param object the object to compare to the current object.
+         * @return <code>true</code> if the two compared object are equals
          * @see java.lang.Object#equals(java.lang.Object)
          */
         public boolean equals(Object object) {
@@ -791,7 +851,8 @@
         }
 
         /**
-         * Gets the factory object used for this handler. The object is get when used for the first time.
+         * Gets the factory object used for this handler. 
+         * The object is get when used for the first time.
          * This method is called with the lock avoiding concurrent modification and on a valid factory.
          * @return the factory object.
          */
@@ -806,7 +867,7 @@
         }
 
         /**
-         * Get the handler full name (namespace:name).
+         * Gets the handler qualified name (<code>namespace:name</code>).
          * @return the handler full name
          */
         public String getFullName() {
@@ -834,7 +895,7 @@
         }
 
         /**
-         * Release the reference of the used factory.
+         * Releases the reference of the used factory.
          * This method is called with the lock on the current factory.
          */
         public void unRef() {
@@ -845,9 +906,9 @@
         }
 
         /**
-         * Set the service reference. If the new service reference is null, it unget the used factory (if already get).
+         * Sets the service reference. If the new service reference is <code>null</code>, it ungets the used factory (if already get).
          * This method is called with the lock on the current factory.
-         * @param ref : new service reference.
+         * @param ref the new service reference.
          */
         public void setReference(ServiceReference ref) {
             m_reference = ref;
@@ -858,10 +919,11 @@
         }
 
         /**
-         * Start level Comparison. This method is used to sort the handler array.
+         * Start level Comparison.
+         * This method is used to sort the handler array.
          * This method is called with the lock.
-         * @param object : object on which compare.
-         * @return -1, 0, +1 according to the comparison of their start level.
+         * @param object the object on which compare.
+         * @return <code>-1</code>, <code>0</code>, <code>+1</code> according to the comparison of their start levels.
          * @see java.lang.Comparable#compareTo(java.lang.Object)
          */
         public int compareTo(Object object) {



Mime
View raw message