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 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 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}