org.osgi.service.subsystem
Interface Subsystem

public interface Subsystem

A subsystem is a collection of resources constituting a logical, possibly isolated, unit of functionality.

A subsystem may be scoped or unscoped. Scoped subsystems are isolated by implicit or explicit sharing policies. Unscoped subsystems are not isolated and, therefore, have no sharing policy. There are three standard types of subsystems.

• Application - An implicitly scoped subsystem. Nothing is exported, and imports are computed based on any unsatisfied content requirements.
• Composite - An explicitly scoped subsystem. The sharing policy is defined by metadata within the subsystem archive.
• Feature - An unscoped subsystem.

Conceptually, a subsystem may be thought of as existing in an isolated region along with zero or more other subsystems. Each region has one and only one scoped subsystem, which dictates the sharing policy. The region may, however, have many unscoped subsystems. It is, therefore, possible to have shared constituents across multiple subsystems within a region. Associated with each region is a bundle whose context may be retrieved from any subsystem within that region. This context may be used to monitor activity occurring within the region.

A subsystem may have children and, unless it's the root subsystem, must have at least one parent. Subsystems become children of the subsystem in which they are installed. Unscoped subsystems have more than one parent if they are installed in more than one subsystem within the same region. The subsystem graph may be thought of as an acyclic digraph with one and only one source vertex, which is the root subsystem. The edges have the child as the head and parent as the tail.

A subsystem has several identifiers.

• Location - An identifier specified by the client as part of installation. It is guaranteed to be unique within the same framework.
• ID - An identifier generated by the implementation as part of installation. It is guaranteed to be unique within the same framework.
• Symbolic Name/Version - The combination of symbolic name and version is guaranteed to be unique within the same region. Although type is not formally part of the identity, two subsystems with the same symbolic names and versions but different types are not considered to be equal.

A subsystem has a well-defined life cycle. Which stage a subsystem is in may be obtained from the subsystem's state and is dependent on which life cycle operation is currently active or was last invoked.

A subsystem archive is a ZIP file having an .esa extension and containing metadata describing the subsystem. The form of the metadata may be a subsystem or deployment manifest, as well as any content resource files. The manifests are optional and will be computed if not present. The subsystem manifest headers may be retrieved in raw or localized forms. There are five standard types of resources that may be included in a subsystem.

• Bundle - A bundle that is not a fragment.
• Fragment - A fragment bundle.
• Application Subsystem - An application subsystem.
• Composite Subsystem - A composite subsystem.
• Feature Subsystem - A feature subsystem.

Resources contained by a subsystem are called constituents. There are several ways a resource may become a constituent of a subsystem:

• A resource is listed as part of the subsystem's content.
• A subsystem resource is a child of the subsystem.
• The subsystem has a provision policy of accept dependencies.
• A bundle resource is installed using the region bundle context.
• A bundle resource is installed using the bundle context of another resource contained by the subsystem.

In addition to invoking one of the install methods, a subsystem instance may be obtained through the service registry. Each installed subsystem has a corresponding service registration. A subsystem service has the following properties.

• ID - The ID of the subsystem.
• Symbolic Name - The symbolic name of the subsystem.
• Version - The version of the subsystem.
• Type - The type of the subsystem.
• State - The state of the subsystem.

Because a subsystem must be used to install other subsystems, a root subsystem is provided as a starting point. The root subsystem may only be obtained as a service and has the following characteristics.

• The ID is 0.
• The symbolic name is org.osgi.service.subsystem.root.
• The version matches this specification's version.
• It has no parents.
• All existing bundles, including the system and subsystem implementation bundles, are constituents.
• The type is osgi.subsystem.application with no imports.
• The provision policy is acceptDependencies.

ThreadSafe

Consumers of this API must not implement this interface

Nested Class Summary

static class

Subsystem.State An enumeration of the possible states of a subsystem.

Method Summary

