001 /* 002 * file CcView.java 003 * 004 * Licensed Materials - Property of IBM 005 * Restricted Materials of IBM 006 * 007 * com.ibm.rational.wvcm.stp.cc.CcView 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 java.io.File; 019 import java.util.Map; 020 021 import javax.wvcm.Feedback; 022 import javax.wvcm.Resource; 023 import javax.wvcm.Stream; 024 import javax.wvcm.WvcmException; 025 import javax.wvcm.PropertyNameList.PropertyName; 026 027 import com.ibm.rational.wvcm.stp.StpActivity; 028 import com.ibm.rational.wvcm.stp.cc.CcFileAreaLockedCallback.CcFileAreaLockInfo; 029 import com.ibm.rational.wvcm.stpex.StpExEnumeration; 030 031 /** 032 * <p>A proxy for a ClearCase view. ClearCase "view" and WVCM "workspace" 033 * are equivalent terms for the same type of resource. 034 * </p> 035 * <p>In this release, only ClearCase CCRC web views are supported. 036 * ClearCase dynamic and snapshot views are not currently supported. 037 * </p> 038 */ 039 public interface CcView 040 extends CcDirectory, javax.wvcm.Workspace 041 { 042 /** Values for view text mode */ 043 enum TextMode implements StpExEnumeration { 044 045 /** 046 * A transparent interop text mode. The line terminator for text files 047 * is a single <code>NL</code> character. The view does not transform 048 * text file line terminators in any way. This is the default text mode 049 * if no value is set upon view creation. 050 */ 051 TRANSPARENT("transparent"), 052 053 /** 054 * An insert_cr interop text mode. The view converts <code>NL</code> line 055 * terminators to the <code>CR NL</code> sequence when reading from a VOB, 056 * and <code>CR NL</code> line terminators to single <code>NL</code> 057 * characters when writing to the VOB. 058 */ 059 INSERT_CR("insert-cr"), 060 061 /** 062 * An nl_to_cr interop text mode. The view converts <code>NL</code> line 063 * terminators to <code>CR</code> characters when reading from a VOB, and 064 * <code>CR</code> line terminators to single <code>NL</code> characters 065 * wehn writing to the VOB. 066 */ 067 NL_TO_CR("nl-to-cr"), 068 069 /** 070 * A strip_cr interop text mode. The view converts <code>CR NL</code> line 071 * terminators to <code>NL</code> when reading from a VOB, and <code>NL</code> 072 * line terminators back to the <code>CR NL</code> sequence when writing to the VOB. 073 */ 074 STRIP_CR("strip-cr"); 075 076 private String m_name; 077 078 private TextMode(String name) { m_name = name; } 079 080 /* (non-Javadoc) 081 * @see java.lang.Object#toString() 082 */ 083 public String toString() { return m_name; } 084 } 085 086 /** Flags for the <code>doSynchronizeFileAreaDb</code> method */ 087 enum SynchronizeFileAreaDbFlag implements StpExEnumeration { 088 089 /** 090 * Synchronize the view's client-side vob database with the 091 * correct information from the server. Specifying this flag 092 * requires a server connection. 093 */ 094 FILE_AREA_VOB_DB("file-area-vob-db"), 095 096 /** 097 * Synchronize the view's client-side modified files database 098 * so that it correctly reflects files that have been modified 099 * as a result of checkouts or hijacks. Specifying this flag 100 * does <i>not</i> require a server connection. 101 */ 102 FILE_AREA_MODIFIED_FILES_DB("file-area-modified-files-db"); 103 104 private String m_name; 105 106 private SynchronizeFileAreaDbFlag(String name) { m_name = name; } 107 108 /* (non-Javadoc) 109 * @see java.lang.Object#toString() 110 */ 111 public String toString() { return m_name; } 112 } 113 114 /** 115 *<p> 116 * Binds a CcActivity proxy to a CqRecord proxy without making the 117 * activity the current one for this view. 118 * </p> 119 * <p> 120 * NOTE: Unlike most API methods, the optional property request will be executed 121 * on the returned StpActivity, not the CcView proxy on which the method 122 * was invoked. 123 * </p> 124 * 125 * <code>act</code> can either be a CcActivity proxy or a CqRecord proxy. 126 * <p> 127 * If <code>act</code> is a CcActivity proxy and the associated project is 128 * not CQ enabled, this operation simply executes the provided property 129 * request -- if any. If the project is CQ enabled, it additionally validates 130 * that the bound CQ record is in an active state. 131 * </p> 132 * <p> 133 * If <code>act</code> is a CqRecord proxy, this operation is more 134 * involved. First, <code>act</code> is automatically transitioned to an 135 * active state. If this transition involves required fields, the caller 136 * may be prompted to provide values for those fields. Next a CcActivity 137 * resource is created in this view's stream and is bound to 138 * <code>act</code>. 139 * </p> 140 * @param act the activity to work on - either a CqRecord or CcActivity 141 * @param feedback optional property request 142 * @return new proxy for the StpActivity, with requested properties 143 * @see javax.wvcm.Workspace#CURRENT_ACTIVITY 144 * @see com.ibm.rational.wvcm.stp.StpActivity#BOUND_CC_ACTIVITY 145 * @see com.ibm.rational.wvcm.stp.StpActivity#BOUND_CQ_RECORD 146 */ 147 public StpActivity doBindActivity(StpActivity act, Feedback feedback) throws WvcmException; 148 149 /** 150 * <p>Create a new ClearCase web view based on this CcView proxy. 151 * </p> 152 * <p> 153 * Preconditions: 154 * </p> 155 * <ul> 156 * <li>This proxy must have a file-based location representing the desired 157 * path of the root directory of the file area on the local machine. 158 * The directory must not yet exist.</li> 159 * <li>The location's leaf name (the directory name) will be used as 160 * the view tag of the new view. A view having that view-tag must not 161 * already exist.</li> 162 * <li>To create a view associated with a UCM stream, specify that stream 163 * by setting this view proxy's STREAM property.</li> 164 * </ul> 165 * <p> 166 * Postconditions: 167 * </p> 168 * <ul> 169 * <li>A ClearCase web view is created, with the view tag 170 * and local file area as described above.</li> 171 * <li>If the view proxy's STREAM property was set, the view will be 172 * associated with that stream.</li> 173 * <li>If the view proxy's VIEW_TAG_STRING property was set, the view will 174 * be assigned that tag. Otherwise, the file area's root directory name 175 * will be used.</li> 176 * </ul> 177 * @throws WvcmException if the preconditions are not met, or if there is an 178 * error creating the view. 179 */ 180 public CcView doCreateCcWebView(Feedback feedback) throws WvcmException; 181 182 /** 183 * <p>Upgrade this web view's file area.</p> 184 * <p>Preconditions:</p> 185 * <ul> 186 * <li>This web view's file area schema version must be older than the 187 * version supported by the currently running CM API file area management 188 * code. 189 * </li> 190 * </ul> 191 * <p>Postconditions:</p> 192 * <ul> 193 * <li>This web view's file area schema will be upgraded to the currently 194 * supported version.</li> 195 * </ul> 196 * <p>This operation has no effect on non-web views, and on web views that 197 * are already compatible. 198 * </p> 199 * @throws WvcmException if the preconditions are not met, or if there is an 200 * error upgrading the file area. 201 */ 202 public CcView doUpgradeFileArea(Feedback feedback) throws WvcmException; 203 204 /** 205 * Work on the specified activity in this CC view. 206 * <code>act</code> can either be a CcActivity proxy or a CqRecord proxy. 207 * <p> 208 * If <code>act</code> is a CcActivity proxy and the associated project is 209 * not CQ enabled, this operation simply makes it the current activity 210 * in this view. If the project is CQ enabled, it additionally validates 211 * that the bound CQ record is in an active state. 212 * </p> 213 * <p> 214 * If <code>act</code> is a CqRecord proxy, this operation is more 215 * involved. First, <code>act</code> is automatically transitioned to an 216 * active state. If this transition involves required fields, the caller 217 * may be prompted to provide values for those fields. Next a CcActivity 218 * resource is created in this view's stream and is bound to 219 * <code>act</code>. Finally, it makes the new CC activity resource the 220 * current activity in this view. 221 * </p> 222 * @param act the activity to work on - either a CqRecord or CcActivity 223 * @param feedback optional property request 224 * @return new proxy for this view, with requested properties 225 * @see javax.wvcm.Workspace#CURRENT_ACTIVITY 226 * @see com.ibm.rational.wvcm.stp.StpActivity#BOUND_CC_ACTIVITY 227 * @see com.ibm.rational.wvcm.stp.StpActivity#BOUND_CQ_RECORD 228 */ 229 public CcView doWorkOnActivity(StpActivity act, Feedback feedback) throws WvcmException; 230 231 /** 232 * <p> 233 * Transitions the specified activity to the default completed state. 234 * <code>act</code> can either be a CcActivity proxy or a CqRecord proxy. 235 * </p> 236 * <p> 237 * NOTE: Unlike most API methods, the optional property request will be executed 238 * on the returned StpActivity, not the CcView proxy on which the method 239 * was invoked. 240 * </p> 241 * <p>Preconditions:</p> 242 * <ul> 243 * <li><code>act</code> is a bound CqRecord/CcActivity pair in a CQ-enabled 244 * context.</li> 245 * </ul> 246 * <p>Postconditions:</p> 247 * <ul> 248 * <li>If <code>act</code>'s CcActivity has checkouts, the operation is 249 * cancelled and there is no change to the activity.</li> 250 * <li>Transitions <code>act</code>'s CqRecord to the default completed state. 251 * If this transition involves required fields, the caller may be prompted 252 * to provide values for those fields.</li> 253 * <li>Unsets <code>act</code>'s CcActivity from all views' 254 * {@link javax.wvcm.Workspace#CURRENT_ACTIVITY} property.</li> 255 * </ul> 256 * @param act the activity to finish 257 * @param feedback optional property request for the activity 258 * @return new proxy for the activity, with requested properties 259 * @throws WvcmException if the preconditions are not met. 260 */ 261 public StpActivity doFinishActivity(StpActivity act, Feedback feedback) 262 throws WvcmException; 263 264 /** 265 * <p> 266 * Synchronize this file area's local databases to accurately reflect the 267 * current state of the file area. The databases available to synchronize are: 268 * </p> 269 * <ul> 270 * <li>VOB database: This contains the loaded vobs in the view. A server connection 271 * is required to synchronize this database.</li> 272 * <li>Modified files database: This contains the checkouts and hijacks in the view. 273 * A server connection <i>not</i> required to synchronize this database.</li> 274 * </ul> 275 * @param flags array of flags which specify the databases to synchronize. 276 * @param feedback optional property request for the view 277 * @return A new proxy for this resource, whose properties are specified by feedback. 278 * @throws WvcmException 279 */ 280 public CcView doSynchronizeFileAreaDb(SynchronizeFileAreaDbFlag[] flags, Feedback feedback) 281 throws WvcmException; 282 283 /** 284 * Register this local web view's file area in the local file area registry. 285 * Web views are registered automatically when created, but may need to be 286 * re-registered if the registry is accidentally deleted, etc. 287 */ 288 public void registerFileArea() throws WvcmException; 289 290 /** 291 * Remove this local web view's file area from the local file area registry. 292 * Once removed, this view will no longer show up when listing local views. 293 * @see com.ibm.rational.wvcm.stp.cc.CcProvider#getClientViewList(javax.wvcm.PropertyRequestItem.PropertyRequest) 294 */ 295 public void unregisterFileArea() throws WvcmException; 296 297 /** 298 * If this is a local web view, the URL of the CM Server where this 299 * view's view database resides. 300 */ 301 PropertyName<String> SERVER_URL = 302 new PropertyName<String>(PROPERTY_NAMESPACE, "server-url"); 303 304 /** 305 * Get the value of this proxy's {@link #SERVER_URL} property. 306 * @return this view's server URL 307 * @throws WvcmException if this proxy doesn't define a value for this property. 308 */ 309 public String getServerUrl() throws WvcmException; 310 311 /** 312 * Change the URL used to connect to the CM server on which this web view resides. 313 * Note: Web views cannot be moved from one CM server to another. 314 * Use this method only to change the server URL, not to try to connect to 315 * a different server. 316 * <p> 317 * This may be necessary if, for example: 318 * <ul> 319 * <li>The CM server administrator changes the CM server's port number</li> 320 * <li>The client needs a secure HTTP connection to the CM server: 321 * "https://..." instead of "http://..."</li> 322 * <li>The CM server is moved to a different internet subdomain</li> 323 * </ul> 324 * @param updatedUrl the updated URL of this web view's CM server 325 * @throws WvcmException 326 */ 327 public void updateServerUrl(String updatedUrl) throws WvcmException; 328 329 /** 330 * This view's view tag as a string. 331 */ 332 PropertyName<String> VIEW_TAG_STRING = 333 new PropertyName<String>(PROPERTY_NAMESPACE, "view-tag-string"); 334 335 /** 336 * Get the value of this proxy's {@link #VIEW_TAG_STRING} property. 337 * @return this view's view tag 338 * @throws WvcmException if this proxy doesn't define a value for this property. 339 */ 340 public String getViewTagString() throws WvcmException; 341 342 /** 343 * Set the value of this view's {@link #VIEW_TAG_STRING} property. 344 * This property may only be set at view creation time. 345 * @param viewTag the view tag for the new view 346 */ 347 void setViewTagString(String viewTag); 348 349 /** 350 * This view's view tag as a {@link CcViewTag} resource. 351 */ 352 PropertyName<CcViewTag> VIEW_TAG = 353 new PropertyName<CcViewTag>(PROPERTY_NAMESPACE, "view-tag"); 354 355 /** 356 * Get the value of this proxy's {@link #VIEW_TAG} property. 357 * @return this view's view tag 358 * @throws WvcmException if this proxy doesn't define a value for this property. 359 */ 360 public CcViewTag getViewTag() throws WvcmException; 361 362 /** 363 * Whereas a CcView resource's {@link javax.wvcm.Folder#CHILD_MAP} property 364 * returns the root directories of <i>all</i> VOBs, LOADED_CHILD_MAP only 365 * returns the root directories of VOBs that are partially or fully loaded 366 * in this view. 367 */ 368 PropertyName<Map<String,Resource>> LOADED_CHILD_MAP = 369 new PropertyName<Map<String,Resource>>(PROPERTY_NAMESPACE, "loaded-child-map"); 370 371 /** 372 * Get the value of this proxy's {@link #LOADED_CHILD_MAP} property. 373 * @return this view's loaded child map 374 * @throws WvcmException if this proxy doesn't define a value for this property. 375 */ 376 public Map<String,Resource> getLoadedChildMap() throws WvcmException; 377 378 /** 379 * This view's file area root directory on the local machine. 380 * The value of this property will be null if this is not a web view, 381 * or if it does not have a file area on the local machine. 382 */ 383 PropertyName<File> FILE_AREA_ROOT_DIRECTORY = 384 new PropertyName<File>(PROPERTY_NAMESPACE, "file-area-root-directory"); 385 386 /** 387 * Returns the value of the {@link #FILE_AREA_ROOT_DIRECTORY} property. 388 * @return This view's copy area root directory, or null if it has 389 * no copy area on the local machine 390 * @throws WvcmException if this property is not defined by this proxy. 391 */ 392 public File getFileAreaRootDirectory() throws WvcmException; 393 394 /** 395 * Is this view's local file area schema version older than the version 396 * supported by the running CM API file management code? If so, the file 397 * area needs to be upgraded before it can be used. 398 * 399 * @see com.ibm.rational.wvcm.stp.cc.CcView#doUpgradeFileArea(Feedback) 400 */ 401 PropertyName<Boolean> FILE_AREA_NEEDS_UPGRADE = 402 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "file-area-needs-upgrade"); 403 404 /** 405 * Get the value of this view's {@link #FILE_AREA_NEEDS_UPGRADE} property. 406 * @return true if this view's local file area needs upgrading; false otherwise. 407 * @throws WvcmException if this property is not defined by this proxy. 408 */ 409 boolean getFileAreaNeedsUpgrade() throws WvcmException; 410 411 /** 412 * Is this view associated with a UCM stream?. 413 */ 414 PropertyName<Boolean> IS_UCM_VIEW = 415 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-ucm-view"); 416 417 /** 418 * Get the value of this view's {@link #IS_UCM_VIEW} property. 419 * @return true if this view represents a UCM view; false otherwise. 420 * @throws WvcmException if this property is not defined by this proxy. 421 */ 422 boolean getIsUcmView() throws WvcmException; 423 424 /** 425 * This view's config spec. 426 */ 427 PropertyName<CcConfigSpec> CONFIG_SPEC = 428 new PropertyName<CcConfigSpec>(PROPERTY_NAMESPACE, "config-spec"); 429 430 /** 431 * Get the value of this view's {@link #CONFIG_SPEC} property. 432 * @return this view's config spec as a CcConfigSpec instance 433 */ 434 CcConfigSpec getConfigSpec() throws WvcmException; 435 436 /** 437 * Set the value of this view's {@link #CONFIG_SPEC} property. 438 * @param configSpec the new config spec for this view 439 */ 440 void setConfigSpec(CcConfigSpec configSpec); 441 442 /** 443 * The text mode of the view. The text mode specifies the line 444 * terminator sequence for text files in the view. If no value is 445 * set upon view creation, defaults to {@link TextMode#TRANSPARENT}. 446 */ 447 PropertyName<TextMode> TEXT_MODE = 448 new PropertyName<TextMode>(PROPERTY_NAMESPACE, "text-mode"); 449 450 /** 451 * Get the value of this view's {@link #TEXT_MODE} property. 452 * @return enumeration value representing this view's text mode. 453 * @throws WvcmException if this proxy doesn't define a value for this property. 454 */ 455 TextMode getTextMode() throws WvcmException; 456 457 /** 458 * Set the value of this view's {@link #TEXT_MODE} property. This 459 * property may only be set at view creation time. 460 * @param textMode the text mode of the view. 461 */ 462 void setTextMode(TextMode textMode); 463 464 /** 465 * Break a file area lock on this view with the given lock info. 466 * @param lockInfo information about the lock 467 * @return true if the lock was broken; false otherwise 468 * @throws WvcmException if a problem occurred breaking the lock 469 */ 470 boolean breakFileAreaLock(CcFileAreaLockInfo lockInfo) throws WvcmException; 471 472 /** 473 * CcViewAccessInfo object contains the supported view access properties. 474 */ 475 public static final PropertyName<CcViewAccessInfo> VIEW_ACCESS_INFO = 476 new PropertyName<CcViewAccessInfo>(PROPERTY_NAMESPACE, "view-access-info"); 477 478 /** 479 * Returns the value of this proxy's {@link #VIEW_ACCESS_INFO} property. 480 * 481 * @return the CcViewAccessInfo object. 482 * @throws WvcmException 483 * if this proxy doesn't define a value for this property. 484 */ 485 public CcViewAccessInfo getViewAccessInfo() throws WvcmException; 486 487 /** 488 * <p> 489 * The permissions applied to this resource. 490 * </p> 491 */ 492 public static final PropertyName<CcPermissions> PERMISSIONS = 493 new PropertyName<CcPermissions>(PROPERTY_NAMESPACE, "cc-permissions"); 494 495 /** 496 * Returns the value of this proxy's {@link #PERMISSIONS} property. 497 * 498 * @return A permissions object from which specific permissions 499 * information can be extracted. 500 * @throws WvcmException 501 * if this proxy doesn't define a value for this property. 502 */ 503 public CcPermissions getPermissions() throws WvcmException; 504 505 /** 506 * Does this view have non-shareable derived objects? 507 */ 508 public static final PropertyName<Boolean> IS_EXPRESS = 509 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-express"); 510 511 /** 512 * Returns the value of this proxy's {@link #IS_EXPRESS} property. 513 * 514 * @return true if this view has non-shareable DOs; false otherwise. 515 * @throws WvcmException 516 * if this proxy doesn't define a value for this property. 517 */ 518 public Boolean getIsExpress() throws WvcmException; 519 520 /** 521 * Are this view's permissions valid? 522 */ 523 public static final PropertyName<Boolean> ARE_PERMISSIONS_VALID = 524 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "are-permissions-valid"); 525 526 /** 527 * Returns the value of this proxy's {@link #ARE_PERMISSIONS_VALID} property. 528 * 529 * @return true if this view's permissions are valid; false otherwise. 530 * @throws WvcmException 531 * if this proxy doesn't define a value for this property. 532 */ 533 public Boolean getArePermissionsValid() throws WvcmException; 534 535 /** 536 * Is this view read-only? 537 */ 538 public static final PropertyName<Boolean> IS_READ_ONLY = 539 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-read-only"); 540 541 /** 542 * Returns the value of this proxy's {@link #IS_READ_ONLY} property. 543 * 544 * @return true if this view is read-only; false otherwise. 545 * @throws WvcmException 546 * if this proxy doesn't define a value for this property. 547 */ 548 public Boolean getIsReadOnly() throws WvcmException; 549 550 /** 551 * Set the {@link #STREAM} property. 552 * 553 * @param stream the {@link Stream} object that 554 * identifies the {@link #STREAM} for this Workspace. 555 * @see #getStream 556 */ 557 public void setStream(Stream stream); 558 }