Service Activator Toolkit
Version 1.1.0 (20081206)

org.eclipse.soda.sat.core.framework.interfaces
Interface IBundleActivationManager


public interface IBundleActivationManager

The IBundleActivationManager interface defines the core API for SAT's bundle activation strategy.


Method Summary
 Object acquireImportedService(String name)
          Configuration Method: Acquire the named imported service.
 void acquireImportedServices()
          Configuration Method: Acquire the imported services.
 Object acquireOptionalImportedService(String name)
          Configuration Method: Acquire the named optional imported service.
 void acquireOptionalImportedServices()
          Configuration Method: Acquire the optional imported services.
 void addExportedProxyService(Class interfaceType, IProxyServiceHandler handler, Dictionary properties)
          Configuration Method: Add an exported proxy service.
 void addExportedProxyServices(Class[] interfaceTypes, IProxyServiceHandler handler, Dictionary properties)
          Configuration Method: Add an exported proxy service.
 void addExportedService(String name, Object service, Dictionary properties)
          Configuration Method: Add an exported service with properties.
 void addExportedServices(String[] names, Object service, Dictionary properties)
          Configuration Method: Add multiple exported service with properties.
 void addExportServiceRecord(IExportServiceRecord record)
          Configuration Method: Add the specified export service record.
 void addExportServiceRecords(IExportServiceRecord[] records)
          Configuration Method: Add the specified export service records.
 void addImportedServiceFilter(String name, String filterString)
          Configuration Method: Add an LDAP filter to an imported service.
 void addImportServiceRecord(IImportServiceRecord record)
          Configuration Method: Add the specified import service record.
 void addOptionalImportedServiceFilter(String name, String filterString)
          Configuration Method: Add an LDAP filter to an optional imported service.
 Bundle getBundle()
          OSGi Query Method: Get the bundle.
 BundleContext getBundleContext()
          OSGi Query Method: Get the BundleContext.
 String getBundleSymbolicName()
          OSGi Query Method: Query the bundle's manifest for its Bundle-SymbolicName header.
 File getDataDirectory()
          Persistent Bundle Storage Method: Get the bundle's private data directory.
 File getDataFile(String filename)
          Persistent Bundle Storage Method: Open a data file contained in the bundle's private data directory.
 Object getExportedService(String name)
          Query Method: Get a named exported service object.
 String[] getExportedServiceNamesFromManifest()
          Deprecated. OSGi R4 has deprecated the Export-Service header.
 Dictionary getExportedServiceProperties(String name)
          Query Method: Answers the properties of an exported service.
 Dictionary getExportedServiceProperties(String name, Object service)
          Query Method: Answers the properties of a specific exported service.
 Map getExportedServices()
          Query Method: Get the exported service objects.
 Object[] getExportedServices(String name)
          Query Method: Query the exported services.
 InputStream getFilePropertiesInputStream()
          Query Method: Create an input stream on the default properties file.
 InputStream getFilePropertiesInputStream(String filename)
          Query Method: Create an input stream on the specified properties file.
 Object getImportedService(String name)
          Query Method: Get the named imported service.
 Filter getImportedServiceFilter(String name)
          Query Method: Search for an imported service filter.
 String[] getImportedServiceNames()
          Query Method: Answers the names of all the required services that are imported by the bundle.
 String[] getImportedServiceNamesFromManifest()
          Deprecated. OSGi R4 has deprecated the Import-Service header.
 Object getImportedServiceProperty(String name, String key)
          Query Method: Get the value of an imported service's property.
 String[] getImportedServicePropertyKeys(String name)
          Query Method: Get the keys of an imported service's properties.
 Map getImportedServices()
          Query Method: Get the imported service objects.
 Object getOptionalImportedService(String name)
          Query Method: Get the named optional imported service.
 Filter getOptionalImportedServiceFilter(String name)
          Query Method: Search for an optional imported service filter.
 String[] getOptionalImportedServiceNames()
          Query Method: Answers the names of all the optional services that are imported by the bundle.
 Object getOptionalImportedServiceProperty(String name, String key)
          Query Method: Get the value of an optional imported service's property.
 String[] getOptionalImportedServicePropertyKeys(String name)
          Query Method: Get the keys of an optional imported service's properties.
 Map getOptionalImportedServices()
          Query Method: Get the option imported service objects.
 Properties getProperties()
          Query API: Create a Properties object out of the bundle's properties.
 String getProperty(String key, String defaultValue)
          Query API: Get the value of a property.
 String[] getUnacquiredImportedServiceNames()
          Query API: Get the names of the imported services that have not been acquired.
 String[] getUnacquiredOptionalImportedServiceNames()
          Query API: Get the names of the optional imported services that have not been acquired.
 void releaseImportedService(String name)
          Configuration Method: Release the named imported service.
 void releaseImportedServices()
          Configuration Method: Release the imported services.
 void releaseOptionalImportedService(String name)
          Configuration Method: Release the named optional imported service.
 void releaseOptionalImportedServices()
          Configuration Method: Release the optional imported services.
 void removeExportedService(String name)
          Configuration Method: Remove the exported service record of the specified type.
 void removeExportedService(String name, Object service)
          Configuration Method: Removes the specified exported service.
 void removeExportedServices(String name)
          Configuration Method: Remove the named exported service domain object.
 void removeExportServiceRecord(IExportServiceRecord record)
          Configuration Method: Remove the specified export service record.
 void removeImportedServiceFilter(String name)
          Configuration Method: Removes the LDAP filter for an imported service.
 void removeOptionalImportedServiceFilter(String name)
          Configuration Method: Removes the LDAP filter for an optional imported service.
 void restartFramework()
          OSGi Framework Method: Stop and restart the OSGi framework.
 void setExportedServiceProperties(String name, Dictionary properties)
          Configuration Method: Sets the properties of an exported service.
 void setExportedServiceProperties(String name, Object service, Dictionary properties)
          Configuration Method: Sets the properties of an exported service.
 void shutdownFramework()
          OSGi Framework Method: Shutdown the OSGi framework.
 void start(BundleContext bundleContext, IBundleActivationManagerOwner owner)
          Start the bundle activation manager.
 void stop()
          Stop the bundle activation manager.
 