BundleContext	getBundleContext() Returns the bundle context of the region within which this subsystem resides.
java.util.Collection<Subsystem>	getChildren() Returns the child subsystems of this subsystem.
java.util.Collection<Resource>	getConstituents() Returns the constituent resources of this subsystem.
java.lang.String	getLocation() Returns the location identifier of this subsystem.
java.util.Collection<Subsystem>	getParents() Returns the parent subsystems of this subsystem.
Subsystem.State	getState() Returns the current state of this subsystem.
java.util.Map<java.lang.String,java.lang.String>	getSubsystemHeaders(java.util.Locale locale) Returns the headers for this subsystem's subsystem manifest.
long	getSubsystemId() Returns the identifier of this subsystem.
java.lang.String	getSymbolicName() Returns the symbolic name of this subsystem.
java.lang.String	getType() Returns the type of this subsystem.
Version	getVersion() Returns the version of this subsystem.
Subsystem	install(java.lang.String location) Installs a subsystem from the specified location identifier.
Subsystem	install(java.lang.String location, java.io.InputStream content) Installs a subsystem from the specified content.
void	start() Starts this subsystem.
void	stop() Stops this subsystem.
void	uninstall() Uninstalls this subsystem.

Method Detail

getBundleContext

BundleContext getBundleContext()

Returns the bundle context of the region within which this subsystem resides.

The bundle context offers the same perspective of any resource contained by a subsystem within the region. It may be used, for example, to monitor events internal to the region as well as external events visible to the region. All subsystems within the same region have the same bundle context. If this subsystem is in a state where the bundle context would be invalid, null is returned.

Returns:

The bundle context of the region within which this subsystem resides or null if this subsystem's state is in INSTALL_FAILED, UNINSTALLED.

Throws:

java.lang.SecurityException - If the caller does not have the appropriate SubsystemPermission[this,CONTEXT], and the runtime supports permissions.

getChildren

java.util.Collection<Subsystem> getChildren()

Returns the child subsystems of this subsystem.

Returns:

The child subsystems of this subsystem. The returned collection is an unmodifiable snapshot of all subsystems that are installed in this subsystem. The collection will be empty if no subsystems are installed in this subsystem.

Throws:

java.lang.IllegalStateException - If this subsystem's state is in INSTALL_FAILED, UNINSTALLED.

getSubsystemHeaders

java.util.Map<java.lang.String,java.lang.String> getSubsystemHeaders(java.util.Locale locale)

Returns the headers for this subsystem's subsystem manifest.

Each key in the map is a header name and the value of the key is the corresponding header value. Because header names are case-insensitive, the methods of the map must treat the keys in a case-insensitive manner. If the header name is not found, null is returned. Both original and derived headers will be included in the map.

This method must continue to return the headers while this subsystem is in the INSTALL_FAILED or UNINSTALLED states.

Parameters:

locale - The locale for which translations are desired. The header values are translated according to the specified locale. If the specified locale is null or not supported, the raw values are returned. If the translation for a particular header is not found, the raw value is returned.

Returns:

The headers for this subsystem's subsystem manifest. The returned map is unmodifiable.

Throws:

java.lang.SecurityException - If the caller does not have the appropriate SubsystemPermission[this,METADATA], and the runtime supports permissions.

getLocation

java.lang.String getLocation()

Returns the location identifier of this subsystem.

The location identifier is the location that was passed to the install method of the parent subsystem. It is unique within the framework.

This method must continue to return this subsystem's headers while this subsystem is in the INSTALL_FAILED or UNINSTALLED states.

Returns:

The location identifier of this subsystem.

Throws:

java.lang.SecurityException - If the caller does not have the appropriate SubsystemPermission[this,METADATA], and the runtime supports permissions.

getParents

java.util.Collection<Subsystem> getParents()

Returns the parent subsystems of this subsystem.

Returns:

The parent subsystems of this subsystem. The returned collection is an unmodifiable snapshot of all subsystems in which this subsystem is installed. The collection will be empty for the root subsystem; otherwise, it must contain at least one parent. Scoped subsystems always have only one parent. Unscoped subsystems may have multiple parents.

Throws:

java.lang.IllegalStateException - If this subsystem's state is in INSTALL_FAILED, UNINSTALLED.

getConstituents

java.util.Collection<Resource> getConstituents()

Returns the constituent resources of this subsystem.

Returns:

The constituent resources of this subsystem. The returned collection is an unmodifiable snapshot of the constituent resources of this subsystem. If this subsystem has no constituents, the collection will be empty.

Throws:

java.lang.IllegalStateException - If this subsystem's state is in INSTALL_FAILED, UNINSTALLED.

