## org.osgi.service.subsystem
Interface Subsystem

All Known Subinterfaces:
  AriesSubsystem

    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`.

Version:
  $Id: 73028a6997272cbac7e90ae00eb0f28afd14c8ee $

Nested Class Summary
`static class` `Subsystem.State` An enumeration of the possible states of a subsystem.

Method Summary
`org.osgi.framework.BundleContext` `getBundleContext()` Returns the bundle context of the region within which this subsystem resides.
`Collection<Subsystem>` `getChildren()` Returns the child subsystems of this subsystem.
`Collection<org.osgi.resource.Resource>` `getConstituents()` Returns the constituent resources of this subsystem.
`String` `getLocation()` Returns the location identifier of this subsystem.
`Collection<Subsystem>` `getParents()` Returns the parent subsystems of this subsystem.
`Subsystem.State` `getState()` Returns the current state of this subsystem.
`Map<String,String>` `getSubsystemHeaders(Locale locale)` Returns the headers for this subsystem's subsystem manifest.
`long` `getSubsystemId()` Returns the identifier of this subsystem.
`String` `getSymbolicName()` Returns the symbolic name of this subsystem.
`String` `getType()` Returns the `type` of this subsystem.
`org.osgi.framework.Version` `getVersion()` Returns the `version` of this subsystem.
`Subsystem` `install(String location)` Installs a subsystem from the specified location identifier.
`Subsystem` `install(String location, 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

    org.osgi.framework.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:
    `SecurityException` - If the caller does not have the appropriate `SubsystemPermission`[this,CONTEXT], and the runtime supports permissions.

### getChildren

    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:
    `IllegalStateException` - If this subsystem's state is in `INSTALL_FAILED`, `UNINSTALLED`.

### getSubsystemHeaders

    Map<String,String> getSubsystemHeaders(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:
    `SecurityException` - If the caller does not have the appropriate `SubsystemPermission`[this,METADATA], and the runtime supports permissions.

### getLocation

    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:
    `SecurityException` - If the caller does not have the appropriate `SubsystemPermission`[this,METADATA], and the runtime supports permissions.

### getParents

    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:
    `IllegalStateException` - If this subsystem's state is in `INSTALL_FAILED`, `UNINSTALLED`.

### getConstituents

    Collection<org.osgi.resource.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:
    `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

    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

    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

    org.osgi.framework.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(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:
    `IllegalStateException` - If this subsystem's state is in `INSTALLING`, `INSTALL_FAILED`, `UNINSTALLING`, `UNINSTALLED`.
    `SubsystemException` - If the installation failed.
    `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(String location,
                      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:
    `IllegalStateException` - If this subsystem's state is in `INSTALLING`, `INSTALL_FAILED`, `UNINSTALLING`, `UNINSTALLED`.
    `SubsystemException` - If the installation failed.
    `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.
    `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`.
    `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.
    `IllegalStateException` - If this subsystem's state is in `INSTALL_FAILED`, `UNINSTALLING`, or `UNINSTALLED`.
    `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.
    `SecurityException` - If the caller does not have the appropriate `SubsystemPermission`[this,LIFECYCLE], and the runtime supports permissions.

Copyright © 2009-2013 The Apache Software Foundation. All Rights Reserved.