org.apache.felix.ipojo

## Class PolicyServiceContext

- java.lang.Object
- - org.apache.felix.ipojo.PolicyServiceContext

All Implemented Interfaces:
  ServiceContext, org.osgi.framework.BundleContext, org.osgi.framework.BundleReference

    public class PolicyServiceContext
    extends java.lang.Object
    implements ServiceContext

The policy service context is a service context aiming to resolve service dependencies inside different service context according to a policy. So, the policy service context behavior follows one of the three following policy:
Local : services are only resolved in the local service context.
Global : services are only resolved in the global context (hte OSGi one)
Local and Global : services are resolved inside the local context and inside the global context

Author:
  Felix Project Team

### Field Summary

Fields
`static int` `GLOBAL` Resolving policy, resolves services inside the global context only.
`static int` `LOCAL` Resolving policy, resolves services only in the composite context (local).
`static int` `LOCAL_AND_GLOBAL` Resolving policy, resolves services only in the composite (local) and in the global context.
`org.osgi.framework.BundleContext` `m_global` The global service registry.
`ServiceContext` `m_local` The local (Composite) Service Registry.

### Constructor Summary

Constructors
Constructor and Description
`PolicyServiceContext(org.osgi.framework.BundleContext global, ServiceContext local, int policy)` Creates a PolicyServiceContext.

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `addBundleListener(org.osgi.framework.BundleListener arg0)` Adds a bundle listener.
`void` `addFrameworkListener(org.osgi.framework.FrameworkListener arg0)` Adds a framework listener.
`void` `addServiceListener(org.osgi.framework.ServiceListener listener)` Adds a service listener according to the policy.
`void` `addServiceListener(org.osgi.framework.ServiceListener listener, java.lang.String filter)` Adds a service listener according to the policy.
`org.osgi.framework.Filter` `createFilter(java.lang.String arg0)` Creates a LDAP filter.
`org.osgi.framework.ServiceReference[]` `getAllServiceReferences(java.lang.String clazz, java.lang.String filter)` Gets all service references.
`org.osgi.framework.Bundle` `getBundle()` Gets the current bundle.
`org.osgi.framework.Bundle` `getBundle(long bundleId)` Gets the bundle object with the given id.
`org.osgi.framework.Bundle` `getBundle(java.lang.String s)` Gets a bundle by name
`org.osgi.framework.Bundle[]` `getBundles()` Gets installed bundles.
`java.io.File` `getDataFile(java.lang.String filename)` Gets a data file.
`java.lang.String` `getProperty(java.lang.String key)` Gets a property value.
`java.lang.Object` `getService(org.osgi.framework.ServiceReference ref)` Gets the service object for the given references.
`<S> org.osgi.framework.ServiceReference<S>` `getServiceReference(java.lang.Class<S> sClass)` Gets a service reference.
`org.osgi.framework.ServiceReference` `getServiceReference(java.lang.String clazz)` Gets a service reference for the required service specification.
`<S> java.util.Collection<org.osgi.framework.ServiceReference<S>>` `getServiceReferences(java.lang.Class<S> clazz, java.lang.String filter)` Gets a collection of service references
`org.osgi.framework.ServiceReference[]` `getServiceReferences(java.lang.String clazz, java.lang.String filter)` Get a service reference for the required service specification.
`org.osgi.framework.Bundle` `installBundle(java.lang.String location)` Installs a bundle.
`org.osgi.framework.Bundle` `installBundle(java.lang.String location, java.io.InputStream input)` Installs a bundle.
`<S> org.osgi.framework.ServiceRegistration<S>` `registerService(java.lang.Class<S> clazz, S svc, java.util.Dictionary<java.lang.String,?> properties)` Registers a service.
`org.osgi.framework.ServiceRegistration` `registerService(java.lang.String[] clazzes, java.lang.Object service, java.util.Dictionary properties)` This method is not supported.
`org.osgi.framework.ServiceRegistration` `registerService(java.lang.String clazz, java.lang.Object service, java.util.Dictionary properties)` This method is not supported.
`void` `removeBundleListener(org.osgi.framework.BundleListener listener)` Removes the bundle listener.
`void` `removeFrameworkListener(org.osgi.framework.FrameworkListener listener)` Removes a framework listener.
`void` `removeServiceListener(org.osgi.framework.ServiceListener listener)` Removes a service listener.
`boolean` `ungetService(org.osgi.framework.ServiceReference reference)` Ungets the service reference.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### LOCAL

    public static final int LOCAL

Resolving policy, resolves services only in the composite context (local). This policy is the default one for services inherited from service-level dependencies.

See Also:
  Constant Field Values

