001 /*
002 * file StpException.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 *
007 * com.ibm.rational.wvcm.stp.StpException
008 *
009 * (C) Copyright IBM Corporation 2006, 2009. 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;
015
016 import java.lang.reflect.InvocationTargetException;
017 import java.lang.reflect.Method;
018 import java.util.HashMap;
019 import java.util.Locale;
020
021 import javax.wvcm.Feedback;
022 import javax.wvcm.Resource;
023 import javax.wvcm.WvcmException;
024 import javax.wvcm.WvcmException.ReasonCode;
025
026 import com.ibm.rational.wvcm.stpex.StpExEnumeration;
027 import com.ibm.rational.wvcm.stpex.StpExEnumerationBase;
028
029 /**
030 * An extension of {@link javax.wvcm.WvcmException javax.wvcm.WvcmException}
031 * used throughout this API. Although API methods are declared to throw
032 * WvcmException, the exception actually thrown is StpException or one of its
033 * subclasses.
034 * <p>
035 * This class extends the WvcmException class, adding a <i>sub-reason code</i>
036 * field that encodes conditions specific to this API more finely than the
037 * {@link javax.wvcm.WvcmException.ReasonCode}
038 * <p>
039 * This class (unlike the WvcmException class) leverages the Java 1.4 chained
040 * exception mechanism. By default, if an StpException is constructed from one
041 * or more nested Throwables, the first nested Throwable in the list is also set
042 * as the StpException's {@link java.lang.Throwable#initCause cause}. In
043 * certain special cases, the cause may be set to something other than the first
044 * nested Throwable.
045 *
046 * Exception classes that extend StpException because they convey additional
047 * information, are as follows:
048 * <ul>
049 * <li>{@link StpPropertyException} - adds name of property responsible for the
050 * exception
051 * <p>
052 * <li>{@link StpPartialResultsException} - holds a ResourceList of child
053 * resources successfully received, a nested list of Exceptions for child
054 * resources that could not be retrieved, and an indicator of whether the two
055 * lists completely identify all resources that were supposed to be retrieved.
056 * <p>
057 * </ul>
058 */
059 public abstract class StpException extends WvcmException
060 {
061 /**
062 * The specification for the data implementation object associated with this
063 * exception.
064 */
065 public interface Data {
066 public String getMessage();
067 public StpReasonCode getStpReasonCode();
068 public String toString();
069 }
070
071 /**
072 * An encoding of exception conditions specific to this API. Each
073 * StpReasonCode maps to one WvcmException.ReasonCode, but, because the
074 * granularity of the StpReasonCode enumeration is finer than that of the
075 * ReasonCode, the mapping may be many-to-one.
076 * <p>
077 *
078 * When the correspondence between an StpReasonCode and a ReasonCode is not
079 * obvious, the StpReasonCode is mapped to either ReasonCode.CONFLICT or
080 * ReasonCode.FORBIDDEN
081 * using the following rationale:
082 * <p>
083 * <ul>
084 * <li>{@link javax.wvcm.WvcmException.ReasonCode#CONFLICT CONFLICT} - the exception
085 * relates to an issue where the client may be able to retry the method
086 * after changing the state on some object.
087 *
088 * <li>{@link javax.wvcm.WvcmException.ReasonCode#FORBIDDEN FORBIDDEN} - the
089 * exception relates to an issue where the client cannot do anything to
090 * retry the method.
091 * </ul>
092 *
093 * For conditions where there is not enough information to decide whether or
094 * not there is anything the client could do to retry the method, the
095 * StpReasonCode is classified as CONFLICT.
096 * <p>
097 */
098
099 public static enum StpReasonCode implements StpExEnumeration
100 {
101 // /**
102 // * Method execution was aborted via notification to the Feedback object.
103 // */
104 // @Deprecated
105 // ABORTED,
106 //
107 /**
108 * The request timed out waiting for a resource to become free.
109 */
110 REQUEST_TIMED_OUT(ReasonCode.ABORTED),
111
112 // /**
113 // * <code>Precondition:</code> The label is already in use by this
114 // * resource.
115 // */
116 // @Deprecated
117 // ADD_MUST_BE_NEW_LABEL,
118 //
119 // /**
120 // * The type of the persistent resource identified by this argument was
121 // * not compatible with the specified argument type.
122 // */
123 // @Deprecated
124 // BAD_ARGUMENT_TYPE,
125 //
126 // /**
127 // * <code>Precondition:</code> Operation failed because the resource
128 // * passed in was not a baseline.
129 // */
130 // @Deprecated
131 // NOT_A_BASELINE(ReasonCode.BAD_ARGUMENT_TYPE),
132 //
133 // /** <code>Precondition:</code> Resource specified was not an activity. */
134 // @Deprecated
135 // NOT_AN_ACTIVITY(ReasonCode.BAD_ARGUMENT_TYPE),
136 //
137 // /**
138 // * <code>Precondition:</code> Cannot checkin since it would cause a
139 // * fork and forking is discouraged.
140 // */
141 // @Deprecated
142 // CANNOT_CHECKIN_FORK_DISCOURAGED,
143 //
144 // /**
145 // * There is a reserved checkout of a version in this version history.
146 // */
147 // @Deprecated
148 // CANNOT_CHECKIN_TO_RESERVED_ACTIVITY,
149 //
150 // /**
151 // * <code>Precondition:</code> Failed to checkout because descendent
152 // * already exists and forking is discouraged.
153 // */
154 // @Deprecated
155 // CANNOT_CHECKOUT_FORKING_IS_DISCOURAGED,
156 //
157 // /**
158 // * <code>Precondition:</code> Failed to checkout the resource because
159 // * a descendent exists and forking is forbidden.
160 // */
161 // @Deprecated
162 // CANNOT_CHECKOUT_FORKING_IS_FORBIDDEN,
163 //
164 // /**
165 // * <code>Precondition:</code> Failed to checkout resource because
166 // * multiple checkout is discouraged and the caller did not specify
167 // * fork-ok.
168 // */
169 // @Deprecated
170 // CANNOT_CHECKOUT_MULTI_CHECKOUT_IS_DISCOURAGED,
171 //
172 // /**
173 // * <code>Precondition:</code> Checkout of an already checked-out
174 // * resource is forbidden.
175 // */
176 // @Deprecated
177 // CANNOT_CHECKOUT_MULTI_CHECKOUT_IS_FORBIDDEN,
178 //
179 /**
180 * <code>Precondition:</code> Cannot create this resource at the
181 * specified location.
182 */
183 CANNOT_CREATE_AT_THIS_LOCATION,
184
185 // /**
186 // * <code>Precondition:</code> Each version in an activity for a given
187 // * version history must be on the same line of descent.
188 // */
189 // @Deprecated
190 // CANNOT_CREATE_BRANCH_IN_ACTIVITY,
191 //
192 // /**
193 // * Each version in a stream for a given version history must be on the
194 // * same line of descent.
195 // */
196 // @Deprecated
197 // CANNOT_CREATE_BRANCH_IN_STREAM,
198 //
199 // /**
200 // * <code>Precondition:</code> A fork in the version tree is not
201 // * allowed.
202 // */
203 // @Deprecated
204 // CANNOT_FORK,
205 //
206 // /**
207 // * <code>Precondition:</code> baseline control failed because the
208 // * folder already has controlled resources.
209 // */
210 // @Deprecated
211 // CANNOT_HAVE_CONTROLLED_MEMBERS,
212 //
213 // /**
214 // * <code>Precondition:</code> A baseline controlled folder already
215 // * exists in this workspace for this baseline history.
216 // */
217 // @Deprecated
218 // CANNOT_HAVE_MULTIPLE_BASELINE_CONTROLLED_FOLDERS,
219 //
220 // /**
221 // * <code>Precondition:</code> Failed to perform the merge because the
222 // * target could not be checked-out.
223 // */
224 // @Deprecated
225 // CANNOT_MERGE_CHECKOUT_NOT_ALLOWED,
226 //
227 /**
228 * <code>Precondition:</code> Operation failed because it attempted to
229 * set a protected property.
230 */
231 CANNOT_MODIFY_PROTECTED_PROPERTY,
232
233 // /**
234 // * <code>Precondition:</code> Failed to modify content/properties
235 // * because the resource specified was a version.
236 // */
237 // @Deprecated
238 // CANNOT_MODIFY_VERSION,
239 //
240 /** Cannot overwrite existing binding. */
241 CANNOT_OVERWRITE,
242
243 // /**
244 // * <code>Precondition:</code> Cannot remove the specified label
245 // * because it is not used by this resource.
246 // */
247 // @Deprecated
248 // CANNOT_REMOVE_LABEL_DOES_NOT_EXIST,
249 //
250 /**
251 * The operation cannot be performed because of a conflict with resource
252 * state.
253 */
254 CONFLICT,
255
256 // /**
257 // * The activity specified for the operation is not accepted into the
258 // * workspace.
259 // */
260 // @Deprecated
261 // ACTIVITY_MUST_BE_ACCEPTED(ReasonCode.CONFLICT),
262 //
263 /**
264 * A checkout was attempted with no explicit activity and no current
265 * activity in the workspace.
266 */
267 ACTIVITY_NEEDED(ReasonCode.CONFLICT),
268
269 /**
270 * The specified record is already being edited (by the same user).
271 */
272 ALREADY_BEING_EDITED(ReasonCode.CONFLICT),
273
274 /**
275 * Authentication information is required but client didn't provide any.
276 */
277 AUTHENTICATION_INFO_REQUIRED(ReasonCode.CONFLICT),
278
279 // /** The duplicated query cannot be found on the server */
280 // @Deprecated
281 // BAD_DUPLICATE_HREF(ReasonCode.CONFLICT),
282 //
283 /**
284 * The requested action is inappropriate for the current state of the
285 * query (precondition failure)
286 */
287 BAD_SOURCE_STATE(ReasonCode.CONFLICT),
288
289 /**
290 * The checkin operation failed because the resource is not checked out.
291 */
292 CANNOT_CHECKIN_MUST_BE_CHECKED_OUT(ReasonCode.CONFLICT),
293
294 /**
295 * Used when a string is not supported by the server's operating system.
296 */
297 CANNOT_ENCODE_STRING(ReasonCode.CONFLICT),
298
299 // /** The resource's version controlled content cannot be modified */
300 // @Deprecated
301 // CANNOT_MODIFY_VERSION_CONTROLLED_CONTENT(ReasonCode.CONFLICT),
302 //
303 // /**
304 // * doRebind() was requested to move a controlled resource to an
305 // * uncontrolled parent directory.
306 // */
307 // @Deprecated
308 // CANNOT_RENAME_TO_UNCONTROLLED_PARENT(ReasonCode.CONFLICT),
309 //
310 /**
311 * The uncheckout operation failed because the resource is not checked
312 * out.
313 */
314 CANNOT_UNCHECKOUT_MUST_BE_CHECKED_OUT(ReasonCode.CONFLICT),
315
316 /**
317 * Checkout failed because the branch was not mastered locally.
318 */
319 CHECKOUT_BRANCH_NOT_MASTERED(ReasonCode.CONFLICT),
320
321 /**
322 * Checkout failed because the branch type was not mastered locally.
323 */
324 CHECKOUT_BRTYPE_NOT_MASTERED(ReasonCode.CONFLICT),
325
326 /** Version being checked out is not the latest **/
327 CHECKOUT_NOT_LATEST(ReasonCode.CONFLICT),
328
329 // /**
330 // * Thrown when a referenced project checkpoint is not the latest.
331 // */
332 // @Deprecated
333 // CHECKPOINT_MUST_BE_LATEST(ReasonCode.CONFLICT),
334 //
335 /** The client location is not within a file area */
336 CLIENT_LOCATION_NOT_IN_FILE_AREA(ReasonCode.CONFLICT),
337
338 /** A communication precondition failed */
339 CONDITIONAL_EXECUTION(ReasonCode.CONFLICT),
340
341 // /**
342 // * Failed to write a property that should be writable. A potentially
343 // * recoverable condition prevented the server from writing the property
344 // * value.
345 // */
346 // @Deprecated
347 // PROPERTY_NOT_CURRENTLY_WRITABLE(ReasonCode.CONFLICT),
348 //
349 /**
350 * An operation failed because the connection to the remote server could
351 * not be established or terminated prematurely after being established.
352 */
353 CONNECTION_FAILED(ReasonCode.CONFLICT),
354
355 // /**
356 // * An activity, specified to be made current to a workspace, is not in
357 // * that workspace's accepted set.
358 // */
359 // @Deprecated
360 // CURRENT_ACTIVITY_MUST_BE_ACCEPTED(ReasonCode.CONFLICT),
361 //
362 /**
363 * An attempt to deliver a resource from the change context to the
364 * database failed.
365 */
366 DELIVERY_ERROR(ReasonCode.CONFLICT),
367
368 /** Version discordance detected **/
369 DISCORDANCE_VERSION(ReasonCode.CONFLICT),
370
371 /** Duplicate activity name **/
372 DUPLICATE_ACTIVITY_NAME(ReasonCode.CONFLICT),
373
374 /** Duplicate stream name **/
375 DUPLICATE_STREAM_NAME(ReasonCode.CONFLICT),
376
377 /**
378 * This code indicates that an external lock couldn't be acquired
379 * because the lock already exists.
380 */
381 EXTERNAL_LOCK_ALREADY_PRESENT(ReasonCode.CONFLICT),
382
383 /**
384 * Some dependency required by the communication channel failed.
385 */
386 FAILED_DEPENDENCY(ReasonCode.CONFLICT),
387
388 /**
389 * A field did not pass validation during an attempted delivery.
390 */
391 FIELD_VALIDATION(ReasonCode.CONFLICT),
392
393 /**
394 * The client resource resides in a file area whose version is not
395 * compatible with the currently running software. The file area needs
396 * to be upgraded in order to work with this software.
397 */
398 FILE_AREA_NEEDS_UPGRADE(ReasonCode.CONFLICT),
399
400 /** A file error was encountered */
401 FILE_ERROR(ReasonCode.CONFLICT),
402
403 // /**
404 // * This code indicates that the server URL stored in the file area
405 // * doesn't match the server URL of the current Provider. E.g., the two
406 // * URLs could differ in the hostname (consider that UCM2 server was
407 // * restored / relocated to another server), web server port identifier,
408 // * general change in the segment names leading up to the UCM2 namespace
409 // * root, ...
410 // */
411 // @Deprecated
412 // FILEAREA_SERVER_MISMATCH(ReasonCode.CONFLICT),
413 //
414 // /**
415 // * Another process already has a write lock on the file area database.
416 // * This code should only be present for a FileAreaWriteLockException.
417 // */
418 // @Deprecated
419 // FILEAREA_WRITE_LOCKED_EXTERNAL(ReasonCode.CONFLICT),
420 //
421 // /**
422 // * Another thread in the process already has a write lock on the file
423 // * area database.
424 // */
425 // @Deprecated
426 // FILEAREA_WRITE_LOCKED_INTERNAL(ReasonCode.CONFLICT),
427 //
428 // /** The resource is currently a hijacked checkout */
429 // @Deprecated
430 // HIJACKED_CHECKOUT(ReasonCode.CONFLICT),
431 //
432 /**
433 * While firing a named ClearQuest hook, the hook returned a message,
434 * which generally represents an error or need for additional
435 * information
436 */
437 HOOK_RETURNED_MESSAGE(ReasonCode.CONFLICT),
438
439 // /** A runtime error occurred in the HTTP subsystem */
440 // @Deprecated
441 // HTTP_RUNTIME(ReasonCode.CONFLICT),
442 //
443 // /** The HTTP subsystem state is not proper for the request */
444 // @Deprecated
445 // HTTP_STATE(ReasonCode.CONFLICT),
446 //
447 /**
448 * An in-line query definition during query execution
449 */
450 ILLEGAL_QUERY(ReasonCode.CONFLICT),
451
452 /**
453 * The client resource resides in a file area whose version is not
454 * compatible with the currently running software. The software needs to
455 * be upgraded to handle this file area.
456 */
457 INCOMPATIBLE_FILE_AREA_VERSION(ReasonCode.CONFLICT),
458
459 /** Insufficient permission for the requested operation */
460 INSUFFICIENT_PERMISSION(ReasonCode.CONFLICT),
461
462 /** An interaction request has occurred */
463 INTERACTION_REQUEST(ReasonCode.CONFLICT),
464
465 /** An internal error has occurred */
466 INTERNAL_ERROR(ReasonCode.CONFLICT),
467
468 /**
469 * The provider's server encountered an unexpected internal error
470 * condition which prevented it from fulfilling the request. This
471 * loosely corresponds to an HTTP 500 Internal Server Error response
472 * from the server.
473 *
474 * @see #SERVER_ERROR
475 */
476 INTERNAL_SERVER_ERROR(ReasonCode.CONFLICT),
477
478 /**
479 * A required field is missing from or malformed in an StpLocation
480 * specification.
481 */
482 INVALID_OBJECT_SELECTOR(ReasonCode.CONFLICT),
483
484 /** An invalid response was received */
485 INVALID_RESPONSE(ReasonCode.CONFLICT),
486
487 /**
488 * Completion of operation was prevented because one or more properties
489 * have invalid values
490 */
491 INVALID_VALUES(ReasonCode.CONFLICT),
492
493 /** License error occurred **/
494 LICENSE_ERROR(ReasonCode.CONFLICT),
495
496 // /**
497 // * An operation attempted to create a conflict in the copy based file
498 // * area's loaded scope set.
499 // *
500 // * E.g., an operation (such as checkout, create or load) attempted to
501 // * add an include-scope for an item that is a child of an exclude-scope
502 // * specification.
503 // */
504 // @Deprecated
505 // LOADED_SCOPES_CONFLICT(ReasonCode.CONFLICT),
506 //
507 /** The database to be affected is currently locked */
508 LOCKED_DATABASE(ReasonCode.CONFLICT),
509
510 // /**
511 // * Maximum logon attempts exceeded.
512 // */
513 // @Deprecated
514 // MAX_LOGON_ATTEMPTS_EXCEEDED(ReasonCode.CONFLICT),
515 //
516 // /** The destination associated with the request is missing */
517 // @Deprecated
518 // MISSING_DESTINATION(ReasonCode.CONFLICT),
519 //
520 // /**
521 // * A supplied location, which must be a client location, is not a client
522 // * location.
523 // */
524 // @Deprecated
525 // MUST_BE_CLIENT_LOCATION(ReasonCode.CONFLICT),
526 //
527 // /**
528 // * Checkin with identical data not allowed and identical data was
529 // * provided.
530 // */
531 // @Deprecated
532 // MUST_BE_DIFFERENT(ReasonCode.CONFLICT),
533 //
534 // /**
535 // * Two locations refer to different workspaces and the
536 // * operation requires that they be in the same workspace.
537 // */
538 // @Deprecated
539 // MUST_BE_SAME_WORKSPACE(ReasonCode.CONFLICT),
540 //
541 /** The name supplied for a new resource is invalid */
542 NAME_MUST_BE_VALID(ReasonCode.CONFLICT),
543
544 /** Resource needs to be merged from latest version **/
545 NEEDS_MERGE_FROM_LATEST(ReasonCode.CONFLICT),
546
547 /** For use when StpException is just a wrapper for a WvcmException */
548 NONE(ReasonCode.CONFLICT),
549
550 /**
551 * A duplicate record is specified but the action is not a duplicate
552 * action.
553 */
554 NOT_DUPLICATE_ACTION(ReasonCode.CONFLICT),
555
556 // /** object not found error **/
557 // @Deprecated
558 // OBJECT_NOT_FOUND_ERROR(ReasonCode.CONFLICT),
559 //
560 /** A parameter mismatch was detected in a response */
561 PARAMETER_MISMATCH(ReasonCode.CONFLICT),
562
563 // /** The parent resource is not under version control but needs to be */
564 // @Deprecated
565 // PARENT_MUST_BE_VERSION_CONTROLLED(ReasonCode.CONFLICT),
566 //
567 /** The parent of a targeted resource needs to exist, but doesn't */
568 PARENT_MUST_EXIST(ReasonCode.CONFLICT),
569
570 /**
571 * This exception is reporting failure in an operation that was applied
572 * independently to multiple resources and failed on some of them.
573 *
574 * @see StpPartialResultsException
575 */
576 PARTIAL_RESULTS(ReasonCode.CONFLICT),
577
578 /** Used when delivering change contexts */
579 PRIOR_COMMIT_FAILURE(ReasonCode.CONFLICT),
580
581 /**
582 * Some other property error such as
583 * <ul>
584 * <li>Can't update value because it is inappropriate for property.
585 * <li>Can't update value because of server-specific restriction such
586 * as length of string or list.
587 * <li>
588 * </ul>
589 */
590 PROPERTY_ERROR(ReasonCode.CONFLICT),
591
592 /**
593 * An exception with this StpReasonCode is thrown by the execution of
594 * any property "getter" method when the targeted property could not be
595 * retrieved from the server. Exceptions of this type wrap the exception
596 * generated by the server, which is accessible via the getCause() or
597 * {@link javax.wvcm.WvcmException#getNestedExceptions()} methods of
598 * this wrapping exception.
599 * <p>
600 * The traceback for the outer, PROPERTY_RETRIEVAL_FAILED exception will
601 * identify the context in which the attempt was made to get the
602 * property value from the proxy, while the traceback for the cause of
603 * that exception will identify the context in which the attempt was
604 * made to read the value into the proxy.
605 */
606 PROPERTY_RETRIEVAL_FAILED(ReasonCode.CONFLICT),
607
608 /**
609 * Thrown by CreateRecord when an attempt is made to create a record with
610 * the same name as one that already exists on the server.
611 */
612 RECORD_WITH_SAME_DISPLAYNAME_EXISTS(ReasonCode.CONFLICT),
613
614 /** Request failed error **/
615 REQUEST_FAILED_ERROR(ReasonCode.CONFLICT),
616
617 // /** Errors were encountered during ResourceLocation deserialization */
618 // @Deprecated
619 // RESOURCE_LOCATION_DESERIALIZE(ReasonCode.CONFLICT),
620 //
621 // /**
622 // * Thrown when the location for a resource in a creation method is not
623 // * valid.
624 // */
625 // @Deprecated
626 // RESOURCE_LOCATION_OK(ReasonCode.CONFLICT),
627 //
628 // /** A typecast attempt on a Resource failed */
629 // @Deprecated
630 // RESOURCE_TYPE_CAST(ReasonCode.CONFLICT),
631 // /*
632 // * Note: the WebDAV protocol requires distinct error codes for CHECKIN
633 // * and UNCHECKOUT, in the case where the method is applied to a
634 // * non-checked-out resource. Since WVCM defines a single reason code for
635 // * both cases, this class defines two different reason codes that both
636 // * map to the same WVCM reason code, but different XML tags.
637 // *
638 // * BIGGER NOTE: regarding why the following are now mapping to
639 // * ReasonCode.CONFLICT and why they can't map to
640 // * ReasonCode.MUST_BE_CHECKED_OUT (note using CONFLICT causes API level
641 // * regression test failures -- sigh)...
642 // *
643 // * John says: I think the problem was with
644 // * PropInfo.initWvcmMappingTables(). It creates the association between
645 // * XmlTags and WvcmException.ReasonCode. But it also looks for a mapping
646 // * from a WVCM reason code to an STP reason code, and if there is one,
647 // * also links the XmlTag to the STP reason code. So if two different STP
648 // * reason codes map to the same WVCM reason code (which has a tag
649 // * mapping), then the last one entered into the map wins, and that one
650 // * will then get mapped to a possibly different XML tag then the one it
651 // * is supposed to be mapped to. (Or an exception will get thrown when
652 // * the map initializer code finds a conflicting mapping). He intends to
653 // * rewrite the tag mapping stuff once things settle down getting EUCM
654 // * working in this merged Baltic / SelfHosting code.
655 // */
656 // /** A general runtime error occurred */
657 // @Deprecated
658 // RUNTIME(ReasonCode.CONFLICT),
659 //
660 // /** Used by the SelectionErrorException subclass */
661 // @Deprecated
662 // SELECTION_ERROR(ReasonCode.CONFLICT),
663 //
664 /**
665 * The provider has detected something inappropriate with a server's
666 * response. It could be the result of a bug in the server's response or
667 * a bug in the provider's processing of the response.
668 *
669 * @see #INTERNAL_SERVER_ERROR
670 */
671 SERVER_ERROR(ReasonCode.CONFLICT),
672
673 /** View update cancel failed **/
674 SYNC_CANCEL_FAILED(ReasonCode.CONFLICT),
675
676 /**
677 * View's config spec is not synchronized with stream's configuration.
678 * An update view operation is required.
679 */
680 VIEW_OUT_OF_SYNC_WITH_STREAM(ReasonCode.CONFLICT),
681
682 // /**
683 // * This code indicates that the client location (file area) for a
684 // * client-side workspace is not defined or unavailable.
685 // */
686 // @Deprecated
687 // WORKSPACE_CLIENT_LOCATION_UNDEFINED(ReasonCode.CONFLICT),
688 //
689 // /** The precondition of "workspace location OK" was not met */
690 // @Deprecated
691 // WORKSPACE_LOCATION_OK(ReasonCode.CONFLICT),
692 //
693 // /**
694 // * <code>Precondition:</code> This folder already has a project
695 // * configuration.
696 // */
697 // @Deprecated
698 // CONTROLLED_CONFIGURATION_ALREADY_EXISTS,
699 //
700 // /** Cannot create location cycle. */
701 // @Deprecated
702 // CYCLE_NOT_ALLOWED,
703 //
704 /**
705 * The provider was unable to complete the operation for an unspecified
706 * reason.
707 */
708 FORBIDDEN,
709
710 /** Request not understood or contextually incorrect for the provider. */
711 BAD_REQUEST(ReasonCode.FORBIDDEN),
712
713 // /**
714 // * <code>Precondition:</code> The operation failed because the server
715 // * does not allow compare/merge of baselines from different baseline
716 // * histories.
717 // */
718 // @Deprecated
719 // BASELINES_FROM_SAME_HISTORY(ReasonCode.FORBIDDEN),
720 //
721 /** Used by REVERT method */
722 CHILD_ORIGINAL_SOURCE_DIRECTORY_NO_LONGER_EXISTS(ReasonCode.FORBIDDEN),
723
724 /** Used by REVERT method */
725 CHILDREN_OF_FOLDER_MUST_BE_REVERTED_FIRST(ReasonCode.FORBIDDEN),
726
727 /**
728 * Used when an operation is forbidden due to operating in disconnected
729 * mode
730 */
731 DISCONNECTED(ReasonCode.FORBIDDEN),
732
733 /** Used when trying to delete query folders */
734 FOLDER_HAS_CHILDREN(ReasonCode.FORBIDDEN),
735
736 /** An illegal argument was specified */
737 ILLEGAL_ARG(ReasonCode.FORBIDDEN),
738
739 /** The request or operation in not valid */
740 INVALID(ReasonCode.FORBIDDEN),
741
742 /**
743 * Thrown by OpenRecord when a duplicate record is not specified with a
744 * duplicate action.
745 */
746 NO_DUPLICATE_RECORD(ReasonCode.FORBIDDEN),
747
748 /** Request not allowed by the provider. */
749 NOT_ALLOWED(ReasonCode.FORBIDDEN),
750
751 /** The request or operation is not supported */
752 NOT_SUPPORTED(ReasonCode.FORBIDDEN),
753
754 // /**
755 // * <code>Precondition:</code> Cannot checkin the project configuration
756 // * because more than one member exists for a given version history.
757 // */
758 // @Deprecated
759 // ONE_VERSION_PER_HISTORY_PER_BASELINE(ReasonCode.FORBIDDEN),
760 //
761 /** The submit request is not allowed */
762 SUBMIT_NOT_ALLOWED(ReasonCode.FORBIDDEN),
763
764 /**
765 * Thrown by OpenRecord when the specified action is not defined for the
766 * record type.
767 */
768 UNKNOWN_ACTION(ReasonCode.FORBIDDEN),
769
770 /**
771 * Thrown when a report has been requested on resource that does not
772 * support that report type.
773 */
774 UNSUPPORTED_REPORT(ReasonCode.FORBIDDEN),
775
776 /** Illegal syntax for location string value. */
777 ILLEGAL_LOCATION_SYNTAX,
778
779 // /**
780 // * Report failed since the resource does not support the specified
781 // * report.
782 // */
783 // @Deprecated
784 // METHOD_NOT_SUPPORTED,
785 //
786 /**
787 * <code>Precondition:</code> Report failed since the resource does
788 * not support the specified report.
789 */
790 BAD_REPORT(ReasonCode.METHOD_NOT_SUPPORTED),
791
792 // ////////////////////////////////////////////////////////////////
793 // These are all from the original ServerConflictException.java,
794 // and each had a "CTG_" prefix, which has been removed here.
795 // ////////////////////////////////////////////////////////////////
796
797 // /**
798 // * <code>Precondition:</code> Failed because the resource specified is
799 // * a folder version.
800 // */
801 // @Deprecated
802 // CANNOT_COPY_FOLDER_VERSION(ReasonCode.METHOD_NOT_SUPPORTED),
803 //
804 // /**
805 // * <code>Precondition:</code> Copy failed because you cannot copy a
806 // * history resource.
807 // */
808 // @Deprecated
809 // CANNOT_COPY_HISTORY(ReasonCode.METHOD_NOT_SUPPORTED),
810 //
811 // /**
812 // * <code>Precondition:</code> Delete failed because you cannot delete
813 // * a version.
814 // */
815 // @Deprecated
816 // CANNOT_DELETE_VERSION(ReasonCode.METHOD_NOT_SUPPORTED),
817 //
818 // /** <code>Precondition:</code> A version history cannot be renamed. */
819 // @Deprecated
820 // CANNOT_RENAME_HISTORY(ReasonCode.METHOD_NOT_SUPPORTED),
821 //
822 // /** <code>Precondition:</code> A version resource cannot be renamed. */
823 // @Deprecated
824 // CANNOT_RENAME_VERSION(ReasonCode.METHOD_NOT_SUPPORTED),
825 //
826 // /** Cannot create multiple bindings to one resource. */
827 // @Deprecated
828 // MULTIPLE_BINDINGS_NOT_ALLOWED(ReasonCode.METHOD_NOT_SUPPORTED),
829 //
830 /** The resource has no content. */
831 NO_CONTENT(ReasonCode.METHOD_NOT_SUPPORTED),
832
833
834 // /**
835 // * Method failed on some of the specified resources.
836 // */
837 // @Deprecated
838 // MULTI_STATUS,
839 //
840 // /**
841 // * <code>Precondition:</code> Activity cannot be checked-in because
842 // * checkin of all referenced resources failed.
843 // */
844 // @Deprecated
845 // CANNOT_CHECKIN_ALL_RESOURCES(ReasonCode.MULTI_STATUS),
846 //
847 // /**
848 // * <code>Precondition:</code> The operation failed because the
849 // * resource must be in the checked-in state.
850 // */
851 // @Deprecated
852 // MUST_BE_CHECKED_IN,
853 //
854 // /**
855 // * STP Reason codes to support Legacy CCRC server
856 // */
857 //
858 // /**
859 // * The operation failed because the resource must be in the checked-out
860 // * state.
861 // */
862 // @Deprecated
863 // MUST_BE_CHECKED_OUT,
864 //
865 // /**
866 // * <code>Precondition:</code> Failed to checkin the project
867 // * configuration because some of it's members are still checked-out.
868 // */
869 // @Deprecated
870 // NO_CHECKED_OUT_BASELINE_CONTROLLED_FOLDER_MEMBERS,
871 //
872 // /** Cannot create cross-server binding. */
873 // @Deprecated
874 // NO_CROSS_SERVER_BINDING,
875 //
876 /**
877 * The corresponding remote resource no longer exists or was never
878 * created.
879 */
880 NOT_FOUND,
881
882 // /**
883 // * <code>Precondition:</code> Failed because more than one version of
884 // * this resource is referenced in the specified activity.
885 // */
886 // @Deprecated
887 // ONE_CHECKOUT_PER_ACTIVITY_PER_HISTORY,
888 //
889 // /**
890 // * <code>Precondition:</code> The operation failed because it would
891 // * result in more than one controlled resource for this version history
892 // * in a workspace.
893 // */
894 // @Deprecated
895 // ONE_CONTROLLED_RESOURCE_PER_HISTORY_PER_WORKSPACE,
896 //
897 /**
898 * <code>Precondition:</code> Failed to retrieve a property that
899 * should be supported. A potentially recoverable condition prevented
900 * the server from retrieving the property value.
901 */
902 PROPERTY_NOT_CURRENTLY_AVAILABLE,
903
904 /**
905 * The requested property value is unavailable because it is not valid
906 * for the targeted resource--the property name used is not defined in
907 * the targeted resource's interface nor is it included in the
908 * PropertyRequest returned by
909 * {@link javax.wvcm.Resource#doGetPropertyNameList(Feedback)} for the
910 * resource.
911 */
912 PROPERTY_NOT_DEFINED_FOR_RESOURCE,
913
914 /**
915 * The property value is maintained only on the server and so is not
916 * available locally
917 */
918 PROPERTY_NOT_AVAILABLE_LOCALLY(ReasonCode.PROPERTY_NOT_DEFINED_FOR_RESOURCE),
919
920 /**
921 * The property value is unavailable because it was not in the property
922 * name list when the proxy was created nor has it subsequently been
923 * added via {@link Resource#setProperty} or one of the other property
924 * setters.
925 */
926 PROPERTY_NOT_REQUESTED,
927
928 /**
929 * Even though this API says the property is valid for the targeted
930 * resource, the server does not support it. For properties the server
931 * intends to support in the release under development, the exception
932 * message should say “NOT YET IMPLEMENTED”.
933 */
934 PROPERTY_NOT_SUPPORTED_BY_SERVER,
935
936 /** The property value update would overwrite an earlier change. */
937 PROPERTY_OVERWRITE_FORBIDDEN,
938
939 /** The provider suffered an I/O failure, the operation may be retried. */
940 READ_FAILED,
941
942 /**
943 * <code>Precondition:</code> Creating a resource failed because a
944 * resource already exists at the specified location.
945 */
946 RESOURCE_ALREADY_EXISTS_AT_LOCATION,
947
948 /** View update was canceled **/
949 SYNC_CANCELLED (ReasonCode.CONFLICT),
950
951 /** The user is not authorized to execute the attempted operation. */
952 UNAUTHORIZED,
953
954 /** Login on server failed**/
955 LOGIN_FAILED(ReasonCode.UNAUTHORIZED),
956
957 // /**
958 // * The referenced record exists but is hidden from the accessing user.
959 // */
960 // @Deprecated
961 // RECORD_NOT_VISIBLE(ReasonCode.UNAUTHORIZED),
962 //
963 // /**
964 // * <code>Precondition:</code> Cannot checkin because the resources
965 // * predecessors are not descendents of the root of the version history.
966 // */
967 // @Deprecated
968 // VERSION_HISTORY_MUST_BE_A_TREE,
969 //
970 /** The provider suffered an I/O failure, the operation may be retried. */
971 WRITE_FAILED,
972
973 /**
974 * Session does not exist or the session has expired.
975 */
976 SESSION_EXPIRED_OR_DOES_NOT_EXIST(ReasonCode.UNAUTHORIZED),
977
978 /**
979 * Used if an operation requires credentials but none were provided
980 */
981 CREDENTIALS_REQUIRED(ReasonCode.UNAUTHORIZED),
982
983 /**
984 * Used when the server capacity has been reached.
985 */
986 SERVER_BUSY(ReasonCode.CONFLICT),
987
988 /**
989 * Used when the client is not compatible with the server. (This may
990 * be caused by a client that is too old, or too new.)
991 */
992 INCOMPATIBLE_SERVER(ReasonCode.VERSION_NOT_SUPPORTED),
993
994 ;
995 /* end of enum StpReasonCode */;
996
997 // ====================================================================
998
999 /**
1000 * Returns the WVCM base reason code associated with this STP reason
1001 * code.
1002 *
1003 * @return The WVCM reason code associated with this STP reason code.
1004 */
1005 public ReasonCode getWvcmReasonCode()
1006 {
1007 return m_wvcmReasonCode;
1008 }
1009
1010 /*
1011 * A string representation of this reason code.
1012 */
1013 public String toString()
1014 {
1015 return name().toLowerCase().replaceAll("_", "-");
1016 }
1017
1018 /**
1019 * Constructs an StpReasonCode that is semantically equivalent to the
1020 * WVCM ReasonCode of the same name.
1021 */
1022 private StpReasonCode()
1023 {
1024 m_wvcmReasonCode = ReasonCode.valueOf(ReasonCode.class, name());
1025 }
1026
1027 /**
1028 * Constructs an StpReasonCode as a refinement of a WVCM base
1029 * ReasonCode.
1030 *
1031 * @param wvcmBaseCode The WVCM reason code that this StpReasonCode
1032 * refines. Cannot be <code>null</code>.
1033 */
1034 private StpReasonCode(ReasonCode wvcmBaseCode)
1035 {
1036 m_wvcmReasonCode = wvcmBaseCode;
1037 }
1038
1039 /**
1040 * The WVCM reason code classification for this SubReasonCode.
1041 */
1042 private final ReasonCode m_wvcmReasonCode;
1043 }
1044
1045 /**
1046 * Casts an Object to a Type, avoiding a type safety warning. Use sparingly.
1047 * May throw ClassCastException at runtime. Some Java compilers can deduce
1048 * U from context, such as in an assignment or a return statement; however,
1049 * others may not. It is suggested, therefore, that all uses of this method
1050 * should include the target type explicitly.
1051 * <pre>
1052 * StpException.<desired-type>unchecked_cast(x)
1053 * </pre>
1054 * The ugliness of this construct matches the sledge hammer that is being
1055 * used to make the code compile without warnings.
1056 *
1057 * @param <U> The Type to which the object should be cast
1058 * @param obj The Object to be cast
1059 * @return The argument Object cast to Type U.
1060 */
1061 @SuppressWarnings("unchecked")
1062 public static <U> U unchecked_cast(Object obj)
1063 {
1064 return (U)obj;
1065 }
1066
1067 /**
1068 * @return Returns an implementation object that stores the fields of this
1069 * exception not defined by WvcmException and implements the other
1070 * methods of this exception. Will never be <b>null</b>.
1071 */
1072 public abstract Data data();
1073
1074 /**
1075 * Localizes the message contained within this exception and returns it.
1076 */
1077 public String getMessage() { return data().getMessage(); }
1078
1079 /**
1080 * @return The StpReasonCode assigned to this exception.
1081 */
1082 public StpReasonCode getStpReasonCode()
1083 { return data().getStpReasonCode(); }
1084
1085 /**
1086 * @return A String image of this StpException and any nested Exceptions
1087 */
1088 public String toString() { return data().toString(); }
1089
1090 /**
1091 * Constructs this exception object for its subclasses.
1092 *
1093 * @param resource The Resource argument to WvcmException
1094 * @param reasonCode The ReasonCode argument to WvcmException
1095 * @param nestedExceptions The Throwable[] argument to WvcmException
1096 *
1097 * @see javax.wvcm.WvcmException
1098 */
1099 protected StpException(Resource resource,
1100 ReasonCode reasonCode,
1101 Throwable... nestedExceptions)
1102 {
1103 super(null, resource, reasonCode, nestedExceptions);
1104 }
1105 }