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 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            RPC_UNEXPECTEDLY_EXITED(ReasonCode.CONFLICT),
995            
996            ;
997            /* end of enum StpReasonCode */;
998            
999            // ====================================================================
1000    
1001            /**
1002             * Returns the WVCM base reason code associated with this STP reason
1003             * code.
1004             * 
1005             * @return The WVCM reason code associated with this STP reason code.
1006             */
1007            public ReasonCode getWvcmReasonCode()
1008            {
1009                return m_wvcmReasonCode;
1010            }
1011    
1012            /*
1013             * A string representation of this reason code.
1014             */
1015            public String toString()
1016            {
1017                return name().toLowerCase().replaceAll("_", "-");
1018            }
1019    
1020            /**
1021             * Constructs an StpReasonCode that is semantically equivalent to the
1022             * WVCM ReasonCode of the same name.
1023             */
1024            private StpReasonCode()
1025            {
1026                m_wvcmReasonCode = ReasonCode.valueOf(ReasonCode.class, name());
1027            }
1028    
1029            /**
1030             * Constructs an StpReasonCode as a refinement of a WVCM base
1031             * ReasonCode.
1032             * 
1033             * @param wvcmBaseCode The WVCM reason code that this StpReasonCode
1034             *            refines. Cannot be <code>null</code>.
1035             */
1036            private StpReasonCode(ReasonCode wvcmBaseCode)
1037            {
1038                m_wvcmReasonCode = wvcmBaseCode;
1039            }
1040    
1041            /**
1042             * The WVCM reason code classification for this SubReasonCode.
1043             */
1044            private final ReasonCode m_wvcmReasonCode;
1045        }
1046    
1047        /**
1048         * Casts an Object to a Type, avoiding a type safety warning. Use sparingly.
1049         * May throw ClassCastException at runtime. Some Java compilers can deduce
1050         * U from context, such as in an assignment or a return statement; however,
1051         * others may not. It is suggested, therefore, that all uses of this method
1052         * should include the target type explicitly.
1053         * <pre>
1054         *  StpException.&lt;desired-type>unchecked_cast(x)
1055         * </pre> 
1056         * The ugliness of this construct matches the sledge hammer that is being
1057         * used to make the code compile without warnings.
1058         * 
1059         * @param <U> The Type to which the object should be cast
1060         * @param obj The Object to be cast
1061         * @return The argument Object cast to Type U.
1062         */
1063        @SuppressWarnings("unchecked")
1064        public static <U> U unchecked_cast(Object obj)
1065        {
1066            return (U)obj;
1067        }
1068        
1069        /**
1070         * @return Returns an implementation object that stores the fields of this
1071         *         exception not defined by WvcmException and implements the other
1072         *         methods of this exception. Will never be <b>null</b>.
1073         */
1074        public abstract Data data();
1075    
1076        /**
1077         * Localizes the message contained within this exception and returns it.
1078         */
1079        public String getMessage() { return data().getMessage(); }
1080        
1081        /**
1082         * @return The StpReasonCode assigned to this exception.
1083         */
1084        public StpReasonCode getStpReasonCode()
1085        { return data().getStpReasonCode(); }
1086        
1087        /**
1088         * @return A String image of this StpException and any nested Exceptions
1089         */
1090        public String toString() { return data().toString(); }
1091    
1092        /**
1093         * Constructs this exception object for its subclasses.
1094         * 
1095         * @param resource The Resource argument to WvcmException
1096         * @param reasonCode The ReasonCode argument to WvcmException
1097         * @param nestedExceptions The Throwable[] argument to WvcmException
1098         * 
1099         * @see javax.wvcm.WvcmException
1100         */
1101        protected StpException(Resource resource,
1102                               ReasonCode reasonCode,
1103                               Throwable... nestedExceptions)
1104        {
1105            super(null, resource, reasonCode, nestedExceptions);
1106        }
1107    }