#### LOCAL_AND_GLOBAL

    public static final int LOCAL_AND_GLOBAL

Resolving policy, resolves services only in the composite (local) and in the global context. This policy is the default one for implementation dependency.

See Also:
  Constant Field Values

#### GLOBAL

    public static final int GLOBAL

Resolving policy, resolves services inside the global context only.

See Also:
  Constant Field Values

#### m_global

    public org.osgi.framework.BundleContext m_global

The global service registry. Targets the OSGi service registry.

#### m_local

    public ServiceContext m_local

The local (Composite) Service Registry.

### Constructor Detail

#### PolicyServiceContext

    public PolicyServiceContext(org.osgi.framework.BundleContext global,
                                ServiceContext local,
                                int policy)

Creates a PolicyServiceContext. If the local context is null, sets the policy to `GLOBAL`, else use the given policy.

Parameters:
  `global` - the global bundle context
  `local` - the parent (local) service context
  `policy` - the resolution policy

### Method Detail

#### addServiceListener

    public void addServiceListener(org.osgi.framework.ServiceListener listener,
                                   java.lang.String filter)
                            throws org.osgi.framework.InvalidSyntaxException

Adds a service listener according to the policy. Be aware, that the listener can be registered both in the local and in the global context if the `LOCAL_AND_GLOBAL` is used.

Specified by:
  `addServiceListener` in interface `ServiceContext`
Specified by:
  `addServiceListener` in interface `org.osgi.framework.BundleContext`
Parameters:
  `listener` - the listener to add
  `filter` - the LDAP filter
Throws:
  `org.osgi.framework.InvalidSyntaxException` - if the filter is malformed.
See Also:
  `ServiceContext.addServiceListener(org.osgi.framework.ServiceListener, java.lang.String)`

#### addServiceListener

    public void addServiceListener(org.osgi.framework.ServiceListener listener)

Adds a service listener according to the policy. Be aware, that the listener can be registered both in the local and in the global context if the `LOCAL_AND_GLOBAL` is used.

Specified by:
  `addServiceListener` in interface `ServiceContext`
Specified by:
  `addServiceListener` in interface `org.osgi.framework.BundleContext`
Parameters:
  `listener` - the listener to add
See Also:
  `ServiceContext.addServiceListener(org.osgi.framework.ServiceListener)`

#### getAllServiceReferences

    public org.osgi.framework.ServiceReference[] getAllServiceReferences(java.lang.String clazz,
                                                                         java.lang.String filter)
                                                                  throws org.osgi.framework.InvalidSyntaxException

Gets all service references. These references are found inside the local registry, global registry or both according to the policy. The returned array can contain service references from both context.

Specified by:
  `getAllServiceReferences` in interface `ServiceContext`
Specified by:
  `getAllServiceReferences` in interface `org.osgi.framework.BundleContext`
Parameters:
  `clazz` - the required service specification.
  `filter` - the LDAP filter
Returns:
  the array of service reference, `null` if no service available
Throws:
  `org.osgi.framework.InvalidSyntaxException` - if the LDAP filter is malformed
See Also:
  `ServiceContext.getAllServiceReferences(java.lang.String, java.lang.String)`

#### getService

    public java.lang.Object getService(org.osgi.framework.ServiceReference ref)

Gets the service object for the given references. The service is get inside the context according to the policy.

Specified by:
  `getService` in interface `ServiceContext`
Specified by:
  `getService` in interface `org.osgi.framework.BundleContext`
Parameters:
  `ref` - the service reference
Returns:
  the service object
See Also:
  `ServiceContext.getService(org.osgi.framework.ServiceReference)`

#### getServiceReference

    public org.osgi.framework.ServiceReference getServiceReference(java.lang.String clazz)

Gets a service reference for the required service specification. The service is looked inside the context according to the policy.

Specified by:
  `getServiceReference` in interface `ServiceContext`
Specified by:
  `getServiceReference` in interface `org.osgi.framework.BundleContext`
Parameters:
  `clazz` - the required service specification
Returns:
  a service reference or `null` if no matching service available
See Also:
  `ServiceContext.getServiceReference(java.lang.String)`

#### getServiceReference

    public <S> org.osgi.framework.ServiceReference<S> getServiceReference(java.lang.Class<S> sClass)

Gets a service reference. This method is delegated on PolicyServiceContext#getServiceReference(String)

Specified by:
  `getServiceReference` in interface `org.osgi.framework.BundleContext`
Type Parameters:
  `S` - the service interface class
Parameters:
  `sClass` - the service interface class
Returns:
  the service reference of `null` if not found
See Also:
  `getServiceReference(String)`

