## org.apache.aries.subsystem.core.internal
Class BasicSubsystem

    java.lang.Object
      org.apache.aries.subsystem.core.internal.BasicSubsystem

All Implemented Interfaces:
  AriesSubsystem, org.osgi.resource.Resource, Subsystem

    public class BasicSubsystem

extends Object
implements org.osgi.resource.Resource, AriesSubsystem

Nested Class Summary

Nested classes/interfaces inherited from interface org.osgi.service.subsystem.Subsystem
`Subsystem.State`

Field Summary
`static String` `ROOT_LOCATION`
`static String` `ROOT_SYMBOLIC_NAME`
`static org.osgi.framework.Version` `ROOT_VERSION`

Constructor Summary
`BasicSubsystem(File file)`
`BasicSubsystem(org.apache.aries.util.filesystem.IDirectory directory)`
`BasicSubsystem(SubsystemResource resource)`

Method Summary
`void` `addRequirements(Collection<org.osgi.resource.Requirement> requirements)` Adds the specified requirements to this subsystem's sharing policy.
`boolean` `equals(Object o)`
`org.osgi.framework.BundleContext` `getBundleContext()` Returns the bundle context of the region within which this subsystem resides.
`List<org.osgi.resource.Capability>` `getCapabilities(String namespace)`
`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.
`List<org.osgi.resource.Requirement>` `getRequirements(String namespace)`
`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.
`int` `hashCode()`
`AriesSubsystem` `install(String location)` Installs a subsystem from the specified location identifier.
`AriesSubsystem` `install(String location, org.apache.aries.util.filesystem.IDirectory content)` Installs a subsystem from the specified location identifier and content.
`AriesSubsystem` `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.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### ROOT_SYMBOLIC_NAME

    public static final String ROOT_SYMBOLIC_NAME

See Also:
  Constant Field Values

### ROOT_VERSION

    public static final org.osgi.framework.Version ROOT_VERSION

### ROOT_LOCATION

    public static final String ROOT_LOCATION

Constructor Detail

### BasicSubsystem

    public BasicSubsystem(SubsystemResource resource)
                   throws URISyntaxException,
                          IOException,
                          org.osgi.framework.BundleException,
                          org.osgi.framework.InvalidSyntaxException

Throws:
  `URISyntaxException`
  `IOException`
  `org.osgi.framework.BundleException`
  `org.osgi.framework.InvalidSyntaxException`

### BasicSubsystem

    public BasicSubsystem(File file)
                   throws IOException,
                          URISyntaxException,
                          org.osgi.service.resolver.ResolutionException

Throws:
  `IOException`
  `URISyntaxException`
  `org.osgi.service.resolver.ResolutionException`

### BasicSubsystem

    public BasicSubsystem(org.apache.aries.util.filesystem.IDirectory directory)
                   throws IOException,
                          URISyntaxException,
                          org.osgi.service.resolver.ResolutionException

Throws:
  `IOException`
  `URISyntaxException`
  `org.osgi.service.resolver.ResolutionException`

Method Detail

### equals

    public boolean equals(Object o)

  Specified by:
    `equals` in interface `org.osgi.resource.Resource`
  Overrides:
    `equals` in class `Object`

### getCapabilities

    public List<org.osgi.resource.Capability> getCapabilities(String namespace)

  Specified by:
    `getCapabilities` in interface `org.osgi.resource.Resource`

### getRequirements

    public List<org.osgi.resource.Requirement> getRequirements(String namespace)

  Specified by:
    `getRequirements` in interface `org.osgi.resource.Resource`

### hashCode

    public int hashCode()

  Specified by:
    `hashCode` in interface `org.osgi.resource.Resource`
  Overrides:
    `hashCode` in class `Object`

### getBundleContext

    public org.osgi.framework.BundleContext getBundleContext()

  Description copied from interface: `Subsystem`
  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.

  Specified by:
    `getBundleContext` in interface `Subsystem`
  Returns:
    The bundle context of the region within which this subsystem resides or `null` if this subsystem's state is in `INSTALL_FAILED`, `UNINSTALLED`.

### getChildren

    public Collection<Subsystem> getChildren()

  Description copied from interface: `Subsystem`
  Returns the child subsystems of this subsystem.

  Specified by:
    `getChildren` in interface `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.

