org.ungoverned.oscar
Class Oscar

java.lang.Object
  extended by org.ungoverned.oscar.Oscar

public class Oscar
extends java.lang.Object


Field Summary
static int RUNNING_STATUS
           
static int STARTING_STATUS
           
static int STOPPING_STATUS
           
static int UNKNOWN_STATUS
           
 
Constructor Summary
Oscar()
           Creates an instance of Oscar where all configuration properties (e.g., profile name, profile directory, strictness, and embedded execution) are specified using system properties.
Oscar(java.util.List activatorList)
           Creates an instance of Oscar where all configuration properties (e.g., profile name, profile directory, strictness, and embedded execution) are specified using system properties.
Oscar(java.util.Properties props)
           Creates an instance of Oscar where all configuration properties (e.g., profile name, profile directory, strictness, and embedded execution) are specified in the supplied Properties instance.
Oscar(java.util.Properties props, java.util.List activatorList)
           Creates an instance of Oscar where all configuration properties (e.g., profile name, profile directory, strictness, and embedded execution) are specified in the supplied Properties instance.
 
Method Summary
protected  void addBundleListener(Bundle bundle, BundleListener l)
          Implementation for BundleContext.addBundleListener().
protected  void addFrameworkListener(Bundle bundle, FrameworkListener l)
          Implementation for BundleContext.addFrameworkListener().
protected  boolean addImport(Module module, java.lang.Object target, java.lang.Object version, boolean force)
          This method adds a import target to the IMPORTS_ATTR attribute array associated with the specified module.
protected  void addServiceListener(Bundle bundle, ServiceListener l, java.lang.String f)
          Implementation for BundleContext.addServiceListener().
protected  boolean bundleHasPermission(org.ungoverned.oscar.BundleImpl bundle, java.lang.Object obj)
          Implementation for Bundle.hasPermission().
static void debug(java.lang.String s)
           
static void error(java.lang.String s)
           
static void error(java.lang.String s, java.lang.Throwable th)
           
protected  Bundle getBundle(long id)
          Implementation for BundleContext.getBundle().
protected  java.io.File getBundleDataFile(org.ungoverned.oscar.BundleImpl bundle, java.lang.String name)
          Implementation for BundleContext.getDataFile().
protected  java.util.Dictionary getBundleHeaders(org.ungoverned.oscar.BundleImpl bundle)
          Implementation for Bundle.getHeaders().
protected  long getBundleId(org.ungoverned.oscar.BundleImpl bundle)
          Implementation for Bundle.getBundleId().
protected  java.lang.String getBundleLocation(org.ungoverned.oscar.BundleImpl bundle)
          Implementation for Bundle.getLocation().
protected  ServiceReference[] getBundleRegisteredServices(org.ungoverned.oscar.BundleImpl bundle)
          Implementation for Bundle.getRegisteredServices().
protected  java.net.URL getBundleResource(org.ungoverned.oscar.BundleImpl bundle, java.lang.String name)
          Implementation for Bundle.getResource().
protected  Bundle[] getBundles()
          Implementation for BundleContext.getBundles().
protected  ServiceReference[] getBundleServicesInUse(org.ungoverned.oscar.BundleImpl bundle)
          Implementation for Bundle.getServicesInUse().
protected  int getBundleStartLevel(Bundle bundle)
          Returns the start level for the specified bundle; this method implements functionality for the Start Level service.
protected  int getBundleState(org.ungoverned.oscar.BundleImpl bundle)
          Implementation for Bundle.getState().
 java.lang.String getConfigProperty(java.lang.String name)
           Oscar uses this method whenever it needs to access any configuration properties.
protected  ExportedPackage getExportedPackage(java.lang.String name)
          Returns the exported package associated with the specified package name.
protected  ExportedPackage[] getExportedPackages(Bundle b)
          Returns an array of all actively exported packages from the specified bundle or if the specified bundle is null an array containing all actively exported packages by all bundles.
 int getFrameworkStatus()
          Returns the current status of Oscar; this information is used to determine which actions to perform during various execution activities.
protected  Bundle[] getImportingBundles(ExportedPackage ep)
           
protected  int getInitialBundleStartLevel()
          Returns the start level into which newly installed bundles will be placed by default; this method implements functionality for the Start Level service.
