/* * 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. * *
* 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. * *
* 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 Type of Service
* @see BundleContext#getServiceObjects(ServiceReference)
* @see PrototypeServiceFactory
* @ThreadSafe
* @since 1.8
* @author $Id$
*/
@ProviderType
public interface ServiceObjects {
/**
* Returns a service object for the {@link #getServiceReference()
* associated} service.
*
*
* 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#getService(ServiceReference)} * method for the associated service. That is, only one, use-counted service * object is available from this {@link ServiceObjects} object. * *
* This method will always return {@code null} when the associated service * has been unregistered. * *
* For a prototype scope service, the following steps are required to obtain * a service object: *
* 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. * *
* For a prototype scope service, the following steps are required to * release a service object: *
* 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 getServiceReference();
}