|
Service Activator Toolkit
Version 1.1.0 (20081206) |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.eclipse.soda.sat.core.framework.BaseBundleActivator
public abstract class BaseBundleActivator
BaseBundleActivator
is an abstract class from which all SAT
bundles typically derive their BundleActivator
. The
BaseBundleActivator
class is central to SAT since it prescribes
the algorithm for managing the life cycle of a bundle.
The BaseBundleActivator
class is implemented using the
Template Method Pattern, providing hook and configuration methods
that subclasses can override, and supporting query methods.
Subclasses of BaseBundleActivator
are often created using the
Eclipse-based SAT Bundle Activator wizard. The wizard can be
accessed by selecting File > New > Other... and selecting the
Service Activator Toolkit category from the dialog.
While subclassing the BaseBundleActivator
is by far the most
common way of using SAT, this is not the only way. A bundle that needs to
be highly customized can have its activator built using the SAT abstractions
that are available via the FactoryUtility
class.
Field Summary | |
---|---|
protected static String[] |
NO_SERVICES
|
Constructor Summary | |
---|---|
BaseBundleActivator()
|
Method Summary | |
---|---|
protected Object |
acquireImportedService(String name)
Configuration API: Acquire the specified imported services. |
protected void |
acquireImportedServices()
Configuration API: Acquire all the imported services. |
protected void |
acquireOptionalImportedServices()
Configuration API: Acquire all the optional imported services. |
protected void |
activate()
Hook API: This method is overridden by subclasses that wish to execute domain specific activation. |
protected void |
addExportedProxyService(Class interfaceType,
IProxyServiceHandler handler,
Dictionary properties)
Configuration API: Add an exported proxy service. |
protected void |
addExportedProxyServices(Class[] interfaceTypes,
IProxyServiceHandler handler,
Dictionary properties)
Configuration API: Add an exported proxy service. |
protected void |
addExportedService(String name,
Object service,
Dictionary properties)
Configuration API: Add an exported service with properties. |
protected void |
addExportedServices(String[] names,
Object service,
Dictionary properties)
Configuration API: Add multiple exported service with properties. |
protected void |
addImportedServiceFilter(String name,
String filterString)
Configuration API: Add an LDAP filter to an imported service. |
protected void |
addOptionalImportedServiceFilter(String name,
String filterString)
Configuration API: Add an LDAP filter to an optional imported service. |
protected String[] |
basicGetImportedServiceNames()
Get the imported service names. |
protected String[] |
basicGetOptionalImportedServiceNames()
Get the optional imported service names. |
protected void |
collectImportedServiceNames(Set serviceNames)
Hook API: This method is extended by subclasses that have required imported services. |
protected void |
collectOptionalImportedServiceNames(Set serviceNames)
Hook API: This method is extended by subclasses that have optional imported services. |
protected void |
deactivate()
Hook API: You have been deactivated. |
protected int |
getAsyncStartPriority()
Configuration Parameter API: Get the async start thread priority. |
protected Bundle |
getBundle()
OSGi Query API: Get the bundle. |
protected IBundleActivationManager |
getBundleActivationManager()
Protected bundleActivationManager getter. |
protected BundleContext |
getBundleContext()
OSGi Query API: Get the bundle context. |
protected String |
getBundleSymbolicName()
OSGi Query API: Query the bundle's manifest for its Bundle-SymbolicName header. |
protected File |
getDataDirectory()
Persistent Bundle Storage API: Get the bundle's private data directory. |
protected File |
getDataFile(String filename)
Persistent Bundle Storage API: Open a data file contained in the bundle's private data directory. |
protected Object |
getExportedService(String name)
Query API: Get a named exported service object. |
protected String[] |
getExportedServiceNamesFromManifest()
Deprecated. OSGi R4 has deprecated the Export-Service header. |
protected Dictionary |
getExportedServiceProperties(String name)
Query API: Answers the properties of an exported service. |
protected Dictionary |
getExportedServiceProperties(String name,
Object service)
Query API: Answers the properties of a specific exported service. |
protected Map |
getExportedServices()
Query API: Query the exported services. |
protected Object[] |
getExportedServices(String name)
Query API: Query the exported services. |
protected InputStream |
getFilePropertiesInputStream()
Query API: Create an input stream on the default properties file. |
protected InputStream |
getFilePropertiesInputStream(String filename)
Query API: Create an input stream on the specified properties file. |
protected Object |
getImportedService(String name)
Query API: Get the named imported service. |
protected Filter |
getImportedServiceFilter(String name)
Query API: Search for an imported service filter. |
protected String[] |
getImportedServiceNames()
Query API: Answers the names of all the services that are imported by the bundle. |
protected String[] |
getImportedServiceNamesFromManifest()
Deprecated. OSGi R4 has deprecated the Import-Service header. |
protected Object |
getImportedServiceProperty(String name,
String key)
Query API: Get the value of an imported service's property. |
protected String[] |
getImportedServicePropertyKeys(String name)
Query API: Get the keys of an imported service's properties. |
protected Map |
getImportedServices()
Query API: Query the imported services. |
protected Object |
getOptionalImportedService(String name)
Query API: Get the named optional imported service. |
protected Filter |
getOptionalImportedServiceFilter(String name)
Query API: Search for an optional imported service filter. |
protected String[] |
getOptionalImportedServiceNames()
Query API: Answers the names of all the services that are optionally imported by the bundle. |
protected Object |
getOptionalImportedServiceProperty(String name,
String key)
Query API: Get the value of an optional imported service's property. |
protected String[] |
getOptionalImportedServicePropertyKeys(String name)
Query API: Get the keys of an optional imported service's properties. |
protected Map |
getOptionalImportedServices()
Query API: Query the optional imported services. |
protected Properties |
getProperties()
Query API: Create a Properties object out of the
bundle's properties. |
protected InputStream |
getPropertiesInputStream()
Hook API: Get an input stream to the bundle's properties. |
protected String |
getProperty(String key,
String defaultValue)
Query API: Get the value of a property. |
protected InputStream |
getResourcePropertiesInputStream()
Query API: Create an input stream on the default resource properties. |
protected InputStream |
getResourcePropertiesInputStream(String filename)
Query API: Create an input stream on the specified resource file. |
protected void |
handleAcquiredOptionalImportedService(String serviceName,
Object service)
Hook Handler API: When an optional imported service is acquired, this method is called. |
protected boolean |
handleException(Exception exception)
Hook Handler API: Handles a thrown exception. |
protected void |
handleFailedToFindProperties(String filename)
Hook Handler API: Handle the fact that the specified properties file could not be found. |
protected void |
handleReleasedOptionalImportedService(String serviceName,
Object service)
Hook Handler API: When an optional imported service is released, this method is called. |
protected boolean |
isStartAsync()
Configuration Parameter API: Specifies whether the bundle should start asynchronously. |
protected boolean |
isTransient()
Configuration Parameter API: Specify whether the bundle should be treated as transient. |
protected boolean |
isUninstallable()
Configuration Parameter API: Specify whether the bundle should be treated as uninstalled. |
protected void |
releaseImportedService(String name)
Configuration API: Release the specified imported services. |
protected void |
releaseImportedServices()
Configuration API: Release all the imported services. |
protected void |
releaseOptionalImportedServices()
Configuration API: Release all the optional imported services. |
protected void |
removeExportedService(String name)
Configuration API: Remove the exported service record of the specified type. |
protected void |
removeExportedService(String name,
Object service)
Configuration API: Removes the specified exported service. |
protected void |
removeExportedServices(String name)
Configuration API: Remove the named exported service domain object. |
protected void |
removeImportedServiceFilter(String name)
Configuration API: Removes the LDAP filter for an imported service. |
protected void |
removeOptionalImportedServiceFilter(String name)
Configuration API: Removes the LDAP filter for an optional imported service. |
protected void |
restartFramework()
OSGi Framework API: Stop and restart the OSGi framework. |
protected void |
setExportedServiceProperties(String name,
Dictionary properties)
Configuration API: Sets the properties of an exported service. |
protected void |
setExportedServiceProperties(String name,
Object service,
Dictionary properties)
Configuration API: Sets the properties of an exported service. |
protected void |
shutdownFramework()
OSGi Framework API: Shutdown the OSGi framework. |
protected void |
start()
Hook API: This method is called by start(BundleContext)
. |
void |
start(BundleContext bundleContext)
Bundle Activator API: This is where the bundle activator starts its execution. |
protected void |
stop()
Hook API: This method is called by stop(BundleContext)
. |
void |
stop(BundleContext bundleContext)
Bundle Activator API: This is where the bundle activator stops its execution. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
protected static final String[] NO_SERVICES
Constructor Detail |
---|
public BaseBundleActivator()
Method Detail |
---|
protected final Object acquireImportedService(String name)
releaseImportedService(String)
.
name
- The name of an imported service.
releaseImportedService(java.lang.String)
,
IBundleActivationManager.acquireImportedService(java.lang.String)
protected final void acquireImportedServices()
releaseImportedServices()
.
releaseImportedServices()
,
IBundleActivationManager.acquireImportedServices()
protected final void acquireOptionalImportedServices()
releaseOptionalImportedServices()
,
IBundleActivationManager.acquireOptionalImportedServices()
protected void activate()
protected void activate() { MyDomainObject object = (MyDomainObject) getExportedService(MyService.SERVICE_NAME); object.startup(); }
IBundleActivationManagerOwner.activate()
protected final void addExportedProxyService(Class interfaceType, IProxyServiceHandler handler, Dictionary properties)
protected void createExportedServices() { IProxyServiceHandler handler = new ProxyServiceAdapter() { public Object createService() { return new HotdogVendor(); } }; Dictionary properties = new Hashtable(11); properties.put("cn", "simona"); properties.put("o", "OTI"); properties.put("c", "US"); addExportedProxyService(VendorService.class, handler, properties); }
IBundleActivationManager.addExportedProxyService(java.lang.Class, org.eclipse.soda.sat.core.framework.interfaces.IProxyServiceHandler, java.util.Dictionary)
protected final void addExportedProxyServices(Class[] interfaceTypes, IProxyServiceHandler handler, Dictionary properties)
protected void createExportedServices() { Class[] interfaceTypes = new Class[] { VendorService.class, TicketService.class }; IProxyServiceHandler handler = new ProxyServiceAdapter() { public Object createService() { return new HotdogVendor(); } }; Dictionary properties = new Hashtable(11); properties.put("cn", "simona"); properties.put("o", "OTI"); properties.put("c", "US"); addExportedProxyService(interfaceTypes, handler, properties); }
IBundleActivationManager.addExportedProxyServices(java.lang.Class[], org.eclipse.soda.sat.core.framework.interfaces.IProxyServiceHandler, java.util.Dictionary)
protected final void addExportedService(String name, Object service, Dictionary properties)
protected void createExportedServices() { VendorService vendor = new HotdogVendor(); Dictionary properties = new Hashtable(11); properties.put("cn", "simona"); properties.put("o", "OTI"); properties.put("c", "US"); addExportedService(VendorService.SERVICE_NAME, vendor, properties); }
IBundleActivationManager.addExportedService(java.lang.String, java.lang.Object, java.util.Dictionary)
protected final void addExportedServices(String[] names, Object service, Dictionary properties)
protected void createExportedServices() { String[] names = new String[] { VendorService.SERVICE_NAME, TicketService.SERVICE_NAME }; Object vendor = new HotdogVendor(); Dictionary properties = new Hashtable(11); properties.put("cn", "simona"); properties.put("o", "OTI"); properties.put("c", "US"); addExportedService(names, vendor, properties); }
IBundleActivationManager.addExportedServices(java.lang.String[], java.lang.Object, java.util.Dictionary)
protected final void addImportedServiceFilter(String name, String filterString)
protected void start() { BundleContext context = getBundleContext(); addImportedServiceFilter(YourService.SERVICE_NAME, "(o=IBM)"); }
IBundleActivationManager.addImportedServiceFilter(java.lang.String, java.lang.String)
protected final void addOptionalImportedServiceFilter(String name, String filterString)
protected void start() { BundleContext context = getBundleContext(); addOptionalImportedServiceFilter(YourService.SERVICE_NAME, "(o=IBM)"); }
IBundleActivationManager.addOptionalImportedServiceFilter(java.lang.String, java.lang.String)
protected final String[] basicGetImportedServiceNames()
protected final String[] basicGetOptionalImportedServiceNames()
protected void collectImportedServiceNames(Set serviceNames)
getImportedServiceNames()
.
serviceNames
- A Set
into which collected service
names must be added.protected void collectOptionalImportedServiceNames(Set serviceNames)
getOptionalImportedServiceNames()
.
serviceNames
- A Set
into which collected service
names must be added.protected void deactivate()
protected void deactivate() { MyDomainObject object = (MyDomainObject) getExportedService(MyService.SERVICE_NAME); object.shutdown(); }
IBundleActivationManagerOwner.deactivate()
protected int getAsyncStartPriority()
isStartAsync()
to return true
and wish
to specify a thread priority other than Thread.NORM_PRIORITY
. For example:
protected int getAsyncStartPriority() { return Thread.NORM_PRIORITY + 1; }
IBundleActivationManagerOwner.getAsyncStartPriority()
protected final Bundle getBundle()
IBundleActivationManager.getBundle()
protected final IBundleActivationManager getBundleActivationManager()
protected final BundleContext getBundleContext()
IBundleActivationManager.getBundleContext()
protected final String getBundleSymbolicName()
Bundle-SymbolicName
header.
IBundleActivationManager.getBundleSymbolicName()
protected final File getDataDirectory()
IBundleActivationManager.getDataDirectory()
protected final File getDataFile(String filename)
IBundleActivationManager.getDataFile(java.lang.String)
protected final Object getExportedService(String name)
IBundleActivationManager.getExportedService(java.lang.String)
protected final String[] getExportedServiceNamesFromManifest()
protected final Dictionary getExportedServiceProperties(String name)
IBundleActivationManager.getExportedServiceProperties(java.lang.String)
protected final Dictionary getExportedServiceProperties(String name, Object service)
IBundleActivationManager.getExportedServiceProperties(java.lang.String, java.lang.Object)
protected final Map getExportedServices()
IBundleActivationManager.getExportedServices()
protected final Object[] getExportedServices(String name)
IBundleActivationManager.getExportedServices(java.lang.String)
protected final InputStream getFilePropertiesInputStream() throws IOException
IOException
IBundleActivationManager.getFilePropertiesInputStream()
protected final InputStream getFilePropertiesInputStream(String filename) throws IOException
IOException
IBundleActivationManager.getFilePropertiesInputStream(java.lang.String)
protected final Object getImportedService(String name)
IBundleActivationManager.getImportedService(java.lang.String)
protected final Filter getImportedServiceFilter(String name)
IBundleActivationManager.getImportedServiceFilter(java.lang.String)
protected String[] getImportedServiceNames()
IBundleActivationManagerOwner.getImportedServiceNames()
protected final String[] getImportedServiceNamesFromManifest()
protected final Object getImportedServiceProperty(String name, String key)
IBundleActivationManager.getImportedServiceProperty(java.lang.String, java.lang.String)
protected final String[] getImportedServicePropertyKeys(String name)
IBundleActivationManager.getImportedServicePropertyKeys(java.lang.String)
protected final Map getImportedServices()
IBundleActivationManager.getImportedServices()
protected final Object getOptionalImportedService(String name)
IBundleActivationManager.getOptionalImportedService(java.lang.String)
protected final Filter getOptionalImportedServiceFilter(String name)
IBundleActivationManager.getOptionalImportedServiceFilter(java.lang.String)
protected String[] getOptionalImportedServiceNames()
IBundleActivationManagerOwner.getOptionalImportedServiceNames()
protected final Object getOptionalImportedServiceProperty(String name, String key)
IBundleActivationManager.getOptionalImportedServiceProperty(java.lang.String, java.lang.String)
protected final String[] getOptionalImportedServicePropertyKeys(String name)
IBundleActivationManager.getOptionalImportedServicePropertyKeys(java.lang.String)
protected final Map getOptionalImportedServices()
IBundleActivationManager.getOptionalImportedServices()
protected final Properties getProperties()
Properties
object out of the
bundle's properties. The properties are obtained using the query method
getPropertiesInputStream()
, which is typically overridden by
subclasses that define properties.
protected InputStream getPropertiesInputStream() throws IOException
BundleActivator
:
protected InputStream getPropertiesInputStream() throws IOException { return getResourcePropertiesInputStream(); }And if the properties are stored as a file in the local file system:
protected InputStream getPropertiesInputStream() throws IOException { return getFilePropertiesInputStream(); }
IOException
IBundleActivationManagerOwner.getPropertiesInputStream()
protected String getProperty(String key, String defaultValue)
key
- The property key.defaultValue
- The default value for the property.
protected final InputStream getResourcePropertiesInputStream() throws IOException
IOException
protected final InputStream getResourcePropertiesInputStream(String filename) throws IOException
filename
- The name of the properties resource file.
IOException
protected void handleAcquiredOptionalImportedService(String serviceName, Object service)
protected void handleAcquiredOptionalImportedService(String serviceName, Object service) { if (serviceName.equals(PrinterApplicationService.SERVICE_NAME)) { PrinterApplicationWindow window = getWindow(); PrinterApplicationService model = (PrinterApplicationService) service; window.setModel(model); } else { super.handleAcquiredOptionalImportedService(serviceName, service); } }Since all acquired optional imported services will arrive via this method, it is important to separately handle each imported service.
IBundleActivationManagerOwner.handleAcquiredOptionalImportedService(java.lang.String, java.lang.Object)
protected boolean handleException(Exception exception)
IBundleActivationManagerOwner.handleException(java.lang.Exception)
protected void handleFailedToFindProperties(String filename)
IBundleActivationManagerOwner.handleFailedToFindProperties(java.lang.String)
protected void handleReleasedOptionalImportedService(String serviceName, Object service)
protected void handleReleasedOptionalImportedService(String serviceName, Object service) { if (serviceName.equals(PrinterApplicationService.SERVICE_NAME)) { PrinterApplicationWindow window = getWindow(); window.setModel(null); } else { super.handleReleasedOptionalImportedService(serviceName, service); } }Since all acquired optional imported services will arrive via this method, it is important to separately handle each imported service.
IBundleActivationManagerOwner.handleReleasedOptionalImportedService(java.lang.String, java.lang.Object)
protected boolean isStartAsync()
protected boolean isStartAsync() { return true; }
IBundleActivationManagerOwner.isStartAsync()
protected boolean isTransient()
Bundle.ACTIVE
state.
This method should be overridden by bundles that are to be considered
transient. For example:
protected boolean isTransient() { return true; }Note:
isUninstallable()
.
IBundleActivationManagerOwner.isTransient()
protected boolean isUninstallable()
true
by bundles that are
uninstallable prerequisites. For example:
protected boolean isUninstallable() { return true; }
Note:
isTransient()
.
IBundleActivationManagerOwner.isUninstallable()
protected final void releaseImportedService(String name)
addImportedServiceFilter(String, String)
to change
the filter for each imported service, it is necessary to call the method
releaseImportedService(String)
for each imported service
that has a filter first. Once the filters have been changed, call the
method acquireImportedService(String)
for each imported
service that has a filter to re-acquire the imported services. Doing so
ensures that the bundle only ever atomically acquires services with the
the appropriate filters.
... try { releaseImportedService(VendorService.SERVICE_NAME); releaseImportedService(NapkinService.SERVICE_NAME); addImportedServiceFilter(VendorService.SERVICE_NAME, "(spiciness=5)"); addImportedServiceFilter(NapkinService.SERVICE_NAME, "(ply=2)"); } finally { acquireImportedService(VendorService.SERVICE_NAME); acquireImportedService(NapkinService.SERVICE_NAME); } ...Using
try
/finally
is not strictly necessary,
but does nicely ensure that the imported services will always be
re-acquired in the face of a thrown exception, however unlikely.
name
- The name of an imported service.acquireImportedService(java.lang.String)
,
IBundleActivationManager.releaseImportedService(java.lang.String)
protected final void releaseImportedServices()
addImportedServiceFilter(String, String)
to change
the filter for each imported service, it is necessary to call the method
releaseImportedServices()
first. Once both filters have
been changed, call the method acquireImportedServices()
to
re-acquire the services. Doing so ensures that the bundle only ever
atomically acquires services with appropriate filters.
... try { releaseImportedServices(); addImportedServiceFilter(VendorService.SERVICE_NAME, "(spiciness=5)"); addImportedServiceFilter(NapkinService.SERVICE_NAME, "(ply=2)"); } finally { acquireImportedServices(); } ...Using
try
/finally
is not strictly necessary,
but does nicely ensure that the imported services will always be
re-acquired in the face of a thrown exception, however unlikely.
acquireImportedServices()
,
IBundleActivationManager.releaseImportedServices()
protected final void releaseOptionalImportedServices()
acquireOptionalImportedServices()
,
IBundleActivationManager.releaseOptionalImportedServices()
protected final void removeExportedService(String name)
Note: All exported services are automatically removed by SAT when the bundle is deactivated.
IBundleActivationManager.removeExportedService(java.lang.String)
protected final void removeExportedService(String name, Object service)
Note: All exported services are automatically removed by SAT when the bundle is deactivated.
IBundleActivationManager.removeExportedService(java.lang.String, java.lang.Object)
protected final void removeExportedServices(String name)
Note: All exported services are automatically removed by SAT when the bundle is deactivated.
IBundleActivationManager.removeExportedServices(java.lang.String)
protected final void removeImportedServiceFilter(String name)
IBundleActivationManager.removeImportedServiceFilter(java.lang.String)
protected final void removeOptionalImportedServiceFilter(String name)
IBundleActivationManager.removeOptionalImportedServiceFilter(java.lang.String)
protected final void restartFramework() throws BundleException
Note: Sadly, this method does not work on Equinox 3.3.0. See Eclipse bug 128531 for more details.
BundleException
IBundleActivationManager.restartFramework()
protected final void setExportedServiceProperties(String name, Dictionary properties)
IBundleActivationManager.setExportedServiceProperties(String, java.util.Dictionary)
protected final void setExportedServiceProperties(String name, Object service, Dictionary properties)
IBundleActivationManager.setExportedServiceProperties(java.lang.String, java.lang.Object, java.util.Dictionary)
protected final void shutdownFramework() throws BundleException
BundleException
IBundleActivationManager.shutdownFramework()
protected void start() throws Exception
start(BundleContext)
. This method is typically overridden by subclasses that wish to
perform behavior exactly once when the bundle starts. For example:
protected void start() { PrinterApplicationWindow window = getWindow(); WindowListener listener = getWindowListener(); window.addWindowListener(listener); window.open(); }
Exception
IBundleActivationManagerOwner.start()
public final void start(BundleContext bundleContext) throws Exception
start
in interface BundleActivator
Exception
BundleActivator.start(org.osgi.framework.BundleContext)
protected void stop() throws Exception
stop(BundleContext)
. This method is overridden by subclasses that wish to perform
behavior exactly once when the bundle stops.
For example:
protected void stop() { PrinterApplicationWindow window = getWindow(); window.close(); WindowListener listener = getWindowListener(); window.removeWindowListener(listener); }
Exception
IBundleActivationManagerOwner.stop()
public final void stop(BundleContext bundleContext) throws Exception
stop
in interface BundleActivator
Exception
BundleActivator.stop(org.osgi.framework.BundleContext)
|
Service Activator Toolkit
Version 1.1.0 (20081206) |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright © 2001, 2008 IBM Corporation and others. All Rights Reserved.