Method Detail

acquireImportedService

Object acquireImportedService(String name)
Configuration Method: Acquire the named imported service.

Parameters:
name - The name of an imported service.
Returns:
Object

acquireImportedServices

void acquireImportedServices()
Configuration Method: Acquire the imported services.


acquireOptionalImportedService

Object acquireOptionalImportedService(String name)
Configuration Method: Acquire the named optional imported service.

Parameters:
name - The name of an optional imported service.
Returns:
Object

acquireOptionalImportedServices

void acquireOptionalImportedServices()
Configuration Method: Acquire the optional imported services.


addExportedProxyService

void addExportedProxyService(Class interfaceType,
                             IProxyServiceHandler handler,
                             Dictionary properties)
Configuration Method: Add an exported proxy service.

Parameters:
interfaceType - The interface used to create the proxy service and register it with the OSGi framework.
handler - The proxy service's handler.
properties - The properties to be registered with the service.

addExportedProxyServices

void addExportedProxyServices(Class[] interfaceTypes,
                              IProxyServiceHandler handler,
                              Dictionary properties)
Configuration Method: Add an exported proxy service.

Parameters:
interfaceTypes - The interfaces used to create the proxy service and register it with the OSGi framework.
handler - The proxy service's handler.
properties - The properties to be registered with the service.

addExportedService

void addExportedService(String name,
                        Object service,
                        Dictionary properties)
Configuration Method: Add an exported service with properties.

Parameters:
name - The name of an exported service.
service - The service.
properties - The properties to be registered with the service.

addExportedServices

void addExportedServices(String[] names,
                         Object service,
                         Dictionary properties)
