Package org.osgi.framework

# Interface ServiceObjects<S>

Type Parameters:
  `S` - Type of Service

@ProviderType public interface ServiceObjects<S>
Allows multiple service objects for a service to be obtained.

For services with `prototype` scope, multiple service objects for the service can be obtained. For services with `singleton` or `bundle` scope, only one, use-counted service object is available to a requesting bundle.

Any unreleased service objects obtained from this `ServiceObjects` object are automatically released by the framework when the bundle associated with the BundleContext used to create this `ServiceObjects` object is stopped.

Since:
  1.8
Author:
  $Id: ServiceObjects.java 1614569 2014-07-30 07:22:32Z cziegeler $
See Also:
  - `BundleContext.getServiceObjects(ServiceReference)`
  - `PrototypeServiceFactory`

## Method Summary

Modifier and Type
Method
Description
`S`
`getService()`
Returns a service object for the `associated` service.
`ServiceReference<S>`
`getServiceReference()`
Returns the `ServiceReference` for the service associated with this `ServiceObjects` object.
`void`
`ungetService(S service)`
Releases a service object for the `associated` service.

## Method Details

### getService

S getService()
Returns a service object for the `associated` service.

This `ServiceObjects` object can be used to obtain multiple service objects for the associated service if the service has `prototype` scope.

If the associated service has `singleton` or `bundle` scope, this method behaves the same as calling the `BundleContext.getService(ServiceReference)` method for the associated service. That is, only one, use-counted service object is available from this `ServiceObjects` object.

This method will always return `null` when the associated service has been unregistered.

For a prototype scope service, the following steps are required to obtain a service object:

1. If the associated service has been unregistered, `null` is returned.
2. The `PrototypeServiceFactory.getService(Bundle, ServiceRegistration)` method is called to supply a customized service object for the caller.
3. If the service object returned by the `PrototypeServiceFactory` object is `null`, not an `instanceof` all the classes named when the service was registered or the `PrototypeServiceFactory` object throws an exception, `null` is returned and a Framework event of type `FrameworkEvent.ERROR` containing a `ServiceException` describing the error is fired.
4. The customized service object is returned.

Returns:
  A service object for the associated service or `null` if the service is not registered, the customized service object returned by a `ServiceFactory` does not implement the classes under which it was registered or the `ServiceFactory` threw an exception.
Throws:
  `IllegalStateException` - If the BundleContext used to create this `ServiceObjects` object is no longer valid.
See Also:
  - `ungetService(Object)`

### ungetService

void ungetService(S service)
Releases a service object for the `associated` service.

This `ServiceObjects` object can be used to obtain multiple service objects for the associated service if the service has `prototype` scope. If the associated service has `singleton` or `bundle` scope, this method behaves the same as calling the `BundleContext.ungetService(ServiceReference)` method for the associated service. That is, only one, use-counted service object is available from this `ServiceObjects` object.

For a prototype scope service, the following steps are required to release a service object:

1. If the associated service has been unregistered, this method returns without doing anything.
2. The `PrototypeServiceFactory.ungetService(Bundle, ServiceRegistration, Object)` method is called to release the specified service object.

The specified service object must no longer be used and all references to it should be destroyed after calling this method.

Parameters:
  `service` - A service object previously provided by this `ServiceObjects` object.
Throws:
  `IllegalStateException` - If the BundleContext used to create this `ServiceObjects` object is no longer valid.
  `IllegalArgumentException` - If the specified service object was not provided by this `ServiceObjects` object.
See Also:
  - `getService()`

### getServiceReference

ServiceReference<S> getServiceReference()
Returns the `ServiceReference` for the service associated with this `ServiceObjects` object.

Returns:
  The `ServiceReference` for the service associated with this `ServiceObjects` object.