org.osgi.service.deploymentadmin.DeploymentAdmin Maven / Gradle / Ivy
/*
* Copyright (c) OSGi Alliance (2005, 2012). 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();
}