Merging api branch back to HEADv20100113

5 files changed, 219 insertions, 5 deletions

diff --git a/bundles/org.eclipse.equinox.p2.core/src/org/eclipse/equinox/p2/core/IAgentLocation.java b/bundles/org.eclipse.equinox.p2.core/src/org/eclipse/equinox/p2/core/IAgentLocation.java
new file mode 100644
index 000000000..13b18ab3a
--- /dev/null
+++ b/bundles/org.eclipse.equinox.p2.core/src/org/eclipse/equinox/p2/core/IAgentLocation.java
@@ -0,0 +1,44 @@
+/*******************************************************************************
+ * Copyright (c) 2007, 2009 IBM Corporation and others.
+ * 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:
+ *     IBM Corporation - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.equinox.p2.core;
+
+import java.net.URI;
+
+/**
+ * An instance of this service represents the location of a provisioning agent's 
+ * metadata. 
+ * 
+ * @noimplement This interface is not intended to be implemented by clients.
+ * @noextend This interface is not intended to be extended by clients.
+ * @since 2.0
+ */
+public interface IAgentLocation {
+	/**
+	 * Service name constant for the agent location service.
+	 */
+	public static final String SERVICE_NAME = IAgentLocation.class.getName();
+
+	/**
+	 * Returns the location where the bundle with the given namespace
+	 * may write its agent-related data.
+	 * @param namespace The namespace of the bundle storing the data
+	 * @return The data location
+	 */
+	public URI getDataArea(String namespace);
+
+	/**
+	 * Returns the root {@link URI} of the agent metadata.
+	 * 
+	 * @return the location of the agent metadata
+	 */
+	public URI getRootLocation();
+
+}
diff --git a/bundles/org.eclipse.equinox.p2.core/src/org/eclipse/equinox/p2/core/IProvisioningAgent.java b/bundles/org.eclipse.equinox.p2.core/src/org/eclipse/equinox/p2/core/IProvisioningAgent.java
index 6bcada44b..52e9470aa 100644
--- a/bundles/org.eclipse.equinox.p2.core/src/org/eclipse/equinox/p2/core/IProvisioningAgent.java
+++ b/bundles/org.eclipse.equinox.p2.core/src/org/eclipse/equinox/p2/core/IProvisioningAgent.java
@@ -25,10 +25,31 @@ import org.eclipse.equinox.p2.core.spi.IAgentServiceFactory;
  * </p>
  * @noimplement This interface is not intended to be implemented by clients.
  * @noextend This interface is not intended to be extended by clients.
