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