#### getServiceReferences

    public <S> java.util.Collection<org.osgi.framework.ServiceReference<S>> getServiceReferences(java.lang.Class<S> clazz,
                                                                                                 java.lang.String filter)
                                                                                          throws org.osgi.framework.InvalidSyntaxException

Gets a collection of service references

Specified by:
  `getServiceReferences` in interface `org.osgi.framework.BundleContext`
Type Parameters:
  `S` - the service interface class
Parameters:
  `clazz` - the service interface class
  `filter` - the filter
Returns:
  the set of service reference
Throws:
  `org.osgi.framework.InvalidSyntaxException` - the filter is invalid
See Also:
  `getServiceReferences(String, String)`

#### getServiceReferences

    public org.osgi.framework.ServiceReference[] getServiceReferences(java.lang.String clazz,
                                                                      java.lang.String filter)
                                                               throws org.osgi.framework.InvalidSyntaxException

Get a service reference for the required service specification. The services are looked inside the context according to the policy.

Specified by:
  `getServiceReferences` in interface `ServiceContext`
Specified by:
  `getServiceReferences` in interface `org.osgi.framework.BundleContext`
Parameters:
  `clazz` - the required service specification
  `filter` - the LDAP filter
Returns:
  a service reference array or `null` if not consistent service available
Throws:
  `org.osgi.framework.InvalidSyntaxException` - if the LDAP filter is malformed
See Also:
  `ServiceContext.getServiceReference(java.lang.String)`

#### registerService

    public org.osgi.framework.ServiceRegistration registerService(java.lang.String[] clazzes,
                                                                  java.lang.Object service,
                                                                  java.util.Dictionary properties)

This method is not supported. This context can only be used to resolve service dependencies.

Specified by:
  `registerService` in interface `ServiceContext`
Specified by:
  `registerService` in interface `org.osgi.framework.BundleContext`
Parameters:
  `clazzes` - the specifications
  `service` - the service object
  `properties` - the service properties
Returns:
  the service registration object
See Also:
  `ServiceContext.registerService(java.lang.String[], java.lang.Object, java.util.Dictionary)`

#### registerService

    public org.osgi.framework.ServiceRegistration registerService(java.lang.String clazz,
                                                                  java.lang.Object service,
                                                                  java.util.Dictionary properties)

This method is not supported. This context can only be used to resolve service dependencies.

Specified by:
  `registerService` in interface `ServiceContext`
Specified by:
  `registerService` in interface `org.osgi.framework.BundleContext`
Parameters:
  `clazz` - the specification
  `service` - the service object
  `properties` - the service properties to publish
Returns:
  the service registration object
See Also:
  `ServiceContext.registerService(java.lang.String, java.lang.Object, java.util.Dictionary)`

#### removeServiceListener

    public void removeServiceListener(org.osgi.framework.ServiceListener listener)

Removes a service listener.

Specified by:
  `removeServiceListener` in interface `ServiceContext`
Specified by:
  `removeServiceListener` in interface `org.osgi.framework.BundleContext`
Parameters:
  `listener` - the service listener to remove
See Also:
  `ServiceContext.removeServiceListener(org.osgi.framework.ServiceListener)`

#### ungetService

    public boolean ungetService(org.osgi.framework.ServiceReference reference)

Ungets the service reference.

Specified by:
  `ungetService` in interface `ServiceContext`
Specified by:
  `ungetService` in interface `org.osgi.framework.BundleContext`
Parameters:
  `reference` - the service reference to unget.
Returns:
  `true` if the service release if the reference is no more used.
See Also:
  `ServiceContext.ungetService(org.osgi.framework.ServiceReference)`

#### addBundleListener

    public void addBundleListener(org.osgi.framework.BundleListener arg0)

Adds a bundle listener. Delegate on the global bundle context.

Specified by:
  `addBundleListener` in interface `org.osgi.framework.BundleContext`
Parameters:
  `arg0` - : bundle listener to add
See Also:
  `BundleContext.addBundleListener(org.osgi.framework.BundleListener)`

#### addFrameworkListener

    public void addFrameworkListener(org.osgi.framework.FrameworkListener arg0)

Adds a framework listener. Delegates on the global bundle context.

Specified by:
  `addFrameworkListener` in interface `org.osgi.framework.BundleContext`
Parameters:
  `arg0` - : framework listener to add.
See Also:
  `BundleContext.addFrameworkListener(org.osgi.framework.FrameworkListener)`

#### createFilter

    public org.osgi.framework.Filter createFilter(java.lang.String arg0)
                                           throws org.osgi.framework.InvalidSyntaxException

Creates a LDAP filter.

