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.