Configuration Method: Add multiple exported service with properties.

Parameters:
names - An array of exported service names.
service - The service.
properties - The properties to be registered with the services.

addExportServiceRecord

void addExportServiceRecord(IExportServiceRecord record)
Configuration Method: Add the specified export service record.

Parameters:
record - The export service record to add.

addExportServiceRecords

void addExportServiceRecords(IExportServiceRecord[] records)
Configuration Method: Add the specified export service records.

Parameters:
records - The export service records to add.

addImportedServiceFilter

void addImportedServiceFilter(String name,
                              String filterString)
Configuration Method: Add an LDAP filter to an imported service.

Parameters:
name - The name of the imported service.
filterString - The LDAP filter to be used for acquiring the imported service.

addImportServiceRecord

void addImportServiceRecord(IImportServiceRecord record)
Configuration Method: Add the specified import service record.

Parameters:
record - The import service record to add.

addOptionalImportedServiceFilter

void addOptionalImportedServiceFilter(String name,
                                      String filterString)
Configuration Method: Add an LDAP filter to an optional imported service.

Parameters:
name - The name of the optional imported service.
filterString - The LDAP filter to be used for acquiring the optional imported service.

getBundle

Bundle getBundle()
OSGi Query Method: Get the bundle.

Returns:
The bundle's Bundle object, or null.

getBundleContext

BundleContext getBundleContext()
OSGi Query Method: Get the BundleContext.

Returns:
The bundle's BundleContext, or null.

getBundleSymbolicName

String getBundleSymbolicName()
OSGi Query Method: Query the bundle's manifest for its Bundle-SymbolicName header.

Returns:
The name of the bundle.

getDataDirectory

File getDataDirectory()
Persistent Bundle Storage Method: Get the bundle's private data directory. The data directory is where it stores persistent data files.

Returns:
A File reference to the bundle's private data directory.
See Also:
getDataFile(String)

getDataFile

File getDataFile(String filename)
Persistent Bundle Storage Method: Open a data file contained in the bundle's private data directory. If the file does not exist, then it is created. The data file resides persistently in the bundle's private data directory within the bundle store.

Parameters:
filename - The name of the persistent data file.
Returns:
A File object associate with the persistent data file.
See Also:
getDataDirectory()

getExportedService

Object getExportedService(String name)
Query Method: Get a named exported service object.

Parameters:
name - The name of the exported service.
Returns:
An exported service object or null.

getExportedServiceNamesFromManifest

String[] getExportedServiceNamesFromManifest()
Deprecated. OSGi R4 has deprecated the Export-Service header.

Query Method: Answers the names of all the services that are exported specified in the bundle's manifest.

Returns:
The exported service names from the bundle manifest.

getExportedServiceProperties

Dictionary getExportedServiceProperties(String name)
Query Method: Answers the properties of an exported service.

Parameters:
name - The name of the exported service.
Returns:
A Dictionary containing the exported service's properties.

getExportedServiceProperties

Dictionary getExportedServiceProperties(String name,
                                        Object service)
Query Method: Answers the properties of a specific exported service.

Parameters:
name - The name of the exported service.
service - The exported service.
Returns:
A Dictionary containing the exported service's properties.

getExportedServices

Map getExportedServices()
Query Method: Get the exported service objects. The returned Map is keyed by service names, and each value is a List of service objects. The value is always a List, even if there is only one exported service for a particular service name.

Returns:
A Map where each key is a service names and each value is a List of service objects.

getExportedServices

Object[] getExportedServices(String name)
Query Method: Query the exported services.

Parameters:
name - The name of the exported service.
Returns:
An array of the named exported services, or an empty array if no match is found.

getFilePropertiesInputStream

InputStream getFilePropertiesInputStream()
                                         throws IOException
Query Method: Create an input stream on the default properties file.

Returns:
An input stream on the default properties.
Throws:
IOException

getFilePropertiesInputStream

InputStream getFilePropertiesInputStream(String filename)
                                         throws IOException
