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