org.eclipse.osgi.launch
Class Equinox

java.lang.Object
  org.eclipse.osgi.launch.Equinox

All Implemented Interfaces:

Bundle, Framework

public class Equinox
extends java.lang.Object
implements Framework

The System Bundle implementation for the Equinox Framework.

Since:

3.5

Field Summary

Fields inherited from interface org.osgi.framework.Bundle

ACTIVE, INSTALLED, RESOLVED, SIGNERS_ALL, SIGNERS_TRUSTED, START_ACTIVATION_POLICY, START_TRANSIENT, STARTING, STOP_TRANSIENT, STOPPING, UNINSTALLED

Constructor Summary

Equinox(java.util.Map configuration)

Method Summary

java.util.Enumeration	findEntries(java.lang.String path, java.lang.String filePattern, boolean recurse) Returns entries in this bundle and its attached fragments.
BundleContext	getBundleContext() Returns this bundle's BundleContext.
long	getBundleId() Returns the Framework unique identifier.
java.net.URL	getEntry(java.lang.String path) Returns a URL to the entry at the specified path in this bundle.
java.util.Enumeration	getEntryPaths(java.lang.String path) Returns an Enumeration of all the paths (String objects) to entries within this bundle whose longest sub-path matches the specified path.
java.util.Dictionary	getHeaders() Returns this bundle's Manifest headers and values.
java.util.Dictionary	getHeaders(java.lang.String locale) Returns this bundle's Manifest headers and values localized to the specified locale.
long	getLastModified() Returns the time when this bundle was last modified.
java.lang.String	getLocation() Returns the Framework location identifier.
ServiceReference[]	getRegisteredServices() Returns this bundle's ServiceReference list for all services it has registered or null if this bundle has no registered services.
java.net.URL	getResource(java.lang.String name) Find the specified resource from this bundle's class loader.
java.util.Enumeration	getResources(java.lang.String name) Find the specified resources from this bundle's class loader.
ServiceReference[]	getServicesInUse() Returns this bundle's ServiceReference list for all services it is using or returns null if this bundle is not using any services.
java.util.Map	getSignerCertificates(int signersType) Return the certificates for the signers of this bundle and the certificate chains for those signers.
int	getState() Returns this bundle's current state.
java.lang.String	getSymbolicName() Returns the symbolic name of this Framework.
Version	getVersion() Returns the version of this bundle as specified by its Bundle-Version manifest header.
boolean	hasPermission(java.lang.Object permission) Determines if this bundle has the specified permissions.
void	init() Initialize this Framework.
java.lang.Class	loadClass(java.lang.String name) Loads the specified class using this bundle's class loader.
void	start() Start this Framework.
void	start(int options) Start this Framework.
void	stop() Stop this Framework.
void	stop(int options) Stop this Framework.
void	uninstall() The Framework cannot be uninstalled.
void	update() Stop and restart this Framework.
void	update(java.io.InputStream in) Stop and restart this Framework.
FrameworkEvent	waitForStop(long timeout) Wait until this Framework has completely stopped.

Methods inherited from class java.lang.Object

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

Constructor Detail

Equinox

public Equinox(java.util.Map configuration)

Method Detail

init

public void init()
          throws BundleException

Description copied from interface: Framework

Initialize this Framework. After calling this method, this Framework must:

• Be in the Bundle.STARTING state.
• Have a valid Bundle Context.
• Be at start level 0.
• Have event handling enabled.
• Have reified Bundle objects for all installed bundles.
• Have registered any framework services. For example, PackageAdmin, ConditionalPermissionAdmin, StartLevel.

This Framework will not actually be started until start is called.

This method does nothing if called when this Framework is in the Bundle.STARTING, Bundle.ACTIVE or Bundle.STOPPING states.

Specified by:

init in interface Framework

Throws:

BundleException - If this Framework could not be initialized.

waitForStop

public FrameworkEvent waitForStop(long timeout)
                           throws java.lang.InterruptedException

Description copied from interface: Framework

Wait until this Framework has completely stopped. The stop and update methods on a Framework performs an asynchronous stop of the Framework. This method can be used to wait until the asynchronous stop of this Framework has completed. This method will only wait if called when this Framework is in the Bundle.STARTING, Bundle.ACTIVE, or Bundle.STOPPING states. Otherwise it will return immediately.

