org.apache.felix.ipojo

## Class IPojoContext

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

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

    public class IPojoContext
    extends java.lang.Object
    implements org.osgi.framework.BundleContext, ServiceContext

The iPOJO Context is a BundleContext implementation allowing the separation between Bundle context and Service (Bundle) Context. This is used inside composition to differentiate the classloading context (i.e. Bundle) and the service registry access. This class delegates calls to the good internal context (either the BundleContext or the ServiceContext) according to the method. If the instance does not have a valid service context, the bundle context is always used.

Author:
  Felix Project Team

### Constructor Summary

Constructors
Constructor and Description
`IPojoContext(org.osgi.framework.BundleContext context)` Creates an iPOJO Context.
`IPojoContext(org.osgi.framework.BundleContext bundleContext, ServiceContext serviceContext)` Creates an iPOJO Context.

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `addBundleListener(org.osgi.framework.BundleListener listener)` Adds a bundle listener.
`void` `addFrameworkListener(org.osgi.framework.FrameworkListener listener)` Adds a framework listener.
`void` `addServiceListener(org.osgi.framework.ServiceListener listener)` Add a service listener.
`void` `addServiceListener(org.osgi.framework.ServiceListener listener, java.lang.String filter)` Adds a service listener.
`org.osgi.framework.Filter` `createFilter(java.lang.String filter)` Creates a filter objects.
`org.osgi.framework.ServiceReference[]` `getAllServiceReferences(java.lang.String clazz, java.lang.String filter)` Gets the service references matching with the given query.
`org.osgi.framework.Bundle` `getBundle()` Gets the current bundle object.
`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 symbolic name
`org.osgi.framework.Bundle[]` `getBundles()` Gets installed bundles.
`java.io.File` `getDataFile(java.lang.String filename)` Gets a data file.
`org.osgi.framework.BundleContext` `getGlobalContext()` Gets the global context, i.e.
`java.lang.String` `getProperty(java.lang.String key)` Gets a property value.
`<S> S` `getService(org.osgi.framework.ServiceReference<S> ref)` Gets a service object.
`ServiceContext` `getServiceContext()` Gets the service context, i.e.
`<S> org.osgi.framework.ServiceReference<S>` `getServiceReference(java.lang.Class<S> sClass)` Gets a service reference for the given interface.
`org.osgi.framework.ServiceReference` `getServiceReference(java.lang.String clazz)` Gets a service reference for the given interface.
`<S> java.util.Collection<org.osgi.framework.ServiceReference<S>>` `getServiceReferences(java.lang.Class<S> sClass, java.lang.String filter)` Gets service reference list for the given query.
`org.osgi.framework.ServiceReference[]` `getServiceReferences(java.lang.String clazz, java.lang.String filter)` Gets service reference list for the given query.
`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> sClass, S s, java.util.Dictionary<java.lang.String,?> stringDictionary)` Registers a service
`org.osgi.framework.ServiceRegistration` `registerService(java.lang.String[] clazzes, java.lang.Object service, java.util.Dictionary properties)` Registers a service.
`org.osgi.framework.ServiceRegistration` `registerService(java.lang.String clazz, java.lang.Object service, java.util.Dictionary properties)` Registers a service.
`void` `removeBundleListener(org.osgi.framework.BundleListener listener)` Removes a 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`

### Constructor Detail

#### IPojoContext

    public IPojoContext(org.osgi.framework.BundleContext context)

Creates an iPOJO Context. No service context is specified. This constructor is used when the instance lives in the global context.

Parameters:
  `context` - the bundle context

#### IPojoContext

    public IPojoContext(org.osgi.framework.BundleContext bundleContext,
                        ServiceContext serviceContext)

Creates an iPOJO Context. A service context is used to refer to the service registry. The service context will be used for all service accesses.

Parameters:
  `bundleContext` - the bundle context
  `serviceContext` - the service context

### Method Detail

#### addBundleListener

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

Adds a bundle listener.

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

#### addFrameworkListener

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

Adds a framework listener.

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

#### addServiceListener

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

Adds a service listener. This methods registers the listener on the service context if it specified. Otherwise, if the internal dispatcher is enabled, it registers the listener inside the internal dispatcher (if the filter match against the iPOJO Filter format `match(String)`). Finally, if the internal dispatcher is disabled, it uses the "regular" bundle context.

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

#### addServiceListener

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

Add a service listener. This methods registers the listener on the service context if it specified. Otherwise, it uses the "regular" bundle context.

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

#### createFilter

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

Creates a filter objects. This method always uses the bundle context.

Specified by:
  `createFilter` in interface `org.osgi.framework.BundleContext`
Parameters:
  `filter` - the string form of the LDAP filter to create
Returns:
  the filter object.
Throws:
  `org.osgi.framework.InvalidSyntaxException` - if the given filter is malformed
See Also:
  `BundleContext.createFilter(java.lang.String)`

#### getBundle

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

Gets a bundle by symbolic name

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