getState

Subsystem.State getState()

Returns the current state of this subsystem.

This method must continue to return this subsystem's state while this subsystem is in the INSTALL_FAILED or UNINSTALLED states.

Returns:

The current state of this subsystem.

getSubsystemId

long getSubsystemId()

Returns the identifier of this subsystem.

The identifier is a monotonically increasing, non-negative integer automatically generated at installation time and guaranteed to be unique within the framework. The identifier of the root subsystem is zero.

This method must continue to return this subsystem's identifier while this subsystem is in the INSTALL_FAILED or UNINSTALLED states.

Returns:

The identifier of this subsystem.

getSymbolicName

java.lang.String getSymbolicName()

Returns the symbolic name of this subsystem.

The subsystem symbolic name conforms to the same grammar rules as the bundle symbolic name and is derived from one of the following, in order.

• The value of the Subsystem-SymbolicName header, if specified.
• The subsystem URI if passed as the location along with the content to the install method.
• Optionally generated in an implementation specific way.

The combination of subsystem symbolic name and version is unique within a region. The symbolic name of the root subsystem is org.osgi.service.subsystem.root.

This method must continue to return this subsystem's symbolic name while this subsystem is in the INSTALL_FAILED or UNINSTALLED states.

Returns:

The symbolic name of this subsystem.

getType

java.lang.String getType()

Returns the type of this subsystem.

This method must continue to return this subsystem's type while this subsystem is in the INSTALL_FAILED or UNINSTALLED states.

Returns:

The type of this subsystem.

getVersion

Version getVersion()

Returns the version of this subsystem.

The subsystem version conforms to the same grammar rules as the bundle version and is derived from one of the following, in order.

• The value of the Subsystem-Version header, if specified.
• The subsystem URI if passed as the location along with the content to the install method.
• Defaults to 0.0.0.

The combination of subsystem symbolic name and version is unique within a region. The version of the root subsystem matches this specification's version.

This method must continue to return this subsystem's version while this subsystem is in the INSTALL_FAILED or UNINSTALLED states.

Returns:

The version of this subsystem.

install

Subsystem install(java.lang.String location)

Installs a subsystem from the specified location identifier.

This method performs the same function as calling install(String, InputStream) with the specified location identifier and null as the content.

Parameters:

location - The location identifier of the subsystem to install.

Returns:

The installed subsystem.

Throws:

java.lang.IllegalStateException - If this subsystem's state is in INSTALLING, INSTALL_FAILED, UNINSTALLING, UNINSTALLED.

SubsystemException - If the installation failed.

java.lang.SecurityException - If the caller does not have the appropriate SubsystemPermission[installed subsystem,LIFECYCLE], and the runtime supports permissions.

See Also:

install(String, InputStream)

install

Subsystem install(java.lang.String location,
                  java.io.InputStream content)

Installs a subsystem from the specified content.

The specified location will be used as an identifier of the subsystem. Every installed subsystem is uniquely identified by its location, which is typically in the form of a URI. If the specified location conforms to the subsystem-uri grammar, the required symbolic name and optional version information will be used as default values.

If the specified content is null, a new input stream must be created from which to read the subsystem by interpreting, in an implementation dependent manner, the specified location.

A subsystem installation must be persistent. That is, an installed subsystem must remain installed across Framework and VM restarts.

All references to changing the state of this subsystem include both changing the state of the subsystem object as well as the state property of the subsystem service registration.

The following steps are required to install a subsystem.

1. If an installed subsystem with the specified location identifier already exists, return the installed subsystem.
2. Read the specified content in order to determine the symbolic name, version, and type of the installing subsystem. If an error occurs while reading the content, an installation failure results.
3. If an installed subsystem with the same symbolic name and version already exists within this subsystem's region, complete the installation with one of the following.
   - If the installing and installed subsystems' types are not equal, an installation failure results.
   - If the installing and installed subsystems' types are equal, and the installed subsystem is already a child of this subsystem, return the installed subsystem.
   - If the installing and installed subsystems' types are equal, and the installed subsystem is not already a child of this subsystem, add the installed subsystem as a child of this subsystem, increment the installed subsystem's reference count by one, and return the installed subsystem.
