| /******************************************************************************* |
| * Copyright (c) 2008, 2012 VMware Inc. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * VMware Inc. - initial contribution |
| * SAP AG - re-factoring |
| *******************************************************************************/ |
| |
| package org.eclipse.virgo.nano.deployer.core; |
| |
| import java.net.URI; |
| |
| import org.osgi.framework.Version; |
| |
| /** |
| * The ApplicationDeployer interface is the programmatic interface to the deployer subsystem for deploying applications |
| * and libraries. |
| * <p /> |
| * |
| * <strong>Concurrent Semantics</strong><br /> |
| * |
| * Implementations of this interface must be thread safe. |
| * |
| */ |
| public interface ApplicationDeployer { |
| |
| /** |
| * Deploys the artifact are the supplied <code>location</code>. The supplied <code>options</code> govern how the |
| * installed artifact is handled by the deployed, e.g. if it is recovered and re-installed upon warm restart. |
| * |
| * @param uri The location of the artifact |
| * @param options The options for the installation |
| * @return The identity of the installed artifact |
| * @throws DeploymentException if installation fails. |
| */ |
| DeploymentIdentity install(URI uri, DeploymentOptions options) throws DeploymentException; |
| |
| /** |
| * Deploys the artifact are the supplied <code>location</code>. The supplied <code>options</code> govern how the |
| * installed artifact is handled by the deployed, e.g. if it is recovered and re-installed upon warm restart. |
| * <p /> |
| * This method is equivalent to calling <code>install(location, new DeploymentOptions())</code>. |
| * |
| * @param uri The location of the artifact |
| * @param options The options for the installation |
| * @return The identity of the installed artifact |
| * @throws DeploymentException if installation fails. |
| */ |
| DeploymentIdentity install(URI uri) throws DeploymentException; |
| |
| /** |
| * Deploy an application which may be either an OSGi application or a legacy application such as a WAR. This is used |
| * by admin. and hot deployment. A successfully deployed application is always recovered on warm restart but the |
| * application at the given location is not deleted when the application is undeployed. <br/> |
| * <p /> |
| * This method is equivalent to calling <code>deploy(location, new DeploymentOptions())</code>. |
| * |
| * @param uri the location of the application JAR file |
| * @return the {@link DeploymentIdentity} of the deployed application |
| * @throws DeploymentException |
| */ |
| DeploymentIdentity deploy(URI uri) throws DeploymentException; |
| |
| /** |
| * Deploy an application which may be either an OSGi application or a legacy application such as a WAR. This is used |
| * by admin. and hot deployment. |
| * |
| * @param uri location of the artifact |
| * @param options the options for this deployment |
| * @return the {@link DeploymentIdentity} of the deployed application |
| * @throws DeploymentException |
| */ |
| DeploymentIdentity deploy(URI uri, DeploymentOptions options) throws DeploymentException; |
| |
| /** |
| * Deploy an artifact from the repository with the given type, name, and version. A successfully deployed |
| * application is always recovered on warm restart. <br/> |
| * <p /> |
| * This method is equivalent to calling <code>deploy(type, name, version, new DeploymentOptions())</code>. |
| * |
| * @param type the type of the artifact to deploy |
| * @param name the name of the artifact to deploy |
| * @param version the {@link Version} of the artifact to deploy |
| * @return the {@link DeploymentIdentity} of the deployed application |
| * @throws DeploymentException |
| */ |
| DeploymentIdentity deploy(String type, String name, Version version) throws DeploymentException; |
| |
| /** |
| * Deploy an artifact from the repository with the given type, name, and version.<br/> |
| * <p /> |
| * If the given {@link DeploymentOptions} specify the artifact is owned by the deployer, then deployment fails and a |
| * deployment exception is thrown. This is to avoid the deployer deleting the artifact from the repository store. |
| * |
| * @param type the type of the artifact to deploy |
| * @param name the name of the artifact to deploy |
| * @param version the {@link Version} of the artifact to deploy |
| * @param options of the deployment |
| * @return the {@link DeploymentIdentity} of the deployed application which must return <code>false</code> from |
| * <code>getDeployerOwned</code> |
| * @throws DeploymentException |
| */ |
| DeploymentIdentity deploy(String type, String name, Version version, DeploymentOptions options) throws DeploymentException; |
| |
| /** |
| * Undeploy an application with a given symbolic name and version. |
| * |
| * WARNING: there can be ambiguity if applications of distinct types have the same symbolic name and version, so |
| * this method is deprecated. |
| * |
| * @param applicationSymbolicName the symbolic name of the application |
| * @param version the version of the application in string form |
| * @throws DeploymentException |
| * @deprecated in favour of the undeploy(String, String, String) which takes artifact type as first parameter |
| */ |
| void undeploy(String applicationSymbolicName, String version) throws DeploymentException; |
| |
| /** |
| * Undeploy an application with a given type, name, and version. |
| * |
| * @param type the type of the application |
| * @param name the symbolic name of the application |
| * @param version the version of the application in string form |
| * @throws DeploymentException |
| */ |
| void undeploy(String type, String name, String version) throws DeploymentException; |
| |
| /** |
| * Undeploy an application with a given {@link DeploymentIdentity}. The application may be either an OSGi |
| * application or a legacy application such as a WAR. |
| * <p> |
| * This method is equivalent to calling <code>undeploy(DeploymentIdentity, boolean)</code> with <code>false</code>. |
| * |
| * @param deploymentIdentity the <code>DeploymentIdentity</code> of the application |
| * @throws DeploymentException |
| */ |
| void undeploy(DeploymentIdentity deploymentIdentity) throws DeploymentException; |
| |
| /** |
| * Undeploy an application with a given {@link DeploymentIdentity}. The application may be either an OSGi |
| * application or a legacy application such as a WAR. |
| * <p> |
| * The deleted parameter indicates whether the undeployment is a consequence of the artifact having been deleted. |
| * This affects the processing of "deployer owned" artifacts which undeploy would normally delete automatically. If |
| * the undeploy is a consequence of the artifact having been deleted, then undeploy must not delete the artifact |
| * automatically since this may actually delete a "new" artifact which has arrived shortly after the "old" artifact |
| * was deleted. |
| * |
| * @param deploymentIdentity the <code>DeploymentIdentity</code> of the application |
| * @param deleted <code>true</code> if and only if undeploy is being driven as a consequence of the artifact having |
| * been deleted |
| * @throws DeploymentException |
| */ |
| void undeploy(DeploymentIdentity deploymentIdentity, boolean deleted) throws DeploymentException; |
| |
| /** |
| * Refresh a single bundle of the application (PAR or bundle) which was deployed from the given URI and return the |
| * deployment identity of the deployed application. <br/> |
| * If the refresh is promoted to a redeploy then the DeploymentIdentity of the newly deployed application is |
| * returned. |
| * |
| * @param uri location of the artifact |
| * @param symbolicName the bundle symbolic name of the bundle to be refreshed |
| * @return the {@link DeploymentIdentity} of the deployed application |
| * @throws DeploymentException |
| */ |
| DeploymentIdentity refresh(URI uri, String symbolicName) throws DeploymentException; |
| |
| /** |
| * Refresh any bundle with the given symbolic name and version and any bundles cloned from a bundle with the given |
| * symbolic name and version. If no bundles or cloned bundles match the given symbolic name and version, simply |
| * return and do not throw an exception. <br/> |
| * <p/> |
| * Certain bundles which are critical to the operation of the system may not be refreshed. If an attempt is made to |
| * refresh one of these bundles, a warning message is logged, the bundle is not refreshed, but any clones of the |
| * bundle are refreshed. |
| * |
| * @param bundleSymbolicName the symbolic name of the bundle |
| * @param bundleVersion the version of the bundle |
| * @throws DeploymentException |
| */ |
| void refreshBundle(String bundleSymbolicName, String bundleVersion) throws DeploymentException; |
| |
| /** |
| * Get a list of deployed applications. |
| * |
| * @return Array of deployed application identities. |
| */ |
| DeploymentIdentity[] getDeploymentIdentities(); |
| |
| /** |
| * Get the {@link DeploymentIdentity} of an application deployed from the given location. If no such application was |
| * found, return <code>null</code>. <br/> |
| * <p /> |
| * Although the deployer currently prevents two applications being deployed from the same location without |
| * un-deploying the first application, this restriction may be lifted in the future in which case this method will |
| * return one of potentially many applications deployed from the given location. |
| * |
| * @param uri location of the artifact |
| * @return a <code>DeploymentIdentity</code> or <code>null</code> |
| */ |
| DeploymentIdentity getDeploymentIdentity(URI uri); |
| |
| /** |
| * Determine whether or not the given artifact is already deployed. Return <code>true</code> if the given artefact |
| * at its file's last modified time is already deployed. The last modified time is only taken into account if the |
| * file was deployed on a previous run of the Server. |
| * |
| * @param uri location of the artifact |
| * @return <code>true</code> if and only if the given artifact at its file's last modified time is already deployed |
| */ |
| boolean isDeployed(URI uri); |
| |
| } |