- * @since 1.1
+ * @since 2.0
  */
 public interface IProvisioningAgent {
 	/**
+	 * Service name constant for the agent service. Note that an agent obtained directly
+	 * as a service typically represents the agent of the currently running system. To
+	 * obtain an agent for a different system the {@link IProvisioningAgentProvider} 
+	 * service must be used.
+	 */
+	public static final String SERVICE_NAME = IProvisioningAgent.class.getName();
+
+	/**
+	 * Service property identifying whether an agent is the default agent.
+	 * 
+	 * <p>
+	 * This property may be used by clients wishing to obtain or track the
+	 * provisioning agent for the currently running system. When the value of
+	 * this property is <code>"true"</code> then the corresponding service is
+	 * the agent for the currently running system. If the property is undefined or
+	 * has any other value, then the service is not the agent for the currently running system.
+	 * </p>
+	 */
+	public static final String SERVICE_CURRENT = "agent.current"; //$NON-NLS-1$
+
+	/**
 	 * Returns the service with the given service name, or <code>null</code>
 	 * if no such service is available in this agent.
 	 */
@@ -43,6 +64,18 @@ public interface IProvisioningAgent {
 	public void registerService(String serviceName, Object service);
 
 	/**
+	 * Stops the provisioning agent. This causes services provided by this 
+	 * agent to be cleaned up and discarded. No services provided by the agent
+	 * should be referenced after the agent has been stopped, and subsequent
+	 * attempts to obtain services after the agent has stopped will fail.
+	 * <p>
+	 * An agent should only be stopped by the client who first created the agent
+	 * by invoking {@link IProvisioningAgentProvider#createAgent(java.net.URI)}.
+	 * </p>
+	 */
+	public void stop();
+
+	/**
 	 * Unregisters a service that has previously been registered with this
 	 * agent via {@link #registerService(String, Object)}. This method has
 	 * no effect if no such service is registered with this agent.
diff --git a/bundles/org.eclipse.equinox.p2.core/src/org/eclipse/equinox/p2/core/IProvisioningAgentProvider.java b/bundles/org.eclipse.equinox.p2.core/src/org/eclipse/equinox/p2/core/IProvisioningAgentProvider.java
index b3067c00c..462b56d60 100644
--- a/bundles/org.eclipse.equinox.p2.core/src/org/eclipse/equinox/p2/core/IProvisioningAgentProvider.java
+++ b/bundles/org.eclipse.equinox.p2.core/src/org/eclipse/equinox/p2/core/IProvisioningAgentProvider.java
@@ -11,12 +11,11 @@
 package org.eclipse.equinox.p2.core;
 
 import java.net.URI;
-import org.eclipse.equinox.internal.provisional.p2.core.ProvisionException;
 
 /**
  * A service that is used to create or obtain instances of an
  * {@link IProvisioningAgent}.
- * @since 1.1
+ * @since 2.0
  */
 public interface IProvisioningAgentProvider {
 
@@ -31,7 +30,10 @@ public interface IProvisioningAgentProvider {
 	 * currently running system is returned, if available. If a <code>null</code>
 	 * location is provided and the currently running system has not been provisioned
 	 * by any known agent, <code>null</code> is returned.
-	 * 
+	 * <p>
+	 * Callers of this method are responsible for stopping the agent
+	 * when they are finished using it by invoking {@link IProvisioningAgent#stop()}.
+	 * </p>
 	 * @param location The location where the agent metadata is stored
 	 * @return A provisioning agent, or <code>null</code> if a <code>null</code>
 	 * parameter is provided an there is no currently running agent.
@@ -39,6 +41,7 @@ public interface IProvisioningAgentProvider {
 	 * <ul>
 	 * <li>The location is not writeable.</li>
 	 * </ul>
+	 * @see IProvisioningAgent#stop()
 	 */
 	public IProvisioningAgent createAgent(URI location) throws ProvisionException;
 }
diff --git a/bundles/org.eclipse.equinox.p2.core/src/org/eclipse/equinox/p2/core/ProvisionException.java b/bundles/org.eclipse.equinox.p2.core/src/org/eclipse/equinox/p2/core/ProvisionException.java
new file mode 100644
index 000000000..af5b6786a
--- /dev/null
+++ b/bundles/org.eclipse.equinox.p2.core/src/org/eclipse/equinox/p2/core/ProvisionException.java
@@ -0,0 +1,134 @@
+/*******************************************************************************
+ *  Copyright (c) 2007, 2010 IBM Corporation and others.
+ *  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:
+ *     IBM Corporation - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.equinox.p2.core;
+
+import org.eclipse.core.runtime.*;
+import org.eclipse.equinox.internal.p2.core.Activator;
+
+/**
+ * A checked exception indicating a recoverable error occurred while provisioning.
+ * The status provides a further description of the problem.
+ * 
+ * @noextend This class is not intended to be subclassed by clients.
+ * @since 2.0
+ */
+public class ProvisionException extends CoreException {
+	private static final long serialVersionUID = 1L;
+
+	//General and core status codes [0-1000]
+	/**
+	 * Status code constant (value 1) for an uncategorized error.
+	 */
+	public static final int INTERNAL_ERROR = 1;
+
+	//Repository status codes [1000-1999]
+	//General repository codes [1000-1099]
+	/** 
+	 * Status code constant (value 1000) indicating a repository
+	 * unexpectedly does not exist.
+	 */
+	public static final int REPOSITORY_NOT_FOUND = 1000;
+
+	/** 
+	 * Status code constant (value 1001) indicating a repository
+	 * unexpectedly exists.
+	 */
+	public static final int REPOSITORY_EXISTS = 1001;
+
+	/** 
+	 * Status code constant (value 1002) indicating a repository
+	 * could not be read
+	 */
+	public static final int REPOSITORY_FAILED_READ = 1002;
+
+	/** 
+	 * Status code constant (value 1003) indicating a failure occurred
+	 * while writing to a repository.
+	 */
+	public static final int REPOSITORY_FAILED_WRITE = 1003;
+
+	/** 
+	 * Status code constant (value 1004) indicating a repository
+	 * could not be written because it is a read-only repository.
+	 */
+	public static final int REPOSITORY_READ_ONLY = 1004;
+
+	/** 
+	 * Status code constant (value 1005) indicating an attempt was
+	 * made to create or access a repository of unknown type.
+	 */
+	public static final int REPOSITORY_UNKNOWN_TYPE = 1005;
+	/** 
+	 * Status code constant (value 1006) indicating that a specified
+	 * repository location is not valid.
+	 */
+	public static final int REPOSITORY_INVALID_LOCATION = 1006;
+
+	/** 
+	 * Status code constant (value 1007) indicating that there was
+	 * an authentication error while reading a repository
+	 */
+	public static final int REPOSITORY_FAILED_AUTHENTICATION = 1007;
+
+	//Metadata repository codes [1100-1199]
+
+	//Artifact repository codes [1200-1299]
+
+	/** 
+	 * Status code constant (value 1200) indicating an artifact unexpectedly
+	 * does not exist.
+	 */
+	public static final int ARTIFACT_NOT_FOUND = 1200;
+
+	/** 
+	 * Status code constant (value 1201) indicating an artifact unexpectedly
+	 * already exists.
+	 */
+	public static final int ARTIFACT_EXISTS = 1201;
+
+	/**
+	 * Status code constant (value 1202) indicating an artifact's size
+	 * could not be found.
+	 */
+	public static final int ARTIFACT_INCOMPLETE_SIZING = 1202;
+
+	/**
+	 * Creates a new exception with the given status object.  The message
+	 * of the given status is used as the exception message.
+	 *
+	 * @param status the status object to be associated with this exception
+	 */
+	public ProvisionException(IStatus status) {
+		super(status);
+	}
+
+	/**
+	 * Creates a new exception with the given message and a severity of 
+	 * {@link IStatus#ERROR}.
+	 *
+	 * @param message The human-readable problem message
+	 */
+	public ProvisionException(String message) {
+		super(new Status(IStatus.ERROR, Activator.ID, message));
+	}
+
+	/**
+	 * Creates a new exception with the given message and cause, and
+	 * a severity of {@link IStatus#ERROR}.
+	 *
+	 * @param message The human-readable problem message
+	 * @param cause The underlying cause of the exception
+	 */
+	public ProvisionException(String message, Throwable cause) {
+		super(new Status(IStatus.ERROR, Activator.ID, message, cause));
+	}
+
+}
diff --git a/bundles/org.eclipse.equinox.p2.core/src/org/eclipse/equinox/p2/core/spi/IAgentServiceFactory.java b/bundles/org.eclipse.equinox.p2.core/src/org/eclipse/equinox/p2/core/spi/IAgentServiceFactory.java
index 8fd467b67..0c1b7de12 100644
--- a/bundles/org.eclipse.equinox.p2.core/src/org/eclipse/equinox/p2/core/spi/IAgentServiceFactory.java
+++ b/bundles/org.eclipse.equinox.p2.core/src/org/eclipse/equinox/p2/core/spi/IAgentServiceFactory.java
@@ -16,7 +16,7 @@ import org.eclipse.equinox.p2.core.IProvisioningAgent;
  * A factory for creating a service that forms part of a provisioning agent instance.
  * Factories themselves are registered in the OSGi service registry so that they
  * can be obtained by a provisioning agent.
- * @since 1.1
+ * @since 2.0
  */
 public interface IAgentServiceFactory {
 	/**