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     * (C) Copyright IBM Corporation 2004, 2009.  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.CcBranch
041     * @see com.ibm.rational.wvcm.stp.cc.CcElement
042     * @see com.ibm.rational.wvcm.stp.cc.CcConfigSpec
043     * @see com.ibm.rational.wvcm.stp.cc.CcBranchType
044     */
045    public interface CcVersion
046        extends Version, CcVobResource 
047    {    
048        /**
049         * This version's branch.
050         * @see javax.wvcm.Version#VERSION_BRANCH
051         */
052        PropertyName<CcBranch> BRANCH =
053            new PropertyName<CcBranch>(PROPERTY_NAMESPACE, "version-branch");
054    
055        /**
056         * Get the value of this version's {@link #BRANCH} property.
057         * 
058         * @return a proxy for this version's branch
059         * @throws WvcmException if property was not requested
060         */
061        public CcBranch getBranch() throws WvcmException;
062    
063        /**
064         * This version's element.
065         * @see javax.wvcm.Version#VERSION_HISTORY
066         */
067        PropertyName<CcElement> ELEMENT =
068            new PropertyName<CcElement>(PROPERTY_NAMESPACE, "version-element");
069    
070        /**
071         * Get the value of this version's {@link #ELEMENT} property.
072         * 
073         * @return a proxy for this version's element
074         * @throws WvcmException if property was not requested
075         */
076        public CcElement getElement() throws WvcmException;
077    
078        /**
079         * <p>
080         * The view-relative path for this version, possibly including
081         * the version extension.
082         * </p>
083         * <p>
084         * NOTE: This property is only available if it is retrieved
085         * using a method with a view context, such as
086         * Resource.doReadProperties(CcView, PropertyRequest).
087         * ClearCase needs a view context to resolve version paths.
088         * </p>
089         */
090        PropertyName<String> VIEW_RELATIVE_PATH =
091            new PropertyName<String>(PROPERTY_NAMESPACE, "version-view-relative-path");
092    
093        /**
094         * Get the value of this version's {@link #VIEW_RELATIVE_PATH} property.
095         * 
096         * @return view-relative path
097         * @throws WvcmException
098         *     if property was not requested, or if the view context
099         *     was not provided
100         */
101        public String getViewRelativePath() throws WvcmException;
102        
103        /**
104         * <p>
105         * The immediate predecessor of this version on this version's branch,
106         * or if this is the first version on the branch, the version from
107         * which the branch emanates.  Will be <code>null</code> if this version
108         * is the <code>/main/0</code> version of its element.
109         * </p>
110         */
111        PropertyName<CcVersion> PREDECESSOR = 
112            new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "predecessor");
113        
114        /**
115         * Get the value of this version's {@link #PREDECESSOR} property.
116         * @return a CcVersion proxy for this version's predecessor.
117         * @throws WvcmException if property was not requested.
118         */
119        public CcVersion getPredecessor() throws WvcmException;
120        
121        /**
122         * <p>
123         * The list of versions that were merged to create this version.
124         * This will be empty if this version was not created by a merge
125         * operation.
126         * </p>
127         */
128        PropertyName<ResourceList<CcVersion>> MERGE_CONTRIBUTOR_LIST = 
129            new PropertyName<ResourceList<CcVersion>>(PROPERTY_NAMESPACE, "merge-contributor-list");
130    
131        /**
132         * Get the value of this version's {@link #MERGE_CONTRIBUTOR_LIST} property.
133         * @return a list of the CcVersion proxies which represent merge contributors for this version.
134         * @throws WvcmException if property was not requested.
135         */
136        public ResourceList<CcVersion> getMergeContributorList() throws WvcmException;
137        
138        /**
139         * Add the specified label to the version.
140         * @param label Label to be applied
141         * @param view View context
142         * @throws WvcmException
143         * @see javax.wvcm.Version#doAddLabel(java.lang.String, javax.wvcm.Feedback)
144         */
145        public Version doAddLabel(String label, CcView view, Feedback feedback) throws WvcmException;
146            
147        /**
148         * Set the specified label on the version.
149         * @param label Label to be applied
150         * @param view View context
151         * @throws WvcmException
152         * @see javax.wvcm.Version#doSetLabel(java.lang.String, javax.wvcm.Feedback)
153         */
154        public Version doSetLabel(String label, CcView view, Feedback feedback) throws WvcmException;
155        
156        /**
157         * Remove the specified label from the version.
158         * @param label Label to be removed
159         * @param view View context
160         * @throws WvcmException
161         * @see javax.wvcm.Version#doRemoveLabel(java.lang.String, javax.wvcm.Feedback)
162         */
163        public Version doRemoveLabel(String label, CcView view, Feedback feedback) throws WvcmException;
164    
165        /**
166         * Create a Merge hyperlink pointing from this version to the specified destination version.
167         * @param toVersion Destination version for the hyperlink
168         * @return A new proxy for this version, whose properties are specified by feedback.
169         */
170        public CcVersion doCreateMergeArrow(CcVersion toVersion, Feedback feedback) throws WvcmException;
171    }