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