## org.apache.aries.subsystem
Interface AriesSubsystem

All Superinterfaces:
  Subsystem

All Known Implementing Classes:
  BasicSubsystem

    public interface AriesSubsystem

extends Subsystem

Nested Class Summary

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

Method Summary
`void` `addRequirements(Collection<org.osgi.resource.Requirement> requirements)` Adds the specified requirements to this subsystem's sharing policy.
`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.

Methods inherited from interface org.osgi.service.subsystem.Subsystem
`getBundleContext, getChildren, getConstituents, getLocation, getParents, getState, getSubsystemHeaders, getSubsystemId, getSymbolicName, getType, getVersion, start, stop, uninstall`

Method Detail

### addRequirements

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

  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.

  Parameters:
    `requirement` - The requirement to add to the sharing policy.
  Throws:
    `SubsystemException` - If the requirement did not already exist and could not be added.
    `UnsupportedOperationException` - If this is the root subsystem or the type does not support additional requirements.

### install

    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 `Subsystem`
  Parameters:
    `location` - The location identifier of the subsystem to install.
  Returns:
    The installed subsystem.
  See Also:
    `Subsystem.install(String, InputStream)`

### install

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

### install

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

  Installs a subsystem from the specified location identifier and content.

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

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

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