org.apache.aries.subsystem

Interface AriesSubsystem

All Superinterfaces:

Subsystem

public interface AriesSubsystem
extends Subsystem

Nested Class Summary

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

Subsystem.State

Method Summary

Methods

Modifier and Type	Method and Description
void	addRequirements(java.util.Collection<org.osgi.resource.Requirement> requirements) Adds the specified requirements to this subsystem's sharing policy.
AriesSubsystem	install(java.lang.String location) Installs a subsystem from the specified location identifier.
AriesSubsystem	install(java.lang.String location, org.apache.aries.util.filesystem.IDirectory content) Installs a subsystem from the specified location identifier and content.
AriesSubsystem	install(java.lang.String location, org.apache.aries.util.filesystem.IDirectory content, java.io.InputStream deploymentManifest) Installs a subsystem from the specified location identifier and content but uses the provided deployment manifest, if any, rather than the computed one or the one provided as part of the content.
AriesSubsystem	install(java.lang.String location, java.io.InputStream content) Installs a subsystem from the specified content.
AriesSubsystem	install(java.lang.String location, java.io.InputStream content, java.io.InputStream deploymentManifest) Installs a subsystem from the specified content according to the specified deployment manifest.

Methods inherited from interface org.osgi.service.subsystem.Subsystem

getBundleContext, getChildren, getConstituents, getDeploymentHeaders, getLocation, getParents, getState, getSubsystemHeaders, getSubsystemId, getSymbolicName, getType, getVersion, start, stop, uninstall

Method Detail

addRequirements

void addRequirements(java.util.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.

java.lang.UnsupportedOperationException - If this is the root subsystem or the type does not support additional requirements.

install

AriesSubsystem install(java.lang.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(java.lang.String location,
                     java.io.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(java.lang.String location,
                     java.io.InputStream content,
                     java.io.InputStream deploymentManifest)

Description copied from interface: Subsystem

Installs a subsystem from the specified content according to the specified deployment manifest.

This method installs a subsystem using the provided deployment manifest instead of the one in the archive, if any, or a computed one. If the deployment manifest is null, the behavior is exactly the same as in the Subsystem.install(String, InputStream) method. Implementations must support deployment manifest input streams in the format described by section 134.2 of the Subsystem Service Specification. If the deployment manifest does not conform to the subsystem manifest (see 134.15.2), the installation fails.

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.

deploymentManifest - The deployment manifest to use in lieu of the one in the archive, if any, or a computed one.

Returns:

The installed subsystem.

install

AriesSubsystem install(java.lang.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, IDirectory, InputStream) with a null deployment manifest.

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:

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, IDirectory, InputStream)

install

AriesSubsystem install(java.lang.String location,
                     org.apache.aries.util.filesystem.IDirectory content,
                     java.io.InputStream deploymentManifest)

Installs a subsystem from the specified location identifier and content but uses the provided deployment manifest, if any, rather than the computed one or the one provided as part of the content.

This method performs the same function as calling install(String, InputStream, 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.

deploymentManifest - The deployment manifest to use in lieu of any others.

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, InputStream)