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