A Framework Event is returned to indicate why this Framework has stopped.

Specified by:

waitForStop in interface Framework

Parameters:

timeout - Maximum number of milliseconds to wait until this Framework has completely stopped. A value of zero will wait indefinitely.

Returns:

A Framework Event indicating the reason this method returned. The following FrameworkEvent types may be returned by this method.

• STOPPED - This Framework has been stopped.
• STOPPED_UPDATE - This Framework has been updated which has shutdown and will now restart.
• STOPPED_BOOTCLASSPATH_MODIFIED - This Framework has been stopped and a bootclasspath extension bundle has been installed or updated. The VM must be restarted in order for the changed boot class path to take affect.
• ERROR - The Framework encountered an error while shutting down or an error has occurred which forced the framework to shutdown.
• WAIT_TIMEDOUT - This method has timed out and returned before this Framework has stopped.

Throws:

java.lang.InterruptedException - If another thread interrupted the current thread before or while the current thread was waiting for this Framework to completely stop. The interrupted status of the current thread is cleared when this exception is thrown.

findEntries

public java.util.Enumeration findEntries(java.lang.String path,
                                         java.lang.String filePattern,
                                         boolean recurse)

Description copied from interface: Bundle

Returns entries in this bundle and its attached fragments. This bundle's class loader is not used to search for entries. Only the contents of this bundle and its attached fragments are searched for the specified entries. If this bundle's state is INSTALLED, this method must attempt to resolve this bundle before attempting to find entries.

This method is intended to be used to obtain configuration, setup, localization and other information from this bundle. This method takes into account that the "contents" of this bundle can be extended with fragments. This "bundle space" is not a namespace with unique members; the same entry name can be present multiple times. This method therefore returns an enumeration of URL objects. These URLs can come from different JARs but have the same path name. This method can either return only entries in the specified path or recurse into subdirectories returning entries in the directory tree beginning at the specified path. Fragments can be attached after this bundle is resolved, possibly changing the set of URLs returned by this method. If this bundle is not resolved, only the entries in the JAR file of this bundle are returned.

Examples:

 // List all XML files in the OSGI-INF directory and below
 Enumeration e = b.findEntries("OSGI-INF", "*.xml", true);
 
 // Find a specific localization file
 Enumeration e = b
                .findEntries("OSGI-INF/l10n", "bundle_nl_DU.properties", false);
 if (e.hasMoreElements())
        return (URL) e.nextElement();
 

Note: Jar and zip files are not required to include directory entries. URLs to directory entries will not be returned if the bundle contents do not contain directory entries.

Specified by:

findEntries in interface Bundle

Parameters:

path - The path name in which to look. The path is always relative to the root of this bundle and may begin with "/". A path value of "/" indicates the root of this bundle.

filePattern - The file name pattern for selecting entries in the specified path. The pattern is only matched against the last element of the entry path. If the entry is a directory then the trailing "/" is not used for pattern matching. Substring matching is supported, as specified in the Filter specification, using the wildcard character ("*"). If null is specified, this is equivalent to "*" and matches all files.

recurse - If true, recurse into subdirectories. Otherwise only return entries from the specified path.

Returns:

An enumeration of URL objects for each matching entry, or null if an entry could not be found or if the caller does not have the appropriate AdminPermission[this,RESOURCE], and the Java Runtime Environment supports permissions. The URLs are sorted such that entries from this bundle are returned first followed by the entries from attached fragments in ascending bundle id order. If this bundle is a fragment, then only matching entries in this fragment are returned.

getBundleContext

public BundleContext getBundleContext()

Description copied from interface: Bundle

Returns this bundle's BundleContext. The returned BundleContext can be used by the caller to act on behalf of this bundle.

If this bundle is not in the Bundle.STARTING, Bundle.ACTIVE, or Bundle.STOPPING states or this bundle is a fragment bundle, then this bundle has no valid BundleContext. This method will return null if this bundle has no valid BundleContext.

Specified by:

getBundleContext in interface Bundle

Returns:

A BundleContext for this bundle or null if this bundle has no valid BundleContext.

getBundleId

public long getBundleId()

Description copied from interface: Framework

Returns the Framework unique identifier. This Framework is assigned the unique identifier zero (0) since this Framework is also a System Bundle.