protected  java.lang.String getProperty(java.lang.String key)
          Implementation for BundleContext.getProperty().
protected  java.lang.Object getService(org.ungoverned.oscar.BundleImpl bundle, ServiceReference ref)
          Implementation for BundleContext.getService().
protected  ServiceReference[] getServiceReferences(java.lang.String className, java.lang.String expr)
          Implementation for BundleContext.getServiceReferences().
protected  int getStartLevel()
          Returns the active start level of the framework; this method implements functionality for the Start Level service.
protected  Bundle[] getUsingBundles(ServiceReference ref)
          Returns the bundles that are using the service referenced by the ServiceReference object.
static void initializeSystemProperties()
          Installs all system properties specified in the system property file associated with the Oscar installation; these properties will be accessible through System.getProperty() at run time.
protected  Bundle installBundle(java.lang.String location, java.io.InputStream is)
          Implementation for BundleContext.installBundle().
protected  boolean isBundlePersistentlyStarted(Bundle bundle)
          Returns whether a bundle is persistently started; this is an method implementation for the Start Level service.
 boolean isStrictOSGi()
          Returns the framework flag that indicates whether Oscar is strictly adhering to the OSGi specification.
protected  void refreshPackages(Bundle[] targets)
           
protected  ServiceRegistration registerService(org.ungoverned.oscar.BundleImpl bundle, java.lang.String[] classNames, java.lang.Object svcObj, java.util.Dictionary dict)
          Implementation for BundleContext.registerService().
protected  void removeBundleListener(BundleListener l)
          Implementation for BundleContext.removeBundleListener().
protected  void removeFrameworkListener(FrameworkListener l)
          Implementation for BundleContext.removeFrameworkListener().
protected  void removeServiceListener(ServiceListener l)
          Implementation for BundleContext.removeServiceListener().
protected  void resolveBundle(org.ungoverned.oscar.BundleImpl bundle)
           
protected  void servicePropertiesModified(ServiceRegistration reg)
          Sets the properties associated with the given service registration.
protected  void setBundleStartLevel(Bundle bundle, int startLevel)
          Sets the start level of the specified bundle; this method implements functionality for the Start Level service.
static void setDebug(java.io.PrintStream ps)
           
protected  void setInitialBundleStartLevel(int startLevel)
          Sets the default start level into which newly installed bundles will be placed; this method implements functionality for the Start Level service.
protected  void setProperty(java.lang.String key, java.lang.String value)
          Set the environment property associated with the container.
protected  void setStartLevelInternal(int requestedLevel)
          Implements the functionality of the setStartLevel() method for the StartLevel service, but does not do the security or parameter check.
 void shutdown()
          This method cleanly shuts down Oscar, it must be called at the end of a session in order to shutdown all active bundles.
protected  void startBundle(org.ungoverned.oscar.BundleImpl bundle)
          Implementation for Bundle.start().
protected  void stopBundle(org.ungoverned.oscar.BundleImpl bundle)
          Implementation for Bundle.stop().
protected  java.lang.Object ungetService(org.ungoverned.oscar.BundleImpl bundle, ServiceReference ref)
          Implementation for BundleContext.ungetService().
protected  void ungetServices(org.ungoverned.oscar.BundleImpl bundle)
          This is a utility method to release all services being used by the specified bundle.
protected  void uninstallBundle(org.ungoverned.oscar.BundleImpl bundle)
          Implementation for Bundle.uninstall().
protected  void unregisterService(org.ungoverned.oscar.BundleImpl bundle, org.ungoverned.oscar.ServiceRegistrationImpl reg)
          Unregisters a service for the specified bundle.
protected  void unregisterServices(org.ungoverned.oscar.BundleImpl bundle)
          Unregisters all services for the specified bundle.
protected  void updateBundle(org.ungoverned.oscar.BundleImpl bundle, java.io.InputStream is)
          Implementation for Bundle.update().
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

UNKNOWN_STATUS

public static final int UNKNOWN_STATUS
See Also:
Constant Field Values

RUNNING_STATUS

public static final int RUNNING_STATUS
See Also:
Constant Field Values

STARTING_STATUS

public static final int STARTING_STATUS
See Also:
Constant Field Values

