diff --git a/org.osgi.framework/src/org/osgi/framework/BundleContext.java b/org.osgi.framework/src/org/osgi/framework/BundleContext.java index ae2f2ebc7f..0b60f6a581 100644 --- a/org.osgi.framework/src/org/osgi/framework/BundleContext.java +++ b/org.osgi.framework/src/org/osgi/framework/BundleContext.java @@ -530,12 +530,10 @@ public interface BundleContext extends BundleReference { * expression, and the packages for the class names under which the services * were registered match the context bundle's packages as defined in * {@link ServiceReference#isAssignableTo(Bundle, String)}. - * *

* The list is valid at the time of the call to this method. However since * the Framework is a very dynamic environment, services can be modified or * unregistered at any time. - * *

* The specified {@code filter} expression is used to select the registered * services whose service properties contain keys and values which satisfy @@ -545,7 +543,6 @@ public interface BundleContext extends BundleReference { * {@code filter} expression cannot be parsed, an * {@link InvalidSyntaxException} will be thrown with a human readable * message where the filter became unparsable. - * *

* The result is an array of {@code ServiceReference} objects for all * services that meet all of the following conditions: @@ -567,12 +564,14 @@ public interface BundleContext extends BundleReference { * * * @param clazz The class name with which the service was registered or - * {@code null} for all services. + * {@code null} for all services. * @param filter The filter expression or {@code null} for all services. * @return An array of {@code ServiceReference} objects or {@code null} if - * no services are registered which satisfy the search. + * no services are registered which satisfy the search. There is no + * guarantee that the {@code ServiceReference} objects in the array + * will be in any specific order. * @throws InvalidSyntaxException If the specified {@code filter} contains - * an invalid filter expression that cannot be parsed. + * an invalid filter expression that cannot be parsed. * @throws IllegalStateException If this BundleContext is no longer valid. */ ServiceReference[] getServiceReferences(String clazz, String filter) throws InvalidSyntaxException; @@ -582,12 +581,10 @@ public interface BundleContext extends BundleReference { * of {@code ServiceReference} objects contains services that were * registered under the specified class and match the specified filter * expression. - * *

* The list is valid at the time of the call to this method. However since * the Framework is a very dynamic environment, services can be modified or * unregistered at any time. - * *

* The specified {@code filter} expression is used to select the registered * services whose service properties contain keys and values which satisfy @@ -597,7 +594,6 @@ public interface BundleContext extends BundleReference { * {@code filter} expression cannot be parsed, an * {@link InvalidSyntaxException} will be thrown with a human readable * message where the filter became unparsable. - * *

* The result is an array of {@code ServiceReference} objects for all * services that meet all of the following conditions: @@ -615,12 +611,14 @@ public interface BundleContext extends BundleReference { * * * @param clazz The class name with which the service was registered or - * {@code null} for all services. + * {@code null} for all services. * @param filter The filter expression or {@code null} for all services. * @return An array of {@code ServiceReference} objects or {@code null} if - * no services are registered which satisfy the search. + * no services are registered which satisfy the search. There is no + * guarantee that the {@code ServiceReference} objects in the array + * will be in any specific order. * @throws InvalidSyntaxException If the specified {@code filter} contains - * an invalid filter expression that cannot be parsed. + * an invalid filter expression that cannot be parsed. * @throws IllegalStateException If this BundleContext is no longer valid. * @since 1.3 */ @@ -629,12 +627,10 @@ public interface BundleContext extends BundleReference { /** * Returns a {@code ServiceReference} object for a service that implements * and was registered under the specified class. - * *

* The returned {@code ServiceReference} object is valid at the time of the * call to this method. However as the Framework is a very dynamic * environment, services can be modified or unregistered at any time. - * *

* This method is the same as calling * {@link #getServiceReferences(String, String)} with a {@code null} filter @@ -642,14 +638,8 @@ public interface BundleContext extends BundleReference { * is provided as a convenience for when the caller is interested in any * service that implements the specified class. *

- * If multiple such services exist, the service with the highest priority is - * selected. This priority is defined as the service reference with the - * highest ranking (as specified in its {@link Constants#SERVICE_RANKING} - * property) is returned. - *

- * If there is a tie in ranking, the service with the lowest service id (as - * specified in its {@link Constants#SERVICE_ID} property); that is, the - * service that was registered first is returned. + * If multiple such services exist, the service that is first in the + * {@link ServiceReference#compareTo(Object) ranking order} is returned. * * @param clazz The class name with which the service was registered. * @return A {@code ServiceReference} object, or {@code null} if no services @@ -662,28 +652,22 @@ public interface BundleContext extends BundleReference { /** * Returns a {@code ServiceReference} object for a service that implements * and was registered under the name of the specified class. - * *

* The returned {@code ServiceReference} object is valid at the time of the * call to this method. However as the Framework is a very dynamic * environment, services can be modified or unregistered at any time. - * *

* This method is the same as calling * {@link #getServiceReferences(Class, String)} with a {@code null} filter * expression. It is provided as a convenience for when the caller is * interested in any service that implements the specified class. *

- * If multiple such services exist, the service with the highest ranking (as - * specified in its {@link Constants#SERVICE_RANKING} property) is returned. - *

- * If there is a tie in ranking, the service with the lowest service id (as - * specified in its {@link Constants#SERVICE_ID} property); that is, the - * service that was registered first is returned. + * If multiple such services exist, the service that is first in the + * {@link ServiceReference#compareTo(Object) ranking order} is returned. * * @param Type of Service. * @param clazz The class under whose name the service was registered. Must - * not be {@code null}. + * not be {@code null}. * @return A {@code ServiceReference} object, or {@code null} if no services * are registered which implement the specified class. * @throws IllegalStateException If this BundleContext is no longer valid. @@ -699,12 +683,10 @@ public interface BundleContext extends BundleReference { * specified filter expression, and the packages for the class names under * which the services were registered match the context bundle's packages as * defined in {@link ServiceReference#isAssignableTo(Bundle, String)}. - * *

* The collection is valid at the time of the call to this method. However * since the Framework is a very dynamic environment, services can be * modified or unregistered at any time. - * *

* The specified {@code filter} expression is used to select the registered * services whose service properties contain keys and values which satisfy @@ -714,7 +696,6 @@ public interface BundleContext extends BundleReference { * {@code filter} expression cannot be parsed, an * {@link InvalidSyntaxException} will be thrown with a human readable * message where the filter became unparsable. - * *

* The result is a collection of {@code ServiceReference} objects for all * services that meet all of the following conditions: @@ -736,12 +717,14 @@ public interface BundleContext extends BundleReference { * * @param Type of Service * @param clazz The class under whose name the service was registered. Must - * not be {@code null}. + * not be {@code null}. * @param filter The filter expression or {@code null} for all services. * @return A collection of {@code ServiceReference} objects. May be empty if - * no services are registered which satisfy the search. + * no services are registered which satisfy the search. There is no + * guarantee that the {@code ServiceReference} objects in the + * collection will be in any specific order. * @throws InvalidSyntaxException If the specified {@code filter} contains - * an invalid filter expression that cannot be parsed. + * an invalid filter expression that cannot be parsed. * @throws IllegalStateException If this BundleContext is no longer valid. * @since 1.6 */ diff --git a/org.osgi.framework/src/org/osgi/framework/ServiceReference.java b/org.osgi.framework/src/org/osgi/framework/ServiceReference.java index d37a0144ab..59dc892c53 100644 --- a/org.osgi.framework/src/org/osgi/framework/ServiceReference.java +++ b/org.osgi.framework/src/org/osgi/framework/ServiceReference.java @@ -171,7 +171,8 @@ public interface ServiceReference /** * Compares this {@code ServiceReference} with the specified * {@code ServiceReference} for order. - * + *

+ * Natural Order *

* If this {@code ServiceReference} and the specified * {@code ServiceReference} have the same {@link Constants#SERVICE_ID @@ -184,15 +185,31 @@ public interface ServiceReference * {@code ServiceReference} is less than the specified * {@code ServiceReference} if it has a higher {@link Constants#SERVICE_ID * service id} and greater if it has a lower service id. + *

+ * Sorting a collection of {@code ServiceReference} objects with natural + * order will result in the first element having the lowest + * {@link Constants#SERVICE_RANKING service ranking} and the last element + * having the highest {@link Constants#SERVICE_RANKING service ranking}. + *

+ * Ranking Order + *

+ * Ranking order, as defined in the Core Specification, is the + * reverse of natural order. + *

+ * Sorting a collection of {@code ServiceReference} objects with ranking + * order will result in the first element having the highest + * {@link Constants#SERVICE_RANKING service ranking} and the last element + * having the lowest {@link Constants#SERVICE_RANKING service ranking}. * * @param reference The {@code ServiceReference} to be compared. * @return Returns a negative integer, zero, or a positive integer if this * {@code ServiceReference} is less than, equal to, or greater than * the specified {@code ServiceReference}. * @throws IllegalArgumentException If the specified - * {@code ServiceReference} was not created by the same framework - * instance as this {@code ServiceReference}. + * {@code ServiceReference} was not created by the same + * framework instance as this {@code ServiceReference}. * @since 1.4 + * @see "Core Specification, Service Ranking Order" */ @Override public int compareTo(Object reference); diff --git a/org.osgi.framework/src/org/osgi/framework/hooks/resolver/ResolverHook.java b/org.osgi.framework/src/org/osgi/framework/hooks/resolver/ResolverHook.java index 889582c116..518572ccbe 100644 --- a/org.osgi.framework/src/org/osgi/framework/hooks/resolver/ResolverHook.java +++ b/org.osgi.framework/src/org/osgi/framework/hooks/resolver/ResolverHook.java @@ -22,6 +22,7 @@ import org.osgi.annotation.versioning.ConsumerType; import org.osgi.framework.Bundle; +import org.osgi.framework.ServiceReference; import org.osgi.framework.namespace.BundleNamespace; import org.osgi.framework.namespace.IdentityNamespace; import org.osgi.framework.wiring.BundleCapability; @@ -32,7 +33,6 @@ /** * OSGi Framework Resolver Hook instances are obtained from the OSGi * {@link ResolverHookFactory Framework Resolver Hook Factory} service. - * *

* A Resolver Hook instance is called by the framework during a resolve process. * A resolver hook may influence the outcome of a resolve process by removing @@ -41,7 +41,6 @@ * supports all remove operations. Any other attempts to modify a shrinkable * collection will result in an {@code UnsupportedOperationException} being * thrown. - * *

* The following steps outline the way a framework uses the resolver hooks * during a resolve process. @@ -60,7 +59,6 @@ * {@link ResolverHookFactory#begin(Collection)} method to inform the hooks * about a resolve process beginning and to obtain a Resolver Hook instance that * will be used for the duration of the resolve process. - * *

  • Determine the collection of unresolved bundle revisions that may be * considered for resolution during the current resolution process and place * each of the bundle revisions in a shrinkable collection {@code Resolvable}. @@ -78,7 +76,8 @@ *
  • Determine the collection of available capabilities that have a namespace * of {@link IdentityNamespace osgi.identity}, are singletons, and have the same * symbolic name as the singleton bundle revision {@code B} and place each of - * the matching capabilities into a shrinkable collection {@code Collisions}.
    • + * the matching capabilities into a shrinkable collection + * {@code Collisions}. *
  • Remove the {@link IdentityNamespace osgi.identity} capability provided by * bundle revision {@code B} from shrinkable collection {@code Collisions}. A * singleton bundle cannot collide with itself.
    • @@ -118,11 +117,11 @@ *
  • For each resolver hook call the {@link #end()} method to inform the hooks * about a resolve process ending.
    • * - * In all cases, the order in which the resolver hooks are called is the reverse - * compareTo ordering of their Service References. That is, the service with the - * highest ranking number must be called first. In cases where a shrinkable - * collection becomes empty the framework is required to call the remaining - * registered hooks. + * In all cases, the resolver hooks are called in + * {@link ServiceReference#compareTo(Object) ranking order}. That is, the + * service with the highest ranking must be called first. In cases where a + * shrinkable collection becomes empty the framework is required to call the + * remaining registered hooks. *

    * Resolver hooks are low level. Implementations of the resolver hook must be * careful not to create an unresolvable state which is very hard for a diff --git a/org.osgi.framework/src/org/osgi/framework/hooks/resolver/package-info.java b/org.osgi.framework/src/org/osgi/framework/hooks/resolver/package-info.java index c390a2c7db..66aeb0b21c 100644 --- a/org.osgi.framework/src/org/osgi/framework/hooks/resolver/package-info.java +++ b/org.osgi.framework/src/org/osgi/framework/hooks/resolver/package-info.java @@ -31,7 +31,7 @@ * @author $Id$ */ -@Version("1.0") +@Version("1.0.1") package org.osgi.framework.hooks.resolver; import org.osgi.annotation.versioning.Version; diff --git a/org.osgi.service.component/src/org/osgi/service/component/ComponentContext.java b/org.osgi.service.component/src/org/osgi/service/component/ComponentContext.java index 7e3189b45d..59359269e0 100644 --- a/org.osgi.service.component/src/org/osgi/service/component/ComponentContext.java +++ b/org.osgi.service.component/src/org/osgi/service/component/ComponentContext.java @@ -49,22 +49,19 @@ public interface ComponentContext { /** * Returns the service object for the specified reference name. - * *

    * If the cardinality of the reference is {@code 0..n} or {@code 1..n} and - * multiple services are bound to the reference, the service with the - * highest ranking (as specified in its {@code Constants.SERVICE_RANKING} - * property) is returned. If there is a tie in ranking, the service with the - * lowest service id (as specified in its {@code Constants.SERVICE_ID} - * property); that is, the service that was registered first is returned. + * multiple services are bound to the reference, the service whose + * {@code ServiceReference} is first in the ranking order is returned. See + * {@code ServiceReference.compareTo(Object)}. * * @param name The name of a reference as specified in a {@code reference} - * element in this component's description. + * element in this component's description. * @return A service object for the referenced service or {@code null} if * the reference cardinality is {@code 0..1} or {@code 0..n} and no * bound service is available. * @throws ComponentException If Service Component Runtime catches an - * exception while activating the bound service. + * exception while activating the bound service. */ public S locateService(String name); @@ -90,14 +87,16 @@ public interface ComponentContext { * Returns the service objects for the specified reference name. * * @param name The name of a reference as specified in a {@code reference} - * element in this component's description. + * element in this component's description. * @return An array of service objects for the referenced service or * {@code null} if the reference cardinality is {@code 0..1} or * {@code 0..n} and no bound service is available. If the reference * cardinality is {@code 0..1} or {@code 1..1} and a bound service - * is available, the array will have exactly one element. + * is available, the array will have exactly one element. There is + * no guarantee that the service objects in the array will be in any + * specific order. * @throws ComponentException If Service Component Runtime catches an - * exception while activating a bound service. + * exception while activating a bound service. */ public Object[] locateServices(String name); diff --git a/org.osgi.service.component/src/org/osgi/service/component/annotations/CollectionType.java b/org.osgi.service.component/src/org/osgi/service/component/annotations/CollectionType.java index e1c84ac125..c74db1029e 100644 --- a/org.osgi.service.component/src/org/osgi/service/component/annotations/CollectionType.java +++ b/org.osgi.service.component/src/org/osgi/service/component/annotations/CollectionType.java @@ -51,9 +51,9 @@ public enum CollectionType { * services. *

    * The Maps must implement {@code Comparable} with the {@code compareTo} - * method comparing service property maps using the same ordering as - * {@code ServiceReference.compareTo} based upon service ranking and service - * id. + * method comparing service property maps using an ordering which is the + * same as the natural ordering of {@code ServiceReference}s as specified in + * {@code ServiceReference.compareTo}. */ PROPERTIES("properties"), @@ -64,9 +64,10 @@ public enum CollectionType { * {@link #PROPERTIES}, and whose value is the bound service object. *

    * The Map.Entries must implement {@code Comparable} with the - * {@code compareTo} method comparing service property maps using the same - * ordering as {@code ServiceReference.compareTo} based upon service ranking - * and service id. + * {@code compareTo} method comparing service property maps using an + * ordering which is the same as the natural ordering of + * {@code ServiceReference}s as specified in + * {@code ServiceReference.compareTo}. */ TUPLE("tuple"); diff --git a/org.osgi.service.component/src/org/osgi/service/component/annotations/package-info.java b/org.osgi.service.component/src/org/osgi/service/component/annotations/package-info.java index ecc433e7fa..cf90c20cd1 100644 --- a/org.osgi.service.component/src/org/osgi/service/component/annotations/package-info.java +++ b/org.osgi.service.component/src/org/osgi/service/component/annotations/package-info.java @@ -25,7 +25,7 @@ * @author $Id$ */ -@Version(COMPONENT_SPECIFICATION_VERSION) +@Version(COMPONENT_SPECIFICATION_VERSION + ".1") package org.osgi.service.component.annotations; import static org.osgi.service.component.ComponentConstants.COMPONENT_SPECIFICATION_VERSION; diff --git a/org.osgi.service.component/src/org/osgi/service/component/package-info.java b/org.osgi.service.component/src/org/osgi/service/component/package-info.java index ed90142c55..2379b1dce2 100644 --- a/org.osgi.service.component/src/org/osgi/service/component/package-info.java +++ b/org.osgi.service.component/src/org/osgi/service/component/package-info.java @@ -35,7 +35,7 @@ * @author $Id$ */ -@Version(COMPONENT_SPECIFICATION_VERSION) +@Version(COMPONENT_SPECIFICATION_VERSION + ".1") package org.osgi.service.component; import static org.osgi.service.component.ComponentConstants.COMPONENT_SPECIFICATION_VERSION; diff --git a/org.osgi.service.http.whiteboard/src/org/osgi/service/http/context/ServletContextHelper.java b/org.osgi.service.http.whiteboard/src/org/osgi/service/http/context/ServletContextHelper.java index ccca49378f..b1080e8c42 100644 --- a/org.osgi.service.http.whiteboard/src/org/osgi/service/http/context/ServletContextHelper.java +++ b/org.osgi.service.http.whiteboard/src/org/osgi/service/http/context/ServletContextHelper.java @@ -34,30 +34,27 @@ /** * Helper service for a servlet context used by a Http Whiteboard implementation * to serve HTTP requests. - * *

    * This service defines methods that the Http Whiteboard implementation may call * to get information for a request when dealing with whiteboard services. - * *

    * Each {@code ServletContextHelper} is registered with a * {@link HttpWhiteboardConstants#HTTP_WHITEBOARD_CONTEXT_NAME * "osgi.http.whiteboard.context.name"} service property containing a name to * reference by servlets, servlet filters, resources, and listeners. If there is * more than one {@code ServletContextHelper} registered with the same context - * name, the one with the highest service ranking is active, the others are - * inactive. - * + * name, the one that is first in the + * {@link org.osgi.framework.ServiceReference#compareTo(Object) ranking order} + * is active, the others are inactive. *

    * A context is registered with the * {@link HttpWhiteboardConstants#HTTP_WHITEBOARD_CONTEXT_PATH * "osgi.http.whiteboard.context.path"} service property to define a path under * which all services registered with this context are reachable. If there is * more than one {@code ServletContextHelper} registered with the same path, - * each duplicate context path is searched by service ranking order according to - * {@link org.osgi.framework.ServiceReference#compareTo(Object)} until a - * matching servlet or resource is found. - * + * each duplicate context path is searched in + * {@link org.osgi.framework.ServiceReference#compareTo(Object) ranking order} + * until a matching servlet or resource is found. *

    * Servlets, servlet filters, resources, and listeners services may be * associated with a {@code ServletContextHelper} service with the @@ -66,23 +63,21 @@ * {@code ServletContextHelper} service does not exist or is currently not * active, the whiteboard services for that {@code ServletContextHelper} are not * active either. - * *

    * If no {@code ServletContextHelper} service is associated, that is no * {@link HttpWhiteboardConstants#HTTP_WHITEBOARD_CONTEXT_SELECT * "osgi.http.whiteboard.context.select"} service property is configured for a * whiteboard service, a default {@code ServletContextHelper} is used. - * *

    * Those whiteboard services that are associated with the same * {@code ServletContextHelper} object will share the same * {@code ServletContext} object. - * *

    * The behavior of the methods on the default {@code ServletContextHelper} is * defined as follows: *

      - *
    • {@link #getMimeType(String) getMimeType} - Always returns {@code null}.
      • + *
    • {@link #getMimeType(String) getMimeType} - Always returns + * {@code null}.
      • *
    • {@link #handleSecurity(HttpServletRequest, HttpServletResponse) * handleSecurity} - Always returns {@code true}.
      • *
    • {@link #getResource(String) getResource} - Assumes the named resource is @@ -90,14 +85,16 @@ * calls the whiteboard service bundle's {@code Bundle.getEntry} method, and * returns the appropriate URL to access the resource. On a Java runtime * environment that supports permissions, the Http Whiteboard implementation - * needs to be granted {@code org.osgi.framework.AdminPermission[*,RESOURCE]}.
      • + * needs to be granted + * {@code org.osgi.framework.AdminPermission[*,RESOURCE]}. *
    • {@link #getResourcePaths(String) getResourcePaths} - Assumes that the * resources are in the bundle of the whiteboard service. This method calls * {@code Bundle.findEntries} method, and returns the found entries. On a Java * runtime environment that supports permissions, the Http Whiteboard * implementation needs to be granted * {@code org.osgi.framework.AdminPermission[*,RESOURCE]}.
      • - *
    • {@link #getRealPath(String) getRealPath} - Always returns {@code null}.
      • + *
    • {@link #getRealPath(String) getRealPath} - Always returns + * {@code null}.
      • *
    * * @ThreadSafe diff --git a/org.osgi.service.http.whiteboard/src/org/osgi/service/http/context/package-info.java b/org.osgi.service.http.whiteboard/src/org/osgi/service/http/context/package-info.java index 631af68958..85ac3d6f9a 100644 --- a/org.osgi.service.http.whiteboard/src/org/osgi/service/http/context/package-info.java +++ b/org.osgi.service.http.whiteboard/src/org/osgi/service/http/context/package-info.java @@ -35,7 +35,7 @@ * @author $Id$ */ -@Version(HTTP_WHITEBOARD_SPECIFICATION_VERSION + ".0") +@Version(HTTP_WHITEBOARD_SPECIFICATION_VERSION + ".1") package org.osgi.service.http.context; import static org.osgi.service.http.whiteboard.HttpWhiteboardConstants.HTTP_WHITEBOARD_SPECIFICATION_VERSION; diff --git a/org.osgi.service.http.whiteboard/src/org/osgi/service/http/runtime/dto/DTOConstants.java b/org.osgi.service.http.whiteboard/src/org/osgi/service/http/runtime/dto/DTOConstants.java index 55ffe95c0c..d8b55fc825 100644 --- a/org.osgi.service.http.whiteboard/src/org/osgi/service/http/runtime/dto/DTOConstants.java +++ b/org.osgi.service.http.whiteboard/src/org/osgi/service/http/runtime/dto/DTOConstants.java @@ -45,8 +45,9 @@ private DTOConstants() { /** * Service is shadowed by another service. *

    - * For example, a service with the same service properties but a higher - * service ranking. + * For example, another service with the same service properties but having + * a higher service ranking. See + * {@link org.osgi.framework.ServiceReference#compareTo(Object)}. */ public static final int FAILURE_REASON_SHADOWED_BY_OTHER_SERVICE = 3; diff --git a/org.osgi.service.http.whiteboard/src/org/osgi/service/http/runtime/dto/package-info.java b/org.osgi.service.http.whiteboard/src/org/osgi/service/http/runtime/dto/package-info.java index a4559c03b6..ad5c469578 100644 --- a/org.osgi.service.http.whiteboard/src/org/osgi/service/http/runtime/dto/package-info.java +++ b/org.osgi.service.http.whiteboard/src/org/osgi/service/http/runtime/dto/package-info.java @@ -35,7 +35,7 @@ * @author $Id$ */ -@Version(HTTP_WHITEBOARD_SPECIFICATION_VERSION + ".0") +@Version(HTTP_WHITEBOARD_SPECIFICATION_VERSION + ".1") package org.osgi.service.http.runtime.dto; import static org.osgi.service.http.whiteboard.HttpWhiteboardConstants.HTTP_WHITEBOARD_SPECIFICATION_VERSION; diff --git a/org.osgi.service.http.whiteboard/src/org/osgi/service/http/whiteboard/Preprocessor.java b/org.osgi.service.http.whiteboard/src/org/osgi/service/http/whiteboard/Preprocessor.java index 5f0ef75b6a..2e23a38f53 100644 --- a/org.osgi.service.http.whiteboard/src/org/osgi/service/http/whiteboard/Preprocessor.java +++ b/org.osgi.service.http.whiteboard/src/org/osgi/service/http/whiteboard/Preprocessor.java @@ -26,10 +26,9 @@ * Services registered as a {@code Preprocessor} using a whiteboard pattern are * executed for every request before the dispatching is performed. *

    - * If there are several services of this type, they are run in order of their - * service ranking, the one with the highest ranking is used first. In the case - * of a service ranking tie, the service with the lowest service id is processed - * first. + * If there are several services of this type, they are run in + * {@link org.osgi.framework.ServiceReference#compareTo(Object) ranking order}, + * the one with the highest ranking is used first. *

    * The preprocessor is handled in the same way as filters. When a preprocessor * is put into service {@link Filter#init(javax.servlet.FilterConfig)} is diff --git a/org.osgi.service.http.whiteboard/src/org/osgi/service/http/whiteboard/package-info.java b/org.osgi.service.http.whiteboard/src/org/osgi/service/http/whiteboard/package-info.java index 0433e91e19..e46233b315 100644 --- a/org.osgi.service.http.whiteboard/src/org/osgi/service/http/whiteboard/package-info.java +++ b/org.osgi.service.http.whiteboard/src/org/osgi/service/http/whiteboard/package-info.java @@ -35,7 +35,7 @@ * @author $Id$ */ -@Version(HTTP_WHITEBOARD_SPECIFICATION_VERSION + ".1") +@Version(HTTP_WHITEBOARD_SPECIFICATION_VERSION + ".2") package org.osgi.service.http.whiteboard; import static org.osgi.service.http.whiteboard.HttpWhiteboardConstants.HTTP_WHITEBOARD_SPECIFICATION_VERSION; diff --git a/org.osgi.service.jaxrs/src/org/osgi/service/jaxrs/runtime/dto/DTOConstants.java b/org.osgi.service.jaxrs/src/org/osgi/service/jaxrs/runtime/dto/DTOConstants.java index fa5927a60f..056a696b55 100644 --- a/org.osgi.service.jaxrs/src/org/osgi/service/jaxrs/runtime/dto/DTOConstants.java +++ b/org.osgi.service.jaxrs/src/org/osgi/service/jaxrs/runtime/dto/DTOConstants.java @@ -37,8 +37,9 @@ private DTOConstants() { /** * Service is shadowed by another service. *

    - * For example, a service with the same service properties but a higher - * service ranking. + * For example, another service with the same service properties but having + * a higher service ranking. See + * {@link org.osgi.framework.ServiceReference#compareTo(Object)}. */ public static final int FAILURE_REASON_SHADOWED_BY_OTHER_SERVICE = 1; diff --git a/org.osgi.service.jaxrs/src/org/osgi/service/jaxrs/runtime/dto/package-info.java b/org.osgi.service.jaxrs/src/org/osgi/service/jaxrs/runtime/dto/package-info.java index 0c0fab8895..28ae9ff063 100644 --- a/org.osgi.service.jaxrs/src/org/osgi/service/jaxrs/runtime/dto/package-info.java +++ b/org.osgi.service.jaxrs/src/org/osgi/service/jaxrs/runtime/dto/package-info.java @@ -35,7 +35,7 @@ * @author $Id$ */ -@Version(JAX_RS_WHITEBOARD_SPECIFICATION_VERSION + ".0") +@Version(JAX_RS_WHITEBOARD_SPECIFICATION_VERSION + ".1") package org.osgi.service.jaxrs.runtime.dto; import static org.osgi.service.jaxrs.whiteboard.JaxrsWhiteboardConstants.JAX_RS_WHITEBOARD_SPECIFICATION_VERSION; diff --git a/org.osgi.service.jaxrs/src/org/osgi/service/jaxrs/whiteboard/package-info.java b/org.osgi.service.jaxrs/src/org/osgi/service/jaxrs/whiteboard/package-info.java index 5da2d783e5..72127e120d 100644 --- a/org.osgi.service.jaxrs/src/org/osgi/service/jaxrs/whiteboard/package-info.java +++ b/org.osgi.service.jaxrs/src/org/osgi/service/jaxrs/whiteboard/package-info.java @@ -35,7 +35,7 @@ * @author $Id$ */ -@Version(JAX_RS_WHITEBOARD_SPECIFICATION_VERSION + ".1") +@Version(JAX_RS_WHITEBOARD_SPECIFICATION_VERSION + ".2") package org.osgi.service.jaxrs.whiteboard; import static org.osgi.service.jaxrs.whiteboard.JaxrsWhiteboardConstants.JAX_RS_WHITEBOARD_SPECIFICATION_VERSION; diff --git a/org.osgi.util.tracker/src/org/osgi/util/tracker/ServiceTracker.java b/org.osgi.util.tracker/src/org/osgi/util/tracker/ServiceTracker.java index 67bfe046ad..c872213110 100644 --- a/org.osgi.util.tracker/src/org/osgi/util/tracker/ServiceTracker.java +++ b/org.osgi.util.tracker/src/org/osgi/util/tracker/ServiceTracker.java @@ -544,15 +544,11 @@ public ServiceReference[] getServiceReferences() { /** * Returns a {@code ServiceReference} for one of the services being tracked * by this {@code ServiceTracker}. - * *

    - * If multiple services are being tracked, the service with the highest - * ranking (as specified in its {@code service.ranking} property) is - * returned. If there is a tie in ranking, the service with the lowest - * service id (as specified in its {@code service.id} property); that is, - * the service that was registered first is returned. This is the same - * algorithm used by {@code BundleContext.getServiceReference}. - * + * If multiple services are being tracked, the service that is first in the + * {@link ServiceReference#compareTo(Object) ranking order} is returned. + * This is the same algorithm used by + * {@code BundleContext.getServiceReference}. *

    * This implementation calls {@link #getServiceReferences()} to get the list * of references for the tracked services. @@ -775,9 +771,8 @@ void modified() { /** * Return a {@code SortedMap} of the {@code ServiceReference}s and service * objects for all services being tracked by this {@code ServiceTracker}. - * The map is sorted in reverse natural order of {@code ServiceReference}. - * That is, the first entry is the service with the highest ranking and the - * lowest service id. + * The map is sorted in {@link ServiceReference#compareTo(Object) ranking + * order}. * * @return A {@code SortedMap} with the {@code ServiceReference}s and * service objects for all services being tracked by this diff --git a/org.osgi.util.tracker/src/org/osgi/util/tracker/package-info.java b/org.osgi.util.tracker/src/org/osgi/util/tracker/package-info.java index 525c871316..1dc0c9a45a 100644 --- a/org.osgi.util.tracker/src/org/osgi/util/tracker/package-info.java +++ b/org.osgi.util.tracker/src/org/osgi/util/tracker/package-info.java @@ -31,7 +31,7 @@ * @author $Id$ */ -@Version("1.5.4") +@Version("1.5.5") package org.osgi.util.tracker; import org.osgi.annotation.versioning.Version; diff --git a/osgi.specs/docbook/112/service.component.xml b/osgi.specs/docbook/112/service.component.xml index 35a3ff2a74..6e4b1e7204 100644 --- a/osgi.specs/docbook/112/service.component.xml +++ b/osgi.specs/docbook/112/service.component.xml @@ -731,9 +731,9 @@ Map - An unmodifiable Map containing the service properties of the bound service. This Map must additionally implement Comparable with the compareTo - method comparing service property maps using the same ordering as - ServiceReference.compareTo based upon service ranking - and service id. + method comparing service property maps using an ordering which is + the same as the natural ordering of ServiceReferences + as specified in ServiceReference.compareTo. @@ -943,9 +943,9 @@ Map - An unmodifiable Map containing the service properties of the bound service. This Map must additionally implement Comparable with the compareTo - method comparing service property maps using the same ordering as - ServiceReference.compareTo based upon service ranking - and service id. + method comparing service property maps using an ordering which is + the same as the natural ordering of ServiceReferences + as specified in ServiceReference.compareTo. @@ -954,9 +954,9 @@ bound service, as above, and whose value is the bound service object. This Map.Entry must additionally implement Comparable with the compareTo method - comparing the service property map key using the same ordering as - ServiceReference.compareTo based upon service ranking - and service id. + comparing the service property map key using an ordering which is + the same as the natural ordering of ServiceReferences + as specified in ServiceReference.compareTo. @@ -1265,11 +1265,8 @@ multiplicity ::= '1' | 'n' unsatisfied, the component configuration must be deactivated. If the reference has a unary cardinality and there is more than one target service for the reference, then the bound service must be the target - service with the highest service ranking as specified by the - service.ranking property. If there are multiple target - services with the same service ranking, then the bound service must be - the target service with the highest service ranking and the lowest - service id as specified by the service.id property. + service whose ServiceReference is first in the ranking + order as specified in ServiceReference.compareTo. In the following example, a component wants to register a resource with all Http Services that are available. Such a scenario has the @@ -1652,17 +1649,19 @@ public class HttpResourceImpl { if present, and the field must not be modified. Before the component instance is activated, SCR must set the field value with a new mutable collection that must contain the initial set of bound services sorted - using the same ordering as ServiceReference.compareTo - based upon service ranking and service id. The collection may be empty + using an ordering which is the same as the natural ordering of + ServiceReferences as specified in + ServiceReference.compareTo. The collection may be empty if the reference has optional cardinality and there are no bound services. If the reference is dynamic, when there is a change in the set of bound services or the service properties of a bound service are modified and the collection holds service properties, SCR must replace the field value with a new mutable collection that must contain the - updated set of bound services sorted using the same ordering as - ServiceReference.compareTo based upon service ranking and - service id. The new collection may be empty if the reference has - optional cardinality and there are no bound services. + updated set of bound services sorted using an ordering which is the + same as the natural ordering of ServiceReferences as + specified in ServiceReference.compareTo. The new + collection may be empty if the reference has optional cardinality and + there are no bound services.

    diff --git a/osgi.specs/docbook/126/service.jndi.xml b/osgi.specs/docbook/126/service.jndi.xml index fbdfa8ef09..6c0a199bdc 100644 --- a/osgi.specs/docbook/126/service.jndi.xml +++ b/osgi.specs/docbook/126/service.jndi.xml @@ -16,7 +16,6 @@ SPDX-License-Identifier: Apache-2.0 --> - registry. If such a service is found, then that service is used to create a new Context, which is subsequently returned. If no class name is specified, the service registry is searched for Initial Context - Factory services. These services are tried in ranking order to see if - they can create an appropriate Context, the first one that can create a - Context is then used. + Factory services. These services are tried in ranking order, as + specified in ServiceReference.compareTo, to see if they can + create an appropriate Context, the first one that can create a Context + is then used. If no class name is specified, all Initial Context Factory Builder services are tried to see if they can create a Context, the first @@ -693,11 +693,8 @@ javax.naming.directory In the following sections the cases for presence or absence of the java.naming.factory.initial property are described. Several steps in these algorithm iterate over a set of available services. This - iteration must always take place in service ranking - order. Service ranking order follows the ordering of the - service.ranking service property, which is the highest - service.ranking value, or when equal, the lowest - service.id value. + iteration must always take place in ranking order as specified in + ServiceReference.compareTo. Exception handling in the following steps is as follows: @@ -971,10 +968,11 @@ javax.naming.directory initial Context their applications receive. An Initial Context Factory Builder provider must register an - Initial Context Factory Builder service. The - service.ranking property defines the iteration ordering of - multiple Initial Context Factory Builder services. Implementations must - be careful to correctly provide defaults. + Initial Context Factory Builder service. The iteration ordering of + multiple Initial Context Factory Builder services must always take place + in ranking order as specified in + ServiceReference.compareTo. Implementations must be careful + to correctly provide defaults. For example, a container could use a thread local variable to mark the stack for a specific application. The implementation of the Initial @@ -1219,11 +1217,11 @@ jndi-name ::= <any string> incompatible with the class space of the owning bundle. The lookup for a URL with the osgi: scheme and - service path returns the service with highest - service.ranking and the lowest service.id. This - scheme only allows a single service to be found. Multiple services can be - obtained with the osgi: scheme and servicelist - path: + service path returns the service whose + ServiceReference is first in ranking order as specified in + ServiceReference.compareTo. This scheme only allows a single + service to be found. Multiple services can be obtained with the + osgi: scheme and servicelist path: servicelist ::= 'osgi:servicelist/' query? diff --git a/osgi.specs/docbook/140/service.http.whiteboard.xml b/osgi.specs/docbook/140/service.http.whiteboard.xml index 91aa3a898a..87ef572b4c 100644 --- a/osgi.specs/docbook/140/service.http.whiteboard.xml +++ b/osgi.specs/docbook/140/service.http.whiteboard.xml @@ -248,12 +248,11 @@ default. To override the default, register a custom ServletContextHelper service with the name default. If multiple Servlet Context Helper services - are registered with the same name, the one with the highest - Service Ranking is used. In case of a tie, the service with the - lowest service ID wins. In other words, the normal OSGi service - ranking applies. Registrations with an invalid or - unspecified name are not used and reflected in the failure DTOs. - See ServiceReference.compareTo, is + used.Registrations with an invalid or unspecified + name are not used and reflected in the failure DTOs. See . @@ -303,10 +302,10 @@ - In the case of two Servlet Context Helpers with the same path, - the service with the highest ranking is searched first for a match. - In the case of a tie, the lowest service ID is searched - first. + In the case of multiple Servlet Context Helper services with + the same path, the services are searched in ranking order, as + specified in ServiceReference.compareTo, for a + match. @@ -324,7 +323,7 @@ osgi.http.whiteboard.context.path = /foo/bar Then a request /foo context looking for a pattern to match /bar/someServlet - Note that whole path segments must match. Therefore the + Note that whole path segments must match. Therefore the following request can only be handled by the Servlet Context Helper registered under the /foo path: http://localhost/foo/bars/someOtherServlet. @@ -335,7 +334,7 @@ osgi.http.whiteboard.context.path = /foo/bar Then a request linkend="service.http.whiteboard.common.properties"/>. If a Servlet Context Helper can not be used, for example because it - is shadowed by another Servlet Context Helper service with the same name, + is shadowed by another Servlet Context Helper service with the same name but with a higher ranking, this is reflected in the . Similarly, if an alternative default @@ -700,8 +699,8 @@ public class CDNServletContextHelper extends ServletContextHelper { osgi.http.whiteboard.servlet.name property, if associated with this Servlet Context Helper. If multiple servlets have the same name and are associated with this Servlet - Context Helper then the highest ranked servlet is used. In the - case of a tie, the one with the lowest service ID is + Context Helper, then the servlet that is first in ranking order, + as specified in ServiceReference.compareTo, is used. @@ -1102,11 +1101,12 @@ public class CDNServletContextHelper extends ServletContextHelper { Servlet and resource service registrations associated with a single Servlet Context share the same namespace. In case of - identical registration patterns, service ranking rules are used to select - the service handling a request. That is, Whiteboard servlets that have - patterns shadowed by other Whiteboard services associated with the - same Servlet Context are represented in the failure - DTOs. + identical registration patterns, the service that is first in ranking + order, as specified in ServiceReference.compareTo, is + selected as the service handling a request. That is, Whiteboard servlets + that have patterns shadowed by other Whiteboard services associated with + the same Servlet Context are represented in the + failure DTOs. The above rules can cause servlets that are already bound becoming unbound if a better match arrives. This ensures a predictable end result @@ -1493,7 +1493,8 @@ public class MyErrorServlet extends HttpServlet { The example servlet is invoked in case of a 500 error code, or if an IOException (or subclass) occurs. If there is more than one error page registered for the same exception or error - code, service ranking rules are used to select the handling + code, the service that is first in ranking order, as specified in + ServiceReference.compareTo, is selected as the handling servlet.
    @@ -1727,13 +1728,12 @@ public class AsyncServlet extends HttpServlet { services. Multiple servlet filters can process the same servlet - request/response. If more than one Filter matches, the order - in which they are processed is governed by their service ranking. The - servlet filter with the highest ranking is processed first in the filter - chain, while the servlet filter with the lowest ranking is processed last, - before the Servlet.service method is called. In the case of a - service ranking tie, the servlet filter with the lowest - service.id is processed first. After the servlet completes + request/response. If more than one Filter matches, they are + processed in ranking order, as specified in + ServiceReference.compareTo. The servlet filter with the + highest ranking is processed first in the filter chain, while the servlet + filter with the lowest ranking is processed last, before the + Servlet.service method is called. After the servlet completes its service method the filter chain is unwound in reverse order. @@ -2064,8 +2064,8 @@ public class SomeResourceService {} Helper. Multiple listeners of the same type registered with a given Servlet - Context Helper are invoked in sequence, service ranking rules are used to - determine the order. + Context Helper are invoked in ranking order, as specified in + ServiceReference.compareTo. Service properties for listener services. diff --git a/osgi.specs/docbook/151/service.jaxrs.xml b/osgi.specs/docbook/151/service.jaxrs.xml index 832e453504..6261ec7316 100644 --- a/osgi.specs/docbook/151/service.jaxrs.xml +++ b/osgi.specs/docbook/151/service.jaxrs.xml @@ -16,7 +16,6 @@ SPDX-License-Identifier: Apache-2.0 --> - ServiceReference.compareTo, is bound and the lower ranked service(s) are reflected in the failure DTOs. See When clashes occur in the JAX-RS whiteboard then resources supplied using the service whiteboard must be preferred to static resources contained in the application. If two or more whiteboard - resources exist then they must be ordered using their service ranking. - Unlike for other services in the JAX-RS whiteboard, whiteboard - resource services must not be ordered using their natural ordering. - Whiteboard resource services with the same ranking must be considered - equal, following the normal resource method selection rules defined in - the JAX-RS specification. As per the core specification, whiteboard - services with no service.ranking property must be treated - as having a ranking of 0. + resources exist then they must be ordered using ranking order, as + specified in ServiceReference.compareTo. Unlike for other + services in the JAX-RS whiteboard, whiteboard resource services must + not be ordered using their natural ordering. Whiteboard resource + services with the same ranking must be considered equal, following the + normal resource method selection rules defined in the JAX-RS + specification. As per the Core specification, whiteboard services with + no service.ranking property must be treated as having a + ranking of 0. @@ -719,17 +720,17 @@ public class Foo { } } - Single valued asynchronous results can also be provided by returning - a suitable type from the resource method. This can be a + Single valued asynchronous results can also be provided by + returning a suitable type from the resource method. This can be a CompletionStage as described in the JAX-RS specification, - or an OSGi Promise type. In this case the response from the - resource method will be sent once the returned type has completed, either - successfully or by failing. - - The following example demonstrates the use of an - asynchronous return value: - -@Component(service = MyResource.class, + or an OSGi Promise type. In this case the response from + the resource method will be sent once the returned type has completed, + either successfully or by failing. + + The following example demonstrates the use of an asynchronous + return value: + + @Component(service = MyResource.class, scope = ServiceScope.PROTOTYPE) @JaxrsResource public class MyResource { @@ -1015,8 +1016,9 @@ public class FizzResource { ordered according to their javax.annotation.Priority. If two extensions of the same type have the same priority then the whiteboard implementation must break the tie by ordering the extensions - according to the natural ordering of their service references, with - static extensions being ranked below all whiteboard services. + according to the natural ordering of their service references, as + specified in ServiceReference.compareTo, with static + extensions being ranked below all whiteboard services. The extension processing flow is as follows: @@ -1326,11 +1328,12 @@ public class JsonProvider implements MessageBodyReader, The base URI for each application within the whiteboard must be unique. If two or more applications targeting the same whiteboard are - registered with the same base URI then only the highest ranked service - will be made available. All other application services with that URI - will have a failure DTO created for them. The same rules also apply to - the osgi.jaxrs.name property, with the highest ranked - service shadowing other applications with the same name. + registered with the same base URI then only the first in ranking order, + as specified in ServiceReference.compareTo, will be made + available. All other application services with that URI will have a + failure DTO created for them. The same rules also apply to the + osgi.jaxrs.name property, with the highest ranked service + shadowing other applications with the same name. The default application is implicitly created by the whiteboard and has the name .default. The default application has a diff --git a/osgi.specs/docbook/core/005/framework.service.xml b/osgi.specs/docbook/core/005/framework.service.xml index df3116549f..aeefda7908 100644 --- a/osgi.specs/docbook/core/005/framework.service.xml +++ b/osgi.specs/docbook/core/005/framework.service.xml @@ -678,8 +678,9 @@ ranking order is in descending service.ranking numeric order where ties give a preference to the earlier registrant. - The ranking order is the reverse of the natural ordering of a - ServiceReference object. + The ranking order is the reverse of the natural + ordering of a ServiceReference object. The purpose of the ranking order is to allow: @@ -735,14 +736,10 @@ ServiceReference object to a service object that implements, and was registered under, the name of the specified service interface. If multiple such service objects exist, a - ServiceReference object to the service object with the - highest is returned. If there is a tie in ranking, a - ServiceReference object to the service object with the - lowest (the service object that was registered - first) is returned. If no matching service objects are registered - then null must be returned. + ServiceReference object to the service that is first in + ranking + order is returned. If no matching service objects are + registered then null must be returned. @@ -772,7 +769,9 @@ xrefstyle="hyperlink"/> method and an empty collection must be returned by the method. + xrefstyle="hyperlink"/> method. There is no guarantee that the + ServiceReference objects in the array or collection + will be in any specific order. diff --git a/osgi.specs/docbook/core/052/service.url.xml b/osgi.specs/docbook/core/052/service.url.xml index 7e2ee6c96a..18fd37d1ab 100644 --- a/osgi.specs/docbook/core/052/service.url.xml +++ b/osgi.specs/docbook/core/052/service.url.xml @@ -16,7 +16,6 @@ SPDX-License-Identifier: Apache-2.0 --> - Once the proxy is created, it must track the service registry for registrations and unregistrations of services matching its associated scheme. The proxy must be associated with the service that matches the - scheme and has the highest value for the - org.osgi.framework.Constants.SERVICE_RANKING service - registration property (see ) at any moment in time. - If a proxy is associated with a URL Stream Handler Service, it must - change the associated handler to a newly registered service when that - service has a higher value for the ranking property. + scheme and has the highest ranking (first in ranking order) at + any moment in time. If a proxy is associated with a URL Stream Handler + Service, it must change the associated handler to a newly registered + service when that service has a higher ranking. The proxy object must forward all method requests to the associated URL Stream Handler Service until this service object becomes @@ -538,8 +535,8 @@ com.acme.url.application.zip implementation classes, the AbstractURLStreamHandlerService has been provided. Apart from making the relevant methods public, the AbstractURLStreamHandlerService stores the - URLStreamHandlerSetter object in a private variable. To make the - setURL method work properly, it overrides the + URLStreamHandlerSetter object in a private variable. To + make the setURL method work properly, it overrides the setURL method to invoke the setURL method on the saved URLStreamHandlerSetter object rather then the URLStreamHandler.setURL method. This means that a subclass diff --git a/osgi.specs/docbook/core/055/framework.servicehooks.xml b/osgi.specs/docbook/core/055/framework.servicehooks.xml index 956eb9f186..bbb9b3eed2 100644 --- a/osgi.specs/docbook/core/055/framework.servicehooks.xml +++ b/osgi.specs/docbook/core/055/framework.servicehooks.xml @@ -16,7 +16,6 @@ SPDX-License-Identifier: Apache-2.0 --> - object as a service with the framework. The framework must then send a service events to all the registered hooks. The - calling order of the hooks is defined by the reversed - compareTo ordering of their Service Reference objects. That - is, the service with the highest ranking number is called first. Event - Listener Hooks are called after the event is - generated but before they are filtered by the - optional filter expressions of the service listeners. Before the return, - the handler can remove bundles from the given list. This allows an Event - Listener Hook to hide service events for specific bundles. + calling order of the hooks is defined by ranking order, see . That is, the service + with the highest ranking is called first. Event Listener Hooks are called + after the event is generated but + before they are filtered by the optional filter + expressions of the service listeners. Before the return, the handler can + remove bundles from the given list. This allows an Event Listener Hook to + hide service events for specific bundles. The model is depicted in the . A target bundle listens for service events but these events can be filtered by the @@ -630,10 +629,10 @@ registry with the getServiceReference or getServiceReferences methods. A registered Find Hook service gets a chance to inspect the returned set of service references and can - optionally shrink the set of returned services. The order in which the - find hooks are called is the reverse compareTo ordering of - their Service References. That is, the service with the highest ranking - number must be called first. + optionally shrink the set of returned services. The calling order of the + hooks is defined by ranking order, see . That is, the service + with the highest ranking number must be called first.