Specified by:

getBundleId in interface Bundle

Specified by:

getBundleId in interface Framework

Returns:

0.

See Also:

Bundle.getBundleId()

getEntry

public java.net.URL getEntry(java.lang.String path)

Description copied from interface: Bundle

Returns a URL to the entry at the specified path in this bundle. This bundle's class loader is not used to search for the entry. Only the contents of this bundle are searched for the entry.

The specified path is always relative to the root of this bundle and may begin with "/". A path value of "/" indicates the root of this bundle.

Note: Jar and zip files are not required to include directory entries. URLs to directory entries will not be returned if the bundle contents do not contain directory entries.

Specified by:

getEntry in interface Bundle

Parameters:

path - The path name of the entry.

Returns:

A URL to the entry, or null if no entry could be found or if the caller does not have the appropriate AdminPermission[this,RESOURCE] and the Java Runtime Environment supports permissions.

getEntryPaths

public java.util.Enumeration getEntryPaths(java.lang.String path)

Description copied from interface: Bundle

Returns an Enumeration of all the paths (String objects) to entries within this bundle whose longest sub-path matches the specified path. This bundle's class loader is not used to search for entries. Only the contents of this bundle are searched.

The specified path is always relative to the root of this bundle and may begin with a "/". A path value of "/" indicates the root of this bundle.

Returned paths indicating subdirectory paths end with a "/". The returned paths are all relative to the root of this bundle and must not begin with "/".

Note: Jar and zip files are not required to include directory entries. Paths to directory entries will not be returned if the bundle contents do not contain directory entries.

Specified by:

getEntryPaths in interface Bundle

Parameters:

path - The path name for which to return entry paths.

Returns:

An Enumeration of the entry paths (String objects) or null if no entry could be found or if the caller does not have the appropriate AdminPermission[this,RESOURCE] and the Java Runtime Environment supports permissions.

getHeaders

public java.util.Dictionary getHeaders()

Description copied from interface: Bundle

Returns this bundle's Manifest headers and values. This method returns all the Manifest headers and values from the main section of this bundle's Manifest file; that is, all lines prior to the first blank line.

Manifest header names are case-insensitive. The methods of the returned Dictionary object must operate on header names in a case-insensitive manner. If a Manifest header value starts with "%", it must be localized according to the default locale. If no localization is found for a header value, the header value without the leading "%" is returned.

For example, the following Manifest headers and values are included if they are present in the Manifest file:

     Bundle-Name
     Bundle-Vendor
     Bundle-Version
     Bundle-Description
     Bundle-DocURL
     Bundle-ContactAddress
 

This method must continue to return Manifest header information while this bundle is in the UNINSTALLED state.

Specified by:

getHeaders in interface Bundle

Returns:

A Dictionary object containing this bundle's Manifest headers and values.

See Also:

Constants.BUNDLE_LOCALIZATION

getHeaders

public java.util.Dictionary getHeaders(java.lang.String locale)

Description copied from interface: Bundle

Returns this bundle's Manifest headers and values localized to the specified locale.

This method performs the same function as Bundle.getHeaders() except the manifest header values are localized to the specified locale.

If a Manifest header value starts with "%", it must be localized according to the specified locale. If a locale is specified and cannot be found, then the header values must be returned using the default locale. Localizations are searched for in the following order:

   bn + "_" + Ls + "_" + Cs + "_" + Vs
   bn + "_" + Ls + "_" + Cs
   bn + "_" + Ls
   bn + "_" + Ld + "_" + Cd + "_" + Vd
   bn + "_" + Ld + "_" + Cd
   bn + "_" + Ld
   bn
 

Where bn is this bundle's localization basename, Ls, Cs and Vs are the specified locale (language, country, variant) and Ld, Cd and Vd are the default locale (language, country, variant). If null is specified as the locale string, the header values must be localized using the default locale. If the empty string ("") is specified as the locale string, the header values must not be localized and the raw (unlocalized) header values, including any leading "%", must be returned. If no localization is found for a header value, the header value without the leading "%" is returned.

This method must continue to return Manifest header information while this bundle is in the UNINSTALLED state, however the header values must only be available in the raw and default locale values.

Specified by:

getHeaders in interface Bundle

Parameters:

