001 /* 002 * file CcBaseline.java 003 * 004 * Licensed Materials - Property of IBM 005 * Restricted Materials of IBM 006 * 007 * com.ibm.rational.wvcm.stp.cc.CcBaseline 008 * 009 * © Copyright IBM Corporation 2004, 2008. 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.Resource; 020 import javax.wvcm.ResourceList; 021 import javax.wvcm.WvcmException; 022 import javax.wvcm.PropertyNameList.PropertyName; 023 import javax.wvcm.ResourceList.ResponseIterator; 024 import javax.wvcm.WvcmException.ReasonCode; 025 026 import com.ibm.rational.wvcm.stpex.StpExEnumeration; 027 028 /** 029 * <p>A proxy for a ClearCase UCM baseline. 030 * </p> 031 * <p> 032 * A UCM baseline represents a snapshot of the changes made to a particular 033 * component in the context of a particular UCM stream: it is a version of a 034 * UCM component, recording a version of each element selected by the stream's 035 * configuration. The baseline also records the list of activities in the 036 * stream whose change sets contain versions of the component's elements. 037 * </p> 038 * <p>UCM baseline creation differs from the standard WVCM baseline creation model 039 * and cannot currently be performed using the CM API. 040 * Instead of checking out a UCM component to create a new UCM baseline, the 041 * user performs a <i>make baseline </i> operation in the UCM stream. By default this 042 * operation automatically creates a new baseline for every component in that 043 * stream's configuration that has been modified in that stream since the last 044 * <i>make baseline </i> operation. 045 * </p> 046 * <p>Every component has an <i>initial </i> (root) baseline, which is analogous to 047 * a ClearCase element's <i>/main/0 </i> version in that it is empty, and serves 048 * as the root of the baseline graph. 049 * </p> 050 * <p>An <i>import</i> baseline contains the set of versions labeled with a 051 * particular label, and is typically used to import non-UCM versions into 052 * a UCM project. 053 * </p> 054 */ 055 public interface CcBaseline extends javax.wvcm.Baseline, CcVobResource { 056 057 /** 058 * @see javax.wvcm.Baseline.AddedActivity 059 */ 060 public interface AddedActivityEx extends AddedActivity { 061 062 /** 063 * Get the list of versions in the added activity. 064 * @return List of CcVersion proxies 065 */ 066 public ResourceList<CcVersion> getVersions(); 067 068 } 069 070 /** 071 * @see javax.wvcm.Baseline.DeletedActivity 072 */ 073 public interface DeletedActivityEx extends DeletedActivity { 074 075 /** 076 * Get the list of versions in the deleted activity. 077 * @return List of CcVersion proxies 078 */ 079 public ResourceList<CcVersion> getVersions(); 080 } 081 082 /** 083 * @see javax.wvcm.Baseline.PartiallyAddedActivity 084 */ 085 public interface PartiallyAddedActivityEx extends PartiallyAddedActivity { 086 087 /** 088 * Get the list of versions in the partially added activity. 089 * @return List of CcVersion proxies 090 */ 091 public ResourceList<CcVersion> getVersions(); 092 } 093 094 /** 095 * @see javax.wvcm.Baseline.PartiallyDeletedActivity 096 */ 097 public interface PartiallyDeletedActivityEx extends PartiallyDeletedActivity { 098 099 /** 100 * Get the list of versions in the partially deleted activity. 101 * @return List of CcVersion proxies 102 */ 103 public ResourceList<CcVersion> getVersions(); 104 } 105 106 /** 107 * Boolean flags for the doCompareReportEx method. 108 */ 109 enum CompareFlagEx implements StpExEnumeration { 110 /** 111 * Provide differences in terms of activites. 112 */ 113 ACTIVITIES("activities"), 114 115 /** 116 * Provide differences in terms of baselines. 117 */ 118 BASELINES("baselines"), 119 120 /** 121 * Provide differences in terms of versions. 122 */ 123 VERSIONS("versions"); 124 125 private CompareFlagEx(String flagName) { _flagName = flagName; } 126 127 /** 128 * Returns a string representation of this flag suitable for diagnostics. 129 */ 130 public String toString() { return _flagName; } 131 132 /** 133 * The string form of this flag. 134 */ 135 private final String _flagName; 136 } 137 138 /** 139 * Labeling status of this baseline. 140 */ 141 enum LabelingStatus implements StpExEnumeration { 142 /** Unlabeled baseline */ 143 NOT_LABELED, 144 145 /** Incrementally labeled baseline */ 146 INCREMENTALLY_LABELED, 147 148 /** Fully labeled baseline */ 149 FULLY_LABELED, 150 151 /** Special case: not labeled but doesn't need to be */ 152 IS_INITIAL, 153 154 /** Baseline of a rootless component */ 155 NO_VERSIONS_TO_LABEL; 156 } 157 158 /** 159 * @deprecated use {@link #doCompareReportEx(CcBaseline, com.ibm.rational.wvcm.stp.cc.CcBaseline.CompareFlagEx[], Resource, Feedback)} 160 */ 161 162 public ResponseIterator<CompareReport> 163 doCompareReportEx(CcBaseline baseline, CompareFlagEx[] flags, Feedback feedback) 164 throws WvcmException; 165 166 /** 167 * @deprecated use {@link #doCompareReportEx(CcStream, com.ibm.rational.wvcm.stp.cc.CcBaseline.CompareFlagEx[], Resource, Feedback)} 168 */ 169 public ResponseIterator<CompareReport> 170 doCompareReportEx(CcStream stream, CompareFlagEx[] flags, Feedback feedback) 171 throws WvcmException; 172 173 /** 174 * <p>Compare two baselines, ClearCase-style.</p> 175 * 176 * @param baseline the baseline being compared to this CcBaseline. 177 * @param flags specifies the types of differences to include in the 178 * compare report. 179 * @param context optional resource (often CcView) providing context for the 180 * generation of certain properties in the returned report. 181 * May be <b>null</b>. 182 * @param feedback the properties available in the returned proxies. 183 * @return a ResponseIterator of CompareReport objects, that enumerate the 184 * differences between the versions selected by this CcBaseline and 185 * the baseline argument. 186 * @throws WvcmException 187 */ 188 public ResponseIterator<CompareReport> 189 doCompareReportEx(CcBaseline baseline, CompareFlagEx[] flags, Resource context, Feedback feedback) 190 throws WvcmException; 191 192 /** 193 * <p> 194 * Compare this baseline with the specified stream. 195 * </p> 196 * <p> 197 * All baselines in the stream are used in the comparison as well 198 * as any changes in the stream that are not yet captured in a baseline. 199 * </p> 200 * @param stream the stream being compared to this CcBaseline. 201 * @param flags specifies the types of differences to include in the 202 * compare report. 203 * @param context optional resource (often CcView) providing context for the 204 * generation of certain properties in the returned report. 205 * May be <b>null</b>. 206 * @param feedback the properties available in the returned proxies. 207 * @return a ResponseIterator of CompareReport objects that enumerate the 208 * differences between the versions selected by this CcBaseline and 209 * the stream argument. 210 * @throws WvcmException 211 */ 212 public ResponseIterator<CompareReport> 213 doCompareReportEx(CcStream stream, CompareFlagEx[] flags, Resource context, Feedback feedback) 214 throws WvcmException; 215 216 /** 217 * The UCM component for which this is a baseline. 218 */ 219 PropertyName<CcComponent> COMPONENT = 220 new PropertyName<CcComponent>(PROPERTY_NAMESPACE, "baseline-component"); 221 222 /** 223 * Get the the {@link #COMPONENT} property of this baseline. 224 * @return a client proxy for the UCM component that this baseline is in. 225 * Will never be null. 226 * @throws WvcmException if this proxy doesn't define a value for this property. 227 */ 228 public CcComponent getComponent() throws WvcmException; 229 230 /** 231 * Is this baseline an "import" baseline? 232 */ 233 PropertyName<Boolean> IS_IMPORT = 234 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "baseline-is-import"); 235 236 /** 237 * Get the {@link #IS_IMPORT} property of this baseline. 238 * @return true if this is an import baseline, else false 239 * @throws WvcmException if this proxy doesn't define a value for this property. 240 */ 241 boolean getIsImport() throws WvcmException; 242 243 /** 244 * Is this baseline the initial baseline for its component? 245 */ 246 PropertyName<Boolean> IS_INITIAL = 247 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "baseline-is-initial"); 248 249 /** 250 * Get the {@link #IS_INITIAL} property of this baseline. 251 * @return true if this is the initial baseline for its component, else false 252 * @throws WvcmException if this proxy doesn't define a value for this property. 253 */ 254 boolean getIsInitial() throws WvcmException; 255 256 /** This baseline's labeling status. One of: 257 * <br>{@link LabelingStatus#NOT_LABELED} 258 * <br>{@link LabelingStatus#INCREMENTALLY_LABELED} 259 * <br>{@link LabelingStatus#FULLY_LABELED} 260 * <br>{@link LabelingStatus#IS_INITIAL} 261 * <br>{@link LabelingStatus#NO_VERSIONS_TO_LABEL} 262 */ 263 PropertyName<LabelingStatus> LABELING_STATUS = 264 new PropertyName<LabelingStatus>(PROPERTY_NAMESPACE, "labeling-status"); 265 266 /** 267 * Get the {@link #LABELING_STATUS} property of this baseline. 268 * @return A {@link LabelingStatus} enumerator indicating the labeling 269 * status of this baseline. 270 * @throws WvcmException if this proxy doesn't define a value for this property. 271 */ 272 LabelingStatus getLabelingStatus() throws WvcmException; 273 274 /** 275 * The promotion level of this baseline. 276 * <p> 277 * Each project VOB includes an ordered set of promotion levels that 278 * can be assigned to baselines to indicate the quality or degree of 279 * completeness of the activities and versions represented by the baseline. 280 */ 281 PropertyName<String> PROMOTION_LEVEL = 282 new PropertyName<String>(PROPERTY_NAMESPACE, "promotion-level"); 283 284 /** 285 * Get the {@link #PROMOTION_LEVEL} property of this baseline. 286 * @return the {@link #PROMOTION_LEVEL} of this baseline, as a string. 287 * @throws WvcmException if this proxy doesn't define a value for this property. 288 */ 289 String getPromotionLevel() throws WvcmException; 290 291 /** 292 * Set the value of this baseline's {@link #PROMOTION_LEVEL} property. 293 * @param promotionLevel the promotion level of this baseline. 294 */ 295 void setPromotionLevel(String promotionLevel); 296 297 /** 298 * The stream in which this baseline was created. Will be null for "import" 299 * and "initial" baselines because they are not created in a stream context. 300 */ 301 PropertyName<CcStream> STREAM = 302 new PropertyName<CcStream>(PROPERTY_NAMESPACE, "baseline-stream"); 303 304 /** 305 * Get the the {@link #STREAM} property of this baseline. 306 * @return a client proxy for the UCM stream in which this baseline was 307 * created. Will be null if this is an import or initial baseline. 308 * @throws WvcmException if this proxy doesn't define a value for this property. 309 */ 310 public CcStream getStream() throws WvcmException; 311 312 /** 313 * The list of sub-baselines of this composite baseline. 314 * As a configuration gets 315 * large, it is often useful to break it up into a set of smaller 316 * configurations that form the logical components of that configuration. 317 * The sub-baseline list of a baseline of a configuration captures the set 318 * of baselines of the component sub-configurations. 319 */ 320 PropertyName<ResourceList<CcBaseline>> SUBBASELINE_LIST = 321 new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE, "subbaseline-list"); 322 323 /** 324 * Get the {@link #SUBBASELINE_LIST} property. 325 * @return list of CcBaseline proxies for this baseline 326 * @throws WvcmException if this proxy doesn't define a value for this property. 327 */ 328 public ResourceList<CcBaseline> getSubbaselineList() throws WvcmException; 329 }