001    /*
002     * file CcVersion.java
003     *
004     * Licensed Materials - Property of IBM
005     * Restricted Materials of IBM 
006     *
007     * com.ibm.rational.wvcm.stp.cc.CcVersion
008     *
009     * © Copyright IBM Corporation 2004, 2008.  All Rights Reserved.
010     * Note to U.S. Government Users Restricted Rights:  Use, duplication or 
011     * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp.
012     */
013    
014    package com.ibm.rational.wvcm.stp.cc;
015    
016    import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017    
018    import javax.wvcm.Feedback;
019    import javax.wvcm.ResourceList;
020    import javax.wvcm.Version;
021    import javax.wvcm.WvcmException;
022    import javax.wvcm.PropertyNameList.PropertyName;
023    
024    import com.ibm.rational.wvcm.stpex.StpExBase;
025    
026    /**
027     * <p>
028     * A proxy for a version of a ClearCase element.
029     * </p>
030     * <p>
031     * Each time a new revision of a version-controlled file or 
032     * directory is checked in, a new <i>version</i> of that element is created. 
033     * Versions are created, in sequence, on the branch of an element selected
034     * by the view's config spec. 
035     * </p>
036     * <p>
037     * For more information about version, see the ClearCase "Guide to Developing Software"
038     * manual.
039     * </p>
040     * @see com.ibm.rational.wvcm.stp.cc.CcElement
041     * @see com.ibm.rational.wvcm.stp.cc.CcConfigSpec
042     * @see com.ibm.rational.wvcm.stp.cc.CcBranchType
043     */
044    public interface CcVersion
045        extends Version, CcVobResource 
046    {    
047        /**
048         * This version's element.
049         * @see javax.wvcm.Version#VERSION_HISTORY
050         */
051        PropertyName<CcElement> ELEMENT =
052            new PropertyName<CcElement>(PROPERTY_NAMESPACE, "version-element");
053    
054        /**
055         * Get the value of this version's {@link #ELEMENT} property.
056         * 
057         * @return a proxy for this version's element
058         * @throws WvcmException if property was not requested
059         */
060        public CcElement getElement() throws WvcmException;
061    
062        /**
063         * <p>
064         * The view-relative path for this version, possibly including
065         * the version extension.
066         * </p>
067         * <p>
068         * NOTE: This property is only available if it is retrieved
069         * using a method with a view context, such as
070         * Resource.doReadProperties(CcView, PropertyRequest).
071         * ClearCase needs a view context to resolve version paths.
072         * </p>
073         */
074        PropertyName<String> VIEW_RELATIVE_PATH =
075            new PropertyName<String>(PROPERTY_NAMESPACE, "version-view-relative-path");
076    
077        /**
078         * Get the value of this version's {@link #VIEW_RELATIVE_PATH} property.
079         * 
080         * @return view-relative path
081         * @throws WvcmException
082         *     if property was not requested, or if the view context
083         *     was not provided
084         */
085        public String getViewRelativePath() throws WvcmException;
086        
087        /**
088         * <p>
089         * The immediate predecessor of this version on this version's branch,
090         * or if this is the first version on the branch, the version from
091         * which the branch emanates.  Will be <code>null</code> if this version
092         * is the <code>/main/0</code> version of its element.
093         * </p>
094         */
095        PropertyName<CcVersion> PREDECESSOR = 
096            new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "predecessor");
097        
098        /**
099         * Get the value of this version's {@link #PREDECESSOR} property.
100         * @return a CcVersion proxy for this version's predecessor.
101         * @throws WvcmException if property was not requested.
102         */
103        public CcVersion getPredecessor() throws WvcmException;
104        
105        /**
106         * <p>
107         * The list of versions that were merged to create this version.
108         * This will be empty if this version was not created by a merge
109         * operation.
110         * </p>
111         */
112        PropertyName<ResourceList<CcVersion>> MERGE_CONTRIBUTOR_LIST = 
113            new PropertyName<ResourceList<CcVersion>>(PROPERTY_NAMESPACE, "merge-contributor-list");
114    
115        /**
116         * Get the value of this version's {@link #MERGE_CONTRIBUTOR_LIST} property.
117         * @return a list of the CcVersion proxies which represent merge contributors for this version.
118         * @throws WvcmException if property was not requested.
119         */
120        public ResourceList<CcVersion> getMergeContributorList() throws WvcmException;
121        
122        /**
123         * Add the specified label to the version.
124         * @param label Label to be applied
125         * @param view View context
126         * @throws WvcmException
127         * @see javax.wvcm.Version#doAddLabel(java.lang.String, javax.wvcm.Feedback)
128         */
129        public Version doAddLabel(String label, CcView view, Feedback feedback) throws WvcmException;
130            
131        /**
132         * Set the specified label on the version.
133         * @param label Label to be applied
134         * @param view View context
135         * @throws WvcmException
136         * @see javax.wvcm.Version#doSetLabel(java.lang.String, javax.wvcm.Feedback)
137         */
138        public Version doSetLabel(String label, CcView view, Feedback feedback) throws WvcmException;
139        
140        /**
141         * Remove the specified label from the version.
142         * @param label Label to be removed
143         * @param view View context
144         * @throws WvcmException
145         * @see javax.wvcm.Version#doRemoveLabel(java.lang.String, javax.wvcm.Feedback)
146         */
147        public Version doRemoveLabel(String label, CcView view, Feedback feedback) throws WvcmException;
148    
149        /**
150         * Create a Merge hyperlink pointing from this version to the specified destination version.
151         * @param toVersion Destination version for the hyperlink
152         * @return A new proxy for this version, whose properties are specified by feedback.
153         */
154        public CcVersion doCreateMergeArrow(CcVersion toVersion, Feedback feedback) throws WvcmException;
155    }