Query Method: Create an input stream on the specified properties file.

Parameters:
filename - The name of the properties file.
Returns:
An input stream on the specified properties file.
Throws:
IOException

getImportedService

Object getImportedService(String name)
Query Method: Get the named imported service. This method is guaranteed to return the requested service so long as the following conditions are true: If these conditions are not true, there is the possibility that this method will return null.

Parameters:
name - The name of the imported service.
Returns:
The imported service or null if no match is found.
See Also:
IBundleActivationManagerOwner.activate(), IBundleActivationManagerOwner.deactivate()

getImportedServiceFilter

Filter getImportedServiceFilter(String name)
Query Method: Search for an imported service filter.

Parameters:
name - The name of the imported service.
Returns:
Answers the filter for the named imported service, or null if no filter exists.

getImportedServiceNames

String[] getImportedServiceNames()
Query Method: Answers the names of all the required services that are imported by the bundle.

Returns:
The required imported service names.

getImportedServiceNamesFromManifest

String[] getImportedServiceNamesFromManifest()
Deprecated. OSGi R4 has deprecated the Import-Service header.

Query Method: Answers the names of all the services that are imported specified in the bundle's manifest.

Returns:
The imported service names from the bundle manifest.

getImportedServiceProperty

Object getImportedServiceProperty(String name,
                                  String key)
Query Method: Get the value of an imported service's property.

Parameters:
name - The name of the imported service.
key - The key of the imported service property.
Returns:
The imported service's property or null if the property cannot be found.

getImportedServicePropertyKeys

String[] getImportedServicePropertyKeys(String name)
Query Method: Get the keys of an imported service's properties.

Parameters:
name - The name of the imported service.
Returns:
The imported service's property keys or null if no properties exist.

getImportedServices

Map getImportedServices()
Query Method: Get the imported service objects. The returned Map is keyed by service names, and each value is a the service object.

Returns:
A Map where each key is a service names and each value is a service object.

getOptionalImportedService

Object getOptionalImportedService(String name)
Query Method: Get the named optional imported service.

Parameters:
name - The name of the optional imported service.
Returns:
The imported service or null if no match is found.

getOptionalImportedServiceFilter

Filter getOptionalImportedServiceFilter(String name)
Query Method: Search for an optional imported service filter.

Parameters:
name - The name of the optional imported service.
Returns:
Answers the filter for the named optional imported service, or null if no filter exists.

getOptionalImportedServiceNames

String[] getOptionalImportedServiceNames()
Query Method: Answers the names of all the optional services that are imported by the bundle.

Returns:
The optional imported service names.

getOptionalImportedServiceProperty

Object getOptionalImportedServiceProperty(String name,
                                          String key)
Query Method: Get the value of an optional imported service's property.

Parameters:
name - The name of the optional imported service.
key - The key of the optional imported service property.
Returns:
The optional imported service's property or null if the property cannot be found.

getOptionalImportedServicePropertyKeys

String[] getOptionalImportedServicePropertyKeys(String name)
Query Method: Get the keys of an optional imported service's properties.

Parameters:
name - The name of the optional imported service.
Returns:
The optional imported service's property keys or null if no properties exist.

getOptionalImportedServices

Map getOptionalImportedServices()
Query Method: Get the option imported service objects. The returned Map is keyed by service names, and each value is a the service object.

Returns:
A Map where each key is a service names and each value is a service object.

getProperties

Properties getProperties()
Query API: Create a Properties object out of the bundle's properties. This method does not cache the Properties object. The properties are obtained using the query method getPropertiesInputStream(), which is typically overridden by subclasses that define properties.

Returns:
The bundle's properties.

getProperty

String getProperty(String key,
                   String defaultValue)
Query API: Get the value of a property.

Parameters:
key - The property key.
defaultValue - The default value for the property.
Returns:
The value of the property, or the default value if the key is not found.

getUnacquiredImportedServiceNames

