You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by cz...@apache.org on 2014/07/30 09:22:35 UTC
svn commit: r1614569 [2/5] - in /felix/trunk/framework: ./
src/main/appended-resources/META-INF/
src/main/java/org/apache/felix/framework/ src/main/java/org/osgi/dto/
src/main/java/org/osgi/framework/ src/main/java/org/osgi/framework/dto/
src/main/java...
Modified: felix/trunk/framework/src/main/java/org/osgi/framework/BundleContext.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/BundleContext.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/BundleContext.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/BundleContext.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2014). 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.
@@ -20,6 +20,7 @@ import java.io.File;
import java.io.InputStream;
import java.util.Collection;
import java.util.Dictionary;
+import org.osgi.annotation.versioning.ProviderType;
/**
* A bundle's execution context within the Framework. The context is used to
@@ -29,15 +30,15 @@ import java.util.Dictionary;
* <p>
* {@code BundleContext} methods allow a bundle to:
* <ul>
- * <li>Subscribe to events published by the Framework.
- * <li>Register service objects with the Framework service registry.
- * <li>Retrieve {@code ServiceReferences} from the Framework service registry.
- * <li>Get and release service objects for a referenced service.
- * <li>Install new bundles in the Framework.
- * <li>Get the list of bundles installed in the Framework.
- * <li>Get the {@link Bundle} object for a bundle.
+ * <li>Subscribe to events published by the Framework.</li>
+ * <li>Register service objects with the Framework service registry.</li>
+ * <li>Retrieve {@code ServiceReferences} from the Framework service registry.</li>
+ * <li>Get and release service objects for a referenced service.</li>
+ * <li>Install new bundles in the Framework.</li>
+ * <li>Get the list of bundles installed in the Framework.</li>
+ * <li>Get the {@link Bundle} object for a bundle.</li>
* <li>Create {@code File} objects for files in a persistent storage area
- * provided for the bundle by the Framework.
+ * provided for the bundle by the Framework.</li>
* </ul>
*
* <p>
@@ -57,8 +58,17 @@ import java.util.Dictionary;
* <p>
* The {@code BundleContext} object is only valid during the execution of its
* context bundle; that is, during the period from when the context bundle is in
- * the {@code STARTING}, {@code STOPPING}, and {@code ACTIVE} bundle states. If
- * the {@code BundleContext} object is used subsequently, an
+ * the {@code STARTING}, {@code STOPPING}, and {@code ACTIVE} bundle states.
+ * However, the {@code BundleContext} object becomes invalid after
+ * {@link BundleActivator#stop(BundleContext)} returns (if the bundle has a
+ * Bundle Activator). The {@code BundleContext} object becomes invalid before
+ * disposing of any remaining registered services and releasing any remaining
+ * services in use. Since those activities can result in other bundles being
+ * called (for example, {@link ServiceListener}s for
+ * {@link ServiceEvent#UNREGISTERING} events and {@link ServiceFactory}s for
+ * unget operations), those other bundles can observe the stopping bundle in the
+ * {@code STOPPING} state but with an invalid {@code BundleContext} object. If
+ * the {@code BundleContext} object is used after it has become invalid, an
* {@code IllegalStateException} must be thrown. The {@code BundleContext}
* object must never be reused after its context bundle is stopped.
*
@@ -75,10 +85,9 @@ import java.util.Dictionary;
* Environment supports permissions.
*
* @ThreadSafe
- * @noimplement
- * @version $Id: 4f166fd274f3965e48a7dbc239213d00e062b6d0 $
+ * @author $Id: fbf0b18296a0b85d628ee8c47d0f0f213a914e48 $
*/
-
+@ProviderType
public interface BundleContext extends BundleReference {
/**
@@ -127,29 +136,24 @@ public interface BundleContext extends B
* The following steps are required to install a bundle:
* <ol>
* <li>If a bundle containing the same location identifier is already
- * installed, the {@code Bundle} object for that bundle is returned.
- *
+ * installed, the {@code Bundle} object for that bundle is returned.</li>
* <li>The bundle's content is read from the input stream. If this fails, a
- * {@link BundleException} is thrown.
- *
+ * {@link BundleException} is thrown.</li>
* <li>The bundle's associated resources are allocated. The associated
* resources minimally consist of a unique identifier and a persistent
* storage area if the platform has file system support. If this step fails,
- * a {@code BundleException} is thrown.
- *
- * <li>The bundle's state is set to {@code INSTALLED}.
- *
- * <li>A bundle event of type {@link BundleEvent#INSTALLED} is fired.
- *
+ * a {@code BundleException} is thrown.</li>
+ * <li>The bundle's state is set to {@code INSTALLED}.</li>
+ * <li>A bundle event of type {@link BundleEvent#INSTALLED} is fired.</li>
* <li>The {@code Bundle} object for the newly or previously installed
- * bundle is returned.
+ * bundle is returned.</li>
* </ol>
*
* <b>Postconditions, no exceptions thrown </b>
* <ul>
* <li>{@code getState()} in { {@code INSTALLED}, {@code RESOLVED}
- * }.
- * <li>Bundle has a unique ID.
+ * }.</li>
+ * <li>Bundle has a unique ID.</li>
* </ul>
* <b>Postconditions, when an exception is thrown </b>
* <ul>
@@ -386,29 +390,36 @@ public interface BundleContext extends B
* <p>
* The following steps are required to register a service:
* <ol>
- * <li>If {@code service} is not a {@code ServiceFactory}, an
+ * <li>If {@code service} does not implement {@code ServiceFactory}, an
* {@code IllegalArgumentException} is thrown if {@code service} is not an
- * {@code instanceof} all the specified class names.
+ * {@code instanceof} all the specified class names.</li>
* <li>The Framework adds the following service properties to the service
* properties from the specified {@code Dictionary} (which may be
- * {@code null}): <br/>
- * A property named {@link Constants#SERVICE_ID} identifying the
- * registration number of the service <br/>
- * A property named {@link Constants#OBJECTCLASS} containing all the
- * specified classes. <br/>
+ * {@code null}):
+ * <ul>
+ * <li>A property named {@link Constants#SERVICE_ID} identifying the
+ * registration number of the service</li>
+ * <li>A property named {@link Constants#OBJECTCLASS} containing all the
+ * specified classes.</li>
+ * <li>A property named {@link Constants#SERVICE_SCOPE} identifying the
+ * scope of the service.</li>
+ * <li>A property named {@link Constants#SERVICE_BUNDLEID} identifying the
+ * the context bundle.</li>
+ * </ul>
* Properties with these names in the specified {@code Dictionary} will be
- * ignored.
+ * ignored.</li>
* <li>The service is added to the Framework service registry and may now be
- * used by other bundles.
- * <li>A service event of type {@link ServiceEvent#REGISTERED} is fired.
+ * used by other bundles.</li>
+ * <li>A service event of type {@link ServiceEvent#REGISTERED} is fired.</li>
* <li>A {@code ServiceRegistration} object for this registration is
- * returned.
+ * returned.</li>
* </ol>
*
* @param clazzes The class names under which the service can be located.
* The class names in this array will be stored in the service's
* properties under the key {@link Constants#OBJECTCLASS}.
- * @param service The service object or a {@code ServiceFactory} object.
+ * @param service The service object or an object implementing
+ * {@code ServiceFactory}.
* @param properties The properties for this service. The keys in the
* properties object must all be {@code String} objects. See
* {@link Constants} for a list of standard service property keys.
@@ -422,10 +433,10 @@ public interface BundleContext extends B
* unregister the service.
* @throws IllegalArgumentException If one of the following is true:
* <ul>
- * <li>{@code service} is {@code null}. <li>{@code service} is not a
- * {@code ServiceFactory} object and is not an instance of all the
- * named classes in {@code clazzes}. <li> {@code properties}
- * contains case variants of the same key name.
+ * <li>{@code service} is {@code null}.</li><li>{@code service} does
+ * not implement {@code ServiceFactory} and is not an instance of
+ * all the specified classes.</li><li> {@code properties} contains
+ * case variants of the same key name.</li>
* </ul>
* @throws SecurityException If the caller does not have the
* {@code ServicePermission} to register the service for all the
@@ -433,6 +444,7 @@ public interface BundleContext extends B
* permissions.
* @throws IllegalStateException If this BundleContext is no longer valid.
* @see ServiceRegistration
+ * @see PrototypeServiceFactory
* @see ServiceFactory
*/
ServiceRegistration<?> registerService(String[] clazzes, Object service, Dictionary<String, ?> properties);
@@ -450,7 +462,8 @@ public interface BundleContext extends B
* than just a single string.
*
* @param clazz The class name under which the service can be located.
- * @param service The service object or a {@code ServiceFactory} object.
+ * @param service The service object or an object implementing
+ * {@code ServiceFactory}.
* @param properties The properties for this service.
* @return A {@code ServiceRegistration} object for use by the bundle
* registering the service to update the service's properties or to
@@ -471,7 +484,8 @@ public interface BundleContext extends B
*
* @param <S> Type of Service.
* @param clazz The class under whose name the service can be located.
- * @param service The service object or a {@code ServiceFactory} object.
+ * @param service The service object or an object implementing
+ * {@code ServiceFactory}.
* @param properties The properties for this service.
* @return A {@code ServiceRegistration} object for use by the bundle
* registering the service to update the service's properties or to
@@ -483,6 +497,29 @@ public interface BundleContext extends B
<S> ServiceRegistration<S> registerService(Class<S> clazz, S service, Dictionary<String, ?> properties);
/**
+ * Registers the specified service factory object with the specified
+ * properties under the name of the specified class with the Framework.
+ *
+ * <p>
+ * This method is otherwise identical to
+ * {@link #registerService(Class, Object, Dictionary)} and is provided to
+ * return a type safe {@code ServiceRegistration} when registering a
+ * {@link ServiceFactory}.
+ *
+ * @param <S> Type of Service.
+ * @param clazz The class under whose name the service can be located.
+ * @param factory The {@code ServiceFactory} object.
+ * @param properties The properties for this service.
+ * @return A {@code ServiceRegistration} object for use by the bundle
+ * registering the service to update the service's properties or to
+ * unregister the service.
+ * @throws IllegalStateException If this BundleContext is no longer valid.
+ * @see #registerService(Class, Object, Dictionary)
+ * @since 1.8
+ */
+ <S> ServiceRegistration<S> registerService(Class<S> clazz, ServiceFactory<S> factory, Dictionary<String, ?> properties);
+
+ /**
* Returns an array of {@code ServiceReference} objects. The returned array
* of {@code ServiceReference} objects contains services that were
* registered under the specified class, match the specified filter
@@ -513,16 +550,16 @@ public interface BundleContext extends B
* service must have been registered with the specified class name. The
* complete list of class names with which a service was registered is
* available from the service's {@link Constants#OBJECTCLASS objectClass}
- * property.
+ * property.</li>
* <li>If the specified {@code filter} is not {@code null}, the filter
- * expression must match the service.
+ * expression must match the service.</li>
* <li>If the Java Runtime Environment supports permissions, the caller must
* have {@code ServicePermission} with the {@code GET} action for at least
- * one of the class names under which the service was registered.
+ * one of the class names under which the service was registered.</li>
* <li>For each class name with which the service was registered, calling
* {@link ServiceReference#isAssignableTo(Bundle, String)} with the context
* bundle and the class name on the service's {@code ServiceReference}
- * object must return {@code true}
+ * object must return {@code true}</li>
* </ul>
*
* @param clazz The class name with which the service was registered or
@@ -565,12 +602,12 @@ public interface BundleContext extends B
* service must have been registered with the specified class name. The
* complete list of class names with which a service was registered is
* available from the service's {@link Constants#OBJECTCLASS objectClass}
- * property.
+ * property.</li>
* <li>If the specified {@code filter} is not {@code null}, the filter
- * expression must match the service.
+ * expression must match the service.</li>
* <li>If the Java Runtime Environment supports permissions, the caller must
* have {@code ServicePermission} with the {@code GET} action for at least
- * one of the class names under which the service was registered.
+ * one of the class names under which the service was registered.</li>
* </ul>
*
* @param clazz The class name with which the service was registered or
@@ -606,7 +643,7 @@ public interface BundleContext extends B
* highest ranking (as specified in its {@link Constants#SERVICE_RANKING}
* property) is returned.
* <p>
- * If there is a tie in ranking, the service with the lowest service ID (as
+ * 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.
*
@@ -636,7 +673,7 @@ public interface BundleContext extends B
* If multiple such services exist, the service with the highest ranking (as
* specified in its {@link Constants#SERVICE_RANKING} property) is returned.
* <p>
- * If there is a tie in ranking, the service with the lowest service ID (as
+ * 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.
*
@@ -681,16 +718,16 @@ public interface BundleContext extends B
* <li>The service must have been registered with the name of the specified
* class. The complete list of class names with which a service was
* registered is available from the service's {@link Constants#OBJECTCLASS
- * objectClass} property.
+ * objectClass} property.</li>
* <li>If the specified {@code filter} is not {@code null}, the filter
- * expression must match the service.
+ * expression must match the service.</li>
* <li>If the Java Runtime Environment supports permissions, the caller must
* have {@code ServicePermission} with the {@code GET} action for at least
- * one of the class names under which the service was registered.
+ * one of the class names under which the service was registered.</li>
* <li>For each class name with which the service was registered, calling
* {@link ServiceReference#isAssignableTo(Bundle, String)} with the context
* bundle and the class name on the service's {@code ServiceReference}
- * object must return {@code true}
+ * object must return {@code true}</li>
* </ul>
*
* @param <S> Type of Service
@@ -707,45 +744,47 @@ public interface BundleContext extends B
<S> Collection<ServiceReference<S>> getServiceReferences(Class<S> clazz, String filter) throws InvalidSyntaxException;
/**
- * Returns the service object referenced by the specified
+ * Returns the service object for the service referenced by the specified
* {@code ServiceReference} object.
+ *
* <p>
- * A bundle's use of a service is tracked by the bundle's use count of that
- * service. Each time a service's service object is returned by
- * {@link #getService(ServiceReference)} the context bundle's use count for
- * that service is incremented by one. Each time the service is released by
- * {@link #ungetService(ServiceReference)} the context bundle's use count
- * for that service is decremented by one.
+ * A bundle's use of a service object obtained from this method is tracked
+ * by the bundle's use count of that service. Each time the service object
+ * is returned by {@link #getService(ServiceReference)} the context bundle's
+ * use count for the service is incremented by one. Each time the service
+ * object is released by {@link #ungetService(ServiceReference)} the context
+ * bundle's use count for the service is decremented by one.
+ *
* <p>
- * When a bundle's use count for a service drops to zero, the bundle should
- * no longer use that service.
+ * When a bundle's use count for the service drops to zero, the bundle
+ * should no longer use the service object.
*
* <p>
* This method will always return {@code null} when the service associated
- * with this {@code reference} has been unregistered.
+ * with the specified {@code reference} has been unregistered.
*
* <p>
* The following steps are required to get the service object:
* <ol>
- * <li>If the service has been unregistered, {@code null} is returned.
+ * <li>If the service has been unregistered, {@code null} is returned.</li>
* <li>If the context bundle's use count for the service is currently zero
- * and the service was registered with an object implementing the
- * {@code ServiceFactory} interface, the
+ * and the service has {@link Constants#SCOPE_BUNDLE bundle} or
+ * {@link Constants#SCOPE_PROTOTYPE prototype} scope, the
* {@link ServiceFactory#getService(Bundle, ServiceRegistration)} method is
- * called to create a service object for the context bundle. If the service
- * object returned by the {@code ServiceFactory} object is {@code null}, not
- * an {@code instanceof} all the classes named when the service was
- * registered or the {@code ServiceFactory} object throws an exception or
- * will be recursively called for the context bundle, {@code null} is
- * returned and a Framework event of type {@link FrameworkEvent#ERROR}
- * containing a {@link ServiceException} describing the error is fired. <br>
- * This service object is cached by the Framework. While the context
- * bundle's use count for the service is greater than zero, subsequent calls
- * to get the services's service object for the context bundle will return
- * the cached service object.
- * <li>The context bundle's use count for this service is incremented by
- * one.
- * <li>The service object for the service is returned.
+ * called to supply the service object for the context bundle. If the
+ * service object returned by the {@code ServiceFactory} object is
+ * {@code null}, not an {@code instanceof} all the classes named when the
+ * service was registered or the {@code ServiceFactory} object throws an
+ * exception or will be recursively called for the context bundle,
+ * {@code null} is returned and a Framework event of type
+ * {@link FrameworkEvent#ERROR} containing a {@link ServiceException}
+ * describing the error is fired. The supplied service object is cached by
+ * the Framework. While the context bundle's use count for the service is
+ * greater than zero, subsequent calls to get the service object for the
+ * context bundle will return the cached service object.</li>
+ * <li>The context bundle's use count for the service is incremented by one.
+ * </li>
+ * <li>The service object for the service is returned.</li>
* </ol>
*
* @param <S> Type of Service.
@@ -770,28 +809,28 @@ public interface BundleContext extends B
<S> S getService(ServiceReference<S> reference);
/**
- * Releases the service object referenced by the specified
+ * Releases the service object for the service referenced by the specified
* {@code ServiceReference} object. If the context bundle's use count for
* the service is zero, this method returns {@code false}. Otherwise, the
* context bundle's use count for the service is decremented by one.
*
* <p>
- * The service's service object should no longer be used and all references
- * to it should be destroyed when a bundle's use count for the service drops
- * to zero.
+ * The service object must no longer be used and all references to it should
+ * be destroyed when a bundle's use count for the service drops to zero.
*
* <p>
- * The following steps are required to unget the service object:
+ * The following steps are required to release the service object:
* <ol>
* <li>If the context bundle's use count for the service is zero or the
- * service has been unregistered, {@code false} is returned.
- * <li>The context bundle's use count for this service is decremented by
- * one.
- * <li>If the context bundle's use count for the service is currently zero
- * and the service was registered with a {@code ServiceFactory} object, the
+ * service has been unregistered, {@code false} is returned.</li>
+ * <li>The context bundle's use count for the service is decremented by one.
+ * </li>
+ * <li>If the context bundle's use count for the service is now zero and the
+ * service has {@link Constants#SCOPE_BUNDLE bundle} or
+ * {@link Constants#SCOPE_PROTOTYPE prototype} scope, the
* {@link ServiceFactory#ungetService(Bundle, ServiceRegistration, Object)}
- * method is called to release the service object for the context bundle.
- * <li>{@code true} is returned.
+ * method is called to release the service object for the context bundle.</li>
+ * <li>{@code true} is returned.</li>
* </ol>
*
* @param reference A reference to the service to be released.
@@ -808,6 +847,47 @@ public interface BundleContext extends B
boolean ungetService(ServiceReference<?> reference);
/**
+ * Returns the {@link ServiceObjects} object for the service referenced by
+ * the specified {@code ServiceReference} object.
+ *
+ * <p>
+ * The {@link ServiceObjects} object can be used to obtain multiple service
+ * objects for services with {@link Constants#SCOPE_PROTOTYPE prototype}
+ * scope.
+ *
+ * <p>
+ * For services with {@link Constants#SCOPE_SINGLETON singleton} or
+ * {@link Constants#SCOPE_BUNDLE bundle} scope, the
+ * {@link ServiceObjects#getService()} method behaves the same as the
+ * {@link #getService(ServiceReference)} method and the
+ * {@link ServiceObjects#ungetService(Object)} method behaves the same as
+ * the {@link #ungetService(ServiceReference)} method. That is, only one,
+ * use-counted service object is available from the {@link ServiceObjects}
+ * object.
+ *
+ * <p>
+ * This method will always return {@code null} when the service associated
+ * with the specified {@code reference} has been unregistered.
+ *
+ * @param <S> Type of Service.
+ * @param reference A reference to the service.
+ * @return A {@link ServiceObjects} object for the service associated with
+ * the specified {@code reference} or {@code null} if the service is
+ * not registered.
+ * @throws SecurityException If the caller does not have the
+ * {@code ServicePermission} to get the service using at least one
+ * of the named classes the service was registered under and the
+ * Java Runtime Environment supports permissions.
+ * @throws IllegalStateException If this BundleContext is no longer valid.
+ * @throws IllegalArgumentException If the specified
+ * {@code ServiceReference} was not created by the same framework
+ * instance as this {@code BundleContext}.
+ * @see PrototypeServiceFactory
+ * @since 1.8
+ */
+ <S> ServiceObjects<S> getServiceObjects(ServiceReference<S> reference);
+
+ /**
* Creates a {@code File} object for a file in the persistent storage area
* provided for the bundle by the Framework. This method will return
* {@code null} if the platform does not have file system support.
Modified: felix/trunk/framework/src/main/java/org/osgi/framework/BundleEvent.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/BundleEvent.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/BundleEvent.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/BundleEvent.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2013). 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.
@@ -32,7 +32,7 @@ import java.util.EventObject;
* @Immutable
* @see BundleListener
* @see SynchronousBundleListener
- * @version $Id: 9e2102212eb526b5f11fdde4b0fc5c171a0b39c8 $
+ * @author $Id: cd49848213816c4f76541b70be12ac3af7900972 $
*/
public class BundleEvent extends EventObject {
@@ -201,16 +201,16 @@ public class BundleEvent extends EventOb
/**
* Returns the type of lifecyle event. The type values are:
* <ul>
- * <li>{@link #INSTALLED}
- * <li>{@link #RESOLVED}
- * <li>{@link #LAZY_ACTIVATION}
- * <li>{@link #STARTING}
- * <li>{@link #STARTED}
- * <li>{@link #STOPPING}
- * <li>{@link #STOPPED}
- * <li>{@link #UPDATED}
- * <li>{@link #UNRESOLVED}
- * <li>{@link #UNINSTALLED}
+ * <li>{@link #INSTALLED}</li>
+ * <li>{@link #RESOLVED}</li>
+ * <li>{@link #LAZY_ACTIVATION}</li>
+ * <li>{@link #STARTING}</li>
+ * <li>{@link #STARTED}</li>
+ * <li>{@link #STOPPING}</li>
+ * <li>{@link #STOPPED}</li>
+ * <li>{@link #UPDATED}</li>
+ * <li>{@link #UNRESOLVED}</li>
+ * <li>{@link #UNINSTALLED}</li>
* </ul>
*
* @return The type of lifecycle event.
Modified: felix/trunk/framework/src/main/java/org/osgi/framework/BundleException.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/BundleException.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/BundleException.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/BundleException.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2013). 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.
@@ -32,7 +32,7 @@ package org.osgi.framework;
* <p>
* This exception conforms to the general purpose exception chaining mechanism.
*
- * @version $Id: 0c97ed2696b4576d61440020922b1a97545beb1e $
+ * @author $Id: a0d23c4cb73b0d6386bcd6b9eebed29fdd9a4deb $
*/
public class BundleException extends Exception {
@@ -203,6 +203,7 @@ public class BundleException extends Exc
* @return The cause of this exception or {@code null} if no cause was set.
* @since 1.3
*/
+ @Override
public Throwable getCause() {
return super.getCause();
}
@@ -218,6 +219,7 @@ public class BundleException extends Exc
* been set.
* @since 1.3
*/
+ @Override
public Throwable initCause(Throwable cause) {
return super.initCause(cause);
}
Modified: felix/trunk/framework/src/main/java/org/osgi/framework/BundleListener.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/BundleListener.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/BundleListener.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/BundleListener.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2000, 2011). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2013). 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.
@@ -17,6 +17,7 @@
package org.osgi.framework;
import java.util.EventListener;
+import org.osgi.annotation.versioning.ConsumerType;
/**
* A {@code BundleEvent} listener. {@code BundleListener} is a listener
@@ -34,9 +35,9 @@ import java.util.EventListener;
*
* @see BundleEvent
* @NotThreadSafe
- * @version $Id: d48b4a8a59c839466a3d749dde23980d236f58c6 $
+ * @author $Id: 2c27d37a3a77e1c80f9b022f8dc2f614dff5f5ef $
*/
-
+@ConsumerType
public interface BundleListener extends EventListener {
/**
* Receives notification that a bundle has had a lifecycle change.
Modified: felix/trunk/framework/src/main/java/org/osgi/framework/BundlePermission.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/BundlePermission.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/BundlePermission.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/BundlePermission.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2004, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2004, 2013). 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.
@@ -58,7 +58,7 @@ import java.util.Map;
*
* @since 1.3
* @ThreadSafe
- * @version $Id: ccba905e3373800dfdb080118e97145abf778da2 $
+ * @author $Id: 5d3a115a2622919f564e2a2f46d70090ad9859cb $
*/
public final class BundlePermission extends BasicPermission {
@@ -287,6 +287,7 @@ public final class BundlePermission exte
* @return {@code true} if the specified {@code BundlePermission} action is
* implied by this object; {@code false} otherwise.
*/
+ @Override
public boolean implies(Permission p) {
if (!(p instanceof BundlePermission)) {
return false;
@@ -309,6 +310,7 @@ public final class BundlePermission exte
* @return Canonical string representation of the {@code BundlePermission
* } actions.
*/
+ @Override
public String getActions() {
String result = actions;
if (result == null) {
@@ -351,6 +353,7 @@ public final class BundlePermission exte
*
* @return A new {@code PermissionCollection} object.
*/
+ @Override
public PermissionCollection newPermissionCollection() {
return new BundlePermissionCollection();
}
@@ -368,6 +371,7 @@ public final class BundlePermission exte
* has the same bundle symbolic name and actions as this
* {@code BundlePermission} object; {@code false} otherwise.
*/
+ @Override
public boolean equals(Object obj) {
if (obj == this) {
return true;
@@ -387,6 +391,7 @@ public final class BundlePermission exte
*
* @return A hash code value for this object.
*/
+ @Override
public int hashCode() {
int h = 31 * 17 + getName().hashCode();
h = 31 * h + getActions().hashCode();
@@ -461,6 +466,7 @@ final class BundlePermissionCollection e
* @throws SecurityException If this {@code BundlePermissionCollection}
* object has been marked read-only.
*/
+ @Override
public void add(final Permission permission) {
if (!(permission instanceof BundlePermission)) {
throw new IllegalArgumentException("invalid permission: " + permission);
@@ -500,6 +506,7 @@ final class BundlePermissionCollection e
* @return {@code true} if {@code permission} is a proper subset of a
* permission in the set; {@code false} otherwise.
*/
+ @Override
public boolean implies(final Permission permission) {
if (!(permission instanceof BundlePermission)) {
return false;
@@ -559,6 +566,7 @@ final class BundlePermissionCollection e
*
* @return Enumeration of all {@code BundlePermission} objects.
*/
+ @Override
public synchronized Enumeration<Permission> elements() {
List<Permission> all = new ArrayList<Permission>(permissions.values());
return Collections.enumeration(all);
@@ -577,6 +585,7 @@ final class BundlePermissionCollection e
private synchronized void readObject(java.io.ObjectInputStream in) throws IOException, ClassNotFoundException {
ObjectInputStream.GetField gfields = in.readFields();
+ @SuppressWarnings("unchecked")
Hashtable<String, BundlePermission> hashtable = (Hashtable<String, BundlePermission>) gfields.get("permissions", null);
permissions = new HashMap<String, BundlePermission>(hashtable);
all_allowed = gfields.get("all_allowed", false);
Modified: felix/trunk/framework/src/main/java/org/osgi/framework/BundleReference.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/BundleReference.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/BundleReference.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/BundleReference.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2009, 2010). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2009, 2013). 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.
@@ -16,14 +16,16 @@
package org.osgi.framework;
+import org.osgi.annotation.versioning.ProviderType;
+
/**
* A reference to a Bundle.
*
* @since 1.5
* @ThreadSafe
- * @noimplement
- * @version $Id: e61bd3e020264b04022a430fe09a85ee3aabf1a3 $
+ * @author $Id: ad4e0b99177540205a1a8f37f9075989434cc59f $
*/
+@ProviderType
public interface BundleReference {
/**
* Returns the {@code Bundle} object associated with this
Modified: felix/trunk/framework/src/main/java/org/osgi/framework/CapabilityPermission.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/CapabilityPermission.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/CapabilityPermission.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/CapabilityPermission.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2013). 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.
@@ -41,13 +41,13 @@ import java.util.Set;
* A bundle's authority to provide or require a capability.
* <ul>
* <li>The {@code provide} action allows a bundle to provide a capability
- * matching the specified filter.
+ * matching the specified filter.</li>
* <li>The {@code require} action allows a bundle to require a capability
- * matching the specified filter.
+ * matching the specified filter.</li>
* </ul>
*
* @ThreadSafe
- * @version $Id: b17bcaec959f67c3eae4c4c80c39a0a8716b22dc $
+ * @author $Id: 1d8e892cf46d7410cd3fdff1f5ca2fb010a33ae6 $
* @since 1.6
*/
@@ -334,6 +334,7 @@ public final class CapabilityPermission
* @return {@code true} if the specified permission is implied by this
* object; {@code false} otherwise.
*/
+ @Override
public boolean implies(Permission p) {
if (!(p instanceof CapabilityPermission)) {
return false;
@@ -382,6 +383,7 @@ public final class CapabilityPermission
*
* @return The canonical string representation of the actions.
*/
+ @Override
public String getActions() {
String result = actions;
if (result == null) {
@@ -413,6 +415,7 @@ public final class CapabilityPermission
* @return A new {@code PermissionCollection} object suitable for storing
* {@code CapabilityPermission} objects.
*/
+ @Override
public PermissionCollection newPermissionCollection() {
return new CapabilityPermissionCollection();
}
@@ -428,6 +431,7 @@ public final class CapabilityPermission
* name and actions as this {@code CapabilityPermission} object;
* {@code false} otherwise.
*/
+ @Override
public boolean equals(Object obj) {
if (obj == this) {
return true;
@@ -448,6 +452,7 @@ public final class CapabilityPermission
*
* @return Hash code value for this object.
*/
+ @Override
public int hashCode() {
int h = 31 * 17 + getName().hashCode();
h = 31 * h + getActions().hashCode();
@@ -486,9 +491,8 @@ public final class CapabilityPermission
}
/**
- * Called by {@code <@link CapabilityPermission#implies(Permission)>}. This
- * method is only called on a requested permission which cannot have a
- * filter set.
+ * Called by {@link CapabilityPermission#implies(Permission)}. This method
+ * is only called on a requested permission which cannot have a filter set.
*
* @return a map of properties for this permission.
*/
@@ -502,8 +506,8 @@ public final class CapabilityPermission
if (bundle == null) {
return properties = props;
}
- AccessController.doPrivileged(new PrivilegedAction<Object>() {
- public Object run() {
+ AccessController.doPrivileged(new PrivilegedAction<Void>() {
+ public Void run() {
props.put("id", new Long(bundle.getBundleId()));
props.put("location", bundle.getLocation());
String name = bundle.getSymbolicName();
@@ -531,6 +535,7 @@ public final class CapabilityPermission
entries = null;
}
+ @Override
public Object get(Object k) {
if (!(k instanceof String)) {
return null;
@@ -609,6 +614,7 @@ final class CapabilityPermissionCollecti
* @throws SecurityException If this {@code CapabilityPermissionCollection}
* object has been marked read-only.
*/
+ @Override
public void add(final Permission permission) {
if (!(permission instanceof CapabilityPermission)) {
throw new IllegalArgumentException("invalid permission: " + permission);
@@ -663,6 +669,7 @@ final class CapabilityPermissionCollecti
* @return {@code true} if {@code permission} is a proper subset of a
* permission in the set; {@code false} otherwise.
*/
+ @Override
public boolean implies(final Permission permission) {
if (!(permission instanceof CapabilityPermission)) {
return false;
@@ -743,6 +750,7 @@ final class CapabilityPermissionCollecti
*
* @return Enumeration of all the CapabilityPermission objects.
*/
+ @Override
public synchronized Enumeration<Permission> elements() {
List<Permission> all = new ArrayList<Permission>(permissions.values());
Map<String, CapabilityPermission> pc = filterPermissions;
@@ -766,9 +774,11 @@ final class CapabilityPermissionCollecti
private synchronized void readObject(java.io.ObjectInputStream in) throws IOException, ClassNotFoundException {
ObjectInputStream.GetField gfields = in.readFields();
+ @SuppressWarnings("unchecked")
HashMap<String, CapabilityPermission> p = (HashMap<String, CapabilityPermission>) gfields.get("permissions", null);
permissions = p;
all_allowed = gfields.get("all_allowed", false);
+ @SuppressWarnings("unchecked")
HashMap<String, CapabilityPermission> fp = (HashMap<String, CapabilityPermission>) gfields.get("filterPermissions", null);
filterPermissions = fp;
}
Modified: felix/trunk/framework/src/main/java/org/osgi/framework/Configurable.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/Configurable.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/Configurable.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/Configurable.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2013). 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.
@@ -26,7 +26,7 @@ package org.osgi.framework;
* {@code instanceof Configurable}.
*
* @deprecated As of 1.2. Please use Configuration Admin service.
- * @version $Id: 1018601ae90d2d16ec34136db4b04dca3ccf8e65 $
+ * @author $Id: dce95833dd076e870099385a306989959a84aafd $
*/
public interface Configurable {
/**
Modified: felix/trunk/framework/src/main/java/org/osgi/framework/Constants.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/Constants.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/Constants.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/Constants.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2014). 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.
@@ -16,6 +16,7 @@
package org.osgi.framework;
+import org.osgi.annotation.versioning.ProviderType;
import org.osgi.framework.hooks.bundle.CollisionHook;
import org.osgi.framework.launch.Framework;
@@ -28,10 +29,9 @@ import org.osgi.framework.launch.Framewo
* otherwise indicated.
*
* @since 1.1
- * @noimplement
- * @version $Id: 6d07a4c3e29a5cd93b3daf0f9fcdab5472b357f6 $
+ * @author $Id: 6873c6f7d537ddbe39a6a2eba107ca3c2de49ce5 $
*/
-
+@ProviderType
public interface Constants {
/**
* Location identifier of the OSGi <i>system bundle </i>, which is defined
@@ -48,6 +48,14 @@ public interface Constants {
String SYSTEM_BUNDLE_SYMBOLICNAME = "system.bundle";
/**
+ * Identifier of the OSGi <i>system bundle </i>, which is defined to be
+ * {@code 0}.
+ *
+ * @since 1.8
+ */
+ long SYSTEM_BUNDLE_ID = 0L;
+
+ /**
* Manifest header identifying the bundle's category.
* <p>
* The header value may be retrieved from the {@code Dictionary} object
@@ -196,7 +204,7 @@ public interface Constants {
String BUNDLE_CONTACTADDRESS = "Bundle-ContactAddress";
/**
- * Manifest header attribute identifying the bundle's activator class.
+ * Manifest header identifying the bundle's activator class.
*
* <p>
* If present, this header specifies the name of the bundle resource class
@@ -211,6 +219,19 @@ public interface Constants {
String BUNDLE_ACTIVATOR = "Bundle-Activator";
/**
+ * Manifest header identifying the extension bundle's activator class.
+ *
+ * <p>
+ * If present, this header specifies the name of the extension bundle
+ * resource class that implements the {@code BundleActivator} interface and
+ * whose {@code start} and {@code stop} methods are called by the Framework
+ * when the Framework is initialized and shutdown, respectively.
+ *
+ * @since 1.8
+ */
+ String EXTENSION_BUNDLE_ACTIVATOR = "ExtensionBundle-Activator";
+
+ /**
* Manifest header identifying the location from which a new bundle version
* is obtained during a bundle update operation.
*
@@ -387,7 +408,8 @@ public interface Constants {
* like:
*
* <pre>
- * Bundle-SymbolicName: com.acme.module.test; fragment-attachment:="resolve-time"
+ * Bundle-SymbolicName: com.acme.module.test;
+ * fragment-attachment:="resolve-time"
* </pre>
*
* @see #FRAGMENT_ATTACHMENT_DIRECTIVE
@@ -543,7 +565,8 @@ public interface Constants {
* like:
*
* <pre>
- * Import-Package: org.osgi.framework; bundle-symbolic-name="com.acme.module.test"
+ * Import-Package: org.osgi.framework;
+ * bundle-symbolic-name="com.acme.module.test"
* </pre>
*
* @see #IMPORT_PACKAGE
@@ -786,6 +809,9 @@ public interface Constants {
* Fragment-Host: system.bundle; extension:="framework"
* </pre>
*
+ * <p>
+ * The default value is {@link #EXTENSION_FRAMEWORK framework}.
+ *
* @see #FRAGMENT_HOST
* @see #EXTENSION_FRAMEWORK
* @see #EXTENSION_BOOTCLASSPATH
@@ -1257,9 +1283,10 @@ public interface Constants {
*
* <p>
* The value of this property is assigned by the Framework when a service is
- * registered. The Framework assigns a unique value that is larger than all
- * previously assigned values since the Framework was started. These values
- * are NOT persistent across restarts of the Framework.
+ * registered. The Framework assigns a unique, non-negative value that is
+ * larger than all previously assigned values since the Framework was
+ * started. These values are NOT persistent across restarts of the
+ * Framework.
*/
String SERVICE_ID = "service.id";
@@ -1331,6 +1358,66 @@ public interface Constants {
String SERVICE_DESCRIPTION = "service.description";
/**
+ * Service property identifying the {@link Bundle#getBundleId() bundle id}
+ * of the {@link ServiceReference#getBundle() bundle registering the
+ * service}.
+ *
+ * <p>
+ * This property is set by the Framework when a service is registered. The
+ * value of this property must be of type {@code Long}.
+ *
+ * @since 1.8
+ */
+ String SERVICE_BUNDLEID = "service.bundleid";
+
+ /**
+ * Service property identifying a service's scope.
+ *
+ * <p>
+ * This property is set by the Framework when a service is registered. If
+ * the registered object implements {@link PrototypeServiceFactory}, then
+ * the value of this service property will be {@link #SCOPE_PROTOTYPE}.
+ * Otherwise, if the registered object implements {@link ServiceFactory},
+ * then the value of this service property will be {@link #SCOPE_BUNDLE}.
+ * Otherwise, the value of this service property will be
+ * {@link #SCOPE_SINGLETON}.
+ *
+ * @since 1.8
+ * @see #SCOPE_SINGLETON
+ * @see #SCOPE_BUNDLE
+ * @see #SCOPE_PROTOTYPE
+ */
+ String SERVICE_SCOPE = "service.scope";
+
+ /**
+ * Service scope is singleton. All bundles using the service receive the
+ * same service object.
+ *
+ * @since 1.8
+ * @see #SERVICE_SCOPE
+ */
+ String SCOPE_SINGLETON = "singleton";
+
+ /**
+ * Service scope is bundle. Each bundle using the service receives a
+ * customized service object.
+ *
+ * @since 1.8
+ * @see #SERVICE_SCOPE
+ */
+ String SCOPE_BUNDLE = "bundle";
+
+ /**
+ * Service scope is prototype. Each bundle using the service receives either
+ * a customized service object or can request multiple customized service
+ * objects via {@link ServiceObjects}.
+ *
+ * @since 1.8
+ * @see #SERVICE_SCOPE
+ */
+ String SCOPE_PROTOTYPE = "prototype";
+
+ /**
* Framework environment property identifying the Framework's universally
* unique identifier (UUID). A UUID represents a 128-bit value. A new UUID
* is generated by the {@link Framework#init()} method each time a framework
@@ -1700,4 +1787,26 @@ public interface Constants {
* @see BundleException#DUPLICATE_BUNDLE_ERROR
*/
String FRAMEWORK_BSNVERSION_MANAGED = "managed";
+
+ /**
+ * Manifest header identifying the bundle's icon URLs.
+ *
+ * <p>
+ * The header value may be retrieved from the {@code Dictionary} object
+ * returned by the {@code Bundle.getHeaders} method.
+ *
+ * @since 1.8
+ */
+ String BUNDLE_ICON = "Bundle-Icon";
+
+ /**
+ * Manifest header identifying the bundle's license information.
+ *
+ * <p>
+ * The header value may be retrieved from the {@code Dictionary} object
+ * returned by the {@code Bundle.getHeaders} method.
+ *
+ * @since 1.8
+ */
+ String BUNDLE_LICENSE = "Bundle-License";
}
Modified: felix/trunk/framework/src/main/java/org/osgi/framework/Filter.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/Filter.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/Filter.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/Filter.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2013). 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,6 +18,7 @@ package org.osgi.framework;
import java.util.Dictionary;
import java.util.Map;
+import org.osgi.annotation.versioning.ProviderType;
/**
* An <a href="http://www.ietf.org/rfc/rfc1960.txt">RFC 1960</a>-based Filter.
@@ -41,9 +42,9 @@ import java.util.Map;
* @since 1.1
* @see "Core Specification, Filters, for a description of the filter string syntax."
* @ThreadSafe
- * @noimplement
- * @version $Id: 807a04ac07c3230b8f4d4e0f9588a35fbdc41e18 $
+ * @author $Id: 58cd4db16892b20e44be1288ccac929a5a26c53a $
*/
+@ProviderType
public interface Filter {
/**
* Filter using a service's properties.
Modified: felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkEvent.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkEvent.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkEvent.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkEvent.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2004, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2004, 2013). 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.
@@ -33,7 +33,7 @@ import org.osgi.framework.wiring.Framewo
*
* @Immutable
* @see FrameworkListener
- * @version $Id: f679c7581879a2e6006ecdd317a5dd5f735764e3 $
+ * @author $Id: 7b74a68311acf2116ccf21e589ece0ce2cd383ba $
*/
public class FrameworkEvent extends EventObject {
@@ -223,16 +223,16 @@ public class FrameworkEvent extends Even
* <p>
* The type values are:
* <ul>
- * <li>{@link #STARTED}
- * <li>{@link #ERROR}
- * <li>{@link #WARNING}
- * <li>{@link #INFO}
- * <li>{@link #PACKAGES_REFRESHED}
- * <li>{@link #STARTLEVEL_CHANGED}
- * <li>{@link #STOPPED}
- * <li>{@link #STOPPED_BOOTCLASSPATH_MODIFIED}
- * <li>{@link #STOPPED_UPDATE}
- * <li>{@link #WAIT_TIMEDOUT}
+ * <li>{@link #STARTED}</li>
+ * <li>{@link #ERROR}</li>
+ * <li>{@link #WARNING}</li>
+ * <li>{@link #INFO}</li>
+ * <li>{@link #PACKAGES_REFRESHED}</li>
+ * <li>{@link #STARTLEVEL_CHANGED}</li>
+ * <li>{@link #STOPPED}</li>
+ * <li>{@link #STOPPED_BOOTCLASSPATH_MODIFIED}</li>
+ * <li>{@link #STOPPED_UPDATE}</li>
+ * <li>{@link #WAIT_TIMEDOUT}</li>
* </ul>
*
* @return The type of state change.
Modified: felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkListener.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkListener.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkListener.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkListener.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2000, 2011). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2013). 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.
@@ -17,6 +17,7 @@
package org.osgi.framework;
import java.util.EventListener;
+import org.osgi.annotation.versioning.ConsumerType;
/**
* A {@code FrameworkEvent} listener. {@code FrameworkListener} is a listener
@@ -34,9 +35,9 @@ import java.util.EventListener;
*
* @see FrameworkEvent
* @NotThreadSafe
- * @version $Id: ad7f563bd13b60e2b8a378f147057ca7f0accae2 $
+ * @author $Id: 97c76c64c6e6595ad445dcc2d8083d52540f73b8 $
*/
-
+@ConsumerType
public interface FrameworkListener extends EventListener {
/**
Modified: felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkUtil.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkUtil.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkUtil.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/FrameworkUtil.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2005, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2005, 2013). 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.
@@ -43,7 +43,7 @@ import javax.security.auth.x500.X500Prin
*
* @since 1.3
* @ThreadSafe
- * @version $Id: 1f46ea2bbbe2a1242fdaf0877709fb9c02eefae1 $
+ * @author $Id: e93d15cef98c0e7f425f3b076d317c46ebb9a52a $
*/
public class FrameworkUtil {
/**
@@ -539,6 +539,7 @@ public class FrameworkUtil {
*
* @return This {@code Filter}'s filter string.
*/
+ @Override
public String toString() {
String result = filterString;
if (result == null) {
@@ -661,6 +662,7 @@ public class FrameworkUtil {
* {@code this.toString().equals(obj.toString()}; {@code false}
* otherwise.
*/
+ @Override
public boolean equals(Object obj) {
if (obj == this) {
return true;
@@ -682,6 +684,7 @@ public class FrameworkUtil {
*
* @return The hashCode of this {@code Filter}.
*/
+ @Override
public int hashCode() {
return this.toString().hashCode();
}
@@ -768,6 +771,7 @@ public class FrameworkUtil {
return compare_Boolean(operation, ((Boolean) value1).booleanValue(), value2);
}
if (value1 instanceof Comparable<?>) {
+ @SuppressWarnings("unchecked")
Comparable<Object> comparable = (Comparable<Object>) value1;
return compare_Comparable(operation, comparable, value2);
}
@@ -1615,6 +1619,7 @@ public class FrameworkUtil {
this.keys = keyList.toArray(new String[keyList.size()]);
}
+ @Override
public Object get(Object o) {
String k = (String) o;
for (String key : keys) {
@@ -1643,6 +1648,7 @@ public class FrameworkUtil {
this.reference = reference;
}
+ @Override
public Object get(Object key) {
if (reference == null) {
return null;
@@ -1655,14 +1661,14 @@ public class FrameworkUtil {
}
}
- static private final class SetAccessibleAction implements PrivilegedAction<Object> {
+ static private final class SetAccessibleAction implements PrivilegedAction<Void> {
private final AccessibleObject accessible;
SetAccessibleAction(AccessibleObject accessible) {
this.accessible = accessible;
}
- public Object run() {
+ public Void run() {
accessible.setAccessible(true);
return null;
}
@@ -1772,45 +1778,51 @@ public class FrameworkUtil {
* wildcard ("*"), or a List of Strings, each String representing a
* name/value pair in the RDN.
*
- * @param dnChain
+ * @param pattern
* @return a list of DNs.
* @throws IllegalArgumentException
*/
- private static List<Object> parseDNchainPattern(String dnChain) {
- if (dnChain == null) {
- throw new IllegalArgumentException("The DN chain must not be null.");
+ private static List<Object> parseDNchainPattern(String pattern) {
+ if (pattern == null) {
+ throw new IllegalArgumentException("The pattern must not be null.");
}
List<Object> parsed = new ArrayList<Object>();
- int startIndex = 0;
- startIndex = skipSpaces(dnChain, startIndex);
- while (startIndex < dnChain.length()) {
+ final int length = pattern.length();
+ char c = ';'; // start with semi-colon to detect empty pattern
+ for (int startIndex = skipSpaces(pattern, 0); startIndex < length;) {
+ int cursor = startIndex;
int endIndex = startIndex;
- boolean inQuote = false;
- out: while (endIndex < dnChain.length()) {
- char c = dnChain.charAt(endIndex);
+ out: for (boolean inQuote = false; cursor < length; cursor++) {
+ c = pattern.charAt(cursor);
switch (c) {
case '"' :
inQuote = !inQuote;
break;
case '\\' :
- endIndex++; // skip the escaped char
+ cursor++; // skip the escaped char
+ if (cursor == length) {
+ throw new IllegalArgumentException("unterminated escape");
+ }
break;
case ';' :
- if (!inQuote)
- break out;
+ if (!inQuote) {
+ break out; // end of pattern
+ }
+ break;
+ }
+ if (c != ' ') { // ignore trailing whitespace
+ endIndex = cursor + 1;
}
- endIndex++;
- }
- if (endIndex > dnChain.length()) {
- throw new IllegalArgumentException("unterminated escape");
}
- parsed.add(dnChain.substring(startIndex, endIndex));
- startIndex = endIndex + 1;
- startIndex = skipSpaces(dnChain, startIndex);
+ parsed.add(pattern.substring(startIndex, endIndex));
+ startIndex = skipSpaces(pattern, cursor + 1);
+ }
+ if (c == ';') { // last non-whitespace character was a semi-colon
+ throw new IllegalArgumentException("empty pattern");
}
- // Now we parse is a list of strings, lets make List of rdn out
- // of them
+ // Now we have parsed into a list of strings, lets make List of rdn
+ // out of them
for (int i = 0; i < parsed.size(); i++) {
String dn = (String) parsed.get(i);
if (dn.equals(STAR_WILDCARD) || dn.equals(MINUS_WILDCARD)) {
@@ -1818,11 +1830,12 @@ public class FrameworkUtil {
}
List<Object> rdns = new ArrayList<Object>();
if (dn.charAt(0) == '*') {
- if (dn.charAt(1) != ',') {
+ int index = skipSpaces(dn, 1);
+ if (dn.charAt(index) != ',') {
throw new IllegalArgumentException("invalid wildcard prefix");
}
rdns.add(STAR_WILDCARD);
- dn = new X500Principal(dn.substring(2)).getName(X500Principal.CANONICAL);
+ dn = new X500Principal(dn.substring(index + 1)).getName(X500Principal.CANONICAL);
} else {
dn = new X500Principal(dn).getName(X500Principal.CANONICAL);
}
@@ -1830,9 +1843,6 @@ public class FrameworkUtil {
parseDN(dn, rdns);
parsed.set(i, rdns);
}
- if (parsed.size() == 0) {
- throw new IllegalArgumentException("empty DN chain");
- }
return parsed;
}
@@ -2056,7 +2066,7 @@ public class FrameworkUtil {
* "cn=me,c=US;*;cn=you" will match
* "cn=me,c=US";cn=you" and "cn=me,c=US;cn=her;cn=you". The
* pattern "cn=me,c=US;-;cn=you" will match "cn=me,c=US";cn=you"
- * and "cn=me,c=US;cn=her;cn=him;cn=you".
+ * and "cn=me,c=US;cn=her;cn=him;cn=you".</li>
* <li>As a DN prefix. In this case, the DN must start with "*,".
* The wild card will match zero or more RDNs at the start of a
* DN. For example, "*,cn=me,c=US;cn=you" will match
Modified: felix/trunk/framework/src/main/java/org/osgi/framework/InvalidSyntaxException.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/InvalidSyntaxException.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/InvalidSyntaxException.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/InvalidSyntaxException.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2013). 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.
@@ -28,7 +28,7 @@ package org.osgi.framework;
* <p>
* This exception conforms to the general purpose exception chaining mechanism.
*
- * @version $Id: 8820ca2db85b557cef8da09ee861249dfb5ee914 $
+ * @author $Id: 59696296eff1574fa844e3a0a975ba6c83ec59af $
*/
public class InvalidSyntaxException extends Exception {
@@ -99,6 +99,7 @@ public class InvalidSyntaxException exte
* @return The cause of this exception or {@code null} if no cause was set.
* @since 1.3
*/
+ @Override
public Throwable getCause() {
return super.getCause();
}
@@ -114,6 +115,7 @@ public class InvalidSyntaxException exte
* been set.
* @since 1.3
*/
+ @Override
public Throwable initCause(Throwable cause) {
return super.initCause(cause);
}
Modified: felix/trunk/framework/src/main/java/org/osgi/framework/PackagePermission.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/PackagePermission.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/PackagePermission.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/PackagePermission.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2013). 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.
@@ -54,7 +54,7 @@ import java.util.Map;
* deprecated, implies the {@code import} action.
*
* @ThreadSafe
- * @version $Id: e993fbc36b6bff84182a8594af5af3cad8c4e2a3 $
+ * @author $Id: c2d45ff158a6a19ff7bc155af3ac9941cb6a89d6 $
*/
public final class PackagePermission extends BasicPermission {
@@ -372,6 +372,7 @@ public final class PackagePermission ext
* @return {@code true} if the specified permission is implied by this
* object; {@code false} otherwise.
*/
+ @Override
public boolean implies(Permission p) {
if (!(p instanceof PackagePermission)) {
return false;
@@ -424,6 +425,7 @@ public final class PackagePermission ext
* @return Canonical string representation of the {@code PackagePermission}
* actions.
*/
+ @Override
public String getActions() {
String result = actions;
if (result == null) {
@@ -453,6 +455,7 @@ public final class PackagePermission ext
*
* @return A new {@code PermissionCollection} object.
*/
+ @Override
public PermissionCollection newPermissionCollection() {
return new PackagePermissionCollection();
}
@@ -470,6 +473,7 @@ public final class PackagePermission ext
* has the same package name and actions as this
* {@code PackagePermission} object; {@code false} otherwise.
*/
+ @Override
public boolean equals(Object obj) {
if (obj == this) {
return true;
@@ -489,6 +493,7 @@ public final class PackagePermission ext
*
* @return A hash code value for this object.
*/
+ @Override
public int hashCode() {
int h = 31 * 17 + getName().hashCode();
h = 31 * h + getActions().hashCode();
@@ -525,9 +530,8 @@ public final class PackagePermission ext
}
/**
- * Called by {@code <@link PackagePermission#implies(Permission)>}. This
- * method is only called on a requested permission which cannot have a
- * filter set.
+ * Called by {@link PackagePermission#implies(Permission)}. This method is
+ * only called on a requested permission which cannot have a filter set.
*
* @return a map of properties for this permission.
*/
@@ -539,8 +543,8 @@ public final class PackagePermission ext
final Map<String, Object> map = new HashMap<String, Object>(5);
map.put("package.name", getName());
if (bundle != null) {
- AccessController.doPrivileged(new PrivilegedAction<Object>() {
- public Object run() {
+ AccessController.doPrivileged(new PrivilegedAction<Void>() {
+ public Void run() {
map.put("id", new Long(bundle.getBundleId()));
map.put("location", bundle.getLocation());
String name = bundle.getSymbolicName();
@@ -610,6 +614,7 @@ final class PackagePermissionCollection
* @throws SecurityException If this {@code PackagePermissionCollection}
* object has been marked read-only.
*/
+ @Override
public void add(final Permission permission) {
if (!(permission instanceof PackagePermission)) {
throw new IllegalArgumentException("invalid permission: " + permission);
@@ -666,6 +671,7 @@ final class PackagePermissionCollection
* @return {@code true} if {@code permission} is a proper subset of a
* permission in the set; {@code false} otherwise.
*/
+ @Override
public boolean implies(final Permission permission) {
if (!(permission instanceof PackagePermission)) {
return false;
@@ -744,6 +750,7 @@ final class PackagePermissionCollection
*
* @return Enumeration of all {@code PackagePermission} objects.
*/
+ @Override
public synchronized Enumeration<Permission> elements() {
List<Permission> all = new ArrayList<Permission>(permissions.values());
Map<String, PackagePermission> pc = filterPermissions;
@@ -768,9 +775,11 @@ final class PackagePermissionCollection
private synchronized void readObject(java.io.ObjectInputStream in) throws IOException, ClassNotFoundException {
ObjectInputStream.GetField gfields = in.readFields();
+ @SuppressWarnings("unchecked")
Hashtable<String, PackagePermission> hashtable = (Hashtable<String, PackagePermission>) gfields.get("permissions", null);
permissions = new HashMap<String, PackagePermission>(hashtable);
all_allowed = gfields.get("all_allowed", false);
+ @SuppressWarnings("unchecked")
HashMap<String, PackagePermission> fp = (HashMap<String, PackagePermission>) gfields.get("filterPermissions", null);
filterPermissions = fp;
}
Added: felix/trunk/framework/src/main/java/org/osgi/framework/PrototypeServiceFactory.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/PrototypeServiceFactory.java?rev=1614569&view=auto
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/PrototypeServiceFactory.java (added)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/PrototypeServiceFactory.java Wed Jul 30 07:22:32 2014
@@ -0,0 +1,124 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). 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.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.framework;
+
+import org.osgi.annotation.versioning.ConsumerType;
+
+/**
+ * A factory for {@link Constants#SCOPE_PROTOTYPE prototype scope} services. The
+ * factory can provide multiple, customized service objects in the OSGi
+ * environment.
+ *
+ * <p>
+ * When registering a service, a {@code PrototypeServiceFactory} object can be
+ * used instead of a service object, so that the bundle developer can create a
+ * customized service object for each caller that is using the service.
+ *
+ * <p>
+ * When a caller uses a {@link ServiceObjects} to
+ * {@link ServiceObjects#getService() request} a service object, the framework
+ * calls the {@link #getService(Bundle, ServiceRegistration) getService} method
+ * to return a service object customized for the requesting caller. The caller
+ * can {@link ServiceObjects#ungetService(Object) release} the returned service
+ * object and the framework will call the
+ * {@link #ungetService(Bundle, ServiceRegistration, Object) ungetService}
+ * method with the service object.
+ *
+ * <p>
+ * When a bundle uses the {@link BundleContext#getService(ServiceReference)}
+ * method to obtain a service object, the framework must act as if the service
+ * has {@link Constants#SCOPE_BUNDLE bundle scope}. That is, the framework will
+ * call the {@link #getService(Bundle, ServiceRegistration) getService} method
+ * to obtain a bundle-scoped service object which will be cached and have a use
+ * count. See {@link ServiceFactory}.
+ *
+ * <p>
+ * A bundle can use both {@link ServiceObjects} and
+ * {@link BundleContext#getService(ServiceReference)} to obtain a service object
+ * for a service. {@link ServiceObjects#getService()} will always return a
+ * service object provided by a call to
+ * {@link #getService(Bundle, ServiceRegistration)} and
+ * {@link BundleContext#getService(ServiceReference)} will always return the
+ * bundle-scoped service object.
+ *
+ * <p>
+ * {@code PrototypeServiceFactory} objects are only used by the Framework and
+ * are not made available to other bundles in the OSGi environment. The
+ * Framework may concurrently call a {@code PrototypeServiceFactory}.
+ *
+ * @param <S> Type of Service
+ * @see BundleContext#getServiceObjects(ServiceReference)
+ * @see ServiceObjects
+ * @ThreadSafe
+ * @since 1.8
+ * @author $Id$
+ */
+@ConsumerType
+public interface PrototypeServiceFactory<S> extends ServiceFactory<S> {
+ /**
+ * Returns a service object for a caller.
+ *
+ * <p>
+ * The Framework invokes this method for each caller requesting a service
+ * object using {@link ServiceObjects#getService()}. The factory can then
+ * return a customized service object for the caller.
+ *
+ * <p>
+ * The Framework must check that the returned service object is valid. If
+ * the returned service object is {@code null} or is not an
+ * {@code instanceof} all the classes named when the service was registered,
+ * a framework event of type {@link FrameworkEvent#ERROR} is fired
+ * containing a service exception of type
+ * {@link ServiceException#FACTORY_ERROR} and {@code null} is returned to
+ * the caller. If this method throws an exception, a framework event of type
+ * {@link FrameworkEvent#ERROR} is fired containing a service exception of
+ * type {@link ServiceException#FACTORY_EXCEPTION} with the thrown exception
+ * as the cause and {@code null} is returned to the caller.
+ *
+ * @param bundle The bundle requesting the service.
+ * @param registration The {@code ServiceRegistration} object for the
+ * requested service.
+ * @return A service object that <strong>must</strong> be an instance of all
+ * the classes named when the service was registered.
+ * @see ServiceObjects#getService()
+ */
+ public S getService(Bundle bundle, ServiceRegistration<S> registration);
+
+ /**
+ * Releases a service object customized for a caller.
+ *
+ * <p>
+ * The Framework invokes this method when a service has been released by a
+ * bundle such as by calling {@link ServiceObjects#ungetService(Object)}.
+ * The service object may then be destroyed.
+ *
+ * <p>
+ * If this method throws an exception, a framework event of type
+ * {@link FrameworkEvent#ERROR} is fired containing a service exception of
+ * type {@link ServiceException#FACTORY_EXCEPTION} with the thrown exception
+ * as the cause.
+ *
+ * @param bundle The bundle releasing the service.
+ * @param registration The {@code ServiceRegistration} object for the
+ * service being released.
+ * @param service The service object returned by a previous call to the
+ * {@link #getService(Bundle, ServiceRegistration) getService}
+ * method.
+ * @see ServiceObjects#ungetService(Object)
+ */
+ public void ungetService(Bundle bundle, ServiceRegistration<S> registration, S service);
+}
Propchange: felix/trunk/framework/src/main/java/org/osgi/framework/PrototypeServiceFactory.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: felix/trunk/framework/src/main/java/org/osgi/framework/PrototypeServiceFactory.java
------------------------------------------------------------------------------
svn:keywords = author date id revision rev url
Propchange: felix/trunk/framework/src/main/java/org/osgi/framework/PrototypeServiceFactory.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Modified: felix/trunk/framework/src/main/java/org/osgi/framework/ServiceEvent.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/ServiceEvent.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/ServiceEvent.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/ServiceEvent.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2013). 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.
@@ -32,7 +32,7 @@ import java.util.EventObject;
* @Immutable
* @see ServiceListener
* @see AllServiceListener
- * @version $Id: 49e34e0ad5564d6f4ca0ab0053b272c22b9fb917 $
+ * @author $Id: b27a941cb68e6416825b1b717090a2eb098733f3 $
*/
public class ServiceEvent extends EventObject {
Modified: felix/trunk/framework/src/main/java/org/osgi/framework/ServiceException.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/ServiceException.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/ServiceException.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/ServiceException.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2007, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2007, 2014). 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.
@@ -30,7 +30,7 @@ package org.osgi.framework;
* <p>
* This exception conforms to the general purpose exception chaining mechanism.
*
- * @version $Id: 9f763412635f59585bb615cbc449fc7ab72b7103 $
+ * @author $Id: 32a515460813c702b127f65dda91cd23781b2a98 $
* @since 1.5
*/
@@ -74,6 +74,12 @@ public class ServiceException extends Ru
* @since 1.6
*/
public static final int FACTORY_RECURSION = 6;
+ /**
+ * An asynchronous operation was unable to obtain the service.
+ *
+ * @since 1.8
+ */
+ public static final int ASYNC_ERROR = 7;
/**
* Creates a {@code ServiceException} with the specified message and
Modified: felix/trunk/framework/src/main/java/org/osgi/framework/ServiceFactory.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/ServiceFactory.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/ServiceFactory.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/ServiceFactory.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2014). 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.
@@ -16,26 +16,34 @@
package org.osgi.framework;
+import org.osgi.annotation.versioning.ConsumerType;
+
/**
- * Allows services to provide customized service objects in the OSGi
+ * A factory for {@link Constants#SCOPE_BUNDLE bundle scope} services. The
+ * factory can provide service objects customized for each bundle in the OSGi
* environment.
*
* <p>
* When registering a service, a {@code ServiceFactory} object can be used
- * instead of a service object, so that the bundle developer can gain control of
- * the specific service object granted to a bundle that is using the service.
+ * instead of a service object, so that the bundle developer can create a
+ * customized service object for each bundle that is using the service.
*
* <p>
- * When this happens, the {@code BundleContext.getService(ServiceReference)}
- * method calls the {@code ServiceFactory.getService} method to create a service
- * object specifically for the requesting bundle. The service object returned by
- * the {@code ServiceFactory} is cached by the Framework until the bundle
- * releases its use of the service.
+ * When a bundle {@link BundleContext#getService(ServiceReference) requests} the
+ * service object, the framework calls the
+ * {@link #getService(Bundle, ServiceRegistration) getService} method to return
+ * a service object customized for the requesting bundle. The returned service
+ * object is cached by the Framework for subsequent calls to
+ * {@link BundleContext#getService(ServiceReference)} until the bundle releases
+ * its use of the service.
*
* <p>
- * When the bundle's use count for the service is decremented to zero (including
- * the bundle stopping or the service being unregistered), the
- * {@code ServiceFactory.ungetService} method is called.
+ * When the bundle's use count for the service is
+ * {@link BundleContext#ungetService(ServiceReference) decremented} to zero
+ * (including the bundle stopping or the service being unregistered), the
+ * framework will call the
+ * {@link #ungetService(Bundle, ServiceRegistration, Object) ungetService}
+ * method.
*
* <p>
* {@code ServiceFactory} objects are only used by the Framework and are not
@@ -45,18 +53,18 @@ package org.osgi.framework;
* @param <S> Type of Service
* @see BundleContext#getService(ServiceReference)
* @ThreadSafe
- * @version $Id: 535776e702ec5ace54f577218ff8f7920741558b $
+ * @author $Id: f11fc6bee18315fb659c7987d1b66f1c9c95548a $
*/
-
+@ConsumerType
public interface ServiceFactory<S> {
/**
- * Creates a new service object.
+ * Returns a service object for a bundle.
*
* <p>
* The Framework invokes this method the first time the specified
* {@code bundle} requests a service object using the
- * {@code BundleContext.getService(ServiceReference)} method. The service
- * factory can then return a specific service object for each bundle.
+ * {@link BundleContext#getService(ServiceReference)} method. The factory
+ * can then return a customized service object for each bundle.
*
* <p>
* The Framework must check that the returned service object is valid. If
@@ -76,9 +84,10 @@ public interface ServiceFactory<S> {
*
* <p>
* The Framework caches the valid service object and will return the same
- * service object on any future call to {@code BundleContext.getService} for
- * the specified bundle. This means the Framework must not allow this method
- * to be concurrently called for the specified bundle.
+ * service object on any future call to
+ * {@link BundleContext#getService(ServiceReference)} for the specified
+ * bundle. This means the Framework must not allow this method to be
+ * concurrently called for the specified bundle.
*
* @param bundle The bundle requesting the service.
* @param registration The {@code ServiceRegistration} object for the
@@ -90,7 +99,7 @@ public interface ServiceFactory<S> {
public S getService(Bundle bundle, ServiceRegistration<S> registration);
/**
- * Releases a service object.
+ * Releases a service object customized for a bundle.
*
* <p>
* The Framework invokes this method when a service has been released by a
Modified: felix/trunk/framework/src/main/java/org/osgi/framework/ServiceListener.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/ServiceListener.java?rev=1614569&r1=1614568&r2=1614569&view=diff
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/ServiceListener.java (original)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/ServiceListener.java Wed Jul 30 07:22:32 2014
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2000, 2012). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2013). 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.
@@ -17,6 +17,7 @@
package org.osgi.framework;
import java.util.EventListener;
+import org.osgi.annotation.versioning.ConsumerType;
/**
* A {@code ServiceEvent} listener. {@code ServiceListener} is a listener
@@ -49,9 +50,9 @@ import java.util.EventListener;
* @see ServiceEvent
* @see ServicePermission
* @ThreadSafe
- * @version $Id: 601dfda6183ab7f18cd3916958a39734ea141c25 $
+ * @author $Id: 8468dbc769382269184c932d41e084cb2fa58eb9 $
*/
-
+@ConsumerType
public interface ServiceListener extends EventListener {
/**
* Receives notification that a service has had a lifecycle change.
Added: felix/trunk/framework/src/main/java/org/osgi/framework/ServiceObjects.java
URL: http://svn.apache.org/viewvc/felix/trunk/framework/src/main/java/org/osgi/framework/ServiceObjects.java?rev=1614569&view=auto
==============================================================================
--- felix/trunk/framework/src/main/java/org/osgi/framework/ServiceObjects.java (added)
+++ felix/trunk/framework/src/main/java/org/osgi/framework/ServiceObjects.java Wed Jul 30 07:22:32 2014
@@ -0,0 +1,142 @@
+/*
+ * Copyright (c) OSGi Alliance (2012, 2014). 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.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.framework;
+
+import org.osgi.annotation.versioning.ProviderType;
+
+/**
+ * Allows multiple service objects for a service to be obtained.
+ *
+ * <p>
+ * For services with {@link Constants#SCOPE_PROTOTYPE prototype} scope, multiple
+ * service objects for the service can be obtained. For services with
+ * {@link Constants#SCOPE_SINGLETON singleton} or {@link Constants#SCOPE_BUNDLE
+ * bundle} scope, only one, use-counted service object is available to a
+ * requesting bundle.
+ *
+ * <p>
+ * Any unreleased service objects obtained from this {@code ServiceObjects}
+ * object are automatically released by the framework when the bundle associated
+ * with the BundleContext used to create this {@code ServiceObjects} object is
+ * stopped.
+ *
+ * @param <S> Type of Service
+ * @see BundleContext#getServiceObjects(ServiceReference)
+ * @see PrototypeServiceFactory
+ * @ThreadSafe
+ * @since 1.8
+ * @author $Id$
+ */
+@ProviderType
+public interface ServiceObjects<S> {
+ /**
+ * Returns a service object for the {@link #getServiceReference()
+ * associated} service.
+ *
+ * <p>
+ * This {@code ServiceObjects} object can be used to obtain multiple service
+ * objects for the associated service if the service has
+ * {@link Constants#SCOPE_PROTOTYPE prototype} scope.
+ *
+ * <p>
+ * If the associated service has {@link Constants#SCOPE_SINGLETON singleton}
+ * or {@link Constants#SCOPE_BUNDLE bundle} scope, this method behaves the
+ * same as calling the {@link BundleContext#getService(ServiceReference)}
+ * method for the associated service. That is, only one, use-counted service
+ * object is available from this {@link ServiceObjects} object.
+ *
+ * <p>
+ * This method will always return {@code null} when the associated service
+ * has been unregistered.
+ *
+ * <p>
+ * For a prototype scope service, the following steps are required to obtain
+ * a service object:
+ * <ol>
+ * <li>If the associated service has been unregistered, {@code null} is
+ * returned.</li>
+ * <li>The
+ * {@link PrototypeServiceFactory#getService(Bundle, ServiceRegistration)}
+ * method is called to supply a customized service object for the caller.</li>
+ * <li>If the service object returned by the {@code PrototypeServiceFactory}
+ * object is {@code null}, not an {@code instanceof} all the classes named
+ * when the service was registered or the {@code PrototypeServiceFactory}
+ * object throws an exception, {@code null} is returned and a Framework
+ * event of type {@link FrameworkEvent#ERROR} containing a
+ * {@link ServiceException} describing the error is fired.</li>
+ * <li>The customized service object is returned.</li>
+ * </ol>
+ *
+ * @return A service object for the associated service or {@code null} if
+ * the service is not registered, the customized service object
+ * returned by a {@code ServiceFactory} does not implement the
+ * classes under which it was registered or the
+ * {@code ServiceFactory} threw an exception.
+ * @throws IllegalStateException If the BundleContext used to create this
+ * {@code ServiceObjects} object is no longer valid.
+ * @see #ungetService(Object)
+ */
+ public S getService();
+
+ /**
+ * Releases a service object for the {@link #getServiceReference()
+ * associated} service.
+ *
+ * <p>
+ * This {@code ServiceObjects} object can be used to obtain multiple service
+ * objects for the associated service if the service has
+ * {@link Constants#SCOPE_PROTOTYPE prototype} scope. If the associated
+ * service has {@link Constants#SCOPE_SINGLETON singleton} or
+ * {@link Constants#SCOPE_BUNDLE bundle} scope, this method behaves the same
+ * as calling the {@link BundleContext#ungetService(ServiceReference)}
+ * method for the associated service. That is, only one, use-counted service
+ * object is available from this {@link ServiceObjects} object.
+ *
+ * <p>
+ * For a prototype scope service, the following steps are required to
+ * release a service object:
+ * <ol>
+ * <li>If the associated service has been unregistered, this method returns
+ * without doing anything.</li>
+ * <li>The
+ * {@link PrototypeServiceFactory#ungetService(Bundle, ServiceRegistration, Object)}
+ * method is called to release the specified service object.</li>
+ * </ol>
+ *
+ * <p>
+ * The specified service object must no longer be used and all references to
+ * it should be destroyed after calling this method.
+ *
+ * @param service A service object previously provided by this
+ * {@code ServiceObjects} object.
+ * @throws IllegalStateException If the BundleContext used to create this
+ * {@code ServiceObjects} object is no longer valid.
+ * @throws IllegalArgumentException If the specified service object was not
+ * provided by this {@code ServiceObjects} object.
+ * @see #getService()
+ */
+ public void ungetService(S service);
+
+ /**
+ * Returns the {@link ServiceReference} for the service associated with this
+ * {@code ServiceObjects} object.
+ *
+ * @return The {@link ServiceReference} for the service associated with this
+ * {@code ServiceObjects} object.
+ */
+ public ServiceReference<S> getServiceReference();
+}