DeploymentAdmin
Date: 2016-06-25

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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `cancel()` This method cancels the currently active deployment session.
    `DeploymentPackage` | `getDeploymentPackage(org.osgi.framework.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(org.osgi.framework.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`