locale - The locale name into which the header values are to be localized. If the specified locale is null then the locale returned by java.util.Locale.getDefault is used. If the specified locale is the empty string, this method will return the raw (unlocalized) manifest headers including any leading "%".

Returns:

A Dictionary object containing this bundle's Manifest headers and values.

See Also:

Bundle.getHeaders(), Constants.BUNDLE_LOCALIZATION

getLastModified

public long getLastModified()

Description copied from interface: Bundle

Returns the time when this bundle was last modified. A bundle is considered to be modified when it is installed, updated or uninstalled.

The time value is the number of milliseconds since January 1, 1970, 00:00:00 GMT.

Specified by:

getLastModified in interface Bundle

Returns:

The time when this bundle was last modified.

getLocation

public java.lang.String getLocation()

Description copied from interface: Framework

Returns the Framework location identifier. This Framework is assigned the unique location "System Bundle" since this Framework is also a System Bundle.

Specified by:

getLocation in interface Bundle

Specified by:

getLocation in interface Framework

Returns:

The string "System Bundle".

See Also:

Bundle.getLocation(), Constants.SYSTEM_BUNDLE_LOCATION

getRegisteredServices

public ServiceReference[] getRegisteredServices()

Description copied from interface: Bundle

Returns this bundle's ServiceReference list for all services it has registered or null if this bundle has no registered services.

If the Java runtime supports permissions, a ServiceReference object to a service is included in the returned list only if the caller has the ServicePermission to get the service using at least one of the named classes the service was registered under.

The list is valid at the time of the call to this method, however, as the Framework is a very dynamic environment, services can be modified or unregistered at anytime.

Specified by:

getRegisteredServices in interface Bundle

Returns:

An array of ServiceReference objects or null.

See Also:

ServiceRegistration, ServiceReference, ServicePermission

getResource

public java.net.URL getResource(java.lang.String name)

Description copied from interface: Bundle

Find the specified resource from this bundle's class loader. This bundle's class loader is called to search for the specified resource. If this bundle's state is INSTALLED, this method must attempt to resolve this bundle before attempting to get the specified resource. If this bundle cannot be resolved, then only this bundle must be searched for the specified resource. Imported packages cannot be searched when this bundle has not been resolved. If this bundle is a fragment bundle then null is returned.

Note: Jar and zip files are not required to include directory entries. URLs to directory entries will not be returned if the bundle contents do not contain directory entries.

Specified by:

getResource in interface Bundle

Parameters:

name - The name of the resource. See ClassLoader.getResource for a description of the format of a resource name.

Returns:

A URL to the named resource, or null if the resource could not be found or if this bundle is a fragment bundle or if the caller does not have the appropriate AdminPermission[this,RESOURCE], and the Java Runtime Environment supports permissions.

See Also:

Bundle.getEntry(java.lang.String), Bundle.findEntries(java.lang.String, java.lang.String, boolean)

getResources

public java.util.Enumeration getResources(java.lang.String name)
                                   throws java.io.IOException

Description copied from interface: Bundle

Find the specified resources from this bundle's class loader. This bundle's class loader is called to search for the specified resources. If this bundle's state is INSTALLED, this method must attempt to resolve this bundle before attempting to get the specified resources. If this bundle cannot be resolved, then only this bundle must be searched for the specified resources. Imported packages cannot be searched when a bundle has not been resolved. If this bundle is a fragment bundle then null is returned.

Note: Jar and zip files are not required to include directory entries. URLs to directory entries will not be returned if the bundle contents do not contain directory entries.

Specified by:

getResources in interface Bundle

Parameters:

name - The name of the resource. See ClassLoader.getResources for a description of the format of a resource name.

Returns:

An enumeration of URLs to the named resources, or null if the resource could not be found or if this bundle is a fragment bundle or if the caller does not have the appropriate AdminPermission[this,RESOURCE], and the Java Runtime Environment supports permissions.

Throws:

java.io.IOException - If there is an I/O error.

getServicesInUse

public ServiceReference[] getServicesInUse()

Description copied from interface: Bundle

Returns this bundle's ServiceReference list for all services it is using or returns null if this bundle is not using any services. A bundle is considered to be using a service if its use count for that service is greater than zero.