String[] getUnacquiredImportedServiceNames()
Query API: Get the names of the imported services that have not been acquired.

Returns:
The names of the imported services that have not been acquired.

getUnacquiredOptionalImportedServiceNames

String[] getUnacquiredOptionalImportedServiceNames()
Query API: Get the names of the optional imported services that have not been acquired.

Returns:
The names of the optional imported services that have not been acquired.

releaseImportedService

void releaseImportedService(String name)
Configuration Method: Release the named imported service.

Parameters:
name - The name of an imported service.

releaseImportedServices

void releaseImportedServices()
Configuration Method: Release the imported services.


releaseOptionalImportedService

void releaseOptionalImportedService(String name)
Configuration Method: Release the named optional imported service.

Parameters:
name - The name of an optional imported service.

releaseOptionalImportedServices

void releaseOptionalImportedServices()
Configuration Method: Release the optional imported services.


removeExportedService

void removeExportedService(String name)
Configuration Method: Remove the exported service record of the specified type. Since an IExportServiceRecord can represent multiple distinct service names, this method will remove all IExportServiceRecord occurrences, regardless of the specified service name. The specified service name is simply used to identify the IExportServiceRecord. While this method is visible to subclasses, it is not typically used.

Note: All exported services are automatically removed by SAT when the bundle stops.

Parameters:
name - The service name.

removeExportedService

void removeExportedService(String name,
                           Object service)
Configuration Method: Removes the specified exported service. Since an IExportServiceRecord can represent multiple distinct service names, this method will remove all IExportServiceRecord occurrences, regardless of the specified service name. The specified service name is simply used to identify the IExportServiceRecord. While this method is visible to subclasses, it is not typically used.

Note: All exported services are automatically removed by SAT when the bundle stops.

Parameters:
name - The service name.
service - The service.

removeExportedServices

void removeExportedServices(String name)
Configuration Method: Remove the named exported service domain object.

Note: All exported services are automatically removed by SAT when the bundle stops.

Parameters:
name - The name of the exported service.

removeExportServiceRecord

void removeExportServiceRecord(IExportServiceRecord record)
Configuration Method: Remove the specified export service record.

Parameters:
record - The export service record to remove.

removeImportedServiceFilter

void removeImportedServiceFilter(String name)
Configuration Method: Removes the LDAP filter for an imported service.

Parameters:
name - The name of the imported service.

removeOptionalImportedServiceFilter

void removeOptionalImportedServiceFilter(String name)
Configuration Method: Removes the LDAP filter for an optional imported service.

Parameters:
name - The name of the optional imported service.

restartFramework

void restartFramework()
                      throws BundleException
OSGi Framework Method: Stop and restart the OSGi framework. If the bundle has been stopped, this method does nothing.

Throws:
BundleException

setExportedServiceProperties

void setExportedServiceProperties(String name,
                                  Dictionary properties)
Configuration Method: Sets the properties of an exported service.

Parameters:
name - The name of the exported service.
properties - The LDAP properties to be registered with the exported service.

setExportedServiceProperties

void setExportedServiceProperties(String name,
                                  Object service,
                                  Dictionary properties)
Configuration Method: Sets the properties of an exported service.

Parameters:
name - The name of the exported service.
service - The service.
properties - The LDAP properties to be registered with the exported service.

shutdownFramework

void shutdownFramework()
                       throws BundleException
OSGi Framework Method: Shutdown the OSGi framework. If the bundle has been stopped, this method does nothing.

Throws:
BundleException

start

void start(BundleContext bundleContext,
           IBundleActivationManagerOwner owner)
           throws Exception
Start the bundle activation manager.

Parameters:
bundleContext - The BundleContext for the bundle.
owner - The owner of the bundle activation manager.
Throws:
Exception - when the bundle activation manager fails to start.

stop

void stop()
          throws Exception
Stop the bundle activation manager.

Throws:
Exception - when the bundle activation manager fails to stop.

Service Activator Toolkit
Version 1.1.0 (20081206)