### getSubsystemHeaders

    public Map<String,String> getSubsystemHeaders(Locale locale)

  Description copied from interface: `Subsystem`
  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.

  Specified by:
    `getSubsystemHeaders` in interface `Subsystem`
  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.

### getLocation

    public String getLocation()

  Description copied from interface: `Subsystem`
  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.

  Specified by:
    `getLocation` in interface `Subsystem`
  Returns:
    The location identifier of this subsystem.

### getParents

    public Collection<Subsystem> getParents()

  Description copied from interface: `Subsystem`
  Returns the parent subsystems of this subsystem.

  Specified by:
    `getParents` in interface `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.

### getConstituents

    public Collection<org.osgi.resource.Resource> getConstituents()

  Description copied from interface: `Subsystem`
  Returns the constituent resources of this subsystem.

  Specified by:
    `getConstituents` in interface `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.

### getState

    public Subsystem.State getState()

  Description copied from interface: `Subsystem`
  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.

  Specified by:
    `getState` in interface `Subsystem`
  Returns:
    The current state of this subsystem.

### getSubsystemId

    public long getSubsystemId()

  Description copied from interface: `Subsystem`
  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.

  Specified by:
    `getSubsystemId` in interface `Subsystem`
  Returns:
    The identifier of this subsystem.

### getSymbolicName

    public String getSymbolicName()

  Description copied from interface: `Subsystem`
  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.

  Specified by:
    `getSymbolicName` in interface `Subsystem`
  Returns:
    The symbolic name of this subsystem.

### getType

    public String getType()

  Description copied from interface: `Subsystem`
  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.

  Specified by:
    `getType` in interface `Subsystem`
  Returns:
    The type of this subsystem.

### getVersion

    public org.osgi.framework.Version getVersion()

  Description copied from interface: `Subsystem`
  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.

  Specified by:
    `getVersion` in interface `Subsystem`
  Returns:
    The version of this subsystem.

### install

    public AriesSubsystem install(String location)

  Description copied from interface: `Subsystem`
  Installs a subsystem from the specified location identifier.

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

  Specified by:
    `install` in interface `AriesSubsystem`
  Specified by:
    `install` in interface `Subsystem`
  Parameters:
    `location` - The location identifier of the subsystem to install.
  Returns:
    The installed subsystem.
  See Also:
    `Subsystem.install(String, InputStream)`

### install

    public AriesSubsystem install(String location,
                                  InputStream content)

  Description copied from interface: `Subsystem`
  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.

  Specified by:
    `install` in interface `AriesSubsystem`
  Specified by:
    `install` in interface `Subsystem`
  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.

### start

    public void start()

  Description copied from interface: `Subsystem`
  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.

  Specified by:
    `start` in interface `Subsystem`

### stop

    public void stop()

  Description copied from interface: `Subsystem`
  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.

  Specified by:
    `stop` in interface `Subsystem`

### uninstall

    public void uninstall()

  Description copied from interface: `Subsystem`
  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.

  Specified by:
    `uninstall` in interface `Subsystem`

### addRequirements

    public void addRequirements(Collection<org.osgi.resource.Requirement> requirements)

  Description copied from interface: `AriesSubsystem`
  Adds the specified requirements to this subsystem's sharing policy.

  The sharing policy of this subsystem's region is updated with the specified requirements (i.e. imports). Requirements already part of the sharing policy are ignored. Upon return, constituents of this subsystem will be allowed to resolve against matching capabilities that are visible to the parent subsystems.

  Specified by:
    `addRequirements` in interface `AriesSubsystem`

### install

    public AriesSubsystem install(String location,
                                  org.apache.aries.util.filesystem.IDirectory content)

  Description copied from interface: `AriesSubsystem`
  Installs a subsystem from the specified location identifier and content.

  This method performs the same function as calling `AriesSubsystem.install(String, InputStream)` except the content is retrieved from the specified `IDirectory` instead.

  Specified by:
    `install` in interface `AriesSubsystem`
  Parameters:
    `location` - The location identifier of the subsystem to install.
    `content` - The directory from which this subsystem will be read or `null` to indicate the directory must be created from the specified location identifier.
  Returns:
    The installed subsystem.
  See Also:
    `AriesSubsystem.install(String, InputStream)`

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