001/* 002 * file CcVersion.java 003 * 004 * Licensed Materials - Property of IBM and/or HCL 005 * Restricted Materials of IBM and/or HCL 006 * 007 * com.ibm.rational.wvcm.stp.cc.CcVersion 008 * 009 * (C) Copyright IBM Corporation 2004, 2016. All Rights Reserved. 010 * (C) Copyright HCL Technologies Ltd. 2017 All rights reserved. 011 * Note to U.S. Government Users Restricted Rights: Use, duplication or 012 * disclosure restricted by GSA ADP Schedule Contract with IBM Corp. 013 */ 014 015package com.ibm.rational.wvcm.stp.cc; 016 017import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE; 018 019import javax.wvcm.Feedback; 020import javax.wvcm.PropertyNameList.PropertyName; 021import javax.wvcm.ResourceList; 022import javax.wvcm.Task; 023import javax.wvcm.Version; 024import 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 */ 045public interface CcVersion 046 extends Version, CcVobResource 047{ 048 /** Flags for the <code>doCcCheckout</code> method. */ 049 enum CcCheckoutFlag { 050 051 /** 052 * Indicates whether to checkout this file reserved. 053 */ 054 RESERVED, 055 056 /** 057 * Fall back to unreserved if a reservation can not be obtained. 058 */ 059 FALLBACK_TO_UNRESERVED, 060 061 /** 062 * Indicates whether to checkout this file even if the 063 * relevant branch is mastered by another replica. The 064 * <code>RESERVED</code> flag must NOT be set with this flag. 065 * 066 * <p>If the file is mastered by this replica, setting this 067 * flag has no effect. 068 */ 069 NON_MASTERED_OK, 070 071 /** 072 * After a file is 'checkedout', set the file's "last modified" 073 * time to be the time when the version was first created. 074 * <p>This only applies to dynamic views. 075 */ 076 PRESERVE_MODIFICATION_TIME; 077 } 078 079 080 /** Flags for the doMerge method */ 081 enum CcMergeFlag { 082 /** 083 * Informs the merge that there is no data being sent. 084 * Just draw the merge arrow. 085 * Can not be specified with NO_ARROWS flag. 086 */ 087 NO_DATA, 088 /** 089 * Requests to only merge the data sent. Do not draw the merge arrow. 090 * Can not be specified with NO_DATA flag. 091 */ 092 NO_ARROWS, 093 /** 094 * If a merge arrow already exists, this will delete and replace that 095 * merge arrow. Does nothing when specified with the NO_ARROWS flag. 096 * This flag is currently unsupported for merge in automatic views. 097 */ 098 REPLACE; 099 } 100 101 /** 102 * This version's branch. 103 */ 104 PropertyName<CcBranch> BRANCH = 105 new PropertyName<CcBranch>(PROPERTY_NAMESPACE, "version-branch"); 106 107 /** 108 * Get the value of this version's {@link #BRANCH} property. 109 * 110 * @return a proxy for this version's branch 111 * @throws WvcmException if property was not requested 112 */ 113 public CcBranch getBranch() throws WvcmException; 114 115 /** 116 * This version's element. 117 * @see javax.wvcm.Version#VERSION_HISTORY 118 */ 119 PropertyName<CcElement> ELEMENT = 120 new PropertyName<CcElement>(PROPERTY_NAMESPACE, "version-element"); 121 122 /** 123 * Get the value of this version's {@link #ELEMENT} property. 124 * 125 * @return a proxy for this version's element 126 * @throws WvcmException if property was not requested 127 */ 128 public CcElement getElement() throws WvcmException; 129 130 /** 131 * <p> 132 * The view-relative path for this version, possibly including 133 * the version extension. 134 * </p> 135 * <p> 136 * NOTE: This property is only available if it is retrieved 137 * using a method with a view context, such as 138 * Resource.doReadProperties(CcView, PropertyRequest). 139 * ClearCase needs a view context to resolve version paths. 140 * </p> 141 */ 142 PropertyName<String> VIEW_RELATIVE_PATH = 143 new PropertyName<String>(PROPERTY_NAMESPACE, "version-view-relative-path"); 144 145 /** 146 * Get the value of this version's {@link #VIEW_RELATIVE_PATH} property. 147 * 148 * @return view-relative path 149 * @throws WvcmException 150 * if property was not requested, or if the view context 151 * was not provided 152 */ 153 public String getViewRelativePath() throws WvcmException; 154 155 /** 156 * <p> 157 * The immediate predecessor of this version on this version's branch, 158 * or if this is the first version on the branch, the version from 159 * which the branch emanates. Will be <code>null</code> if this version 160 * is the <code>/main/0</code> version of its element. 161 * </p> 162 */ 163 PropertyName<CcVersion> PREDECESSOR = 164 new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "predecessor"); 165 166 /** 167 * Get the value of this version's {@link #PREDECESSOR} property. 168 * @return a CcVersion proxy for this version's predecessor. 169 * @throws WvcmException if property was not requested. 170 */ 171 public CcVersion getPredecessor() throws WvcmException; 172 173 /** 174 * <p> 175 * The list of versions that were merged to create this version. 176 * This will be empty if this version was not created by a merge 177 * operation. 178 * </p> 179 */ 180 PropertyName<ResourceList<CcVersion>> MERGE_CONTRIBUTOR_LIST = 181 new PropertyName<ResourceList<CcVersion>>(PROPERTY_NAMESPACE, "merge-contributor-list"); 182 183 /** 184 * Get the value of this version's {@link #MERGE_CONTRIBUTOR_LIST} property. 185 * @return a list of the CcVersion proxies which represent merge contributors for this version. 186 * @throws WvcmException if property was not requested. 187 */ 188 public ResourceList<CcVersion> getMergeContributorList() throws WvcmException; 189 190 /** 191 * The list of tasks associated with this version. 192 */ 193 public PropertyName<ResourceList<Task>> TASK_LIST = 194 new PropertyName<ResourceList<Task>>(PROPERTY_NAMESPACE, "version-task-list"); 195 196 /** 197 * Get the value of this versions's (@link #TASK_LIST) property. 198 * @return a list of the tasks associated with this version. 199 * @throws WvcmException if property was not requested. 200 */ 201 public ResourceList<Task> getTaskList() throws WvcmException; 202 203 /** 204 * Set the specified list of tasks as being associated with this version. 205 * Overwrites any existing associations. Can be used to clear all associations 206 * by setting an empty list. 207 * @param tasks List of tasks to be associated with this version. 208 */ 209 public void setTaskList(ResourceList<Task> tasks) throws WvcmException; 210 211 /** 212 * Modify the list of tasks associated with this version by adding and 213 * removing the items from the specified lists. 214 * An intersection between the addition and removal lists is considered an error. 215 * @param taskAdditions List of tasks to be added to the list of 216 * associations for this version. Items in this list which are already associated 217 * with the version are ignored. 218 * @param taskRemovals List of tasks to be removed from the list of 219 * associations for this version. Items in this list which are not associated 220 * with the version are ignored. 221 */ 222 public void setTaskList(ResourceList<Task> taskAdditions, ResourceList<Task> taskRemovals) throws WvcmException; 223 224 /** 225 * Add the specified label to the version. 226 * @param label Label to be applied 227 * @param view View context 228 * @throws WvcmException 229 * @see javax.wvcm.Version#doAddLabel(java.lang.String, javax.wvcm.Feedback) 230 */ 231 public Version doAddLabel(String label, CcView view, Feedback feedback) throws WvcmException; 232 233 /** 234 * Add the specified label to the version. 235 * @param comment The comment for this operation, or null for no comment 236 * @param label Label to be applied 237 * @param view View context 238 * @throws WvcmException 239 * @see javax.wvcm.Version#doAddLabel(java.lang.String, javax.wvcm.Feedback) 240 */ 241 public Version doAddLabel(String comment, String label, CcView view, Feedback feedback) throws WvcmException; 242 243 /** 244 * Set the specified label on the version. 245 * @param label Label to be applied 246 * @param view View context 247 * @throws WvcmException 248 * @see javax.wvcm.Version#doSetLabel(java.lang.String, javax.wvcm.Feedback) 249 */ 250 public Version doSetLabel(String label, CcView view, Feedback feedback) throws WvcmException; 251 252 253 /** 254 * Set the specified label on the version. 255 * @param comment The comment for this operation, or null for no comment 256 * @param label Label to be applied 257 * @param view View context 258 * @throws WvcmException 259 * @see javax.wvcm.Version#doSetLabel(java.lang.String, javax.wvcm.Feedback) 260 */ 261 public Version doSetLabel(String comment, String label, CcView view, Feedback feedback) throws WvcmException; 262 263 /** 264 * Remove the specified label from the version. 265 * @param label Label to be removed 266 * @param view View context 267 * @throws WvcmException 268 * @see javax.wvcm.Version#doRemoveLabel(java.lang.String, javax.wvcm.Feedback) 269 */ 270 public Version doRemoveLabel(String label, CcView view, Feedback feedback) throws WvcmException; 271 272 /** 273 * Create a Merge hyperlink pointing from this version to the specified destination version. 274 * @param toVersion Destination version for the hyperlink 275 * @return A new proxy for this version, whose properties are specified by feedback. 276 */ 277 public CcVersion doCreateMergeArrow(CcVersion toVersion, Feedback feedback) throws WvcmException; 278 279 /** 280 * Create a Merge hyperlink pointing from this version to the specified destination version. 281 * @param toVersion Destination version for the hyperlink 282 * @param view View context (ensures path EVs set for mkhlink when a merge is being made). 283 * @return A new proxy for this version, whose properties are specified by feedback. 284 */ 285 public CcVersion doCreateMergeArrow(CcVersion toVersion, CcView view, Feedback feedback) throws WvcmException; 286 287 /** 288 * <p>Check out the specific version of a file or directory specified 289 * by this proxy. The resource is checked out to the specified ClearCase view. 290 * Note that directory version checkout is only supported for dynamic views. 291 * </p> 292 * <p>If the view is a UCM view, the caller must insure there is a 293 * {@link javax.wvcm.Workspace#CURRENT_ACTIVITY} for this operation. 294 * The checked out file will be added to the current activity's change set. 295 * The caller may explicitly specify an activity using this resource's 296 * {@link javax.wvcm.ControllableResource#setActivity} method. In that case, 297 * the specified activity will become the new current activity. 298 * Otherwise, the existing current activity will be used. 299 * If the view is a UCM view and there is no current activity, the operation 300 * will fail. 301 * </p> 302 * <p>The caller may optionally specify a checkout comment using this 303 * resource's {@link javax.wvcm.Resource#setComment} method. 304 * </p> 305 * @param flags array of flags which specify the behavior of the operation 306 * @param view View context 307 * @param feedback 308 * @return new CcFile proxy representing the checked out file in the specified view 309 * @throws WvcmException 310 */ 311 public CcFile doCcCheckout(CcCheckoutFlag[] flags, CcView view, Feedback feedback) 312 throws WvcmException; 313 314 /** 315 * Check to see if this version is an ancestor of the specified version. 316 * @param descVersion Version to check for relationship 317 * @return {@code true} if this version is an ancestor of descVersion, else {@code false} 318 * @throws WvcmException if versions are not from the same element 319 */ 320 public boolean doIsAncestorOf(CcVersion descVersion) throws WvcmException; 321}