4. Create a new subsystem based on the specified location and content.
5. If the subsystem is scoped, install and start a new region context bundle.
6. Change the state to INSTALLING and register a new subsystem service.
7. Discover the subsystem's content resources. If any mandatory resource is missing, an installation failure results.
8. Discover the dependencies required by the content resources. If any mandatory dependency is missing, an installation failure results.
9. Using a framework ResolverHook, disable runtime resolution for the resources.
10. For each resource, increment the reference count by one. If the reference count is one, install the resource. If an error occurs while installing a resource, an install failure results with that error as the cause.
11. If the subsystem is scoped, enable the import sharing policy.
12. Enable runtime resolution for the resources.
13. Change the state of the subsystem to INSTALLED.
14. Return the new subsystem.

Implementations should be sensitive to the potential for long running operations and periodically check the current thread for interruption. An interrupted thread should result in a SubsystemException with an InterruptedException as the cause and be treated as an installation failure.

All installation failure flows include the following, in order.

1. Change the state to INSTALL_FAILED.
2. Change the state to UNINSTALLING.
3. All content and dependencies which may have been installed by the installing process must be uninstalled.
4. Change the state to UNINSTALLED.
5. Unregister the subsystem service.
6. If the subsystem is a scoped subsystem then, uninstall the region context bundle.
7. Throw a SubsystemException with the cause of the installation failure.

Parameters:

location - The location identifier of the subsystem to be installed.

content - The input stream from which this subsystem will be read or null to indicate the input stream must be created from the specified location identifier. The input stream will always be closed when this method completes, even if an exception is thrown.

Returns:

The installed subsystem.

Throws:

java.lang.IllegalStateException - If this subsystem's state is in INSTALLING, INSTALL_FAILED, UNINSTALLING, UNINSTALLED.

SubsystemException - If the installation failed.

java.lang.SecurityException - If the caller does not have the appropriate SubsystemPermission[installed subsystem,LIFECYCLE], and the runtime supports permissions.

start

void start()

Starts this subsystem.

The following table shows which actions are associated with each state. An action of Wait means this method will block until a state transition occurs, upon which the new state will be evaluated in order to determine how to proceed. If a state transition does not occur in a reasonable time while waiting then no action is taken and a SubsystemException is thrown to indicate the subsystem was unable to be started. An action of Return means this method returns immediately without taking any other action.

State	Action
INSTALLING	Wait
INSTALLED	Resolve Start
INSTALL_FAILED	IllegalStateException
RESOLVING	Wait
RESOLVED	Start
STARTING	Wait
ACTIVE	Return
STOPPING	Wait
UNINSTALLING	IllegalStateException
UNINSTALLED	IllegalStateException

All references to changing the state of this subsystem include both changing the state of the subsystem object as well as the state property of the subsystem service registration.

A subsystem must be persistently started. That is, a started subsystem must be restarted across Framework and VM restarts, even if a start failure occurs.

The following steps are required to start this subsystem.

1. Set the subsystem autostart setting to started.
2. If this subsystem is in the RESOLVED state, proceed to step 7.
3. Change the state to RESOLVING.
4. Resolve the content resources. A resolution failure results in a start failure with a state of INSTALLED.
5. Change the state to RESOLVED.
6. If this subsystem is scoped, enable the export sharing policy.
7. Change the state to STARTING.
8. For each eligible resource, increment the active use count by one. If the active use count is one, start the resource. All dependencies must be started before any content resource, and content resources must be started according to the specified start order. If an error occurs while starting a resource, a start failure results with that error as the cause.
9. Change the state to ACTIVE.

Implementations should be sensitive to the potential for long running operations and periodically check the current thread for interruption. An interrupted thread should be treated as a start failure with an InterruptedException as the cause.

All start failure flows include the following, in order.

1. If the subsystem state is STARTING then change the state to STOPPING and stop all resources that were started as part of this operation.
2. Change the state to either INSTALLED or RESOLVED.
3. Throw a SubsystemException with the specified cause.

Throws:

SubsystemException - If this subsystem fails to start.

java.lang.IllegalStateException - If this subsystem's state is in INSTALL_FAILED, UNINSTALLING, or UNINSTALLED, or if the state of at least one of this subsystem's parents is not in STARTING, ACTIVE.

java.lang.SecurityException - If the caller does not have the appropriate SubsystemPermission[this,EXECUTE], and the runtime supports permissions.

