diff options
author | Thomas Watson | 2020-05-18 21:48:47 +0000 |
---|---|---|
committer | Thomas Watson | 2020-05-19 14:30:10 +0000 |
commit | 9fde91945623e9c9ed9c4e4a39a2839d66819353 (patch) | |
tree | be42e9e8a0f6b3fe67303b776dd72c677bcececd | |
parent | 6f37585b0f192c49df9c3ccba5c1704a5d62bf8a (diff) | |
download | rt.equinox.framework-9fde91945623e9c9ed9c4e4a39a2839d66819353.tar.gz rt.equinox.framework-9fde91945623e9c9ed9c4e4a39a2839d66819353.tar.xz rt.equinox.framework-9fde91945623e9c9ed9c4e4a39a2839d66819353.zip |
Update OSGi R8 API to the latest
Change-Id: Ifb5c360e8c198a8def8065501136e1ef89598e4b
Signed-off-by: Thomas Watson <tjwatson@us.ibm.com>
9 files changed, 187 insertions, 151 deletions
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/FrameworkEvent.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/FrameworkEvent.java index 41528f8de..bcff0614c 100644 --- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/FrameworkEvent.java +++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/FrameworkEvent.java @@ -173,9 +173,9 @@ public class FrameworkEvent extends EventObject { * The Framework has stopped and the framework requires a new class loader * to restart. * <p> - * This event is fired when the Framework has been stopped because of a stop - * operation on the system bundle and the framework requires a new class - * loader to be used to restart. For example, if a framework extension + * This event is fired when the Framework has been stopped because of a + * refresh operation on the system bundle and the framework requires a new + * class loader to be used to restart. For example, if a framework extension * bundle has been refreshed. The source of this event is the System Bundle. * * @since 1.9 diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectContent.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectContent.java index d6df33668..9e455f9d4 100644 --- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectContent.java +++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectContent.java @@ -21,138 +21,156 @@ import java.io.InputStream; import java.util.Map; import java.util.Optional; +import org.osgi.annotation.versioning.ConsumerType; import org.osgi.framework.Bundle; import org.osgi.framework.launch.Framework; import org.osgi.framework.namespace.IdentityNamespace; import org.osgi.framework.wiring.BundleRevisions; /** - * A connect content provides a {@link Framework framework} access to the - * content of a connect {@link ConnectModule module}. A framework may - * {@link #open() open} and {@link #close() close} the content for a connect - * module multiple times while the connect content is in use by the framework - * instance. The framework must close the connect content once the connect - * content is no longer used as the content of a current bundle revision or an - * in use bundle revision. + * A {@code ConnectContent} provides a {@link Framework} instance access to the + * content of a {@link ConnectModule}. * <p> - * An entry in a connect content is identified by a path name that is a - * '{@code /}'-separated path. A connect content may treat directories as - * entries. A directory entry path name will end with a slash ('/'). A directory - * entry may be located using a path name that drops the trailing slash. + * A framework may {@link #open() open} and {@link #close() close} the content + * for a {@link ConnectModule} multiple times while the {@code ConnectContent} + * is in use by the framework. The framework must close the + * {@code ConnectContent} once the {@code ConnectContent} is no longer used as + * the content of a current bundle revision or an in use bundle revision. + * <p> + * An entry in a {@code ConnectContent} is identified by a path name that is a + * solidus (<code>'/' \u002F</code>) separated path. A {@code ConnectContent} + * may treat directories as entries. A directory entry path name will end with a + * solidus. A directory entry may be located using a path name that omits the + * trailing solidus. * * @see BundleRevisions * @ThreadSafe * @author $Id$ */ +@ConsumerType public interface ConnectContent { /** * The {@code osgi.identity} * {@link IdentityNamespace#CAPABILITY_TAGS_ATTRIBUTE tags} attribute value * used by the framework to tag connect bundle revisions. */ - public static final String TAG_OSGI_CONNECT = "osgi.connect"; + String TAG_OSGI_CONNECT = "osgi.connect"; /** - * Returns this connect content Manifest headers and values. The - * {@link Optional#empty() empty} value is returned if the framework should - * handle parsing the Manifest of the content itself. + * Returns the Manifest headers and values of this {@code ConnectContent}. * - * @return This connect content Manifest headers and values. - * @throws IllegalStateException if the connect content has been closed + * @return An {@code Optional} containing the Manifest headers and values + * for this {@code ConnectContent}, or an empty {@code Optional} if + * the framework should handle parsing the Manifest of the content + * itself. + * @throws IllegalStateException If this {@code ConnectContent} has been + * closed. */ Optional<Map<String,String>> getHeaders(); /** - * Returns an iterable with all the entry names available in this - * ConnectContent + * Returns the entry names available in this {@code ConnectContent}. * - * @return the entry names - * @throws IOException if an error occurs reading the ConnectContent - * @throws IllegalStateException if the connect content has been closed + * @return An {@code Iterable} which can supply the available entry names. + * @throws IOException If an error occurs reading this + * {@code ConnectContent}. + * @throws IllegalStateException If this {@code ConnectContent} has been + * closed. */ Iterable<String> getEntries() throws IOException; /** - * Returns the connect entry for the specified path name in this content. + * Returns the {@link ConnectEntry} for the specified path name in this + * content. + * <p> * The {@link Optional#empty() empty} value is returned if an entry with the * specified path name does not exist. The path must not start with a * "/" and is relative to the root of this content. A connect * entry for a directory will have a path name that ends with a slash ('/'). * - * @param path the path name of the entry - * @return the connect entry, or {@link Optional#empty() empty} if not - * found. - * @throws IllegalStateException if the connect content has been closed + * @param path The path name of the entry. + * @return An {@code Optional} containing the {@link ConnectEntry} for the + * specified path, or an empty {@code Optional} if no entry for + * specified path can be found. + * @throws IllegalStateException If this {@code ConnectContent} has been + * closed. */ Optional<ConnectEntry> getEntry(String path); /** - * Returns a class loader for this connect content. The - * {@link Optional#empty() empty} value is returned if the framework should - * handle creating a class loader for the bundle revision associated with - * this connect content. + * Returns a class loader for this {@code ConnectContent}. * <p> * This method is called by the framework for {@link Bundle#RESOLVED * resolved} bundles only and will be called at most once while a bundle is - * resolved. If a bundle associated with a connect module is refreshed and - * resolved again the framework will ask the content for the class loader - * again. This allows for a connect content to reuse or create a new class - * loader each time the bundle revision is resolved. + * resolved. If a bundle associated with a {@link ConnectModule} is + * refreshed and resolved again, the framework will ask the + * {@code ConnectContent} for the class loader again. This allows for a + * {@code ConnectContent} to reuse or create a new class loader each time + * the bundle revision is resolved. * - * @return a class loader for the content. + * @return An {@code Optional} containing the class loader for this + * {@code ConnectContent}, or an empty {@code Optional} if framework + * should handle creating a class loader for the bundle revision + * associated with this {@code ConnectContent}. + * @throws IllegalStateException If this {@code ConnectContent} has been + * closed. */ Optional<ClassLoader> getClassLoader(); /** - * Opens this connect content. The framework will open the content when it - * needs to access the content for a bundle revision associated with the - * connect content. The framework may lazily postpone to open the content - * until right before requests to access the bundle revision content are - * made. + * Opens this {@code ConnectContent}. + * <p> + * The framework will open the content when it needs to access the content + * for a bundle revision associated with this {@code ConnectContent}. The + * framework may defer calling this method until requests to access the + * bundle revision content are made. * - * @throws IOException if an error occurred opening the content + * @throws IOException If an error occurred opening this + * {@code ConnectContent}. */ void open() throws IOException; /** - * Closes this connect content. + * Closes this {@code ConnectContent}. * - * @throws IOException if an error occurred closing the connect content + * @throws IOException If an error occurred closing this + * {@code ConnectContent}. */ void close() throws IOException; /** - * Represents the entry of a connect content + * Represents the entry of a {@code ConnectContent}. */ + @ConsumerType public interface ConnectEntry { /** - * Returns the path name of the entry + * Returns the path name of this entry. * - * @return the path name of the entry + * @return The path name of this entry. */ String getName(); /** - * Returns the size of the entry. The value {@code -1} is returned if - * the content length is not known. + * Returns the content length of this entry. * - * @return the size of the entry, or {@code -1} if the content length is - * not known. + * @return The content length of the entry, or {@code -1} if the content + * length is not known. */ public long getContentLength(); /** - * Returns the last modification time of the entry + * Returns the last modification time of this entry. * - * @return the last modification time of the entry + * @return The last modification time of this entry measured in + * milliseconds since the epoch (00:00:00 GMT, January 1, 1970). */ public long getLastModified(); /** - * Returns the content of the entry as a byte array. + * Returns the content of this entry. * - * @return the content bytes - * @throws IOException if an error occurs reading the content + * @return The content of this entry. + * @throws IOException If an error occurs reading the content. */ default byte[] getBytes() throws IOException { long longLength = getContentLength(); @@ -190,10 +208,10 @@ public interface ConnectContent { } /** - * Returns the content of the entry as an input stream. + * Returns an input stream for the content of this entry. * - * @return the content input stream - * @throws IOException if an error occurs reading the content + * @return An input stream for the content of this entry. + * @throws IOException If an error occurs reading the content. */ InputStream getInputStream() throws IOException; } diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectFrameworkFactory.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectFrameworkFactory.java index 9bb703015..fee4e8875 100644 --- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectFrameworkFactory.java +++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectFrameworkFactory.java @@ -24,7 +24,7 @@ import org.osgi.framework.launch.Framework; /** * A factory for creating {@link Framework} instances. * <p> - * If a framework supports {@link ModuleConnector} then the implementation jar + * If a framework supports {@link ModuleConnector}, then the implementation jar * must contain the following resource: * * <pre> @@ -73,7 +73,6 @@ public interface ConnectFrameworkFactory { * {@code AllPermission}, and the Java Runtime Environment * supports permissions. * @see ModuleConnector - * @since 1.3 */ Framework newFramework(Map<String,String> configuration, ModuleConnector moduleConnector); diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectModule.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectModule.java index 2661cc8c1..d81245bff 100644 --- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectModule.java +++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ConnectModule.java @@ -17,28 +17,30 @@ package org.osgi.framework.connect; import java.io.IOException; +import org.osgi.annotation.versioning.ConsumerType; import org.osgi.framework.launch.Framework; import org.osgi.framework.wiring.BundleRevision; /** - * A connect module instance is used by a {@link Framework framework} when a - * bundle location is connected to connect module. The connected bundle must use - * the connect module to load content for the bundle revisions installed in the - * framework for the connected bundle. + * A {@code ConnectModule} is used by a {@link Framework} instance to access the + * content of the connected bundle. * * @ThreadSafe * @author $Id$ */ +@ConsumerType public interface ConnectModule { /** - * Returns the current content of this connect module. The framework will - * call this method when it needs to access the content for the current - * {@link BundleRevision bundle revision} that is connected to this connect - * module. The framework may lazily postpone to open the content until right - * before requests to access the bundle revision content are made. + * Returns the current content of this connect module. + * <p> + * The framework must call this method when it needs to access the content + * for the current {@link BundleRevision bundle revision} of this + * {@code ConnectModule}. The framework may defer opening the returned + * {@link ConnectContent} until requests to access the bundle revision + * content are made. * - * @return the current content of this connect module - * @throws IOException if an error occurred getting the content + * @return The current {@link ConnectContent} of this {@code ConnectModule}. + * @throws IOException If an error occurred getting the content. * @see ModuleConnector#connect(String) */ ConnectContent getContent() throws IOException; diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/FrameworkUtilHelper.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/FrameworkUtilHelper.java index d418a6bcc..f7b54ab0f 100644 --- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/FrameworkUtilHelper.java +++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/FrameworkUtilHelper.java @@ -1,5 +1,5 @@ /* - * Copyright (c) OSGi Alliance (2019). All Rights Reserved. + * Copyright (c) OSGi Alliance (2019, 2020). All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -18,24 +18,29 @@ package org.osgi.framework.connect; import java.util.Optional; +import org.osgi.annotation.versioning.ConsumerType; import org.osgi.framework.Bundle; import org.osgi.framework.FrameworkUtil; /** - * A helper for the {@link FrameworkUtil} class. This helper provides - * alternative implementations for methods on {@link FrameworkUtil}. + * A helper for the {@link FrameworkUtil} class. + * <p> + * This helper provides alternative implementations for methods on + * {@link FrameworkUtil}. */ +@ConsumerType public interface FrameworkUtilHelper { /** - * Return a {@code Bundle} associated with the specified class. + * Returns the {@link Bundle} associated with the specified class. * <p> * This helper method is called by {@link FrameworkUtil#getBundle(Class)} if - * the standard implementation of {@code FrameworkUtil} cannot find the - * bundle. + * the standard implementation of {@link FrameworkUtil} is unable to find + * the bundle. * - * @param classFromBundle A class associated with a bundle - * @return An Optional containing a {@code Bundle} for the specified class - * or an empty Optional if the specified class is not from a bundle. + * @param classFromBundle A class associated with a bundle. + * @return An {@code Optional} containing the {@link Bundle} for the + * specified class, or an empty {@code Optional} if the specified + * class is not from a bundle. */ default Optional<Bundle> getBundle(Class< ? > classFromBundle) { return Optional.empty(); diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ModuleConnector.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ModuleConnector.java index da93a235c..5ee358acf 100644 --- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ModuleConnector.java +++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/ModuleConnector.java @@ -19,77 +19,87 @@ import java.io.File; import java.util.Map; import java.util.Optional; +import org.osgi.annotation.versioning.ConsumerType; import org.osgi.framework.BundleActivator; +import org.osgi.framework.BundleContext; import org.osgi.framework.BundleException; import org.osgi.framework.Constants; +import org.osgi.framework.FrameworkListener; import org.osgi.framework.launch.Framework; /** - * A <code>ModuleConnector</code> provides connections to instances of + * A {@code ModuleConnector} provides connections to instances of * {@link ConnectModule} that are used by a {@link Framework} instance to * connect installed bundles locations with content provided by the - * <code>ModuleConnector</code>. This allows a <code>ModuleConnector</code> to - * provide content and classes for a connected bundle installed in the - * <code>Framework</code>. A <code>ModuleConnector</code> is provided when - * {@link ConnectFrameworkFactory#newFramework(java.util.Map, ModuleConnector) - * creating} a framework instance. Because a <code>ModuleConnector</code> - * instance can participate in the initialization of the <code>Framework</code> - * and the life cycle of a <code>Framework</code> instance the - * <code>ModuleConnector</code> instance should only be used with a single - * <code>Framework</code> instance at a time. + * {@code ModuleConnector}. + * <p> + * This allows a {@code ModuleConnector} to provide content and classes for a + * connected bundle installed in the {@code Framework}. A + * {@code ModuleConnector} is provided when + * {@link ConnectFrameworkFactory#newFramework(Map, ModuleConnector) creating} a + * framework instance. Because a {@code ModuleConnector} instance can + * participate in the initialization of the {@code Framework} and the life cycle + * of a {@code Framework} instance the {@code ModuleConnector} instance should + * only be used with a single {@code Framework} instance at a time. * * @ThreadSafe * @author $Id$ */ +@ConsumerType public interface ModuleConnector { /** - * Initializes this module connector with the + * Initializes this {@code ModuleConnector} with the * {@link Constants#FRAMEWORK_STORAGE framework persistent storage} file and - * framework properties configured for a {@link Framework} instance. This - * method is called once by a {@link Framework} instance and is called + * framework properties configured for a {@link Framework} instance. + * <p> + * This method is called once by a {@link Framework} instance and is called * before any other methods on this module connector are called. * - * @param configuration The framework properties used configure the new - * framework instance. An unmodifiable map of framework - * configuration properties that were used to create a new - * framework instance. - * @param storage the persistent storage area used by the {@link Framework} + * @param storage The persistent storage area used by the {@link Framework} * or {@code null} if the platform does not have file system * support. + * @param configuration An unmodifiable map of framework configuration + * properties that were used to configure the new framework + * instance. */ void initialize(File storage, Map<String,String> configuration); /** - * Connects a bundle location with a {@link ConnectModule}. If an - * {@link Optional#empty() empty} optional is returned then the framework - * must handle reading the content of the bundle itself. If a value is - * {@link Optional#isPresent() present} in the returned optional then the - * <code>ConnectModule</code> {@link Optional#get() value} from the optional - * must be used to connect the bundle to the returned {@link ConnectModule}. - * The returned connect module is used by the framework to access the - * content of the bundle. + * Connects a bundle location with a {@link ConnectModule}. + * <p> + * When the result is empty, then the framework must handle reading the + * content of the bundle itself. Otherwise, the returned + * {@link ConnectModule} must be used by the framework to access the content + * of the bundle. * - * @param location the bundle location used to install a bundle - * @return the connect module for the specified bundle location - * @throws BundleException if the location cannot be handled + * @param location The bundle location used to install a bundle. + * @return An {@code Optional} containing the {@link ConnectModule} for the + * specified bundle location, or an empty {@code Optional} if the + * framework must handle reading the content of the bundle itself. + * @throws BundleException If the location cannot be handled. */ Optional<ConnectModule> connect(String location) throws BundleException; /** - * Creates a new activator for this module connector. A new activator is - * created by the framework each time the framework is - * {@link Framework#init() initialized}. An activator allows the module - * connector to participate in the framework life cycle. When the framework - * is {@link Framework#init() initialized} the activator - * {@link BundleActivator#start(org.osgi.framework.BundleContext) start} - * method is called. When the framework is {@link Framework#stop() stopped} - * the activator - * {@link BundleActivator#stop(org.osgi.framework.BundleContext) stop} - * method is called + * Creates a new activator for this {@code ModuleConnector}. + * <p> + * This method is called by the framework during framework + * {@link Framework#init(FrameworkListener...) initialization}. Returning an + * activator allows this {@code ModuleConnector} to participate in the + * framework life cycle. If an activator is returned: + * <ul> + * <li>The framework will call the activator's + * {@link BundleActivator#start(BundleContext) start} method prior to + * activating any extension bundles.</li> + * <li>The framework will call the activator's + * {@link BundleActivator#stop(BundleContext) stop} method after + * deactivating any extension bundles.</li> + * </ul> * - * @return a new activator for this module connector or - * {@link Optional#empty() empty} if no activator is available + * @return An {@code Optional} containing a new {@link BundleActivator} for + * this {@code ModuleConnector}, or an empty {@code Optional} if no + * {@link BundleActivator} is necessary. */ Optional<BundleActivator> newBundleActivator(); } diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/package-info.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/package-info.java index a196dc76c..b7344ca62 100644 --- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/package-info.java +++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/connect/package-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) OSGi Alliance (2010, 2019). All Rights Reserved. + * Copyright (c) OSGi Alliance (2019, 2020). All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -31,4 +31,3 @@ package org.osgi.framework.connect; import org.osgi.annotation.versioning.Version; - diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/Framework.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/Framework.java index 2c9536186..bf960bdc3 100644 --- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/Framework.java +++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/launch/Framework.java @@ -118,31 +118,33 @@ public interface Framework extends Bundle { * A Framework Event is returned to indicate why this Framework has stopped. * * @param timeout Maximum number of milliseconds to wait until this - * Framework has completely stopped. A value of zero will wait - * indefinitely. + * Framework has completely stopped. A value of zero will wait + * indefinitely. * @return A Framework Event indicating the reason this method returned. The * following {@code FrameworkEvent} types may be returned by this * method. * <ul> * <li>{@link FrameworkEvent#STOPPED STOPPED} - This Framework has - * been stopped. </li> - * + * been stopped.</li> * <li>{@link FrameworkEvent#STOPPED_UPDATE STOPPED_UPDATE} - This * Framework has been updated which has shutdown and will now * restart.</li> - * + * <li>{@link FrameworkEvent#STOPPED_SYSTEM_REFRESHED + * STOPPED_SYSTEM_REFRESHED} - The Framework has been stopped + * because of a refresh operation on the system bundle. A new class + * loader must be used to restart the Framework.</li> * <li>{@link FrameworkEvent#ERROR ERROR} - The Framework * encountered an error while shutting down or an error has occurred - * which forced the framework to shutdown. </li> - * - * <li> {@link FrameworkEvent#WAIT_TIMEDOUT WAIT_TIMEDOUT} - This + * which forced the framework to shutdown.</li> + * <li>{@link FrameworkEvent#WAIT_TIMEDOUT WAIT_TIMEDOUT} - This * method has timed out and returned before this Framework has * stopped.</li> * </ul> * @throws InterruptedException If another thread interrupted the current - * thread before or while the current thread was waiting for this - * Framework to completely stop. The <i>interrupted status</i> of - * the current thread is cleared when this exception is thrown. + * thread before or while the current thread was waiting for + * this Framework to completely stop. The <i>interrupted + * status</i> of the current thread is cleared when this + * exception is thrown. * @throws IllegalArgumentException If the value of timeout is negative. */ FrameworkEvent waitForStop(long timeout) throws InterruptedException; diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/condition/Condition.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/condition/Condition.java index 34980301c..f196a94f7 100644 --- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/condition/Condition.java +++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/condition/Condition.java @@ -19,19 +19,18 @@ package org.osgi.service.condition; import org.osgi.annotation.versioning.ConsumerType; /** - * OSGi due to its modular nature provides <code>Requirements</code> and - * <code>Capabilities</code> to declare what a Bundle needs in order to run - * properly. This is honored by the resolver and enforced by the Framework at - * runtime. The dynamic nature however can provide some impediments at runtime. - * That there is a Bundle that might provide a certain service or capability - * does not mean, that it will be available when and a component expects it be. - * <p> - * Conditions are to the Service Layer what Requirements and Capabilities are to - * the module Layer + * In dynamic systems, such as OSGi, one of the more challenging problems can be + * to define when a System or part of it is ready to do work. The answer can + * change depending on the individual perspective. The developer of a Webserver + * might say, the System is ready when the server starts listening to port 80. + * An Application developer however would define the system as ready, when the + * database connection is up and all Servlets are registered. Taking the + * Application developers view, the Server should start Listening on Port 80 + * when the System is ready and not beforehand. * <p> * The <code>Condition</code> interface is designed to address this issue. Its - * task is to provide a marker that can be tracked if a some Condition is meet - * and for example a Requirement is meet at Runtime. + * task is to provide a marker that can be tracked. It acts as a defined signal + * to other services. * <p> * A Condition must be registered with the {@link Condition#CONDITION_ID} as * property. @@ -41,9 +40,11 @@ import org.osgi.annotation.versioning.ConsumerType; */ @ConsumerType public interface Condition { + /** - * Service property identifying a condition's unique identifier. The type of - * this service property is {@code String+} + * Service property identifying a condition's unique identifier. As a + * Condition can potentially describe more then one state, the type of this + * service property is {@code String+} */ public static final String CONDITION_ID = "osgi.condition.id"; |