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, 2015.  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.PropertyNameList.PropertyName;
020    import javax.wvcm.ResourceList;
021    import javax.wvcm.Task;
022    import javax.wvcm.Version;
023    import javax.wvcm.WvcmException;
024    
025    /**
026     * <p>
027     * A proxy for a version of a ClearCase element.
028     * </p>
029     * <p>
030     * Each time a new revision of a version-controlled file or 
031     * directory is checked in, a new <i>version</i> of that element is created. 
032     * Versions are created, in sequence, on the branch of an element selected
033     * by the view's config spec. 
034     * </p>
035     * <p>
036     * For more information about version, see the ClearCase "Guide to Developing Software"
037     * manual.
038     * </p>
039     * @see com.ibm.rational.wvcm.stp.cc.CcBranch
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        /** Flags for the doMerge method */
048        enum CcMergeFlag {
049            /**
050             * Informs the merge that there is no data being sent.
051             * Just draw the merge arrow.
052             * Can not be specified with NO_ARROWS flag.
053             */
054            NO_DATA,
055            /**
056             * Requests to only merge the data sent. Do not draw the merge arrow.
057             * Can not be specified with NO_DATA flag.
058             */
059            NO_ARROWS,
060            /**
061             * If a merge arrow already exists, this will delete and replace that 
062             * merge arrow. Does nothing when specified with the NO_ARROWS flag.
063             * This flag is currently unsupported for merge in automatic views.
064             */
065            REPLACE;
066        }
067        
068        /**
069         * This version's branch.
070         */
071        PropertyName<CcBranch> BRANCH =
072            new PropertyName<CcBranch>(PROPERTY_NAMESPACE, "version-branch");
073    
074        /**
075         * Get the value of this version's {@link #BRANCH} property.
076         * 
077         * @return a proxy for this version's branch
078         * @throws WvcmException if property was not requested
079         */
080        public CcBranch getBranch() throws WvcmException;
081    
082        /**
083         * This version's element.
084         * @see javax.wvcm.Version#VERSION_HISTORY
085         */
086        PropertyName<CcElement> ELEMENT =
087            new PropertyName<CcElement>(PROPERTY_NAMESPACE, "version-element");
088    
089        /**
090         * Get the value of this version's {@link #ELEMENT} property.
091         * 
092         * @return a proxy for this version's element
093         * @throws WvcmException if property was not requested
094         */
095        public CcElement getElement() throws WvcmException;
096    
097        /**
098         * <p>
099         * The view-relative path for this version, possibly including
100         * the version extension.
101         * </p>
102         * <p>
103         * NOTE: This property is only available if it is retrieved
104         * using a method with a view context, such as
105         * Resource.doReadProperties(CcView, PropertyRequest).
106         * ClearCase needs a view context to resolve version paths.
107         * </p>
108         */
109        PropertyName<String> VIEW_RELATIVE_PATH =
110            new PropertyName<String>(PROPERTY_NAMESPACE, "version-view-relative-path");
111    
112        /**
113         * Get the value of this version's {@link #VIEW_RELATIVE_PATH} property.
114         * 
115         * @return view-relative path
116         * @throws WvcmException
117         *     if property was not requested, or if the view context
118         *     was not provided
119         */
120        public String getViewRelativePath() throws WvcmException;
121        
122        /**
123         * <p>
124         * The immediate predecessor of this version on this version's branch,
125         * or if this is the first version on the branch, the version from
126         * which the branch emanates.  Will be <code>null</code> if this version
127         * is the <code>/main/0</code> version of its element.
128         * </p>
129         */
130        PropertyName<CcVersion> PREDECESSOR = 
131            new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "predecessor");
132        
133        /**
134         * Get the value of this version's {@link #PREDECESSOR} property.
135         * @return a CcVersion proxy for this version's predecessor.
136         * @throws WvcmException if property was not requested.
137         */
138        public CcVersion getPredecessor() throws WvcmException;
139        
140        /**
141         * <p>
142         * The list of versions that were merged to create this version.
143         * This will be empty if this version was not created by a merge
144         * operation.
145         * </p>
146         */
147        PropertyName<ResourceList<CcVersion>> MERGE_CONTRIBUTOR_LIST = 
148            new PropertyName<ResourceList<CcVersion>>(PROPERTY_NAMESPACE, "merge-contributor-list");
149    
150        /**
151         * Get the value of this version's {@link #MERGE_CONTRIBUTOR_LIST} property.
152         * @return a list of the CcVersion proxies which represent merge contributors for this version.
153         * @throws WvcmException if property was not requested.
154         */
155        public ResourceList<CcVersion> getMergeContributorList() throws WvcmException;
156        
157        /**
158         * The list of tasks associated with this version.
159         */
160        public PropertyName<ResourceList<Task>> TASK_LIST =
161            new PropertyName<ResourceList<Task>>(PROPERTY_NAMESPACE, "version-task-list");
162        
163        /**
164         * Get the value of this versions's (@link #TASK_LIST) property.
165         * @return a list of the tasks associated with this version. 
166         * @throws WvcmException if property was not requested.
167         */
168        public ResourceList<Task> getTaskList() throws WvcmException;
169        
170        /**
171         * Set the specified list of tasks as being associated with this version.
172         * Overwrites any existing associations.  Can be used to clear all associations
173         * by setting an empty list.
174         * @param tasks List of tasks to be associated with this version.
175         */
176        public void setTaskList(ResourceList<Task> tasks) throws WvcmException;
177        
178        /**
179         * Modify the list of tasks associated with this version by adding and
180         * removing the items from the specified lists.
181         * An intersection between the addition and removal lists is considered an error.
182         * @param taskAdditions List of tasks to be added to the list of 
183         * associations for this version.  Items in this list which are already associated
184         * with the version are ignored.
185         * @param taskRemovals List of tasks to be removed from the list of 
186         * associations for this version.  Items in this list which are not associated
187         * with the version are ignored.
188         */
189        public void setTaskList(ResourceList<Task> taskAdditions, ResourceList<Task> taskRemovals) throws WvcmException;
190    
191        /**
192         * Add the specified label to the version.
193         * @param label Label to be applied
194         * @param view View context
195         * @throws WvcmException
196         * @see javax.wvcm.Version#doAddLabel(java.lang.String, javax.wvcm.Feedback)
197         */
198        public Version doAddLabel(String label, CcView view, Feedback feedback) throws WvcmException;    
199        
200        /**
201         * Add the specified label to the version.
202         * @param comment The comment for this operation, or null for no comment
203         * @param label Label to be applied
204         * @param view View context
205         * @throws WvcmException
206         * @see javax.wvcm.Version#doAddLabel(java.lang.String, javax.wvcm.Feedback)
207         */
208        public Version doAddLabel(String comment, String label, CcView view, Feedback feedback) throws WvcmException;
209    
210        /**
211         * Set the specified label on the version.
212         * @param label Label to be applied
213         * @param view View context
214         * @throws WvcmException
215         * @see javax.wvcm.Version#doSetLabel(java.lang.String, javax.wvcm.Feedback)
216         */
217        public Version doSetLabel(String label, CcView view, Feedback feedback) throws WvcmException;    
218        
219        
220        /**
221         * Set the specified label on the version.
222         * @param comment The comment for this operation, or null for no comment
223         * @param label Label to be applied
224         * @param view View context
225         * @throws WvcmException
226         * @see javax.wvcm.Version#doSetLabel(java.lang.String, javax.wvcm.Feedback)
227         */
228        public Version doSetLabel(String comment, String label, CcView view, Feedback feedback) throws WvcmException;
229        
230        /**
231         * Remove the specified label from the version.
232         * @param label Label to be removed
233         * @param view View context
234         * @throws WvcmException
235         * @see javax.wvcm.Version#doRemoveLabel(java.lang.String, javax.wvcm.Feedback)
236         */
237        public Version doRemoveLabel(String label, CcView view, Feedback feedback) throws WvcmException;
238    
239        /**
240         * Create a Merge hyperlink pointing from this version to the specified destination version.
241         * @param toVersion Destination version for the hyperlink
242         * @return A new proxy for this version, whose properties are specified by feedback.
243         */
244        public CcVersion doCreateMergeArrow(CcVersion toVersion, Feedback feedback) throws WvcmException;
245        
246        /**
247         * Create a Merge hyperlink pointing from this version to the specified destination version.
248         * @param toVersion Destination version for the hyperlink
249         * @param view View context (ensures path EVs set for mkhlink when a merge is being made).
250         * @return A new proxy for this version, whose properties are specified by feedback.
251         */
252        public CcVersion doCreateMergeArrow(CcVersion toVersion, CcView view, Feedback feedback) throws WvcmException;
253        
254    }