xercesc/dom/DOMException.hpp

0001 /*
0002  * Licensed to the Apache Software Foundation (ASF) under one or more
0003  * contributor license agreements.  See the NOTICE file distributed with
0004  * this work for additional information regarding copyright ownership.
0005  * The ASF licenses this file to You under the Apache License, Version 2.0
0006  * (the "License"); you may not use this file except in compliance with
0007  * the License.  You may obtain a copy of the License at
0008  *
0009  *      http://www.apache.org/licenses/LICENSE-2.0
0010  *
0011  * Unless required by applicable law or agreed to in writing, software
0012  * distributed under the License is distributed on an "AS IS" BASIS,
0013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0014  * See the License for the specific language governing permissions and
0015  * limitations under the License.
0016  */
0017
0018 /*
0019  * $Id$
0020  */
0021
0022 #if !defined(XERCESC_INCLUDE_GUARD_DOMEXCEPTION_HPP)
0023 #define XERCESC_INCLUDE_GUARD_DOMEXCEPTION_HPP
0024
0025 #include <xercesc/util/XercesDefs.hpp>
0026 #include <xercesc/util/PlatformUtils.hpp>
0027
0028 XERCES_CPP_NAMESPACE_BEGIN
0029
0030
0031 /**
0032  * DOM operations only raise exceptions in "exceptional" circumstances, i.e.,
0033  * when an operation is impossible to perform (either for logical reasons,
0034  * because data is lost, or because the implementation has become unstable).
0035  * In general, DOM methods return specific error values in ordinary
0036  * processing situations, such as out-of-bound errors when using
0037  * <code>DOMNodeList</code>.
0038  * <p>Implementations should raise other exceptions under other circumstances.
0039  * For example, implementations should raise an implementation-dependent
0040  * exception if a <code>null</code> argument is passed.
0041  * <p>Some languages and object systems do not support the concept of
0042  * exceptions. For such systems, error conditions may be indicated using
0043  * native error reporting mechanisms. For some bindings, for example,
0044  * methods may return error codes similar to those listed in the
0045  * corresponding method descriptions.
0046  * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>Document Object Model (DOM) Level 2 Core Specification</a>.
0047  * @since DOM Level 1
0048  */
0049
0050 class MemoryManager;
0051
0052 class CDOM_EXPORT DOMException  {
0053 public:
0054     // -----------------------------------------------------------------------
0055     //  Class Types
0056     // -----------------------------------------------------------------------
0057     /** @name Public Constants */
0058     //@{
0059     /**
0060      * ExceptionCode
0061      *
0062      * <p><code>INDEX_SIZE_ERR:</code>
0063      * If index or size is negative, or greater than the allowed value.</p>
0064      *
0065      * <p><code>DOMSTRING_SIZE_ERR:</code>
0066      * If the specified range of text does not fit into a DOMString.</p>
0067      *
0068      * <p><code>HIERARCHY_REQUEST_ERR:</code>
0069      * If any node is inserted somewhere it doesn't belong.</p>
0070      *
0071      * <p><code>WRONG_DOCUMENT_ERR:</code>
0072      * If a node is used in a different document than the one that created it
0073      * (that doesn't support it).</p>
0074      *
0075      * <p><code>INVALID_CHARACTER_ERR:</code>
0076      * If an invalid or illegal character is specified, such as in a name. See
0077      * production 2 in the XML specification for the definition of a legal
0078      * character, and production 5 for the definition of a legal name
0079      * character.</p>
0080      *
0081      * <p><code>NO_DATA_ALLOWED_ERR:</code>
0082      * If data is specified for a node which does not support data.</p>
0083      *
0084      * <p><code>NO_MODIFICATION_ALLOWED_ERR:</code>
0085      * If an attempt is made to modify an object where modifications are not
0086      * allowed.</p>
0087      *
0088      * <p><code>NOT_FOUND_ERR:</code>
0089      * If an attempt is made to reference a node in a context where it does
0090      * not exist.</p>
0091      *
0092      * <p><code>NOT_SUPPORTED_ERR:</code>
0093      * If the implementation does not support the requested type of object or
0094      * operation.</p>
0095      *
0096      * <p><code>INUSE_ATTRIBUTE_ERR:</code>
0097      * If an attempt is made to add an attribute that is already in use
0098      * elsewhere.</p>
0099      *
0100      * The above are since DOM Level 1
0101      * @since DOM Level 1
0102      *
0103      * <p><code>INVALID_STATE_ERR:</code>
0104      * If an attempt is made to use an object that is not, or is no longer,
0105      * usable.</p>
0106      *
0107      * <p><code>SYNTAX_ERR:</code>
0108      * If an invalid or illegal string is specified.</p>
0109      *
0110      * <p><code>INVALID_MODIFICATION_ERR:</code>
0111      * If an attempt is made to modify the type of the underlying object.</p>
0112      *
0113      * <p><code>NAMESPACE_ERR:</code>
0114      * If an attempt is made to create or change an object in a way which is
0115      * incorrect with regard to namespaces.</p>
0116      *
0117      * <p><code>INVALID_ACCESS_ERR:</code>
0118      * If a parameter or an operation is not supported by the underlying
0119      * object.
0120      *
0121      * The above are since DOM Level 2
0122      * @since DOM Level 2
0123      *
0124      * <p><code>VALIDATION_ERR:</code>
0125      * If a call to a method such as <code>insertBefore</code> or
0126      * <code>removeChild</code> would make the <code>Node</code> invalid
0127      * with respect to "partial validity", this exception would be raised
0128      * and the operation would not be done.
0129      *
0130      * <p><code>TYPE_MISMATCH_ERR:</code>
0131      * If the type of an object is incompatible with the expected type of
0132      * the parameter associated to the object, this exception would be raised.
0133      *
0134      * The above is since DOM Level 3
0135      * @since DOM Level 3
0136      */
0137     enum ExceptionCode {
0138          INDEX_SIZE_ERR                 = 1,
0139          DOMSTRING_SIZE_ERR             = 2,
0140          HIERARCHY_REQUEST_ERR          = 3,
0141          WRONG_DOCUMENT_ERR             = 4,
0142          INVALID_CHARACTER_ERR          = 5,
0143          NO_DATA_ALLOWED_ERR            = 6,
0144          NO_MODIFICATION_ALLOWED_ERR    = 7,
0145          NOT_FOUND_ERR                  = 8,
0146          NOT_SUPPORTED_ERR              = 9,
0147          INUSE_ATTRIBUTE_ERR            = 10,
0148          INVALID_STATE_ERR              = 11,
0149          SYNTAX_ERR                     = 12,
0150          INVALID_MODIFICATION_ERR       = 13,
0151          NAMESPACE_ERR                  = 14,
0152          INVALID_ACCESS_ERR             = 15,
0153          VALIDATION_ERR                 = 16,
0154          TYPE_MISMATCH_ERR              = 17
0155         };
0156     //@}
0157
0158 public:
0159     // -----------------------------------------------------------------------
0160     //  Constructors
0161     // -----------------------------------------------------------------------
0162     /** @name Constructors */
0163     //@{
0164     /**
0165       * Default constructor for DOMException.
0166       *
0167       */
0168     DOMException();
0169
0170     /**
0171       * Constructor which takes an error code and an optional message code.
0172       *
0173       * @param code           The error code which indicates the exception
0174       * @param messageCode    The string containing the error message
0175       * @param memoryManager  The memory manager used to (de)allocate memory
0176       */
0177     DOMException(short code,
0178                  short messageCode = 0,
0179                  MemoryManager* const  memoryManager = XMLPlatformUtils::fgMemoryManager);
0180
0181     /**
0182       * Copy constructor.
0183       *
0184       * @param other The object to be copied.
0185       */
0186     DOMException(const DOMException &other);
0187
0188     //@}
0189
0190     // -----------------------------------------------------------------------
0191     //  Destructors
0192     // -----------------------------------------------------------------------
0193     /** @name Destructor. */
0194     //@{
0195      /**
0196       * Destructor for DOMException.
0197       *
0198       */
0199     virtual ~DOMException();
0200     //@}
0201
0202
0203 public:
0204     // -----------------------------------------------------------------------
0205     //  Getter
0206     // -----------------------------------------------------------------------
0207     inline const XMLCh* getMessage()    const;
0208
0209     // -----------------------------------------------------------------------
0210     //  Class Types
0211     // -----------------------------------------------------------------------
0212     /** @name Public variables */
0213     //@{
0214     /**
0215      * A code value, from the set defined by the ExceptionCode enum,
0216      * indicating the type of error that occured.
0217      */
0218     short   code;
0219
0220     /**
0221      * A string value.  Applications may use this field to hold an error
0222      *  message.  The field value is not set by the DOM implementation,
0223      *  meaning that the string will be empty when an exception is first
0224      *  thrown.
0225      */
0226     const XMLCh *msg;
0227     //@}
0228
0229 protected:
0230     MemoryManager*  fMemoryManager;
0231
0232 private:
0233
0234      /**
0235       * A boolean value.
0236       *   If the message is provided by the applications, it is not
0237       *   adopted.
0238       *   If the message is resolved by the DOM implementation, it is
0239       *   owned.
0240       */
0241     bool            fMsgOwned;
0242
0243 private:
0244     // -----------------------------------------------------------------------
0245     // Unimplemented constructors and operators
0246     // -----------------------------------------------------------------------
0247     DOMException & operator = (const DOMException &);
0248 };
0249
0250 inline const XMLCh* DOMException::getMessage() const
0251 {
0252     return msg;
0253 }
0254
0255 XERCES_CPP_NAMESPACE_END
0256
0257 #endif