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