stop

void stop()

Stops this subsystem.

The following table shows which actions are associated with each state. An action of Wait means this method will block until a state transition occurs, upon which the new state will be evaluated in order to determine how to proceed. If a state transition does not occur in a reasonable time while waiting then no action is taken and a SubsystemException is thrown to indicate the subsystem was unable to be stopped. An action of Return means this method returns immediately without taking any other action.

State	Action
INSTALLING	Wait
INSTALLED	Return
INSTALL_FAILED	IllegalStateException
RESOLVING	Wait
RESOLVED	Return
STARTING	Wait
ACTIVE	Stop
STOPPING	Wait
UNINSTALLING	IllegalStateException
UNINSTALLED	IllegalStateException

A subsystem must be persistently stopped. That is, a stopped subsystem must remain stopped across Framework and VM restarts.

All references to changing the state of this subsystem include both changing the state of the subsystem object as well as the state property of the subsystem service registration.

The following steps are required to stop this subsystem.

1. Set the subsystem autostart setting to stopped.
2. Change the state to STOPPING.
3. For each eligible resource, decrement the active use count by one. If the active use count is zero, stop the resource. All content resources must be stopped before any dependencies, and content resources must be stopped in reverse start order.
4. Change the state to RESOLVED.

With regard to error handling, once this subsystem has transitioned to the STOPPING state, every part of each step above must be attempted. Errors subsequent to the first should be logged. Once the stop process has completed, a SubsystemException must be thrown with the initial error as the specified cause.

Implementations should be sensitive to the potential for long running operations and periodically check the current thread for interruption, in which case a SubsystemException with an InterruptedException as the cause should be thrown. If an interruption occurs while waiting, this method should terminate immediately. Once the transition to the STOPPING state has occurred, however, this method must not terminate due to an interruption until the stop process has completed.

Throws:

SubsystemException - If this subsystem fails to stop cleanly.

java.lang.IllegalStateException - If this subsystem's state is in INSTALL_FAILED, UNINSTALLING, or UNINSTALLED.

java.lang.SecurityException - If the caller does not have the appropriate SubsystemPermission[this,EXECUTE], and the runtime supports permissions.

uninstall

void uninstall()

Uninstalls this subsystem.

The following table shows which actions are associated with each state. An action of Wait means this method will block until a state transition occurs, upon which the new state will be evaluated in order to determine how to proceed. If a state transition does not occur in a reasonable time while waiting then no action is taken and a SubsystemException is thrown to indicate the subsystem was unable to be uninstalled. An action of Return means this method returns immediately without taking any other action.

State	Action
INSTALLING	Wait
INSTALLED	Uninstall
INSTALL_FAILED	Wait
RESOLVING	Wait
RESOLVED	Uninstall
STARTING	Wait
ACTIVE	Stop Uninstall
STOPPING	Wait
UNINSTALLING	Wait
UNINSTALLED	Return

All references to changing the state of this subsystem include both changing the state of the subsystem object as well as the state property of the subsystem service registration.

The following steps are required to uninstall this subsystem after being stopped if necessary.

1. Change the state to INSTALLED.
2. Change the state to UNINSTALLING.
3. For each referenced resource, decrement the reference count by one. If the reference count is zero, uninstall the resource. All content resources must be uninstalled before any dependencies.
4. Change the state to UNINSTALLED.
5. Unregister the subsystem service.
6. If the subsystem is scoped, uninstall the region context bundle.

With regard to error handling, once this subsystem has transitioned to the UNINSTALLING state, every part of each step above must be attempted. Errors subsequent to the first should be logged. Once the uninstall process has completed, a SubsystemException must be thrown with the specified cause.

Implementations should be sensitive to the potential for long running operations and periodically check the current thread for interruption, in which case a SubsystemException with an InterruptedException as the cause should be thrown. If an interruption occurs while waiting, this method should terminate immediately. Once the transition to the UNINSTALLING state has occurred, however, this method must not terminate due to an interruption until the uninstall process has completed.

Throws:

SubsystemException - If this subsystem fails to uninstall cleanly.

java.lang.SecurityException - If the caller does not have the appropriate SubsystemPermission[this,LIFECYCLE], and the runtime supports permissions.