Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
  /*
   * Copyright (c) OSGi Alliance (2012, 2013). All Rights Reserved.
   * 
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *      http://www.apache.org/licenses/LICENSE-2.0
   *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 
 package org.osgi.service.subsystem;
 
 import java.util.Map;
A subsystem is a collection of resources constituting a logical, possibly isolated, unit of functionality.

A subsystem may be scoped or unscoped. Scoped subsystems are isolated by implicit or explicit sharing policies. Unscoped subsystems are not isolated and, therefore, have no sharing policy. There are three standard types of subsystems.

  • Application - An implicitly scoped subsystem. Nothing is exported, and imports are computed based on any unsatisfied content requirements.
  • Composite - An explicitly scoped subsystem. The sharing policy is defined by metadata within the subsystem archive.
  • Feature - An unscoped subsystem.
Conceptually, a subsystem may be thought of as existing in an isolated region along with zero or more other subsystems. Each region has one and only one scoped subsystem, which dictates the sharing policy. The region may, however, have many unscoped subsystems. It is, therefore, possible to have shared constituents across multiple subsystems within a region. Associated with each region is a bundle whose context may be retrieved from any subsystem within that region. This context may be used to monitor activity occurring within the region.

A subsystem may have children and, unless it's the root subsystem, must have at least one parent. Subsystems become children of the subsystem in which they are installed. Unscoped subsystems have more than one parent if they are installed in more than one subsystem within the same region. The subsystem graph may be thought of as an acyclic digraph with one and only one source vertex, which is the root subsystem. The edges have the child as the head and parent as the tail.

A subsystem has several identifiers.

  • Location - An identifier specified by the client as part of installation. It is guaranteed to be unique within the same framework.
  • ID - An identifier generated by the implementation as part of installation. It is guaranteed to be unique within the same framework.
  • Symbolic Name/Version - The combination of symbolic name and version is guaranteed to be unique within the same region. Although type is not formally part of the identity, two subsystems with the same symbolic names and versions but different types are not considered to be equal.
A subsystem has a well-defined life cycle. Which stage a subsystem is in may be obtained from the subsystem's state and is dependent on which life cycle operation is currently active or was last invoked.

A subsystem archive is a ZIP file having an .esa extension and containing metadata describing the subsystem. The form of the metadata may be a subsystem or deployment manifest, as well as any content resource files. The manifests are optional and will be computed if not present. The subsystem manifest headers may be retrieved in raw or localized forms. There are five standard types of resources that may be included in a subsystem.

  • Bundle - A bundle that is not a fragment.
  • Fragment - A fragment bundle.
  • Application Subsystem - An application subsystem.
  • Composite Subsystem - A composite subsystem.
  • Feature Subsystem - A feature subsystem.
Resources contained by a subsystem are called constituents. There are several ways a resource may become a constituent of a subsystem:
  • A resource is listed as part of the subsystem's content.
  • A subsystem resource is a child of the subsystem.
  • The subsystem has a provision policy of accept dependencies.
  • A bundle resource is installed using the region bundle context.
  • A bundle resource is installed using the bundle context of another resource contained by the subsystem.

In addition to invoking one of the install methods, a subsystem instance may be obtained through the service registry. Each installed subsystem has a corresponding service registration. A subsystem service has the following properties.

  • ID - The ID of the subsystem.
  • Symbolic Name - The symbolic name of the subsystem.
  • Version - The version of the subsystem.
  • Type - The type of the subsystem.
  • State - The state of the subsystem.

Because a subsystem must be used to install other subsystems, a root subsystem is provided as a starting point. The root subsystem may only be obtained as a service and has the following characteristics.

  • The ID is 0.
  • The symbolic name is org.osgi.service.subsystem.root.
  • The version matches this specification's version.
  • It has no parents.
  • All existing bundles, including the system and subsystem implementation bundles, are constituents.
  • The type is osgi.subsystem.application with no imports.
  • The provision policy is acceptDependencies.

Author(s):
$Id: 98c29e1bfd80828ab025a1aa0530019184185242 $
ThreadSafe:
Noimplement:
public interface Subsystem {
An enumeration of the possible states of a subsystem.

These states are a reflection of what constituent resources are permitted to do and not an aggregation of constituent resource states.

	public static enum State {
The subsystem is in the process of installing.

A subsystem is in the INSTALLING state when the install method of its parent is active, and attempts are being made to install its content resources. If the install method completes without exception, then the subsystem has successfully installed and must move to the INSTALLED state. Otherwise, the subsystem has failed to install and must move to the INSTALL_FAILED state.

		INSTALLING,
The subsystem is installed but not yet resolved.

A subsystem is in the INSTALLED state when it has been installed in a parent subsystem but is not or cannot be resolved. This state is visible if the dependencies of the subsystem's content resources cannot be resolved.

		INSTALLED,
The subsystem failed to install.

A subsystem is in the INSTALL_FAILED state when an unrecoverable error occurred during installation. The subsystem is in an unusable state but references to the subsystem object may still be available and used for introspection.

		INSTALL_FAILED,
The subsystem is in the process of resolving.

A subsystem is in the RESOLVING state when the start method is active, and attempts are being made to resolve its content resources. If the resolve method completes without exception, then the subsystem has successfully resolved and must move to the RESOLVED state. Otherwise, the subsystem has failed to resolve and must move to the INSTALLED state.

		RESOLVING,
The subsystem is resolved and able to be started.

A subsystem is in the RESOLVED state when all of its content resources are resolved. Note that the subsystem is not active yet.

		RESOLVED,
The subsystem is in the process of starting.

A subsystem is in the STARTING state when its start method is active, and attempts are being made to start its content and dependencies. If the start method completes without exception, then the subsystem has successfully started and must move to the ACTIVE state. Otherwise, the subsystem has failed to start and must move to the RESOLVED state.

		STARTING,
The subsystem is now running.

A subsystem is in the ACTIVE state when its content and dependencies have been successfully started.

		ACTIVE,
The subsystem is in the process of stopping.

A subsystem is in the STOPPING state when its stop method is active, and attempts are being made to stop its content and dependencies. When the stop method completes, the subsystem is stopped and must move to the RESOLVED state.

		STOPPING,
The subsystem is in the process of uninstalling.

A subsystem is in the UNINSTALLING state when its uninstall method is active, and attempts are being made to uninstall its constituent and dependencies. When the uninstall method completes, the subsystem is uninstalled and must move to the UNINSTALLED state.

		UNINSTALLING,
The subsystem is uninstalled and may not be used.

The UNINSTALLED state is only visible after a subsystem's constituent and dependencies are uninstalled. The subsystem is in an unusable state but references to the subsystem object may still be available and used for introspection.

		UNINSTALLED
	}

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.

Returns:
The bundle context of the region within which this subsystem resides or null if this subsystem's state is in INSTALL_FAILED, UNINSTALLED.
Throws:
java.lang.SecurityException If the caller does not have the appropriate SubsystemPermission[this,CONTEXT], and the runtime supports permissions.
Returns the child subsystems of this 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.
Throws:
java.lang.IllegalStateException If this subsystem's state is in INSTALL_FAILED, UNINSTALLED.
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.

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.
Throws:
java.lang.SecurityException If the caller does not have the appropriate SubsystemPermission[this,METADATA], and the runtime supports permissions.
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.

Returns:
The location identifier of this subsystem.
Throws:
java.lang.SecurityException If the caller does not have the appropriate SubsystemPermission[this,METADATA], and the runtime supports permissions.
	public String getLocation();

Returns the parent subsystems of this 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.
Throws:
java.lang.IllegalStateException If this subsystem's state is in INSTALL_FAILED, UNINSTALLED.
Returns the constituent resources of this 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.
Throws:
java.lang.IllegalStateException If this subsystem's state is in INSTALL_FAILED, UNINSTALLED.
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.

Returns:
The current state of this subsystem.
	public State getState();

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.

Returns:
The identifier of this subsystem.
	public long getSubsystemId();

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.

Returns:
The symbolic name of this 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.

Returns:
The type of this subsystem.
	public String getType();

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.

Returns:
The version of this subsystem.
	public Version getVersion();

Installs a subsystem from the specified location identifier.

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

Parameters:
location The location identifier of the subsystem to install.
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(java.lang.String,java.io.InputStream)
	public Subsystem install(String location);

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.

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.
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.
	public Subsystem install(String locationInputStream content);

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.

StateAction
INSTALLINGWait
INSTALLEDResolve, Start
INSTALL_FAILEDIllegalStateException
RESOLVINGWait
RESOLVEDStart
STARTINGWait
ACTIVEReturn
STOPPINGWait
UNINSTALLINGIllegalStateException
UNINSTALLEDIllegalStateException

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.

Throws:
SubsystemException If this subsystem fails to start.
java.lang.IllegalStateException If this subsystem's state is in INSTALL_FAILED, UNINSTALLING, or UNINSTALLED, or if the state of at least one of this subsystem's parents is not in STARTING, ACTIVE.
java.lang.SecurityException If the caller does not have the appropriate SubsystemPermission[this,EXECUTE], and the runtime supports permissions.
	public void start();

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.

StateAction
INSTALLINGWait
INSTALLEDReturn
INSTALL_FAILEDIllegalStateException
RESOLVINGWait
RESOLVEDReturn
STARTINGWait
ACTIVEStop
STOPPINGWait
UNINSTALLINGIllegalStateException
UNINSTALLEDIllegalStateException

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.

Throws:
SubsystemException If this subsystem fails to stop cleanly.
java.lang.IllegalStateException If this subsystem's state is in INSTALL_FAILED, UNINSTALLING, or UNINSTALLED.
java.lang.SecurityException If the caller does not have the appropriate SubsystemPermission[this,EXECUTE], and the runtime supports permissions.
	public void stop();

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.

StateAction
INSTALLINGWait
INSTALLEDUninstall
INSTALL_FAILEDWait
RESOLVINGWait
RESOLVEDUninstall
STARTINGWait
ACTIVEStop, Uninstall
STOPPINGWait
UNINSTALLINGWait
UNINSTALLEDReturn

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.

Throws:
SubsystemException If this subsystem fails to uninstall cleanly.
java.lang.SecurityException If the caller does not have the appropriate SubsystemPermission[this,LIFECYCLE], and the runtime supports permissions.
	public void uninstall();
New to GrepCode? Check out our FAQ X