#### getAllServiceReferences

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

Gets the service references matching with the given query. Uses the service context if specified, used the bundle context otherwise.

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

#### getBundle

    public org.osgi.framework.Bundle getBundle()

Gets the current bundle object.

Specified by:
  `getBundle` in interface `org.osgi.framework.BundleContext`
Specified by:
  `getBundle` in interface `org.osgi.framework.BundleReference`
Returns:
  the bundle declaring the component type of the instance using the current IPojoContext.
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)`

#### getService

    public <S> S getService(org.osgi.framework.ServiceReference<S> ref)

Gets a service object. The given service reference must come from the same context than where the service is get. This method uses the service context if specified, the bundle context otherwise. This method may throw `IllegalStateException` if the used bundle context is no more valid (because we're leaving).

Specified by:
  `getService` in interface `ServiceContext`
Specified by:
  `getService` in interface `org.osgi.framework.BundleContext`
Parameters:
  `ref` - the required service reference
Returns:
  the service object or `null` if the service reference is no more valid or if the service object is not accessible.
See Also:
  `BundleContext.getService(org.osgi.framework.ServiceReference)`

#### getServiceReference

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

Gets a service reference for the given interface. This method uses the service context if specified, the bundle context otherwise.

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

#### getServiceReference

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

Gets a service reference for the given interface. This method uses the service context if specified, the bundle context otherwise.

Specified by:
  `getServiceReference` in interface `org.osgi.framework.BundleContext`
Type Parameters:
  `S` - the service class
Parameters:
  `sClass` - the required interface class
Returns:
  a service reference on a available provider or `null` if no providers available
See Also:
  `BundleContext.getServiceReference(java.lang.String)`

#### getServiceReferences

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

Gets service reference list for the given query. This method uses the service context if specified, the bundle context otherwise.

Specified by:
  `getServiceReferences` in interface `org.osgi.framework.BundleContext`
Type Parameters:
  `S` - the service class
Parameters:
  `sClass` - the name of the required service interface
  `filter` - the LDAP filter to apply on service provider
Returns:
  the array of consistent service reference or `null` if no available providers
Throws:
  `org.osgi.framework.InvalidSyntaxException` - if the LDAP filter is malformed

#### getServiceReferences

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

Gets service reference list for the given query. This method uses the service context if specified, the bundle context otherwise.

Specified by:
  `getServiceReferences` in interface `ServiceContext`
Specified by:
  `getServiceReferences` in interface `org.osgi.framework.BundleContext`
Parameters:
  `clazz` - the name of the required service interface
  `filter` - the LDAP filter to apply on service provider
Returns:
  the array of consistent service reference or `null` if no available providers
Throws:
  `org.osgi.framework.InvalidSyntaxException` - if the LDAP filter is malformed
See Also:
  `BundleContext.getServiceReferences(java.lang.String, 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.
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)`

#### registerService

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

Registers a service. This method uses the service context if specified (and so, registers the service in this service registry), the bundle context otherwise (the service will be available to every global instances).

Specified by:
  `registerService` in interface `ServiceContext`
Specified by:
  `registerService` in interface `org.osgi.framework.BundleContext`
Parameters:
  `clazzes` - the interfaces provided by the service.
  `service` - the service object.
  `properties` - the service properties to publish
Returns:
  the service registration for this service publication.
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)

Registers a service. This method uses the service context if specified (and so, registers the service in this service registry), the bundle context otherwise (the service will be available to every global instances).

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

#### removeBundleListener

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

Removes a 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> sClass,
                                                                         S s,
                                                                         java.util.Dictionary<java.lang.String,?> stringDictionary)

Registers a service

Specified by:
  `registerService` in interface `org.osgi.framework.BundleContext`
Type Parameters:
  `S` - the Service Class (specification)
Parameters:
  `sClass` - the service class
  `s` - the service object (must implement sClass)
  `stringDictionary` - service properties
Returns:
  the service registration

#### removeServiceListener

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

Removes a service listener. Removes the service listener from where it was registered so either in the global context, or in the service context or in the internal dispatcher.

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)`, `BundleContext.removeServiceListener(org.osgi.framework.ServiceListener)`

#### ungetService

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

Ungets the service reference. This method uses the service context if specified, the bundle context otherwise.

Specified by:
  `ungetService` in interface `ServiceContext`
Specified by:
  `ungetService` in interface `org.osgi.framework.BundleContext`
Parameters:
  `reference` - the reference to unget
Returns:
  `true` if you are the last user of the reference
See Also:
  `BundleContext.ungetService(org.osgi.framework.ServiceReference)`

#### getGlobalContext

    public org.osgi.framework.BundleContext getGlobalContext()

Gets the global context, i.e. the bundle context of the factory.

Returns:
  the global bundle context.

#### getServiceContext

    public ServiceContext getServiceContext()

Gets the service context, i.e. the composite context. Returns `null` if the instance does not live inside a composite.

Returns:
  the service context or `null`.