javadoc

3 files changed, 165 insertions, 31 deletions

diff --git a/bundles/org.eclipse.equinox.p2.engine/src/org/eclipse/equinox/p2/engine/IProfile.java b/bundles/org.eclipse.equinox.p2.engine/src/org/eclipse/equinox/p2/engine/IProfile.java
index c4c582ed6..58a867600 100644
--- a/bundles/org.eclipse.equinox.p2.engine/src/org/eclipse/equinox/p2/engine/IProfile.java
+++ b/bundles/org.eclipse.equinox.p2.engine/src/org/eclipse/equinox/p2/engine/IProfile.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- *  Copyright (c) 2005, 2009 IBM Corporation and others.
+ *  Copyright (c) 2005, 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
@@ -17,6 +17,11 @@ import org.eclipse.equinox.p2.metadata.IInstallableUnit;
 import org.eclipse.equinox.p2.query.*;
 
 /**
+ * Represents the state of a profile in a profile registry at a given moment in time.
+ * Note this object contains only a snapshot of a particular profile state, and will
+ * never be updated if subsequent changes are made to this profile. A client should
+ * never retain an {@link IProfile} instance, but rather retain the profile id and obtain
+ * the current state of the profile from the profile registry only when required.
  * @since 2.0
  */
 public interface IProfile extends IQueryable<IInstallableUnit> {
@@ -52,7 +57,17 @@ public interface IProfile extends IQueryable<IInstallableUnit> {
 	 */
 	public static final String PROP_PROFILE_LOCKED_IU = "org.eclipse.equinox.p2.type.lock"; //$NON-NLS-1$
 
-	//TODO Move to UI
+	/**
+	 * A property key (value <code>"org.eclipse.equinox.p2.type.root"</code>) for a
+	 * boolean property indicating whether an installable unit should be considered
+	 * a root of the install. Typically this means the unit will appear to the end user
+	 * as a top-level installed item. The property should be obtained from a profile using 
+	 * IProfile#getInstallableUnitProperty(IInstallableUnit, String).
+	 * 
+	 * @see #LOCK_UNINSTALL
+	 * @see #LOCK_UPDATE
+	 * @see #LOCK_NONE
+	 */
 	public static final String PROP_PROFILE_ROOT_IU = "org.eclipse.equinox.p2.type.root"; //$NON-NLS-1$
 
 	/**
@@ -118,23 +133,57 @@ public interface IProfile extends IQueryable<IInstallableUnit> {
 	 */
 	public IProvisioningAgent getProvisioningAgent();
 
+	/**
+	 * Returns the id of this profile, unique within a given profile registry
+	 * @return the profile id
+	 */
 	public String getProfileId();
 
 	/**
-	 * Get the stored value associated with the given key.
-	 *  
-	 * <code>null</code> is returned if this property is not present
+	 * Returns the profile property associated with the given key,
+	 * or <code>null</code> if this property is not present
+	 * @param key The property kid
+	 * @return the property value, or <code>null</code>
 	 */
 	public String getProperty(String key);
 
+	/**
+	 * Returns the profile property associated with the given installable unit.
+	 * @param iu the installable unit to return the property for
+	 * @param key the property key
+	 * @return the property value, or <code>null</code> if no such property is defined
+	 */
 	public String getInstallableUnitProperty(IInstallableUnit iu, String key);
 
+	/**
+	 * Returns an unmodifiable map of all profile properties.
+	 * @return a map of all profile properties.
+	 */
 	public Map<String, String> getProperties();
 
+	/**
+	 * Returns an unmodifiable map of all profile properties associated with the given
+	 * installable unit in this profile.
+	 * @param iu the installable unit to return profile properties for
+	 * @return an unmodifiable map of installable unit profile properties
+	 */
 	public Map<String, String> getInstallableUnitProperties(IInstallableUnit iu);
 
+	/**
+	 * Returns a timestamp describing when this profile snapshot was created.
+	 * @return A profile timestamp
+	 */
 	public long getTimestamp();
 
+	/**
+	 * Returns the installable units in this profile that match the given query. In a shared
+	 * install, this will include both the installable units in the shared base location, and in
+	 * the current user's private install area.
+	 * @param query
+	 * @param monitor a progress monitor, or <code>null</code> if progress
+	 *    reporting is not desired
+	 * @return The installable units that match the given query
+	 */
 	public IQueryResult<IInstallableUnit> available(IQuery<IInstallableUnit> query, IProgressMonitor monitor);
 
 }
\ No newline at end of file
diff --git a/bundles/org.eclipse.equinox.p2.engine/src/org/eclipse/equinox/p2/engine/IProfileRegistry.java b/bundles/org.eclipse.equinox.p2.engine/src/org/eclipse/equinox/p2/engine/IProfileRegistry.java
index adbd48360..ad1bf520a 100644
--- a/bundles/org.eclipse.equinox.p2.engine/src/org/eclipse/equinox/p2/engine/IProfileRegistry.java
+++ b/bundles/org.eclipse.equinox.p2.engine/src/org/eclipse/equinox/p2/engine/IProfileRegistry.java
@@ -19,6 +19,13 @@ import org.eclipse.equinox.p2.core.ProvisionException;
  * @since 2.0
  */
 public interface IProfileRegistry {
+	/**
+	 * A special profile id representing the profile of the currently running system.
+	 * This constant can be used when invoking {@link #getProfile(String)} to obtain
+	 * the profile of the currently running system. Note that a given profile registry
+	 * may not have a defined self profile, for example if the running system doesn't
+	 * have a profile, or resides in a different profile registry.
+	 */
 	public static final String SELF = "_SELF_"; //$NON-NLS-1$
 	/**
 	 * Service name constant for the profile registry service.
@@ -32,7 +39,7 @@ public interface IProfileRegistry {
 	 * @param id the profile identifier
 	 * @return the profile or <code>null</code>
 	 */
-	IProfile getProfile(String id);
+	public IProfile getProfile(String id);
 
 	/**
 	 * Return the profile in the registry that has the given id and timestamp. If it does not exist, 
@@ -40,18 +47,18 @@ public interface IProfileRegistry {
 	 * 
 	 * @param id the profile identifier
 	 * @param timestamp the profile's timestamp
-
 	 * @return the profile or <code>null</code>
 	 */
-	IProfile getProfile(String id, long timestamp);
+	public IProfile getProfile(String id, long timestamp);
 
 	/**
-	 * Return an array of timestamps in ascending order for the profile in question. If there are none, then
-	 * return an empty array.
+	 * Return an array of timestamps in ascending order for the profile id in question. 
+	 * If there are none, then return an empty array.
 	 * 
+	 * @param id the id of the profile to list timestamps for
 	 * @return the array of timestamps
 	 */
-	long[] listProfileTimestamps(String id);
+	public long[] listProfileTimestamps(String id);
 
 	/**
 	 * Return an array of profiles known to this registry. If there are none, then
@@ -59,28 +66,28 @@ public interface IProfileRegistry {
 	 * 
 	 * @return the array of profiles
 	 */
-	IProfile[] getProfiles();
+	public IProfile[] getProfiles();
 
 	/**
 	 * Add the given profile to this profile registry.
 	 * 
 	 * @param id the profile id
-	 * 
 	 * @throws ProvisionException if a profile
 	 *         with the same id is already present in the registry.
+	 * @return the new empty profile
 	 */
-	IProfile addProfile(String id) throws ProvisionException;
+	public IProfile addProfile(String id) throws ProvisionException;
 
 	/**
 	 * Add the given profile to this profile registry.
 	 * 
 	 * @param id the profile id
 	 * @param properties the profile properties
-	 * 
 	 * @throws ProvisionException if a profile
 	 *         with the same id is already present in the registry.
+	 * @return the new empty profile
 	 */
-	IProfile addProfile(String id, Map<String, String> properties) throws ProvisionException;
+	public IProfile addProfile(String id, Map<String, String> properties) throws ProvisionException;
 
 	/**
 	 * Returns whether this profile registry contains a profile with the given id.
@@ -98,10 +105,9 @@ public interface IProfileRegistry {
 	 * 
 	 * @param id the profile to remove
 	 * @param timestamp the timestamp of the profile to remove 
-	 * 
 	 * @throws ProvisionException if the profile with the specified id and timestamp is the current profile.
 	 */
-	void removeProfile(String id, long timestamp) throws ProvisionException;
+	public void removeProfile(String id, long timestamp) throws ProvisionException;
 
 	/**
 	 * Remove the given profile from this profile registry.  This method has no effect
@@ -109,7 +115,7 @@ public interface IProfileRegistry {
 	 * 
 	 * @param id the profile to remove
 	 */
-	void removeProfile(String id);
+	public void removeProfile(String id);
 
 	/**
 	 * Check if the given profile from this profile registry is up-to-date.
diff --git a/bundles/org.eclipse.equinox.p2.engine/src/org/eclipse/equinox/p2/engine/IProvisioningPlan.java b/bundles/org.eclipse.equinox.p2.engine/src/org/eclipse/equinox/p2/engine/IProvisioningPlan.java
index b4251fcf2..aa8fdcd26 100644
--- a/bundles/org.eclipse.equinox.p2.engine/src/org/eclipse/equinox/p2/engine/IProvisioningPlan.java
+++ b/bundles/org.eclipse.equinox.p2.engine/src/org/eclipse/equinox/p2/engine/IProvisioningPlan.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2009 IBM Corporation and others.
+ * Copyright (c) 2009, 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
@@ -30,7 +30,7 @@ public interface IProvisioningPlan {
 	 * 
 	 * @return The proposed profile additions
 	 */
-	public abstract IQueryable<IInstallableUnit> getAdditions();
+	public IQueryable<IInstallableUnit> getAdditions();
 
 	/**
 	 * Returns the provisioning context in which this plan was created.
@@ -46,23 +46,21 @@ public interface IProvisioningPlan {
 	 * 
 	 * @return The installer plan.
 	 */
-	public abstract IProvisioningPlan getInstallerPlan();
-
-	public abstract void setInstallerPlan(IProvisioningPlan installerPlan);
+	public IProvisioningPlan getInstallerPlan();
 
 	/**
 	 * Returns the profile that this plan will operate on.
 	 * 
 	 * @return The target profile for this plan
 	 */
-	public abstract IProfile getProfile();
+	public IProfile getProfile();
 
 	/**
 	 * Returns the proposed set of installable units to be removed from this profile.
 	 * 
 	 * @return The proposed profile removals.
 	 */
-	public abstract IQueryable<IInstallableUnit> getRemovals();
+	public IQueryable<IInstallableUnit> getRemovals();
 
 	/**
 	 * Returns the overall plan status. The severity of this status indicates
@@ -79,17 +77,98 @@ public interface IProvisioningPlan {
 	 * 
 	 * @return The overall plan status.
 	 */
-	public abstract IStatus getStatus();
-
-	public abstract void setStatus(IStatus status);
+	public IStatus getStatus();
 
+	/**
+	 * Adds an installable unit to the plan. This will cause the given installable unit
+	 * to be installed into the profile when this plan is executed by the engine. 
+	 * <p>
+	 * This is an advanced operation that should only be performed by clients crafting
+	 * their own custom plan. Most clients should instead use a planner service
+	 * to construct a valid plan based on a profile change request.
+	 * </p>
+	 * @param iu the installable unit to add
+	 */
 	public void addInstallableUnit(IInstallableUnit iu);
 
+	/**
+	 * Removes an installable unit from the plan. This will cause the given installable unit
+	 * to be remove from the profile when this plan is executed by the engine. 
+	 * <p>
+	 * This is an advanced operation that should only be performed by clients crafting
+	 * their own custom plan. Most clients should instead use a planner service
+	 * to construct a valid plan based on a profile change request.
+	 * </p>
+	 * @param iu the installable unit to add
+	 */
 	public void removeInstallableUnit(IInstallableUnit iu);
 
-	public void updateInstallableUnit(IInstallableUnit from, IInstallableUnit to);
+	/**
+	 * Adds a profile property corresponding to the given installable unit to the plan. 
+	 * This will cause the given installable unit property to be installed into the profile 
+	 * when this plan is executed by the engine. 
+	 * <p>
+	 * This is an advanced operation that should only be performed by clients crafting
+	 * their own custom plan. Most clients should instead use a planner service
+	 * to construct a valid plan based on a profile change request.
+	 * </p>
+	 * @param iu the installable unit to set a property for
+	 * @param name the property name
+	 * @param value the property value
+	 */
+	public void setInstallableUnitProfileProperty(IInstallableUnit iu, String name, String value);
+
+	/**
+	 * Sets the installer plan for this plan. The installer plan describes the set of changes
+	 * that must be made to the provisioning agent in order for this plan to execute
+	 * successfully.
+	 * <p>
+	 * This is an advanced operation that should only be performed by clients crafting
+	 * their own custom plan. Most clients should instead use a planner service
+	 * to construct a valid plan based on a profile change request.
+	 * </p>
+	 * @param installerPlan the plan describing changes to the provisioning agent
+	 */
+	public void setInstallerPlan(IProvisioningPlan installerPlan);
 
+	/**
+	 * Sets a profile property in the plan. This will cause the given property
+	 * to be added to the profile when this plan is executed by the engine. 
+	 * <p>
+	 * This is an advanced operation that should only be performed by clients crafting
+	 * their own custom plan. Most clients should instead use a planner service
+	 * to construct a valid plan based on a profile change request.
+	 * </p>
+	 * @param name the profile property name
+	 * @param value the profile property value
+	 */
 	public void setProfileProperty(String name, String value);
 
-	public void setInstallableUnitProfileProperty(IInstallableUnit iu, String name, String value);
+	/**
+	 * Sets the overall plan status, describing whether the planner constructing
+	 * this plan believes it will install successfully, or whether it contains errors
+	 * or the plan computation has been canceled.
+	 * <p>
+	 * This is an advanced operation that should only be performed by clients crafting
+	 * their own custom plan. Most clients should instead use a planner service
+	 * to construct a valid plan based on a profile change request.
+	 * </p>
+	 * @param status the plan status
+	 */
+	public void setStatus(IStatus status);
+
+	/**
+	 * Adds an instruction to replace one installable unit in the profile with another.
+	 * This will cause the 'from' installable unit property to be uninstalled from the profile 
+	 * and the 'to' installable unit to be added to the profile when this plan is executed 
+	 * by the engine. 
+	 * <p>
+	 * This is an advanced operation that should only be performed by clients crafting
+	 * their own custom plan. Most clients should instead use a planner service
+	 * to construct a valid plan based on a profile change request.
+	 * </p>
+	 * @param from the installable unit to remove
+	 * @param to the installable unit to add
+	 */
+	public void updateInstallableUnit(IInstallableUnit from, IInstallableUnit to);
 }
\ No newline at end of file