STOPPING_STATUS

public static final int STOPPING_STATUS
See Also:
Constant Field Values
Constructor Detail

Oscar

public Oscar()

Creates an instance of Oscar where all configuration properties (e.g., profile name, profile directory, strictness, and embedded execution) are specified using system properties. If the DefaulBundleCache is being used, then at a minimum a profile name or profile directory must be specified in the system properties.

System properties can be set using a system.properties file; refer to the usage document for more information.

See Also:
For information on Oscar properties.

Oscar

public Oscar(java.util.Properties props)

Creates an instance of Oscar where all configuration properties (e.g., profile name, profile directory, strictness, and embedded execution) are specified in the supplied Properties instance. If Properties is a null instance, then System.getProperty() is used to find all configuration properties. If the DefaulBundleCache is being used, then at a minimum a profile name or profile directory must be specified.

The following are framework configuration properties that can be specified in the Properties instance:

Besides the above framework properties, it is also possible to set properties for the bundle cache via the Oscar constructor. The available bundle cache properties depend on the cache implementation being used. For the properties of the default bundle cache, refer to the DefaulBundleCache API documentation. All of these properties can specified in one of three ways:

The system.properties file overwrites any property values specified on the command line. If a Properties instance is passed into Oscar's constructor, then all system properties are ignored and only the Properties instance is used to locate configuration property values.

Parameters:
props - the properties used to initialize Oscar; may also be null.

Oscar

public Oscar(java.util.List activatorList)

Creates an instance of Oscar where all configuration properties (e.g., profile name, profile directory, strictness, and embedded execution) are specified using system properties. If the DefaulBundleCache is being used, then at a minimum a profile name or profile directory must be specified in the system properties. This constructor accepts a list of BundleActivator instances that will be started/stopped by the System Bundle when the framework is started/stopped; this is useful for when Oscar is embedded into a host application that wants to provide services to the bundles inside of Oscar.

Parameters:
activatorList - list of bundle activators to be started/stopped by the system bundle; may also be null
See Also:
For information on Oscar properties.

Oscar

public Oscar(java.util.Properties props,
             java.util.List activatorList)

Creates an instance of Oscar where all configuration properties (e.g., profile name, profile directory, strictness, and embedded execution) are specified in the supplied Properties instance. If Properties is a null instance, then System.getProperty() is used to find all configuration properties. If the DefaulBundleCache is being used, then at a minimum a profile name or profile directory must be specified in the system properties. This constructor also accepts a list of BundleActivator instances that will be started/stopped by the System Bundle when the framework is started/stopped; this is useful for when Oscar is embedded into a host application that wants to provide services to the bundles inside of Oscar.

Parameters:
props - the properties used to initialize Oscar; may also be null.
activatorList - list of bundle activators to be started/stopped by the system bundle; may also be null
See Also:
For information on Oscar properties.
Method Detail

getConfigProperty

public java.lang.String getConfigProperty(java.lang.String name)

Oscar uses this method whenever it needs to access any configuration properties. This will look for a configuration property either in the system properties or in the configuration property map that was passed into the Oscar constructor; that is, Oscar will look in one place or the other, but not both. This approach was taken to simplify support for having multiple instances of Oscar in memory at the same time.

The approach is very simple. If no Properties instance was passed into the constructor, then this method only searches System.getProperty() to find property values. If a Properties instance was passed into the constructor, then it only searches the supplied instance. When creating multiple instances of Oscar, a Properties instance should be supplied to the constructor so that all instances do not end up using the same bundle cache directory.

Parameters:
name - the name of the configuration property to retrieve.
Returns:
the value of the specified configuration property or null if the property is not defined.

shutdown

public void shutdown()
This method cleanly shuts down Oscar, it must be called at the end of a session in order to shutdown all active bundles.


getStartLevel

protected int getStartLevel()
Returns the active start level of the framework; this method implements functionality for the Start Level service.

Returns:
the active start level of the framework.

setStartLevelInternal

protected void setStartLevelInternal(int requestedLevel)
Implements the functionality of the setStartLevel() method for the StartLevel service, but does not do the security or parameter check. The security and parameter check are done in the StartLevel service implementation because this method is called on a separate thread and the caller's thread would already be gone if we did the checks in this method.

