org.osgi.service.deploymentadmin.spi.DeploymentSession 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.spi;

import org.osgi.service.deploymentadmin.DeploymentPackage;

/**
 * The session interface represents a currently running deployment session
 * (install/update/uninstall).
 * 
 * 
 * When a deployment package is installed the target package, when uninstalled
 * the source package is an empty deployment package. The empty deployment
 * package is a virtual entity it doesn't appear for the outside world. It is
 * only visible on the DeploymentSession interface used by Resource Processors.
 * Although the empty package is only visible for Resource Processors it has the
 * following characteristics:
 * 

 * 
 * 

 * has version 0.0.0
 * its name is an empty string
 * it is stale
 * it has no bundles (see {@link DeploymentPackage#getBundle(String)})
 * it has no resources (see {@link DeploymentPackage#getResources()})
 * it has no headers except
 * 
 * {@code DeploymentPackage-SymbolicName} and
 * {@code DeploymentPackage-Version}
 * 
 * (see {@link DeploymentPackage#getHeader(String)})
 * it has no resource headers (see
 * {@link DeploymentPackage#getResourceHeader(String, String)})
 * {@link DeploymentPackage#uninstall()} throws
 * {@link java.lang.IllegalStateException}
 * {@link DeploymentPackage#uninstallForced()} throws
 * {@link java.lang.IllegalStateException}
 * 
 * 
 */
public interface DeploymentSession {

	/**
	 * If the deployment action is an update or an uninstall, this call returns
	 * the {@code DeploymentPackage} instance for the installed deployment
	 * package. If the deployment action is an install, this call returns the
	 * empty deployment package (see {@link DeploymentPackage}).
	 * 
	 * @return the target deployment package
	 * @see DeploymentPackage
	 */
	DeploymentPackage getTargetDeploymentPackage();

	/**
	 * If the deployment action is an install or an update, this call returns
	 * the {@code DeploymentPackage} instance that corresponds to the deployment
	 * package being streamed in for this session. If the deployment action is
	 * an uninstall, this call returns the empty deployment package (see
	 * {@link DeploymentPackage}).
	 * 
	 * @return the source deployment package
	 * @see DeploymentPackage
	 */
	DeploymentPackage getSourceDeploymentPackage();

	/**
	 * Returns the private data area of the specified bundle. The bundle must be
	 * part of either the source or the target deployment packages. The
	 * permission set the caller resource processor needs to manipulate the
	 * private area of the bundle is set by the Deployment Admin on the fly when
	 * this method is called. The permissions remain available during the
	 * deployment action only.
	 * 
	 * 
	 * The bundle and the caller Resource Processor have to be in the same
	 * Deployment Package.
	 * 
	 * @param bundle the bundle the private area belongs to
	 * @return file representing the private area of the bundle. It cannot be
	 *         null.
	 * @throws SecurityException if the caller doesn't have the appropriate
	 *         {@link DeploymentCustomizerPermission}("<filter>",
	 *         "privatearea") permission.
	 * @see DeploymentPackage
	 * @see DeploymentCustomizerPermission
	 */
	java.io.File getDataFile(org.osgi.framework.Bundle bundle);

}