| database.h | | database.h | |
| | | | |
| skipping to change at line 226 | | skipping to change at line 226 | |
| /** Send a "keep-alive" to remote databases to stop them timing | | /** Send a "keep-alive" to remote databases to stop them timing | |
| * out. | | * out. | |
| */ | | */ | |
| void keep_alive(); | | void keep_alive(); | |
| | | | |
| /** Get a document from the database, given its document id. | | /** Get a document from the database, given its document id. | |
| * | | * | |
| * This method returns a Xapian::Document object which provides the | | * This method returns a Xapian::Document object which provides the | |
| * information about a document. | | * information about a document. | |
| * | | * | |
|
| * @param did The document id for which to retrieve the data. | | * @param did The document id of the document to retrieve. | |
| * | | * | |
| * @return A Xapian::Document object containing the document d
ata | | * @return A Xapian::Document object containing the document d
ata | |
| * | | * | |
| * @exception Xapian::DocNotFoundError The document specified | | * @exception Xapian::DocNotFoundError The document specified | |
| * could not be found in the database. | | * could not be found in the database. | |
| */ | | */ | |
| Xapian::Document get_document(Xapian::docid did) const; | | Xapian::Document get_document(Xapian::docid did) const; | |
| | | | |
| /** Suggest a spelling correction. | | /** Suggest a spelling correction. | |
| * | | * | |
| | | | |
| skipping to change at line 393 | | skipping to change at line 393 | |
| | | | |
| /** Assignment is allowed. The internals are reference counted, | | /** Assignment is allowed. The internals are reference counted, | |
| * so assignment is cheap. | | * so assignment is cheap. | |
| * | | * | |
| * Note that only an WritableDatabase may be assigned to an | | * Note that only an WritableDatabase may be assigned to an | |
| * WritableDatabase: an attempt to assign a Database is caught | | * WritableDatabase: an attempt to assign a Database is caught | |
| * at compile-time. | | * at compile-time. | |
| */ | | */ | |
| void operator=(const WritableDatabase &other); | | void operator=(const WritableDatabase &other); | |
| | | | |
|
| /** Flush to disk any modifications made to the database. | | /** Commit any pending modifications made to the database. | |
| * | | * | |
| * For efficiency reasons, when performing multiple updates to a | | * For efficiency reasons, when performing multiple updates to a | |
| * database it is best (indeed, almost essential) to make as many | | * database it is best (indeed, almost essential) to make as many | |
| * modifications as memory will permit in a single pass through | | * modifications as memory will permit in a single pass through | |
| * the database. To ensure this, Xapian batches up modifications. | | * the database. To ensure this, Xapian batches up modifications. | |
| * | | * | |
| * Flush may be called at any time to | | * Flush may be called at any time to | |
| * ensure that the modifications which have been made are written t
o | | * ensure that the modifications which have been made are written t
o | |
| * disk: if the flush succeeds, all the preceding modifications wil
l | | * disk: if the flush succeeds, all the preceding modifications wil
l | |
| * have been written to disk. | | * have been written to disk. | |
| * | | * | |
| * If any of the modifications fail, an exception will be thrown an
d | | * If any of the modifications fail, an exception will be thrown an
d | |
| * the database will be left in a state in which each separate | | * the database will be left in a state in which each separate | |
| * addition, replacement or deletion operation has either been full
y | | * addition, replacement or deletion operation has either been full
y | |
| * performed or not performed at all: it is then up to the | | * performed or not performed at all: it is then up to the | |
| * application to work out which operations need to be repeated. | | * application to work out which operations need to be repeated. | |
| * | | * | |
|
| * It's not valid to call flush within a transaction. | | * It's not valid to call flush() within a transaction. | |
| * | | * | |
|
| * Beware of calling flush too frequently: this will have a severe | | * Beware of calling flush() too frequently: this will make indexin | |
| * performance cost. | | g | |
| | | * take much longer. | |
| * | | * | |
|
| * Note that flush need not be called explicitly: it will be called | | * Note that flush() need not be called explicitly: it will be call
ed | |
| * automatically when the database is closed, or when a sufficient | | * automatically when the database is closed, or when a sufficient | |
| * number of modifications have been made. By default, this is eve
ry | | * number of modifications have been made. By default, this is eve
ry | |
| * 10000 documents added, deleted, or modified. This value is rath
er | | * 10000 documents added, deleted, or modified. This value is rath
er | |
| * conservative, and if you have a machine with plenty of memory, | | * conservative, and if you have a machine with plenty of memory, | |
| * you can improve indexing throughput dramatically by setting | | * you can improve indexing throughput dramatically by setting | |
| * XAPIAN_FLUSH_THRESHOLD in the environment to a larger value. | | * XAPIAN_FLUSH_THRESHOLD in the environment to a larger value. | |
| * | | * | |
| * @exception Xapian::DatabaseError will be thrown if a problem occ
urs | | * @exception Xapian::DatabaseError will be thrown if a problem occ
urs | |
| * while modifying the database. | | * while modifying the database. | |
| * | | * | |
| | | | |
| skipping to change at line 444 | | skipping to change at line 444 | |
| * In Xapian a transaction is a group of modifications to the datab
ase | | * In Xapian a transaction is a group of modifications to the datab
ase | |
| * which are linked such that either all will be applied | | * which are linked such that either all will be applied | |
| * simultaneously or none will be applied at all. Even in the case
of | | * simultaneously or none will be applied at all. Even in the case
of | |
| * a power failure, this characteristic should be preserved (as lon
g | | * a power failure, this characteristic should be preserved (as lon
g | |
| * as the filesystem isn't corrupted, etc). | | * as the filesystem isn't corrupted, etc). | |
| * | | * | |
| * A transaction is started with begin_transaction() and can | | * A transaction is started with begin_transaction() and can | |
| * either be committed by calling commit_transaction() or aborted | | * either be committed by calling commit_transaction() or aborted | |
| * by calling cancel_transaction(). | | * by calling cancel_transaction(). | |
| * | | * | |
|
| * By default, a transaction implicitly calls flush before and afte | | * By default, a transaction implicitly calls flush() before and | |
| r | | * after so that the modifications stand and fall without affecting | |
| * so that the modifications stand and fall without affecting | | | |
| * modifications before or after. | | * modifications before or after. | |
| * | | * | |
|
| * The downside of this flushing is that small transactions cause | | * The downside of these implicit calls to flush() is that small | |
| * modifications to be frequently flushed which can harm indexing | | * transactions can harm indexing performance in the same way that | |
| * performance in the same way that explicitly calling flush | | * explicitly calling flush() frequently can. | |
| * frequently can. | | | |
| * | | * | |
| * If you're applying atomic groups of changes and only wish to | | * If you're applying atomic groups of changes and only wish to | |
| * ensure that each group is either applied or not applied, then | | * ensure that each group is either applied or not applied, then | |
| * you can prevent the automatic flush before and after the | | * you can prevent the automatic flush before and after the | |
| * transaction by starting the transaction with | | * transaction by starting the transaction with | |
| * begin_transaction(false). However, if cancel_transaction is | | * begin_transaction(false). However, if cancel_transaction is | |
| * called (or if commit_transaction isn't called before the | | * called (or if commit_transaction isn't called before the | |
| * WritableDatabase object is destroyed) then any changes which | | * WritableDatabase object is destroyed) then any changes which | |
| * were pending before the transaction began will also be discarded
. | | * were pending before the transaction began will also be discarded
. | |
| * | | * | |
| | | | |
| skipping to change at line 501 | | skipping to change at line 500 | |
| * | | * | |
| * @exception Xapian::InvalidOperationError will be thrown if a | | * @exception Xapian::InvalidOperationError will be thrown if a | |
| * transaction is not currently in progress. | | * transaction is not currently in progress. | |
| * | | * | |
| * @exception Xapian::UnimplementedError will be thrown if transact
ions | | * @exception Xapian::UnimplementedError will be thrown if transact
ions | |
| * are not available for this database type. | | * are not available for this database type. | |
| */ | | */ | |
| void commit_transaction(); | | void commit_transaction(); | |
| | | | |
| /** Abort the transaction currently in progress, discarding the | | /** Abort the transaction currently in progress, discarding the | |
|
| * potential modifications made to the database. | | * pending modifications made to the database. | |
| * | | * | |
| * If an error occurs in this method, an exception will be thrown, | | * If an error occurs in this method, an exception will be thrown, | |
| * but the transaction will be cancelled anyway. | | * but the transaction will be cancelled anyway. | |
| * | | * | |
| * @exception Xapian::DatabaseError will be thrown if a problem occ
urs | | * @exception Xapian::DatabaseError will be thrown if a problem occ
urs | |
| * while modifying the database. | | * while modifying the database. | |
| * | | * | |
| * @exception Xapian::DatabaseCorruptError will be thrown if the | | * @exception Xapian::DatabaseCorruptError will be thrown if the | |
| * database is in a corrupt state. | | * database is in a corrupt state. | |
| * | | * | |
| | | | |
| skipping to change at line 536 | | skipping to change at line 535 | |
| * | | * | |
| * If you want to specify the document ID to be used, you should | | * If you want to specify the document ID to be used, you should | |
| * call replace_document() instead. | | * call replace_document() instead. | |
| * | | * | |
| * Note that changes to the database won't be immediately committed
to | | * Note that changes to the database won't be immediately committed
to | |
| * disk; see flush() for more details. | | * disk; see flush() for more details. | |
| * | | * | |
| * As with all database modification operations, the effect is | | * As with all database modification operations, the effect is | |
| * atomic: the document will either be fully added, or the document | | * atomic: the document will either be fully added, or the document | |
| * fails to be added and an exception is thrown (possibly at a | | * fails to be added and an exception is thrown (possibly at a | |
|
| * later time when flush is called or the database is closed). | | * later time when flush() is called or the database is closed). | |
| * | | * | |
| * @param document The new document to be added. | | * @param document The new document to be added. | |
| * | | * | |
| * @return The document ID of the newly added document. | | * @return The document ID of the newly added document. | |
| * | | * | |
| * @exception Xapian::DatabaseError will be thrown if a problem occ
urs | | * @exception Xapian::DatabaseError will be thrown if a problem occ
urs | |
| * while writing to the database. | | * while writing to the database. | |
| * | | * | |
| * @exception Xapian::DatabaseCorruptError will be thrown if the | | * @exception Xapian::DatabaseCorruptError will be thrown if the | |
| * database is in a corrupt state. | | * database is in a corrupt state. | |
| | | | |
| skipping to change at line 561 | | skipping to change at line 560 | |
| * | | * | |
| * This method removes the document with the specified document ID | | * This method removes the document with the specified document ID | |
| * from the database. | | * from the database. | |
| * | | * | |
| * Note that changes to the database won't be immediately committed
to | | * Note that changes to the database won't be immediately committed
to | |
| * disk; see flush() for more details. | | * disk; see flush() for more details. | |
| * | | * | |
| * As with all database modification operations, the effect is | | * As with all database modification operations, the effect is | |
| * atomic: the document will either be fully removed, or the docume
nt | | * atomic: the document will either be fully removed, or the docume
nt | |
| * fails to be removed and an exception is thrown (possibly at a | | * fails to be removed and an exception is thrown (possibly at a | |
|
| * later time when flush is called or the database is closed). | | * later time when flush() is called or the database is closed). | |
| * | | * | |
| * @param did The document ID of the document to be removed. | | * @param did The document ID of the document to be removed. | |
| * | | * | |
| * @exception Xapian::DatabaseError will be thrown if a problem occ
urs | | * @exception Xapian::DatabaseError will be thrown if a problem occ
urs | |
| * while writing to the database. | | * while writing to the database. | |
| * | | * | |
| * @exception Xapian::DatabaseCorruptError will be thrown if the | | * @exception Xapian::DatabaseCorruptError will be thrown if the | |
| * database is in a corrupt state. | | * database is in a corrupt state. | |
| */ | | */ | |
| void delete_document(Xapian::docid did); | | void delete_document(Xapian::docid did); | |
| | | | |
| skipping to change at line 614 | | skipping to change at line 613 | |
| * WritableDatabase::add_document(), Xapian may get to a state wher
e | | * WritableDatabase::add_document(), Xapian may get to a state wher
e | |
| * this counter wraps around and will be unable to automatically | | * this counter wraps around and will be unable to automatically | |
| * allocate document IDs! | | * allocate document IDs! | |
| * | | * | |
| * Note that changes to the database won't be immediately committed
to | | * Note that changes to the database won't be immediately committed
to | |
| * disk; see flush() for more details. | | * disk; see flush() for more details. | |
| * | | * | |
| * As with all database modification operations, the effect is | | * As with all database modification operations, the effect is | |
| * atomic: the document will either be fully replaced, or the docum
ent | | * atomic: the document will either be fully replaced, or the docum
ent | |
| * fails to be replaced and an exception is thrown (possibly at a | | * fails to be replaced and an exception is thrown (possibly at a | |
|
| * later time when flush is called or the database is closed). | | * later time when flush() is called or the database is closed). | |
| * | | * | |
| * @param did The document ID of the document to be replaced. | | * @param did The document ID of the document to be replaced. | |
| * @param document The new document. | | * @param document The new document. | |
| * | | * | |
| * @exception Xapian::DatabaseError will be thrown if a problem occ
urs | | * @exception Xapian::DatabaseError will be thrown if a problem occ
urs | |
| * while writing to the database. | | * while writing to the database. | |
| * | | * | |
| * @exception Xapian::DatabaseCorruptError will be thrown if the | | * @exception Xapian::DatabaseCorruptError will be thrown if the | |
| * database is in a corrupt state. | | * database is in a corrupt state. | |
| */ | | */ | |
| void replace_document(Xapian::docid did, | | void replace_document(Xapian::docid did, | |
| const Xapian::Document & document); | | const Xapian::Document & document); | |
| | | | |
| /** Replace any documents matching a term. | | /** Replace any documents matching a term. | |
| * | | * | |
| * This method replaces any documents indexed by the specified term | | * This method replaces any documents indexed by the specified term | |
| * with the specified document. If any documents are indexed by th
e | | * with the specified document. If any documents are indexed by th
e | |
| * term, the lowest document ID will be used for the document, | | * term, the lowest document ID will be used for the document, | |
| * otherwise a new document ID will be generated as for add_documen
t. | | * otherwise a new document ID will be generated as for add_documen
t. | |
| * | | * | |
|
| * A major use is for convenience when UIDs from another system are | | * One common use is to allow UIDs from another system to easily be | |
| * mapped to terms in Xapian, although this method has other uses | | * mapped to terms in Xapian. Note that this method doesn't | |
| * (for example, you could add a "deletion date" term to documents | | * automatically add unique_term as a term, so you'll need to call | |
| at | | * document.add_term(unique_term) first when using replace_document | |
| * index time and use this method to delete all documents due for | | () | |
| * deletion on a particular date). | | * in this way. | |
| | | * | |
| | | * Another possible use is to allow groups of documents to be marke | |
| | | d for | |
| | | * later deletion - for example, you could add a "deletion date" te | |
| | | rm | |
| | | * to documents at index time and use this method to easily and eff | |
| | | iciently | |
| | | * delete all documents due for deletion on a particular date. | |
| * | | * | |
| * Note that changes to the database won't be immediately committed
to | | * Note that changes to the database won't be immediately committed
to | |
| * disk; see flush() for more details. | | * disk; see flush() for more details. | |
| * | | * | |
| * As with all database modification operations, the effect is | | * As with all database modification operations, the effect is | |
| * atomic: the document(s) will either be fully replaced, or the | | * atomic: the document(s) will either be fully replaced, or the | |
| * document(s) fail to be replaced and an exception is thrown | | * document(s) fail to be replaced and an exception is thrown | |
| * (possibly at a | | * (possibly at a | |
|
| * later time when flush is called or the database is closed). | | * later time when flush() is called or the database is closed). | |
| * | | * | |
| * @param unique_term The "unique" term. | | * @param unique_term The "unique" term. | |
| * @param document The new document. | | * @param document The new document. | |
| * | | * | |
| * @return The document ID that document was given. | | * @return The document ID that document was given. | |
| * | | * | |
| * @exception Xapian::DatabaseError will be thrown if a problem occ
urs | | * @exception Xapian::DatabaseError will be thrown if a problem occ
urs | |
| * while writing to the database. | | * while writing to the database. | |
| * | | * | |
| * @exception Xapian::DatabaseCorruptError will be thrown if the | | * @exception Xapian::DatabaseCorruptError will be thrown if the | |
| | | | |
End of changes. 13 change blocks. |
| 24 lines changed or deleted | | 31 lines changed or added | |
|