Parameters:
requestedLevel - the new start level of the framework.

getInitialBundleStartLevel

protected int getInitialBundleStartLevel()
Returns the start level into which newly installed bundles will be placed by default; this method implements functionality for the Start Level service.

Returns:
the default start level for newly installed bundles.

setInitialBundleStartLevel

protected void setInitialBundleStartLevel(int startLevel)
Sets the default start level into which newly installed bundles will be placed; this method implements functionality for the Start Level service.

Parameters:
startLevel - the new default start level for newly installed bundles.
Throws:
java.lang.IllegalArgumentException - if the specified start level is not greater than zero.
java.security.SecurityException - if the caller does not have AdminPermission.

getBundleStartLevel

protected int getBundleStartLevel(Bundle bundle)
Returns the start level for the specified bundle; this method implements functionality for the Start Level service.

Parameters:
bundle - the bundle to examine.
Returns:
the start level of the specified bundle.
Throws:
java.lang.IllegalArgumentException - if the specified bundle has been uninstalled.

setBundleStartLevel

protected void setBundleStartLevel(Bundle bundle,
                                   int startLevel)
Sets the start level of the specified bundle; this method implements functionality for the Start Level service.

Parameters:
bundle - the bundle whose start level is to be modified.
startLevel - the new start level of the specified bundle.
Throws:
java.lang.IllegalArgumentException - if the specified bundle is the system bundle or if the bundle has been uninstalled.
java.security.SecurityException - if the caller does not have AdminPermission.

isBundlePersistentlyStarted

protected boolean isBundlePersistentlyStarted(Bundle bundle)
Returns whether a bundle is persistently started; this is an method implementation for the Start Level service.

Parameters:
bundle - the bundle to examine.
Returns:
true if the bundle is marked as persistently started, false otherwise.
Throws:
java.lang.IllegalArgumentException - if the specified bundle has been uninstalled.

getFrameworkStatus

public int getFrameworkStatus()
Returns the current status of Oscar; this information is used to determine which actions to perform during various execution activities. For example, during startup a bundle's state should not be saved since the state was recorded at and at shutdown a bundle's state should not be saved since since the last active state is used.

Returns:
UNKNOWN_STATUS if Oscar is in a bad state, RUNNING_STATUS if Oscar is up and running, STARTING_STATUS if Oscar is in its startup sequence, or STOPPING_STATUS if Oscar is in its shutdown sequence.

isStrictOSGi

public boolean isStrictOSGi()
Returns the framework flag that indicates whether Oscar is strictly adhering to the OSGi specification. If this is false, then Oscar may provides some extended functionality that is not part of the OSGi specification.

Returns:
true if Oscar is in strict mode, false otherwise.

getExportedPackage

protected ExportedPackage getExportedPackage(java.lang.String name)
Returns the exported package associated with the specified package name. This is used by the PackageAdmin service implementation.

Parameters:
name - the name of the exported package to find.
Returns:
the exported package or null if no matching package was found.

getExportedPackages

protected ExportedPackage[] getExportedPackages(Bundle b)
Returns an array of all actively exported packages from the specified bundle or if the specified bundle is null an array containing all actively exported packages by all bundles.

Parameters:
b - the bundle whose exported packages are to be retrieved or null if the exported packages of all bundles are to be retrieved.
Returns:
an array of exported packages.

getImportingBundles

protected Bundle[] getImportingBundles(ExportedPackage ep)

refreshPackages

protected void refreshPackages(Bundle[] targets)

addImport

protected boolean addImport(Module module,
                            java.lang.Object target,
                            java.lang.Object version,
                            boolean force)
This method adds a import target to the IMPORTS_ATTR attribute array associated with the specified module. If the module is already validated, then this method will not add the new import target if it will cause the specified module to become invalidate. It is possible to "force" the method to add the new import target, but doing so might cause module and modules that depend on it to be invalidated.

Parameters:
module - the module whose IMPORTS_ATTR meta-data is to be modified.
target - the target to import.
version - the version of the target to import.
force - indicates whether to force the operation, even in the case where the module will be invalidated.
Returns:
true if the import target was added, false otherwise.

getBundleId

