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)