| /* |
| * Copyright (c) OSGi Alliance (2012, 2016). 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. Since implementations of |
| * {@link PrototypeServiceFactory} can return the same service object |
| * repeatedly, the framework must use count the returned service objects to |
| * release the service object only when its use count returns to zero. |
| * <p> |
| * 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 use count for the customized service object is incremented by |
| * one.</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 use count for the specified service object is decremented by one. |
| * </li> |
| * <li>If the use count for the specified service object is now zero, 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 when the use count has |
| * returned to zero. |
| * |
| * @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 is |
| * {@code null} or was not provided by a {@code ServiceObjects} |
| * object for the associated service. |
| * @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(); |
| } |