protected long getBundleId(org.ungoverned.oscar.BundleImpl bundle)
Implementation for Bundle.getBundleId().


getBundleHeaders

protected java.util.Dictionary getBundleHeaders(org.ungoverned.oscar.BundleImpl bundle)
Implementation for Bundle.getHeaders().


getBundleLocation

protected java.lang.String getBundleLocation(org.ungoverned.oscar.BundleImpl bundle)
Implementation for Bundle.getLocation().


getBundleResource

protected java.net.URL getBundleResource(org.ungoverned.oscar.BundleImpl bundle,
                                         java.lang.String name)
Implementation for Bundle.getResource().


getBundleRegisteredServices

protected ServiceReference[] getBundleRegisteredServices(org.ungoverned.oscar.BundleImpl bundle)
Implementation for Bundle.getRegisteredServices().


getBundleServicesInUse

protected ServiceReference[] getBundleServicesInUse(org.ungoverned.oscar.BundleImpl bundle)
Implementation for Bundle.getServicesInUse().


getBundleState

protected int getBundleState(org.ungoverned.oscar.BundleImpl bundle)
Implementation for Bundle.getState().


bundleHasPermission

protected boolean bundleHasPermission(org.ungoverned.oscar.BundleImpl bundle,
                                      java.lang.Object obj)
Implementation for Bundle.hasPermission().


startBundle

protected void startBundle(org.ungoverned.oscar.BundleImpl bundle)
                    throws BundleException
Implementation for Bundle.start().

Throws:
BundleException

updateBundle

protected void updateBundle(org.ungoverned.oscar.BundleImpl bundle,
                            java.io.InputStream is)
                     throws BundleException
Implementation for Bundle.update().

Throws:
BundleException

stopBundle

protected void stopBundle(org.ungoverned.oscar.BundleImpl bundle)
                   throws BundleException
Implementation for Bundle.stop().

Throws:
BundleException

uninstallBundle

protected void uninstallBundle(org.ungoverned.oscar.BundleImpl bundle)
                        throws BundleException
Implementation for Bundle.uninstall().

Throws:
BundleException

getProperty

protected java.lang.String getProperty(java.lang.String key)
Implementation for BundleContext.getProperty(). Returns environment property associated with the container.

Parameters:
key - the name of the property to retrieve.
Returns:
the value of the specified property or null.

setProperty

protected void setProperty(java.lang.String key,
                           java.lang.String value)
Set the environment property associated with the container.

Parameters:
key - the name of the property to set.
value - the value of the specified property.

installBundle

protected Bundle installBundle(java.lang.String location,
                               java.io.InputStream is)
                        throws BundleException
Implementation for BundleContext.installBundle(). Installs the bundle associated with the location string, using the specified input stream if is it not null; the input stream will be closed at the end of this method.

Parameters:
location - the location string (URL) for the bundle.
is - input stream from which to read the bundle, can be null.
Returns:
a reference to the installed bundle.
Throws:
BundleException - if any problems are encountered during installation.

getBundle

protected Bundle getBundle(long id)
Implementation for BundleContext.getBundle(). Retrieves a bundle from its identifier.

Parameters:
id - the identifier of the bundle to retrieve.
Returns:
the bundle associated with the identifier or null if there is no bundle associated with the identifier.

getBundles

protected Bundle[] getBundles()
Implementation for BundleContext.getBundles(). Retrieves all installed bundles.

Returns:
an array containing all installed bundles or null if there are no installed bundles.

addBundleListener

protected void addBundleListener(Bundle bundle,
                                 BundleListener l)
Implementation for BundleContext.addBundleListener(). Adds bundle listener to the listener list so that it can listen for BundleEvents.

Parameters:
bundle - the bundle that registered the listener.
l - the bundle listener to add to the listener list.

removeBundleListener

protected void removeBundleListener(BundleListener l)
Implementation for BundleContext.removeBundleListener(). Removes bundle listeners from the listener list.

Parameters:
l - the bundle listener to remove from the listener list.

addServiceListener

protected void addServiceListener(Bundle bundle,
                                  ServiceListener l,
                                  java.lang.String f)
                           throws InvalidSyntaxException
Implementation for BundleContext.addServiceListener(). Adds service listener to the listener list so that is can listen for ServiceEvents.

