org.osgi.service.deploymentadmin
Interface DeploymentAdmin

public interface DeploymentAdmin

This is the interface of the Deployment Admin service.

The OSGi Service Platform provides mechanisms to manage the life cycle of bundles, configuration objects, permission objects, etc. but the overall consistency of the runtime configuration is the responsibility of the management agent. In other words, the management agent decides to install, update, or uninstall bundles, create or delete configuration or permission objects, as well as manage other resource types, etc.

The Deployment Admin service standardizes the access to some of the responsibilities of the management agent. The service provides functionality to manage Deployment Packages (see DeploymentPackage). A Deployment Package groups resources as a unit of management. A Deployment Package is something that can be installed, updated, and uninstalled as a unit.

The Deployment Admin functionality is exposed as a standard OSGi service with no mandatory service parameters.

Method Summary

boolean	cancel() This method cancels the currently active deployment session.
DeploymentPackage	getDeploymentPackage(Bundle bundle) Gives back the installed DeploymentPackage that owns the bundle.
DeploymentPackage	getDeploymentPackage(java.lang.String symbName) Gets the currently installed DeploymentPackage instance which has the given symbolic name.
DeploymentPackage	installDeploymentPackage(java.io.InputStream in) Installs a Deployment Package from an input stream.
DeploymentPackage[]	listDeploymentPackages() Lists the Deployment Packages currently installed on the platform.

Method Detail

installDeploymentPackage

DeploymentPackage installDeploymentPackage(java.io.InputStream in)
                                           throws DeploymentException

Installs a Deployment Package from an input stream. If a version of that Deployment Package is already installed and the versions are different, the installed version is updated with this new version even if it is older (downgrade). If the two versions are the same, then this method simply returns with the old (target) Deployment Package without any action.

Parameters:

in - the input stream the Deployment Package can be read from. It mustn't be null.

Returns:

A DeploymentPackage object representing the newly installed/updated Deployment Package. It is never null.

Throws:

java.lang.IllegalArgumentException - if the got InputStream parameter is null

DeploymentException - if the installation was not successful. For detailed error code description see DeploymentException.

java.lang.SecurityException - if the caller doesn't have the appropriate DeploymentAdminPermission("<filter>", "install") permission.

See Also:

DeploymentAdminPermission, DeploymentPackage, DeploymentPackage

listDeploymentPackages

DeploymentPackage[] listDeploymentPackages()

Lists the Deployment Packages currently installed on the platform.

DeploymentAdminPermission("<filter>", "list") is needed for this operation to the effect that only those packages are listed in the array to which the caller has appropriate DeploymentAdminPermission. It has the consequence that the method never throws SecurityException only doesn't put certain Deployment Packages into the array.

During an installation of an existing package (update) or during an uninstallation, the target must remain in this list until the installation (uninstallation) process is completed, after which the source (or null in case of uninstall) replaces the target.

Returns:

the array of DeploymentPackage objects representing all the installed Deployment Packages. The return value cannot be null. In case of missing permissions it may give back an empty array.

See Also:

DeploymentPackage, DeploymentAdminPermission

getDeploymentPackage

DeploymentPackage getDeploymentPackage(java.lang.String symbName)

Gets the currently installed DeploymentPackage instance which has the given symbolic name.

During an installation of an existing package (update) or during an uninstallation, the target Deployment Package must remain the return value until the installation (uninstallation) process is completed, after which the source (or null in case of uninstall) is the return value.

Parameters:

symbName - the symbolic name of the Deployment Package to be retrieved. It mustn't be null.

Returns:

The DeploymentPackage for the given symbolic name. If there is no Deployment Package with that symbolic name currently installed, null is returned.

Throws:

java.lang.IllegalArgumentException - if the given symbName is null

java.lang.SecurityException - if the caller doesn't have the appropriate DeploymentAdminPermission("<filter>", "list") permission.

See Also:

DeploymentPackage, DeploymentAdminPermission

getDeploymentPackage

DeploymentPackage getDeploymentPackage(Bundle bundle)

Gives back the installed DeploymentPackage that owns the bundle. Deployment Packages own their bundles by their Bundle Symbolic Name. It means that if a bundle belongs to an installed Deployment Packages (and at most to one) the Deployment Admin assigns the bundle to its owner Deployment Package by the Symbolic Name of the bundle.

Parameters:

bundle - the bundle whose owner is queried

Returns:

the Deployment Package Object that owns the bundle or null if the bundle doesn't belong to any Deployment Packages (standalone bundles)

Throws:

java.lang.IllegalArgumentException - if the given bundle is null

java.lang.SecurityException - if the caller doesn't have the appropriate DeploymentAdminPermission("<filter>", "list") permission.

See Also:

DeploymentPackage, DeploymentAdminPermission

cancel

boolean cancel()

This method cancels the currently active deployment session. This method addresses the need to cancel the processing of excessively long running, or resource consuming install, update or uninstall operations.

Returns:

true if there was an active session and it was successfully canceled.

Throws:

java.lang.SecurityException - if the caller doesn't have the appropriate DeploymentAdminPermission("<filter>", "cancel") permission.

See Also:

DeploymentAdminPermission