ceph/src/boost/libs/serialization/doc/exceptions.html

   1 <!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <!--
   4 (C) Copyright 2002-4 Robert Ramey - http://www.rrsd.com .
   5 Use, modification and distribution is subject to the Boost Software
   6 License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
   7 http://www.boost.org/LICENSE_1_0.txt)
   8 -->
   9 <head>
  10 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  11 <link rel="stylesheet" type="text/css" href="../../../boost.css">
  12 <link rel="stylesheet" type="text/css" href="style.css">
  13 <title>Serialization - Archive Exceptions</title>
  14 </head>
  15 <body link="#0000ff" vlink="#800080">
  16 <table border="0" cellpadding="7" cellspacing="0" width="100%" summary="header">
  17   <tr>
  18     <td valign="top" width="300">
  19       <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../boost.png" border="0"></a></h3>
  20     </td>
  21     <td valign="top">
  22       <h1 align="center">Serialization</h1>
  23       <h2 align="center">Archive Exceptions</h2>
  24     </td>
  25   </tr>
  26 </table>
  27 <hr>
  28 <dl class="page-index">
  29   <dt><a href="#unregistered_class"><code style="white-space: normal">unregistered_class</code></a>
  30   <dt><a href="#invalid_signature"><code style="white-space: normal">invalid_signature</code></a>
  31   <dt><a href="#unsupported_version"><code style="white-space: normal">unsupported_version</code></a>
  32   <dt><a href="#unsupported_class_version"><code style="white-space: normal">unsupported_class_version</code></a>
  33   <dt><a href="#pointer_conflict"><code style="white-space: normal">pointer_conflict</code></a>
  34   <dt><a href="#incompatible_native_format"><code style="white-space: normal">incompatible_native_format</code></a>
  35   <dt><a href="#array_size_too_short"><code style="white-space: normal">array_size_too_short</code></a>
  36   <dt><a href="#input_stream_error"><code style="white-space: normal">input_stream_error</code></a>
  37   <dt><a href="#output_stream_error"><code style="white-space: normal">output_stream_error</code></a>
  38   <dt><a href="#invalid_class_name"><code style="white-space: normal">invalid_class_name</code></a>
  39   <dt><a href="#unregistered_class"><code style="white-space: normal">unregistered_class</code></a>
  40   <dt><a href="#multiple_code_instantiation"><code style="white-space: normal">multiple_code_instantiation</code></a>
  41   <dt><a href="#xml_archive_parsing_error"><code style="white-space: normal">xml_archive_parsing_error</code></a>
  42   <dt><a href="#xml_archive_tag_mismatch"><code style="white-space: normal">xml_archive_tag_mismatch</code></a>
  43   <dt><a href="#xml_archive_tag_name_error"><code style="white-space: normal">xml_archive_tag_name_error</code></a>
  44 </dl>
  45
  46 Archive operators can throw a <code style="white-space: normal">boost::archive_exception</code>
  47 object which can be caught by an application program.  These exceptions are defined
  48 in the files <a target="archive_exception_hpp" href="../../../boost/archive/archive_exception.hpp">
  49 archive_exception.hpp</a>
  50 and <a target="basic_xml_archive_hpp" href="../../../boost/archive/basic_xml_archive.hpp">
  51 basic_xml_archive.hpp</a>.
  52 <pre><code>
  53 namespace boost {
  54 namespace archive {
  55
  56 class archive_exception  : public std::exception
  57 {
  58 public:
  59     typedef enum {
  60         unregistered_class,     // attempt to serialize a pointer of
  61                                 // an unregistered class
  62         invalid_signature,      // first line of archive does not contain
  63                                 // expected string
  64         unsupported_version,    // archive created with library version subsequent
  65                                 // to this one
  66         pointer_conflict        // an attempt has been made to directly serialize
  67                                 // an object after having already serialized the same
  68                                 // object through a pointer.  Were this permitted,
  69                                 // the archive load would result in the creation
  70                                 // of an extraneous object.
  71         incompatible_native_format, // attempt to read native binary format
  72                                 // on incompatible platform
  73         array_size_too_short,   // array being loaded doesn't fit in array allocated
  74         input_stream_error      // error on stream input
  75         invalid_class_name,     // class name greater than the maximum permitted.
  76                                 // most likely a corrupted archive or an attempt
  77                                 // to insert virus via buffer overrun method.
  78         unregistered_cast,      // base - derived relationship not registered with
  79                                 // void_cast_register
  80         unsupported_class_version, // type saved with a version # greater than the
  81                             // one used by the program.  This indicates that the proggram
  82                             // needs to be rebuilt.
  83         multiple_code_instantiation, // code for implementing serialization for some
  84                             // type has been instantiated in more than one module.
  85         output_stream_error     // error on stream output
  86     } exception_code;
  87     exception_code code;
  88     archive_exception(exception_code c) : code(c) {}
  89     virtual const char *what( ) const throw();
  90 };
  91
  92 class xml_archive_exception : public virtual archive_exception
  93 {
  94 public:
  95     typedef enum {
  96         xml_archive_parsing_error,  // archive doesn't contain expected data
  97         xml_archive_tag_mismatch,   // start/end tag in archive doesn't match program
  98         xml_archive_tag_name_error  // tag name contains invalid characters
  99
 100     } exception_code;
 101     xml_archive_exception(exception_code c){}
 102     virtual const char *what( ) const throw();
 103 };
 104
 105 } // archive
 106 } // boost
 107 </code></pre>
 108 <p>
 109 <h3><a name="unregistered_class"><code style="white-space: normal">unregistered_class</code></a></h3>
 110 An attempt has been made to serialize a polymorphic class through a pointer
 111 without either registering it or associating it with an export key.  This can also occur
 112 when using a new archive whose class name has not been added to the system with the
 113 <code style="white-space: normal">BOOST_ARCHIVE_CUSTOM_ARCHIVE_TYPES</code> macro.
 114
 115 <h3><a name="invalid_signature"><code style="white-space: normal">invalid_signature</code></a></h3>
 116 Archives are initiated with a known string.  If this string is not found when
 117 the archive is opened, It is presumed that this file is not a valid archive and this
 118 exception is thrown.
 119
 120 <h3><a name="unsupported_version"><code style="white-space: normal">unsupported_version</code></a></h3>
 121 This system records the current library version number to all archives created.  Note that this is in
 122 no way related to version number of classes used by application programs. This refers
 123 to the version of the serialization system used to create the archive. Future versions
 124 of this serialization system will be able to identify archives created under a previous
 125 (i.e. this) system and alter the loading procedure accordingly.  Hence, future enhancements
 126 to this serialization system should not obsolete any existing archive files.  It is only
 127 necessary to increment this version number when the newer system creates archives
 128 incompatible in format with the current one.
 129 <p>Should it ever occur that an older program attempts to read newer archives whose
 130 format has changed, this exception is thrown.
 131
 132 <h3><a name="unsupported_class_version"><code style="white-space: normal">unsupported_class_version</code></a></h3>
 133 An attempt has been made to load a class whose version has been incremented since the
 134 program was written.  Suppose that a class has been assigned version number 3 and the program
 135 has been built and sent to third parties.  Now suppose that the definition of that class
 136 has been altered, the version number has been incremented to 4 and new archives have been
 137 built.  If one attempts to load these new archives with the original program, this
 138 exception will be thrown.
 139
 140 <h3><a name="pointer_conflict"><code style="white-space: normal">pointer_conflict</code></a></h3>
 141 To understand what this exception means consider the following scenario
 142 <pre><code>
 143 template&lt;class Archive&gt;
 144 void T::save(Archive &ar) const
 145 {
 146     const A * aptr = &a;
 147     ar << aptr;          // save an instance of object of class A through a pointer
 148     ...
 149     ar << a;             // save an instance of an object of class A
 150     assert(aptr == &a);  // this must be true
 151 }
 152
 153 template&lt;class Archive&gt;
 154 void T::load(Archive &ar)
 155 {
 156     A * aptr;
 157     ar >> aptr;          // create and initialize a new instance of class A
 158     ...
 159     ar >> a;             // restore state of on object of class A
 160     assert(aptr == &a);  // this won't be true
 161 }
 162 </pre></code>
 163 An object is saved first through a pointer then directly.  Upon loading back
 164 in the same sequence, we first create an new object and load in its data.  Then
 165 we load the data into another existing object.  Where we started with one
 166 object during save, we have two objects after restore.  In a more realistic
 167 situation, it could be very difficult to find this error.  Fortunately,
 168 these situations can be detected when the archive is created. When
 169 this occurs, this exception is thrown.
 170
 171 <h3><a name = "incompatible_native_format"><code style="white-space: normal">incompatible_native_format</code></a></h3>
 172 The library currently supports char text, wide char text and native binary
 173 archive files. At the beginning of every archive, a signature is written indicating
 174 the type of archive.  This exception is thrown when an attempt is made to read
 175 an archive written in a different format.
 176
 177 <h3><a name="array_size_too_short"><code style="white-space: normal">array_size_too_short</code></a></h3>
 178 An attempt has been made to read an array that is larger than the array size.
 179 This should only occur when the size of an array in code is reduced after an
 180 archive has already been created.
 181
 182 <h3>
 183 <a name="input_stream_error"><code style="white-space: normal">input_stream_error</code></a>
 184 <br>
 185 <a name="output_stream_error"><code style="white-space: normal">output_stream_error</code></a>
 186 </h3>
 187 An error has occured during stream input or ouput.  Aside from the common
 188 situations such as a corrupted or truncated input file, there are
 189 several less obvious ones that sometimes occur.
 190 <p>
 191 This includes
 192 an attempt to read past the end of the file. Text files need a terminating
 193 new line character at the end of the file which is appended when the
 194 archive destructor is invoked.  Be sure that an output archive on a stream
 195 is destroyed before opening an input archive on that same stream.  That is,
 196 rather than using something like:
 197 <pre><code>
 198 std::stringstream ss;
 199 std::vector&lt;V&gt; v;
 200 boost::archive::text_oarchive oa(ss);
 201 oa &lt;&lt; v;
 202 boost::archive::text_iarchive ia(ss);
 203 ia &gt;&gt; v;
 204 </code></pre>
 205 use
 206 <pre><code>
 207 std::stringstream ss;
 208 std::vector&lt;V&gt; v;
 209 {
 210     boost::archive::text_oarchive oa(ss);
 211     oa &lt;&lt; v;
 212 }
 213 {
 214     boost::archive::text_iarchive ia(ss);
 215     ia &gt;&gt; v;
 216 }
 217 </code></pre>
 218 <p>
 219 Another one is the passing of uninitialized data.  In general, the behavior
 220 of the serialization library when passed uninitialized data is undefined.
 221 If it can be detected, it will invoke an assertion in debug builds.
 222 Otherwise, depending on the type of archive, it may pass through without
 223 incident or it may result in an archive with unexpected data in it.
 224 This, in turn, can result in the throwing of this exception.
 225
 226 <h3><a name="invalid_class_name"><code style="white-space: normal">invalid_class_name</code></a></h3>
 227 Class name length greater than the maximum permitted. Most likely cause is a corrupted
 228 archive  or an attempt to insert a virus via the buffer overrun method.
 229
 230 <h3><a name="unregistered_cast"><code style="white-space: normal">unregistered_cast</code></a></h3>
 231 In order to support casting between pointers of base and derived classes
 232 at runtime, a collection of legitimate conversions is maintained by the system.
 233 Normally this collection is maintained without any explicit action
 234 on the part of the user of the library.  However, there are special cases
 235 where this might have to be done explicitly and could be overlooked. This
 236 is described in <a href="serialization.html#runtimecasting">Runtime Casting</a>.
 237 This exception is thrown if an attempt is made to convert between two pointers
 238 whose relationship has not been registered,
 239
 240 <h3><a name="multiple_code_instantiation"><code style="white-space: normal">multiple_code_instantiation</code></a></h3>
 241 This exception is thrown when it is detected that the serialization of the same type
 242 has been instantiated more than once.  This might occur when
 243 serialization code is instantiated in both the mainline and one or more DLLS.
 244
 245 <h3><a name="xml_archive_parsing_error"><code style="white-space: normal">xml_archive_parsing_error</code></a></h3>
 246 The XML generated by the serialization process is intimately coupled to the
 247 C++ class structure, relationships between objects and the serialization
 248 specifications.  If these become out of sync in any way, the XML may not map
 249 to the loading serialization and this exception might be thrown.  This might
 250 occur for one of the following reasons:
 251 <ul>
 252     <li>The archive has been edited outside the serialization system.  This might
 253 be possible if only the data is changed and the XML attributes and nesting
 254 structure are left unaltered.  But any other editing is likely to render the
 255 archive unreadable by the serialization library.
 256     <li>The serialization has been altered and an archive generated by the old
 257 code is being read.  That is, versioning has not been properly employed to
 258 properly deserialize previously created archives.
 259 </ul>
 260
 261 <h3><a name="xml_archive_tag_mismatch"><code style="white-space: normal">xml_archive_tag_mismatch</code></a></h3>
 262 This exception will be thrown if the start or end tag of an XML element doesn't match
 263 the name specified for the object in the program.
 264
 265 <h3><a name="xml_archive_tag_name_error"><code style="white-space: normal">xml_archive_tag_name_error</code></a></h3>
 266 This exception will be thrown if the tag name contains invalid characters.  Valid characters
 267 for an XML tag are: upper and lower case letters, digits, and the following punctuation: .(period),
 268 _(underscore), :(colon), and -(hyphen).
 269
 270 <hr>
 271 <p><i>&copy; Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2002-2004.
 272 Distributed under the Boost Software License, Version 1.0. (See
 273 accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 274 </i></p>
 275 </body>
 276 </html>