Ticket #144: formaterror.patch

include/xapian/database.h

@@ -49 +49 @@
  *
  *  @exception DatabaseOpeningError may be thrown if the database cannot
  *  be opened (for example, a required file cannot be found).
+ *
+ *  @exception DatabaseFormatError may be thrown if the database is in an
+ *  unsupported format (for example, created by a newer version of Xapian
+ *  which uses an incompatible format).
  */
 class XAPIAN_VISIBILITY_DEFAULT Database {
     public:

exception_data.pm

@@ -128 +128 @@
 /** DatabaseOpeningError indicates failure to open a database. */
 DOC
 
+errorclass('DatabaseFormatError', 'DatabaseOpeningError', <<'DOC');
+/** DatabaseFormatError indicates that a database is in an unknown format.
+ *
+ *  From time to time, new versions of Xapian will require the database format
+ *  to be changed, to allow new information to be stored or new optimisations
+ *  to be performed.  Backwards compatibility will sometimes be maintained, so
+ *  that new versions of Xapian can open old databases, but in some cases
+ *  Xapian will be unable to open a database because it is in too old (or new)
+ *  a format.  This can be resolved either be upgrading or downgrading the
+ *  version of Xapian in use, or by rebuilding the database from scratch with
+ *  the current version of Xapian.
+ */
+DOC
+
 errorclass('DocNotFoundError', 'RuntimeError', <<'DOC');
 /** Indicates an attempt to access a document not present in the database. */
 DOC

backends/quartz/quartz_metafile.cc

@@ -80 +80 @@
     unsigned int version;
     version = decode_version(data.substr(metafile_magic.length(), 4));
     if (version != metafile_version) {
-        throw Xapian::DatabaseOpeningError("Unknown Quartz metafile version " +
+        throw Xapian::DatabaseFormatError("Unknown Quartz metafile version " +
                              om_tostring(version) + " in " +
                              filename);
     }

backends/quartz/quartz_database.h

@@ -183 +183 @@
          *  @exception Xapian::DatabaseCorruptError is thrown if there is no
          *             consistent revision available.
          *
-         *  @exception Xapian::DatabaseOpeningError thrown if database can't be opened.
+         *  @exception Xapian::DatabaseOpeningError thrown if database can't be
+         *             opened.
          *
+         *  @exception Xapian::DatabaseFormatError thrown if database is in an
+         *             unsupported format.  This implies that the database was
+         *             created by an older or newer version of Xapian.
+         *
          *  @param dbdir directory holding quartz tables
          *
          *  @param block_size Block size, in bytes, to use when creating
@@ -282 +287 @@
     public:
         /** Create and open a writable quartz database.
          *
-         *  @exception Xapian::DatabaseOpeningError thrown if database can't be opened.
+         *  @exception Xapian::DatabaseOpeningError thrown if database can't be
+         *             opened.
          *
+         *  @exception Xapian::DatabaseFormatError thrown if database is in an
+         *             unsupported format.  This implies that the database was
+         *             created by an older or newer version of Xapian.
+         *
          *  @param dir directory holding quartz tables
          */
         QuartzWritableDatabase(const string &dir, int action, int block_size);

backends/quartz/quartz_metafile.h

@@ -45 +45 @@
         /** Open the meta-file.
          *
          *  @except     Xapian::DatabaseOpeningError if the meta-file was not
-         *              opened successfully or is compatible with this version
-         *              of the library.
+         *              opened successfully or is not compatible with this
+         *              version of the library.
          */
         void open();
 

backends/quartz/quartz_database.cc

@@ -96 +96 @@
         if (!dbexists) {
             // Catch pre-0.6 Xapian databases and give a better error
             if (file_exists(db_dir + "/attribute_DB"))
-                throw Xapian::DatabaseOpeningError("Cannot open database at `" + db_dir + "' - it was created by a pre-0.6 version of Xapian");
+                throw Xapian::DatabaseFormatError("Cannot open database at `" + db_dir + "' - it was created by a pre-0.6 version of Xapian");
             throw Xapian::DatabaseOpeningError("Cannot open database at `" + db_dir + "' - it does not exist");
         }
         // Can still allow searches even if recovery is needed
@@ -107 +107 @@
             if (action == Xapian::DB_OPEN) {
                 // Catch pre-0.6 Xapian databases and give a better error
                 if (file_exists(db_dir + "/attribute_DB"))
-                    throw Xapian::DatabaseOpeningError("Cannot open database at `" + db_dir + "' - it was created by a pre-0.6 version of Xapian");
+                    throw Xapian::DatabaseFormatError("Cannot open database at `" + db_dir + "' - it was created by a pre-0.6 version of Xapian");
                 throw Xapian::DatabaseOpeningError("Cannot open database at `" + db_dir + "' - it does not exist");
             }
 

backends/flint/flint_database.h

@@ -176 +176 @@
          *  @exception Xapian::DatabaseCorruptError is thrown if there is no
          *             consistent revision available.
          *
-         *  @exception Xapian::DatabaseOpeningError thrown if database can't be opened.
+         *  @exception Xapian::DatabaseOpeningError thrown if database can't
+         *             be opened.
          *
+         *  @exception Xapian::DatabaseFormatError thrown if database is in an
+         *             unsupported format.  This implies that the database was
+         *             created by an older or newer version of Xapian.
+         *
          *  @param dbdir directory holding flint tables
          *
          *  @param block_size Block size, in bytes, to use when creating
@@ -275 +280 @@
     public:
         /** Create and open a writable flint database.
          *
-         *  @exception Xapian::DatabaseOpeningError thrown if database can't be opened.
+         *  @exception Xapian::DatabaseOpeningError thrown if database can't
+         *             be opened.
          *
+         *  @exception Xapian::DatabaseFormatError thrown if database is in an
+         *             unsupported format.  This implies that the database was
+         *             created by an older or newer version of Xapian.
+         *
          *  @param dir directory holding flint tables
          */
         FlintWritableDatabase(const string &dir, int action, int block_size);

backends/flint/flint_version.cc

@@ -126 +126 @@
         msg += " is version ";
         msg += om_tostring(version);
         msg += " but I only understand "STRINGIZE(FLINT_VERSION);
-        throw Xapian::DatabaseOpeningError(msg);
+        throw Xapian::DatabaseFormatError(msg);
     }
 }

backends/flint/flint_database.cc

@@ -82 +82 @@
         if (!dbexists) {
             // Catch pre-0.6 Xapian databases and give a better error
             if (file_exists(db_dir + "/attribute_DB"))
-                throw Xapian::DatabaseOpeningError("Cannot open database at `" + db_dir + "' - it was created by a pre-0.6 version of Xapian");
+                throw Xapian::DatabaseFormatError("Cannot open database at `" + db_dir + "' - it was created by a pre-0.6 version of Xapian");
             throw Xapian::DatabaseOpeningError("Cannot open database at `" + db_dir + "' - it does not exist");
         }
         // Can still allow searches even if recovery is needed