If the Java Runtime Environment supports permissions, a ServiceReference object to a service is included in the returned list only if the caller has the ServicePermission to get the service using at least one of the named classes the service was registered under.

The list is valid at the time of the call to this method, however, as the Framework is a very dynamic environment, services can be modified or unregistered at anytime.

Specified by:

getServicesInUse in interface Bundle

Returns:

An array of ServiceReference objects or null.

See Also:

ServiceReference, ServicePermission

getState

public int getState()

Description copied from interface: Bundle

Returns this bundle's current state.

A bundle can be in only one state at any time.

Specified by:

getState in interface Bundle

Returns:

An element of UNINSTALLED,INSTALLED, RESOLVED,STARTING, STOPPING,ACTIVE.

getSymbolicName

public java.lang.String getSymbolicName()

Description copied from interface: Framework

Returns the symbolic name of this Framework. The symbolic name is unique for the implementation of the framework. However, the symbolic name "system.bundle" must be recognized as an alias to the implementation-defined symbolic name since this Framework is also a System Bundle.

Specified by:

getSymbolicName in interface Bundle

Specified by:

getSymbolicName in interface Framework

Returns:

The symbolic name of this Framework.

See Also:

Bundle.getSymbolicName(), Constants.SYSTEM_BUNDLE_SYMBOLICNAME

hasPermission

public boolean hasPermission(java.lang.Object permission)

Description copied from interface: Bundle

Determines if this bundle has the specified permissions.

If the Java Runtime Environment does not support permissions, this method always returns true.

permission is of type Object to avoid referencing the java.security.Permission class directly. This is to allow the Framework to be implemented in Java environments which do not support permissions.

If the Java Runtime Environment does support permissions, this bundle and all its resources including embedded JAR files, belong to the same java.security.ProtectionDomain; that is, they must share the same set of permissions.

Specified by:

hasPermission in interface Bundle

Parameters:

permission - The permission to verify.

Returns:

true if this bundle has the specified permission or the permissions possessed by this bundle imply the specified permission; false if this bundle does not have the specified permission or permission is not an instanceof java.security.Permission.

loadClass

public java.lang.Class loadClass(java.lang.String name)
                          throws java.lang.ClassNotFoundException

Description copied from interface: Bundle

Loads the specified class using this bundle's class loader.

If this bundle is a fragment bundle then this method must throw a ClassNotFoundException.

If this bundle's state is INSTALLED, this method must attempt to resolve this bundle before attempting to load the class.

If this bundle cannot be resolved, a Framework event of type FrameworkEvent.ERROR is fired containing a BundleException with details of the reason this bundle could not be resolved. This method must then throw a ClassNotFoundException.

If this bundle's state is UNINSTALLED, then an IllegalStateException is thrown.

Specified by:

loadClass in interface Bundle

Parameters:

name - The name of the class to load.

Returns:

The Class object for the requested class.

Throws:

java.lang.ClassNotFoundException - If no such class can be found or if this bundle is a fragment bundle or if the caller does not have the appropriate AdminPermission[this,CLASS], and the Java Runtime Environment supports permissions.

start

public void start(int options)
           throws BundleException

Description copied from interface: Framework

Start this Framework.

Calling this method is the same as calling Framework.start(). There are no start options for the Framework.

Specified by:

start in interface Bundle

Specified by:

start in interface Framework

Parameters:

options - Ignored. There are no start options for the Framework.

Throws:

BundleException - If this Framework could not be started.

See Also:

Framework.start()

start

public void start()
           throws BundleException

Description copied from interface: Framework

Start this Framework.

The following steps are taken to start this Framework:

1. If this Framework is not in the Bundle.STARTING state, initialize this Framework.
2. All installed bundles must be started in accordance with each bundle's persistent autostart setting. This means some bundles will not be started, some will be started with eager activation and some will be started with their declared activation policy. If this Framework implements the optional Start Level Service Specification, then the start level of this Framework is moved to the start level specified by the beginning start level framework property, as described in the Start Level Service Specification. If this framework property is not specified, then the start level of this Framework is moved to start level one (1). Any exceptions that occur during bundle starting must be wrapped in a BundleException and then published as a framework event of type FrameworkEvent.ERROR
3. This Framework's state is set to Bundle.ACTIVE.
4. A framework event of type FrameworkEvent.STARTED is fired

Specified by:

