001/*
002 * file VersionHistory.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 *
007 * (c) Copyright IBM Corporation 2004, 2008.  All Rights Reserved. 
008 * Note to U.S. Government Users Restricted Rights:  Use, duplication or  
009 * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp. 
010 */
011package javax.wvcm;
012
013import javax.wvcm.PropertyNameList.PropertyName;
014import javax.wvcm.WvcmException.ReasonCode;
015
016
017/**
018 * A proxy for a version history resource.
019 * 
020 * A version history resource contains all versions of a version-controlled resource
021 * as the bound members of the version history.
022 * The binding name of a version in a version history is the version name of that version.
023 * When a version is removed as a bound member from its version history,
024 * it is also removed from any other folder that contains it as a bound member.
025 * 
026 * @since 1.0
027 */
028public interface VersionHistory extends Folder {
029
030    /**
031     * Get the workspace provider of this resource.
032     * 
033     * @return the {@link WorkspaceProvider} for this Resource.
034     */
035    public WorkspaceProvider workspaceProvider();
036
037    /**
038     * The root version of this VersionHistory.
039     * The root version has no predecessors,
040     * and every other version in this version history
041     * is a descendant of the root version.
042     */
043    public static final PropertyName<Version> ROOT_VERSION =
044        new PropertyName<Version>("root-version"); //$NON-NLS-1$
045
046    /**
047     * Get the {@link #ROOT_VERSION} property.
048     * 
049     * @return the {@link #ROOT_VERSION} property.
050     * @throws WvcmException if this VersionHistory was not created with
051     * {@link #ROOT_VERSION} as a wanted property.
052     */
053    public Version getRootVersion() throws WvcmException;
054
055    /**
056     * Get the latest Version for a given activity.
057     * 
058     * @param activity the activity whose latest product is to be returned.
059     * @param feedback the properties available in the returned proxies.
060     * @return the latest Version in this VersionHistory
061     * that is a product of the specified activity. May be <code>null</code>.
062     * @throws WvcmException ReasonCode:
063     * <li>{@link ReasonCode#METHOD_NOT_SUPPORTED}:
064     *  This resource does not support this report.
065     * <li>{@link ReasonCode#BAD_ARGUMENT_TYPE}:
066     *  The activity argument MUST identify an activity.  
067     */
068    public Version doLatestActivityVersionReport(
069            Activity activity,
070            Feedback feedback)
071    throws WvcmException;
072
073}