001 /*
002 * file CcFile.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 *
007 * com.ibm.rational.wvcm.stp.cc.CcFile
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 package com.ibm.rational.wvcm.stp.cc;
014
015 import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
016 import static com.ibm.rational.wvcm.stpex.StpExBase.STP_NAMESPACE;
017
018 import java.io.File;
019 import java.io.OutputStream;
020 import java.util.List;
021
022 import javax.wvcm.ControllableResource;
023 import javax.wvcm.Feedback;
024 import javax.wvcm.Resource;
025 import javax.wvcm.WvcmException;
026 import javax.wvcm.PropertyNameList.PropertyName;
027
028 import com.ibm.rational.wvcm.stpex.StpExBase;
029 import com.ibm.rational.wvcm.stpex.StpExEnumeration;
030
031 /**
032 * A proxy for a file, directory, or symbolic link resource in a ClearCase view.
033 * This resource is either under version control or could potentially be
034 * put under version control.
035 */
036 public interface CcFile
037 extends CcResource, ControllableResource
038 {
039 /** Flags for the doApplyLabel method */
040 enum ApplyLabelFlag implements StpExEnumeration {
041
042 /**
043 * Replace existing label instance.
044 */
045 REPLACE("replace"),
046
047 /**
048 * Apply label recursively over sub-tree.
049 */
050 RECURSE("recurse"),
051
052 /**
053 * Follow symbolic links
054 */
055 FOLLOW_SYMLINKS("follow-symlinks");
056
057 private String m_name;
058
059 private ApplyLabelFlag(String name) { m_name = name; }
060
061 /* (non-Javadoc)
062 * @see java.lang.Object#toString()
063 */
064 public String toString() { return m_name; }
065 }
066
067 /** Flags for the doRemoveLabel method */
068 enum RemoveLabelFlag implements StpExEnumeration {
069
070 /**
071 * Remove label recursively over sub-tree.
072 */
073 RECURSE("recurse"),
074
075 /**
076 * Follow symbolic links
077 */
078 FOLLOW_SYMLINKS("follow-symlinks");
079
080 private String m_name;
081
082 private RemoveLabelFlag(String name) { m_name = name; }
083
084 /* (non-Javadoc)
085 * @see java.lang.Object#toString()
086 */
087 public String toString() { return m_name; }
088 }
089
090 /** Flags for the doUncheckout method */
091 enum UncheckoutFlag implements StpExEnumeration {
092 /**
093 * Preserve changes in checked out version in a ".keep" file.
094 */
095 KEEP("keep");
096
097 private String m_name;
098
099 private UncheckoutFlag(String name) { m_name = name; }
100
101 /* (non-Javadoc)
102 * @see java.lang.Object#toString()
103 */
104 public String toString() { return m_name; }
105 }
106
107 /** Flags for the doUnhijack method */
108 enum UnhijackFlag implements StpExEnumeration {
109
110 /**
111 * Preserve changes in hijacked version in a ".keep" file.
112 */
113 KEEP("keep");
114
115 private UnhijackFlag(String name) { m_name = name; }
116
117 /* (non-Javadoc)
118 * @see java.lang.Object#toString()
119 */
120 public String toString() { return m_name; }
121
122 private String m_name;
123 }
124
125 /**
126 * Flags for the <code>doRefresh</code> and <code>doRestore</code> methods.
127 */
128 enum RefreshFlag implements StpExEnumeration {
129
130 /**
131 * Do <i>not</i> refresh hijacked files.
132 * Leave hijacked files in the hijacked state, and do not alter
133 * their contents.
134 * <p>
135 * Note: a deleted file or directory is considered to be hijacked.
136 * In order to refresh or restore a deleted file or directory,
137 * you must specify <code>OVERWRITE_HIJACKS</code> or
138 * <code>RENAME_HIJACKS</code>.
139 * </p>
140 * This is the default hijack behavior for both <code>doRefresh</code>
141 * and <code>doRestore</code>.
142 */
143 KEEP_HIJACKS("keep-hijacks"),
144
145 /**
146 * If a file being refreshed is hijacked in this view,
147 * overwrite the hijacked contents with the new version's contents.
148 * Do not preserve the hijacked contents.
149 */
150 OVERWRITE_HIJACKS("overwrite-hijacks"),
151
152 /**
153 * If a file being refreshed is hijacked in this view,
154 * preserve the hijacked contents by moving the hijacked file to
155 * <code><file-name>.keep</code>.
156 */
157 RENAME_HIJACKS("rename-hijacks"),
158
159 /**
160 * When refreshing a file to a different version, set the file's
161 * "last modified" time to be the time when the version was created.
162 * By default, a refreshed file's "last modified" time will simply be
163 * the time when the <code>doRefresh</code> was performed.
164 */
165 PRESERVE_CREATION_TIME("preserve-creation-time"),
166
167 /**
168 * Preview the refresh operation, but don't actually perform it.
169 * Invoke the caller's feedback methods to inform them what the
170 * refresh would do if it were performed right now.
171 */
172 PREVIEW_ONLY("preview-only");
173
174 private String m_name;
175
176 private RefreshFlag(String name) { m_name = name; }
177
178 /* (non-Javadoc)
179 * @see java.lang.Object#toString()
180 */
181 public String toString() { return m_name; }
182 }
183
184 /** Flags for the <code>doCheckout</code> method. */
185 enum CcCheckoutFlag implements StpExEnumeration {
186
187 /**
188 * Indicates whether to checkout this file reserved.
189 */
190 RESERVED("reserved"),
191
192 /**
193 * Fall back to unreserved if a reservation can not be obtained.
194 */
195 FALLBACK_TO_UNRESERVED("fallback-to-unreserved"),
196
197 /**
198 * Checkout the version of the file that is currently loaded in the
199 * view, even if that version is not the version selected by the
200 * view's config spec.
201 *
202 * <p>If the loaded version is not the version selected by the view's
203 * config spec, and neither {@link #LOADED_NOT_LATEST} nor
204 * {@link #LATEST_NOT_LOADED} flags are set, the checkout operation
205 * will throw an exception with reason code <code>CHECKOUT_NOT_LATEST</code>.
206 */
207 LOADED_NOT_LATEST("checkout-loaded-not-latest"),
208
209 /**
210 * Checkout the version of the file that is selected by the view's
211 * config spec. If this version is not loaded at checkout time, then
212 * load it prior to performing the checkout.
213 *
214 * <p>If the loaded version is not the version selected by the view's
215 * config spec, and neither {@link #LOADED_NOT_LATEST} nor
216 * {@link #LATEST_NOT_LOADED} flags are set, the checkout operation
217 * will throw an exception with reason code <code>CHECKOUT_NOT_LATEST</code>.
218 */
219 LATEST_NOT_LOADED("checkout-latest-not-loaded"),
220
221 /**
222 * Indicates whether to checkout this file even if the currently
223 * selected branch is mastered by another replica. The
224 * <code>RESERVED</code> flag must NOT be set with this flag.
225 *
226 * <p>If the file is mastered by this replica, setting this
227 * flag has no effect.
228 */
229 NON_MASTERED_OK("non-mastered-ok"),
230
231 /**
232 * If the file is hijacked, keep the hijacked contents upon checkout.
233 */
234 PRESERVE_HIJACK_CONTENTS("preserve-hijack-contents");
235
236 private String m_name;
237
238 private CcCheckoutFlag(String name) { m_name = name; }
239
240 /* (non-Javadoc)
241 * @see java.lang.Object#toString()
242 */
243 public String toString() { return m_name; }
244 }
245
246 /** Values for file or directory load state */
247 enum LoadState implements StpExEnumeration {
248
249 /**
250 * This file or directory is loaded in its file area.
251 */
252 LOADED,
253
254 /**
255 * This directory is partially loaded in its file area, i.e.,
256 * some but not all of its children are loaded.
257 */
258 PARTIALLY_LOADED,
259
260 /**
261 * This file or directory is not loaded in its file area.
262 */
263 NOT_LOADED;
264 }
265
266 /**
267 * Create a new view-private file at the location specified by this resource.
268 * The request will fail if a resource already exists at that location.
269 * @param feedback
270 * @return a CcFile proxy for the new file
271 * @see javax.wvcm.ControllableResource#doCreateResource(Feedback)
272 */
273 public CcFile createCcFile(Feedback feedback) throws WvcmException;
274
275 /**
276 * Apply the specified label to the checked-in version of this controllable resource.
277 * @param flags array of flags which specify the behavior of the operation
278 * @param label the label to be added to this version
279 * @param feedback
280 * @return A new proxy for this resource, whose properties are specified by feedback.
281 * @throws WvcmException
282 */
283 ControllableResource doApplyLabel(ApplyLabelFlag[] flags, String label, Feedback feedback)
284 throws WvcmException;
285
286 /**
287 * Remove the specified label from the checked-in version of this controllable resource.
288 * @param flags array of flags which specify the behavior of the operation
289 * @param label the label to be removed from this version
290 * @param feedback
291 * @return A new proxy for this resource, whose properties are specified by feedback.
292 * @throws WvcmException
293 */
294 ControllableResource doRemoveLabel(RemoveLabelFlag[] flags, String label, Feedback feedback)
295 throws WvcmException;
296
297 /**
298 * <p>Check out this version-controlled file or directory resource.
299 * The resource is checked out to the ClearCase view implied by its location.
300 * </p>
301 * <p>If the view is a UCM view, the caller must insure there is a
302 * {@link javax.wvcm.Workspace#CURRENT_ACTIVITY} for this operation.
303 * The checked out file will be added to the current activity's change set.
304 * The caller may explicitly specify an activity using this resource's
305 * {@link javax.wvcm.ControllableResource#setActivity} method. In that case,
306 * the specified activity will become the new current activity.
307 * Otherwise, the existing current activity will be used.
308 * If the view is a UCM view and there is no current activity, the operation
309 * will fail.
310 * </p>
311 * <p>The caller may optionally specify a checkout comment using this
312 * resource's {@link javax.wvcm.Resource#setComment} method.
313 * </p>
314 * @param flags array of flags which specify the behavior of the operation
315 * @param feedback
316 * @return new CcFile proxy representing the checked out file.
317 * @throws WvcmException
318 */
319 CcFile doCcCheckout(CcCheckoutFlag[] flags, Feedback feedback)
320 throws WvcmException;
321
322 /**
323 * Cancel the checkout of this version-controlled resource,
324 * and restore its content to the state of its CHECKED_IN version.
325 * @param flags array of flags which specify the behavior of the operation
326 * @param feedback
327 * @return new CcFile proxy representing the file whose checkout has been canceled
328 * @throws WvcmException
329 * @see javax.wvcm.ControllableResource#doUncheckout
330 */
331 CcFile doUncheckout(UncheckoutFlag[] flags, Feedback feedback)
332 throws WvcmException;
333
334 /**
335 * <p>Check in this checked out file or directory resource.
336 * </p>
337 * <p>If this resource is in a UCM view, it was added to an activity's
338 * change set at checkout time. The caller may specify an alternate
339 * change set using this resource's
340 * {@link javax.wvcm.ControllableResource#setActivity} method just before
341 * calling <code>doCheckin</code>.
342 * </p>
343 * <p>The caller may also specify a checkin comment using this
344 * resource's {@link javax.wvcm.Resource#setComment} method.
345 * This will override the comment specified at checkout time, if any.
346 * </p>
347 * @param flags array of flags which specify the behavior of the operation
348 * @param feedback
349 * @return new ControllableResource proxy representing the checked in file.
350 * @throws WvcmException
351 * @see javax.wvcm.ControllableResource#doCheckin
352 * @see com.ibm.rational.wvcm.stp.cc.CcFile#doCheckout
353 */
354 ControllableResource doCheckin(CheckinFlag[] flags, Feedback feedback)
355 throws WvcmException;
356
357 /**
358 * Places the view-private file specified by this proxy under version control.
359 * <p>If the view is a UCM view, the caller must insure there is a
360 * {@link javax.wvcm.Workspace#CURRENT_ACTIVITY} for this operation.
361 * The newly version controlled file will be added to the current activity's change set.
362 * The caller may explicitly specify an activity using this resource's
363 * {@link javax.wvcm.ControllableResource#setActivity} method. In that case,
364 * the specified activity will become the new current activity.
365 * Otherwise, the existing current activity will be used.
366 * If the view is a UCM view and there is no current activity, the operation
367 * will fail.
368 * </p>
369 * <p>The caller may optionally specify a creation comment using this
370 * resource's {@link javax.wvcm.Resource#setComment} method.
371 * </p>
372 * @param feedback
373 * @return new ControllableResource proxy representing the version controlled file.
374 * @throws WvcmException
375 * @see javax.wvcm.ControllableResource#doVersionControl
376 */
377 ControllableResource
378 doVersionControl(Feedback feedback)
379 throws WvcmException;
380
381 /**
382 * <p>
383 * Refresh this file or directory. Re-evaluate the
384 * view's config spec and update resources on the client to be whatever
385 * is currently selected by the config spec. If this is a directory,
386 * recursively refresh its contents.
387 * </p>
388 * <p>
389 * Example: The config spec says "element * /main/LATEST", and you
390 * have version "/main/7" of this resource loaded. Someone else checks
391 * in a new version, thus creating a "/main/8". In that case,
392 * doRefresh() will cause version "/main/8" of this resource to
393 * be loaded into your view.
394 * </p>
395 * <p>
396 * Preconditions: This resource must be a version-controlled file
397 * or directory.
398 * </p>
399 * <p>
400 * Postconditions: This resource (and its descendants if this is a
401 * directory) are updated to be what is currently selected by the view's
402 * config spec.
403 * </p>
404 * @param flags array of flags which specify the behavior of the operation
405 * @param feedback a list of properties to fetch on the
406 * updated resources. The resources returned by the iterator returned
407 * by doRefresh will have these properties filled in.
408 * @return a new CcFile proxy representing the refreshed file
409 * @throws WvcmException if the precondition is not met or if an error
410 */
411 CcFile doRefresh(RefreshFlag[] flags, Feedback feedback)
412 throws WvcmException;
413
414 /**
415 * <p>
416 * Restore this file or directory. If this is a directory, recursively
417 * restore its contents. This repairs any damage to the portion of the file
418 * area database specified by this resource.
419 * </p>
420 *
421 * @param flags array of flags which specify the behavior of the operation
422 * @param feedback
423 * @return a new CcFile proxy representing the restored file
424 * @throws WvcmException
425 */
426 CcFile doRestore(RefreshFlag[] flags, Feedback feedback)
427 throws WvcmException;
428
429 /**
430 * <p>
431 * Load this controllable resource into the view's local file area.
432 * If this is a controllable folder, loads the tree of controllable
433 * resources under this folder.
434 * Also updates the view's load rules if necessary
435 * to include this file or folder.
436 * </p>
437 * <p>
438 * If this resource was already loaded, doLoad is a no-op.
439 * </p>
440 * <p>
441 * Preconditions: This must be a version-controlled file or folder
442 * in a web view.
443 * </p>
444 * <p>
445 * Postconditions: This file, or the tree of files under this folder,
446 * is loaded into the web view. Thus, the file(s) appear, and the view's
447 * load rules are updated to include this file or folder.
448 * </p>
449 * @param feedback (optional) feedback's notifyIsModified() method will be
450 * called for each file or directory as it is loaded
451 * @return a new CcFile proxy for the file that has been loaded
452 * @throws WvcmException
453 */
454 CcFile doLoad(Feedback feedback) throws WvcmException;
455
456 /**
457 * Hijack this controllable resource.
458 * Make the resource writable and set its "last modified" time to the
459 * current time. This operation does <i>not</i> contact the server.
460 * @param feedback
461 * @return a new CcFile proxy for the hijacked file
462 * @throws WvcmException
463 */
464 CcFile hijack(Feedback feedback)
465 throws WvcmException;
466
467 /**
468 * Undo a hijack on this hijacked controllable resource. Reload the file's
469 * contents from the appropriate version on the server.
470 * @param flags Specify <code>KEEP</code> to save a copy of the hijacked
471 * file's contents in a ".keep" file before undoing the hijack.
472 * @param feedback
473 * @return a new CcFile proxy for the unhijacked file
474 * @throws WvcmException
475 */
476 CcFile doUnhijack(UnhijackFlag[] flags, Feedback feedback)
477 throws WvcmException;
478
479 /**
480 * For client resources, identifies the file system path to the local file
481 * representing this controllable resource.
482 */
483 PropertyName<File> CLIENT_PATH =
484 new PropertyName<File>(StpExBase.STP_NAMESPACE, "client-path");
485
486 /**
487 * Returns the value of this proxy's {@link #CLIENT_PATH} property.
488 * @return The path to this ControllableResource in the local file area.
489 * Will never be <code>null</code>.
490 * @throws WvcmException if requested of a ControllableResource without client state
491 */
492 File getClientPath() throws WvcmException;
493
494 /**
495 * For version-controlled resources, this resource's element type.
496 */
497 PropertyName<CcElementType> ELEMENT_TYPE =
498 new PropertyName<CcElementType>(STP_NAMESPACE, "element-type");
499
500 /**
501 * Returns the value of this proxy's {@link #ELEMENT_TYPE} property.
502 * @return This resource's element type. Will be <code>null</code>
503 * if resource is not version-controlled.
504 * @throws WvcmException if this proxy doesn't define a value for this property.
505 */
506 CcElementType getElementType() throws WvcmException;
507
508 /**
509 * Set the value of this file or directory's {@link #ELEMENT_TYPE} property.
510 * This property can only be set just prior to calling doVersionControl()
511 * on the resource.
512 * @param eltype resource's desired element type
513 */
514 void setElementType(CcElementType eltype);
515
516 /**
517 * Is this file a file area database file? File area DB files require
518 * special treatment. For instance, they cannot be source controlled.
519 * For this reason, applications may choose to hide these files from
520 * the end user.
521 */
522 PropertyName<Boolean> IS_DB_FILE =
523 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-db-file");
524
525 /**
526 * Get the value of this files {@link #IS_DB_FILE} property.
527 * @return true if this file is a file area database file, else false
528 * @throws WvcmException
529 * if this proxy doesn't define a value for this property.
530 */
531 public boolean getIsDbFile() throws WvcmException;
532
533 /**
534 * Property which is true/false depending on whether this version-controlled
535 * resource has been hijacked.
536 */
537 PropertyName<Boolean> IS_HIJACKED =
538 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-hijacked");
539
540 /**
541 * Get the value of this file's {@link #IS_HIJACKED} property.
542 * @return true if the file is hijacked, false otherwise
543 * @throws WvcmException
544 * if this proxy doesn't define a value for this property.
545 */
546 public boolean getIsHijacked() throws WvcmException;
547
548 /**
549 * Is this file actually a symbolic link?
550 */
551 PropertyName<Boolean> IS_SYMLINK =
552 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-symlink");
553
554 /**
555 * Get the value of the {@link #IS_SYMLINK} property.
556 * @return true if this resource is a symbolic link, false otherwise.
557 * @throws WvcmException
558 * if this proxy doesn't define a value for this property.
559 */
560 public boolean getIsSymlink() throws WvcmException;
561
562 /**
563 * Returns the direct parent of this file. The value will
564 * be <code>null</code> if the file has no parent (e.g. VOB root).
565 * Does not find parents of hard-linked names for the file.
566 */
567 public static final PropertyName<CcDirectory> PARENT =
568 new PropertyName<CcDirectory>(PROPERTY_NAMESPACE, "cc-parent");
569
570 /**
571 * Get the value of the {@link #PARENT} property.
572 * @return A CcDirectory proxy for the parent, null if no parent
573 * @throws WvcmException
574 */
575 public CcDirectory getParent() throws WvcmException;
576
577 /**
578 * <p>If this file is actually a symbolic link, the path to its target file
579 * or directory. The path is interpreted relative to this file's parent
580 * directory.</p>
581 *
582 * <p>If this file is not a symbolic link, this value will be
583 * <code>null</code>.</p>
584 */
585 PropertyName<String> SYMLINK_TARGET_PATH =
586 new PropertyName<String>(PROPERTY_NAMESPACE, "symlink-target-path");
587
588 /**
589 * Get the value of this resource's {@link #SYMLINK_TARGET_PATH} property.
590 * @return path to symlink's target file or directory, or <code>null</code>
591 * if this file is not a symbolic link.
592 * @throws WvcmException if property was not requested
593 */
594 public String getSymlinkTargetPath() throws WvcmException;
595
596 /**
597 * The view-relative path for this resource.
598 */
599 PropertyName<String> VIEW_RELATIVE_PATH =
600 new PropertyName<String>(PROPERTY_NAMESPACE, "cr-view-relative-path");
601
602 /**
603 * Get the value of this resource's {@link #VIEW_RELATIVE_PATH} property.
604 * @return view-relative path
605 * @throws WvcmException if property was not requested
606 */
607 public String getViewRelativePath() throws WvcmException;
608
609 /**
610 * The CC version resource associated with this file.
611 * The value of this property will be null if this is not a version-
612 * controlled resource.
613 * @see javax.wvcm.ControllableResource#CHECKED_IN and
614 * javax.wvcm.ControllableResource#CHECKED_OUT
615 */
616 PropertyName<CcVersion> VERSION =
617 new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "version");
618
619 /**
620 * Get the value of this resource's {@link #VERSION} property.
621 * @return this file's version, or <code>null</code> if this file is
622 * not version controlled
623 * @throws WvcmException if property was not requested
624 */
625 public CcVersion getVersion() throws WvcmException;
626
627 /**
628 * The OID of the CC version resource associated with this file.
629 * The value of this property will be null if this is not a version-
630 * controlled resource.
631 */
632 PropertyName<String> VERSION_OID =
633 new PropertyName<String>(PROPERTY_NAMESPACE, "version-oid");
634
635 /**
636 * Get the value of this resource's {@link #VERSION_OID} property.
637 * @return this file's version oid, or <code>null</code> if this file is
638 * not version controlled
639 * @throws WvcmException if property was not requested
640 */
641 public String getVersionOid() throws WvcmException;
642
643 /**
644 * The tag of the VOB in which this file resides.
645 */
646 PropertyName<CcVobTag> VOB_TAG =
647 new PropertyName<CcVobTag>(PROPERTY_NAMESPACE, "file-vob-tag");
648
649 /**
650 * Get the value of this resource's {@link #VOB_TAG} property.
651 * @return the VOB tag for this file's VOB as a CcVobTag proxy,
652 * or <code>null</code> if this file is not version controlled
653 * @throws WvcmException if property was not requested
654 */
655 public CcVobTag getVobTag() throws WvcmException;
656
657 /**
658 * The CC element resource associated with this file.
659 * The value of this property will be null if this is not a version-
660 * controlled resource.
661 * @see javax.wvcm.ControllableResource#VERSION_HISTORY
662 */
663 PropertyName<CcElement> ELEMENT =
664 new PropertyName<CcElement>(PROPERTY_NAMESPACE, "element");
665
666 /**
667 * Get the value of this resource's {@link #ELEMENT} property.
668 * @return this file's element, or <code>null</code> if this file is
669 * not version controlled
670 * @throws WvcmException if property was not requested
671 */
672 public CcElement getElement() throws WvcmException;
673
674 /**
675 * Returns a {@link java.io.File File} representing the location of this
676 * client-side Resource in the local file system, else <code>null</code> if
677 * this Resource is a server-side resource only.
678 * @return The location of this Resource in the local file system, else
679 * <code>null</code> if this is a proxy to a server-side resource only.
680 *
681 * @throws WvcmException Thrown if there was an error in determining the
682 * path for this client-side Resource.
683 */
684 File clientResourceFile() throws WvcmException;
685
686 /**
687 * Reads the file's properties, if they are available locally on the client machine.
688 * @param feedback the properties to be available in the returned proxy,
689 * and any other feedback desired, such as progress indications.
690 * @return a {@link CcFile} containing the wanted properties
691 * that are available locally on the client machine
692 * without communicating with the server.
693 * @see Resource#doReadProperties(Feedback) doReadProperties.
694 * @throws WvcmException ReasonCode:
695 * <br> {@link javax.wvcm.WvcmException.ReasonCode#NOT_FOUND}:
696 * The file MUST be available locally on the client machine.
697 */
698 CcFile readProperties(Feedback feedback) throws WvcmException;
699
700 /**
701 * Reads the file's content, if it is available locally on the client machine.
702 * @see Resource#doReadContent(OutputStream,Feedback) doReadContent
703 * @param feedback the properties to be available in the returned proxy,
704 * and any other feedback desired, such as progress indications.
705 * @param content the file's content, if available, is written to this
706 * byte stream. The stream is then closed.
707 * @return a CcFile proxy containing the wanted properties
708 * that are available on the client host without communicating with the server.
709 * @throws WvcmException ReasonCode:
710 * <br> {@link javax.wvcm.WvcmException.ReasonCode#NOT_FOUND}:
711 * The file MUST be available locally on the client machine.
712 */
713 CcFile readContent(OutputStream content, Feedback feedback) throws WvcmException;
714
715 /**
716 * Resolve this file resource, but do not consult the ClearCase server.
717 * Unlike {@link CcResource#doResolve()}, use only information currently
718 * available information on the local client machine.
719 * @see CcResource#doResolve()
720 * @return a new file proxy of the correct, most specific resource type
721 * @throws WvcmException with NOT_FOUND reason code if this file does not
722 * exist on the local machine.
723 */
724 CcFile resolve() throws WvcmException;
725
726 /**
727 * Whether this file is loaded, partially loaded, or not loaded in the
728 * file area in which it resides.
729 */
730 PropertyName<LoadState> LOAD_STATE =
731 new PropertyName<LoadState>(PROPERTY_NAMESPACE, "load-state");
732
733 /**
734 * Get the value of this resource's {@link #LOAD_STATE} property.
735 * @return LoadState.LOADED, LoadState.PARTIALLY_LOADED or LoadState.NOT_LOADED
736 * @throws WvcmException
737 * if this proxy doesn't define a value for this property.
738 */
739 LoadState getLoadState() throws WvcmException;
740
741 /**
742 * <p>Version controlled files and directories may have both client state -
743 * state maintained in a local file area - and server state. When the
744 * client state and server state get out of synch, we call this <i>skew</i>.
745 * </p>
746 * <p>The caller can detect skew by including the {@link #SKEWED_PROPERTY_LIST}
747 * property in property requests to <code>doReadProperties()</code> and
748 * other <code>do</code> methods that accept property requests.
749 * The resulting value of this property is the list of names of properties
750 * in the request that differed between the client and the server for this
751 * particular file or directory.
752 * </p>
753 * <p>Note that only certain properties are checked for skew - properties
754 * where skew can cause significant problems. For example,
755 * {@link #IS_CHECKED_OUT}, {@link #IS_VERSION_CONTROLLED}, and
756 * {@link #VERSION_OID}.
757 * </p>
758 * <p>Note also that <i>only</i> properties in the current property request
759 * are checked for skew.
760 * </p>
761 */
762 PropertyName<List<PropertyName>> SKEWED_PROPERTY_LIST =
763 new PropertyName<List<PropertyName>>(PROPERTY_NAMESPACE, "skewed-property-list");
764
765 /**
766 * Get the value of this file's {@link #SKEWED_PROPERTY_LIST} property.
767 * @return a list of property names in the current property request whose
768 * values differed between the client and the server for this file
769 * or directory.
770 * @throws WvcmException
771 * if this proxy doesn't define a value for this property.
772 */
773 List<PropertyName> getSkewedPropertyList() throws WvcmException;
774
775 /**
776 * The config spec rule that selects this file.
777 */
778 PropertyName<String> SELECTION_RULE =
779 new PropertyName<String>(PROPERTY_NAMESPACE, "selection-rule");
780
781 /**
782 * Get the value of this resource's {@link #SELECTION_RULE} property.
783 * @return this file's config spec rule, as a string.
784 * @throws WvcmException
785 * if this proxy doesn't define a value for this property.
786 */
787 String getSelectionRule() throws WvcmException;
788
789 /**
790 * The version of this file that is currently the latest on the same branch.
791 */
792 PropertyName<CcVersion> LATEST_VERSION_ON_BRANCH =
793 new PropertyName<CcVersion>(PROPERTY_NAMESPACE, "latest-version-on-branch");
794
795 /**
796 * Get the value of this resource's {@link #LATEST_VERSION_ON_BRANCH} property.
797 * @return the version of this file that is the latest on the same branch as the
798 * version in the view.
799 * @throws WvcmException
800 * if this proxy doesn't define a value for this property.
801 */
802 CcVersion getLatestVersionOnBranch() throws WvcmException;
803 }