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