org.osgi.service.deploymentadmin.DeploymentAdmin Maven / Gradle / Ivy
/*
* Copyright (c) OSGi Alliance (2005, 2010). 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.deploymentadmin;
import java.io.InputStream;
import org.osgi.framework.Bundle;
/**
* 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 {@link 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.
*/
public interface DeploymentAdmin {
/**
* 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.
*
* @param in the input stream the Deployment Package can be read from. It mustn't be {@code null}.
* @return A DeploymentPackage object representing the newly installed/updated Deployment Package.
* It is never {@code null}.
* @throws IllegalArgumentException if the got InputStream parameter is {@code null}
* @throws DeploymentException if the installation was not successful. For detailed error code description
* see {@link DeploymentException}.
* @throws SecurityException if the caller doesn't have the appropriate
* {@link DeploymentAdminPermission}("<filter>", "install") permission.
* @see DeploymentAdminPermission
* @see DeploymentPackage
* @see DeploymentPackage
*/
DeploymentPackage installDeploymentPackage(InputStream in) throws DeploymentException;
/**
* Lists the Deployment Packages currently installed on the platform.
*
* {@link 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 {@code null} in case of uninstall)
* replaces the target.
*
* @return the array of {@code DeploymentPackage} objects representing all the
* installed Deployment Packages. The return value cannot be {@code null}.
* In case of missing permissions it may give back an empty array.
* @see DeploymentPackage
* @see DeploymentAdminPermission
*/
DeploymentPackage[] listDeploymentPackages();
/**
* Gets the currently installed {@link 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 {@code null}
* in case of uninstall) is the return value.
*
* @param symbName the symbolic name of the Deployment Package to be retrieved. It mustn't be
* {@code null}.
* @return The {@code DeploymentPackage} for the given symbolic name.
* If there is no Deployment Package with that symbolic name currently installed,
* {@code null} is returned.
* @throws IllegalArgumentException if the given {@code symbName} is {@code null}
* @throws SecurityException if the caller doesn't have the appropriate
* {@link DeploymentAdminPermission}("<filter>", "list") permission.
* @see DeploymentPackage
* @see DeploymentAdminPermission
*/
DeploymentPackage getDeploymentPackage(String symbName);
/**
* Gives back the installed {@link 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.
*
* @param bundle the bundle whose owner is queried
* @return the Deployment Package Object that owns the bundle or {@code null} if the bundle doesn't
* belong to any Deployment Packages (standalone bundles)
* @throws IllegalArgumentException if the given {@code bundle} is {@code null}
* @throws SecurityException if the caller doesn't have the appropriate
* {@link DeploymentAdminPermission}("<filter>", "list") permission.
* @see DeploymentPackage
* @see DeploymentAdminPermission
*/
DeploymentPackage getDeploymentPackage(Bundle bundle);
/**
* 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.
*
* @return true if there was an active session and it was successfully canceled.
* @throws SecurityException if the caller doesn't have the appropriate
* {@link DeploymentAdminPermission}("<filter>", "cancel") permission.
* @see DeploymentAdminPermission
*/
boolean cancel();
}