Specified by:
  `createFilter` in interface `org.osgi.framework.BundleContext`
Parameters:
  `arg0` - the String-form of the filter
Returns:
  the created filter object
Throws:
  `org.osgi.framework.InvalidSyntaxException` - if the given argument is not a valid against the LDAP grammar.
See Also:
  `BundleContext.createFilter(java.lang.String)`

#### getBundle

    public org.osgi.framework.Bundle getBundle(java.lang.String s)

Gets a bundle by name

Specified by:
  `getBundle` in interface `org.osgi.framework.BundleContext`
Parameters:
  `s` - the name
Returns:
  the matching bundle or `null` if not found

#### getBundle

    public org.osgi.framework.Bundle getBundle()

Gets the current bundle.

Specified by:
  `getBundle` in interface `org.osgi.framework.BundleContext`
Specified by:
  `getBundle` in interface `org.osgi.framework.BundleReference`
Returns:
  the current bundle
See Also:
  `BundleContext.getBundle()`

#### getBundle

    public org.osgi.framework.Bundle getBundle(long bundleId)

Gets the bundle object with the given id.

Specified by:
  `getBundle` in interface `org.osgi.framework.BundleContext`
Parameters:
  `bundleId` - the bundle id
Returns:
  the bundle object
See Also:
  `BundleContext.getBundle(long)`

#### getBundles

    public org.osgi.framework.Bundle[] getBundles()

Gets installed bundles.

Specified by:
  `getBundles` in interface `org.osgi.framework.BundleContext`
Returns:
  the list of installed bundles
See Also:
  `BundleContext.getBundles()`

#### getDataFile

    public java.io.File getDataFile(java.lang.String filename)

Gets a data file.

Specified by:
  `getDataFile` in interface `org.osgi.framework.BundleContext`
Parameters:
  `filename` - the File name.
Returns:
  the File object
See Also:
  `BundleContext.getDataFile(java.lang.String)`

#### getProperty

    public java.lang.String getProperty(java.lang.String key)

Gets a property value.

Specified by:
  `getProperty` in interface `org.osgi.framework.BundleContext`
Parameters:
  `key` - the key of the asked property
Returns:
  the property value (object) or `null` if no property are associated with the given key
See Also:
  `BundleContext.getProperty(java.lang.String)`

#### installBundle

    public org.osgi.framework.Bundle installBundle(java.lang.String location)
                                            throws org.osgi.framework.BundleException

Installs a bundle.

Specified by:
  `installBundle` in interface `org.osgi.framework.BundleContext`
Parameters:
  `location` - the URL of the bundle to install
Returns:
  the installed bundle
Throws:
  `org.osgi.framework.BundleException` - if the bundle cannot be installed correctly
See Also:
  `BundleContext.installBundle(java.lang.String)`

#### installBundle

    public org.osgi.framework.Bundle installBundle(java.lang.String location,
                                                   java.io.InputStream input)
                                            throws org.osgi.framework.BundleException

Installs a bundle.

Specified by:
  `installBundle` in interface `org.osgi.framework.BundleContext`
Parameters:
  `location` - the URL of the bundle to install
  `input` - the input stream to load the bundle content
Returns:
  the installed bundle
Throws:
  `org.osgi.framework.BundleException` - if the bundle cannot be installed correctly
See Also:
  `BundleContext.installBundle(java.lang.String, java.io.InputStream)`

#### removeBundleListener

    public void removeBundleListener(org.osgi.framework.BundleListener listener)

Removes the bundle listener.

Specified by:
  `removeBundleListener` in interface `org.osgi.framework.BundleContext`
Parameters:
  `listener` - the listener to remove
See Also:
  `BundleContext.removeBundleListener(org.osgi.framework.BundleListener)`

#### removeFrameworkListener

    public void removeFrameworkListener(org.osgi.framework.FrameworkListener listener)

Removes a framework listener.

Specified by:
  `removeFrameworkListener` in interface `org.osgi.framework.BundleContext`
Parameters:
  `listener` - the listener to remove
See Also:
  `BundleContext.removeFrameworkListener(org.osgi.framework.FrameworkListener)`

#### registerService

    public <S> org.osgi.framework.ServiceRegistration<S> registerService(java.lang.Class<S> clazz,
                                                                         S svc,
                                                                         java.util.Dictionary<java.lang.String,?> properties)

Registers a service. Operation not supported.

Specified by:
  `registerService` in interface `org.osgi.framework.BundleContext`
Type Parameters:
  `S` - the type of service
Parameters:
  `clazz` - the class object
  `svc` - the service object
  `properties` - the properties
Returns:
  the service registration