Parameters:
bundle - the bundle that registered the listener.
l - the service listener to add to the listener list.
f - the filter for the listener; may be null.
Throws:
InvalidSyntaxException

removeServiceListener

protected void removeServiceListener(ServiceListener l)
Implementation for BundleContext.removeServiceListener(). Removes service listeners from the listener list.

Parameters:
l - the service listener to remove from the listener list.

addFrameworkListener

protected void addFrameworkListener(Bundle bundle,
                                    FrameworkListener l)
Implementation for BundleContext.addFrameworkListener(). Adds framework listener to the listener list so that it can listen for FrameworkEvents.

Parameters:
bundle - the bundle that registered the listener.
l - the framework listener to add to the listener list.

removeFrameworkListener

protected void removeFrameworkListener(FrameworkListener l)
Implementation for BundleContext.removeFrameworkListener(). Removes framework listeners from the listener list.

Parameters:
l - the framework listener to remove from the listener list.

registerService

protected ServiceRegistration registerService(org.ungoverned.oscar.BundleImpl bundle,
                                              java.lang.String[] classNames,
                                              java.lang.Object svcObj,
                                              java.util.Dictionary dict)
Implementation for BundleContext.registerService(). Registers a service for the specified bundle bundle.

Parameters:
clazzes - a string array containing the names of the classes under which the new service is available.
svcObj - the service object or ServiceFactory.
dict - a dictionary of properties that further describe the service or null.
Returns:
a ServiceRegistration object or null.

getServiceReferences

protected ServiceReference[] getServiceReferences(java.lang.String className,
                                                  java.lang.String expr)
                                           throws InvalidSyntaxException
Implementation for BundleContext.getServiceReferences().

Throws:
InvalidSyntaxException

getService

protected java.lang.Object getService(org.ungoverned.oscar.BundleImpl bundle,
                                      ServiceReference ref)
Implementation for BundleContext.getService().


ungetService

protected java.lang.Object ungetService(org.ungoverned.oscar.BundleImpl bundle,
                                        ServiceReference ref)
Implementation for BundleContext.ungetService().


getBundleDataFile

protected java.io.File getBundleDataFile(org.ungoverned.oscar.BundleImpl bundle,
                                         java.lang.String name)
                                  throws java.lang.IllegalStateException
Implementation for BundleContext.getDataFile().

Throws:
java.lang.IllegalStateException

resolveBundle

protected void resolveBundle(org.ungoverned.oscar.BundleImpl bundle)
                      throws BundleException
Throws:
BundleException

servicePropertiesModified

protected void servicePropertiesModified(ServiceRegistration reg)
Sets the properties associated with the given service registration.


getUsingBundles

protected Bundle[] getUsingBundles(ServiceReference ref)
Returns the bundles that are using the service referenced by the ServiceReference object. Specifically, this method returns the bundles whose usage count for that service is greater than zero.

Returns:
An array of bundles whose usage count for the service referenced by this ServiceReference object is greater than zero; null if no bundles are currently using that service.

unregisterService

protected void unregisterService(org.ungoverned.oscar.BundleImpl bundle,
                                 org.ungoverned.oscar.ServiceRegistrationImpl reg)
Unregisters a service for the specified bundle.

Parameters:
reg - the service registration for the service to unregister.

unregisterServices

protected void unregisterServices(org.ungoverned.oscar.BundleImpl bundle)
Unregisters all services for the specified bundle.


ungetServices

protected void ungetServices(org.ungoverned.oscar.BundleImpl bundle)
This is a utility method to release all services being used by the specified bundle.

Parameters:
bundle - the bundle whose services are to be released.

initializeSystemProperties

public static void initializeSystemProperties()
Installs all system properties specified in the system property file associated with the Oscar installation; these properties will be accessible through System.getProperty() at run time. By default, the system property file is located in the same directory as the oscar.jar file and is called "system.properties". This may be changed by setting the "oscar.system.properties" system property to an arbitrary absolute path. The properties in this file will overwrite any existing system properties.


setDebug

public static void setDebug(java.io.PrintStream ps)

debug

public static void debug(java.lang.String s)

error

public static void error(java.lang.String s)

error

public static void error(java.lang.String s,
                         java.lang.Throwable th)