start in interface Bundle

Specified by:

start in interface Framework

Throws:

BundleException - If this Framework could not be started.

See Also:

"Start Level Service Specification"

stop

public void stop(int options)
          throws BundleException

Description copied from interface: Framework

Stop this Framework.

Calling this method is the same as calling Framework.stop(). There are no stop options for the Framework.

Specified by:

stop in interface Bundle

Specified by:

stop in interface Framework

Parameters:

options - Ignored. There are no stop options for the Framework.

Throws:

BundleException - If stopping this Framework could not be initiated.

See Also:

Framework.stop()

stop

public void stop()
          throws BundleException

Description copied from interface: Framework

Stop this Framework.

The method returns immediately to the caller after initiating the following steps to be taken on another thread.

1. This Framework's state is set to Bundle.STOPPING.
2. All installed bundles must be stopped without changing each bundle's persistent autostart setting. If this Framework implements the optional Start Level Service Specification, then the start level of this Framework is moved to start level zero (0), as described in the Start Level Service Specification. Any exceptions that occur during bundle stopping must be wrapped in a BundleException and then published as a framework event of type FrameworkEvent.ERROR
3. Unregister all services registered by this Framework.
4. Event handling is disabled.
5. This Framework's state is set to Bundle.RESOLVED.
6. All resources held by this Framework are released. This includes threads, bundle class loaders, open files, etc.
7. Notify all threads that are waiting at waitForStop that the stop operation has completed.

After being stopped, this Framework may be discarded, initialized or started.

Specified by:

stop in interface Bundle

Specified by:

stop in interface Framework

Throws:

BundleException - If stopping this Framework could not be initiated.

See Also:

"Start Level Service Specification"

uninstall

public void uninstall()
               throws BundleException

Description copied from interface: Framework

The Framework cannot be uninstalled.

This method always throws a BundleException.

Specified by:

uninstall in interface Bundle

Specified by:

uninstall in interface Framework

Throws:

BundleException - This Framework cannot be uninstalled.

See Also:

Bundle.stop()

update

public void update()
            throws BundleException

Description copied from interface: Framework

Stop and restart this Framework.

The method returns immediately to the caller after initiating the following steps to be taken on another thread.

1. Perform the steps in the Framework.stop() method to stop this Framework.
2. Perform the steps in the Framework.start() method to start this Framework.

Specified by:

update in interface Bundle

Specified by:

update in interface Framework

Throws:

BundleException - If stopping and restarting this Framework could not be initiated.

See Also:

Bundle.update(InputStream)

update

public void update(java.io.InputStream in)
            throws BundleException

Description copied from interface: Framework

Stop and restart this Framework.

Calling this method is the same as calling Framework.update() except that any provided InputStream is immediately closed.

Specified by:

update in interface Bundle

Specified by:

update in interface Framework

Parameters:

in - Any provided InputStream is immediately closed before returning from this method and otherwise ignored.

Throws:

BundleException - If stopping and restarting this Framework could not be initiated.

See Also:

Bundle.stop(), Bundle.start()

getSignerCertificates

public java.util.Map getSignerCertificates(int signersType)

Description copied from interface: Bundle

Return the certificates for the signers of this bundle and the certificate chains for those signers.

Specified by:

getSignerCertificates in interface Bundle

Parameters:

signersType - If Bundle.SIGNERS_ALL is specified, then information on all signers of this bundle is returned. If Bundle.SIGNERS_TRUSTED is specified, then only information on the signers of this bundle trusted by the framework is returned.

Returns:

The X509Certificates for the signers of this bundle and the X509Certificate chains for those signers. The keys of the Map are the X509Certificates of the signers of this bundle. The value for a key is a List containing the X509Certificate chain for the signer. The first item in the List is the signer's X509Certificate which is then followed by the rest of the X509Certificate chain. The returned Map will be empty if there are no signers. The returned Map is the property of the caller who is free to modify it.

getVersion

public Version getVersion()

Description copied from interface: Bundle

Returns the version of this bundle as specified by its Bundle-Version manifest header. If this bundle does not have a specified version then Version.emptyVersion is returned.

This method must continue to return this bundle's version while this bundle is in the UNINSTALLED state.

Specified by:

getVersion in interface Bundle

Returns:

The version of this bundle.