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, 2011.  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 java.util.List;
019    
020    import javax.wvcm.Feedback;
021    import javax.wvcm.PropertyNameList.PropertyName;
022    import javax.wvcm.ResourceList;
023    import javax.wvcm.Version;
024    import javax.wvcm.WvcmException;
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        /** Flags for the doMerge method */
049        enum CcMergeFlag {
050            /**
051             * Informs the merge that there is no data being sent.
052             * Just draw the merge arrow.
053             * Can not be specified with NO_ARROWS flag.
054             */
055            NO_DATA,
056            /**
057             * Requests to only merge the data sent. Do not draw the merge arrow.
058             * Can not be specified with NO_DATA flag.
059             */
060            NO_ARROWS;
061        }
062        
063        /**
064         * This version's branch.
065         */
066        PropertyName<CcBranch> BRANCH =
067            new PropertyName<CcBranch>(PROPERTY_NAMESPACE, "version-branch");
068    
069        /**
070         * Get the value of this version's {@link #BRANCH} property.
071         * 
072         * @return a proxy for this version's branch
073         * @throws WvcmException if property was not requested
074         */
075        public CcBranch getBranch() throws WvcmException;
076    
077        /**
078         * This version's element.
079         * @see javax.wvcm.Version#VERSION_HISTORY
080         */
081        PropertyName<CcElement> ELEMENT =
082            new PropertyName<CcElement>(PROPERTY_NAMESPACE, "version-element");
083    
084        /**
085         * Get the value of this version's {@link #ELEMENT} property.
086         * 
087         * @return a proxy for this version's element
088         * @throws WvcmException if property was not requested
089         */
090        public CcElement getElement() throws WvcmException;
091    
092        /**
093         * <p>
094         * The view-relative path for this version, possibly including
095         * the version extension.
096         * </p>
097         * <p>
098         * NOTE: This property is only available if it is retrieved
099         * using a method with a view context, such as
100         * Resource.doReadProperties(CcView, PropertyRequest).
101         * ClearCase needs a view context to resolve version paths.
102         * </p>
103         */
104        PropertyName<String> VIEW_RELATIVE_PATH =
105            new PropertyName<String>(PROPERTY_NAMESPACE, "version-view-relative-path");
106    
107        /**
108         * Get the value of this version's {@link #VIEW_RELATIVE_PATH} property.
109         * 
110         * @return view-relative path
111         * @throws WvcmException
112         *     if property was not requested, or if the view context
113         *     was not provided
114         */
115        public String getViewRelativePath() throws WvcmException;
116        
117        /**
118         * <p>
119         * The immediate predecessor of this version on this version's branch,
120         * or if this is the first version on the branch, the version from
121         * which the branch emanates.  Will be <code>null</code> if this version
122         * is the <code>/main/0</code> version of its element.
123         * </p>
124         */
125        PropertyName<CcVersion> PREDECESSOR = 
126            new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "predecessor");
127        
128        /**
129         * Get the value of this version's {@link #PREDECESSOR} property.
130         * @return a CcVersion proxy for this version's predecessor.
131         * @throws WvcmException if property was not requested.
132         */
133        public CcVersion getPredecessor() throws WvcmException;
134        
135        /**
136         * <p>
137         * The list of versions that were merged to create this version.
138         * This will be empty if this version was not created by a merge
139         * operation.
140         * </p>
141         */
142        PropertyName<ResourceList<CcVersion>> MERGE_CONTRIBUTOR_LIST = 
143            new PropertyName<ResourceList<CcVersion>>(PROPERTY_NAMESPACE, "merge-contributor-list");
144    
145        /**
146         * Get the value of this version's {@link #MERGE_CONTRIBUTOR_LIST} property.
147         * @return a list of the CcVersion proxies which represent merge contributors for this version.
148         * @throws WvcmException if property was not requested.
149         */
150        public ResourceList<CcVersion> getMergeContributorList() throws WvcmException;
151        
152        /**
153         * The list of tasks associated with this version.
154         */
155        PropertyName<List<CcTask>> TASK_LIST =
156            new PropertyName<List<CcTask>>(PROPERTY_NAMESPACE, "task-list");
157        
158        /**
159         * Get the value of this versions's (@link #TASK_LIST) property.
160         * @return a list of the tasks associated with this version. 
161         * @throws WvcmException if property was not requested.
162         */
163        public List<CcTask> getTaskList() throws WvcmException;
164        
165        /**
166         * Set the specified list of tasks as being associated with this version.
167         * Overwrites any existing associations.  Can be used to clear all associations
168         * by setting an empty list.
169         * @param tasks List of tasks to be associated with this version.
170         */
171        public void setTaskList(List<CcTask> tasks);
172        
173        /**
174         * Modify the list of tasks associated with this version by adding and
175         * removing the items from the specified lists.
176         * An intersection between the addition and removal lists is considered an error.
177         * @param taskAdditions List of tasks to be added to the list of 
178         * associations for this version.  Items in this list which are already associated
179         * with the version are ignored.
180         * @param taskRemovals List of tasks to be removed from the list of 
181         * associations for this version.  Items in this list which are not associated
182         * with the version are ignored.
183         */
184        public void setTaskList(List<CcTask> taskAdditions, List<CcTask> taskRemovals);
185            
186        /**
187         * Add the specified label to the version.
188         * @param label Label to be applied
189         * @param view View context
190         * @throws WvcmException
191         * @see javax.wvcm.Version#doAddLabel(java.lang.String, javax.wvcm.Feedback)
192         */
193        public Version doAddLabel(String label, CcView view, Feedback feedback) throws WvcmException;
194            
195        /**
196         * Set the specified label on the version.
197         * @param label Label to be applied
198         * @param view View context
199         * @throws WvcmException
200         * @see javax.wvcm.Version#doSetLabel(java.lang.String, javax.wvcm.Feedback)
201         */
202        public Version doSetLabel(String label, CcView view, Feedback feedback) throws WvcmException;
203        
204        /**
205         * Remove the specified label from the version.
206         * @param label Label to be removed
207         * @param view View context
208         * @throws WvcmException
209         * @see javax.wvcm.Version#doRemoveLabel(java.lang.String, javax.wvcm.Feedback)
210         */
211        public Version doRemoveLabel(String label, CcView view, Feedback feedback) throws WvcmException;
212    
213        /**
214         * Create a Merge hyperlink pointing from this version to the specified destination version.
215         * @param toVersion Destination version for the hyperlink
216         * @return A new proxy for this version, whose properties are specified by feedback.
217         */
218        public CcVersion doCreateMergeArrow(CcVersion toVersion, Feedback feedback) throws WvcmException;
219        
220    }