Xapian's API is fairly stable and has been polished piece by piece over time, but it still occasionally needs to be changed. This may be because a new feature has been implemented and the interface needs to allow access to it, but it may also be required in order to polish a rough edge which has been missed in earlier versions of Xapian, or simply to reflect an internal change which requires a modification to the external interface.
We aim to make such changes in a way that allows developers to work against a stable API, while avoiding the need for the Xapian developers to maintain too many old historical interface artifacts. This document describes the process we use to deprecate old pieces of the API, lists parts of the API which are currently marked as deprecated, and also describes parts of the API which have been deprecated for some time, and are now removed from the Xapian library.
It is possible for functions, methods, constants, types or even whole classes to be deprecated, but to save words this document will often use the term "features" to refer collectively to any of these types of interface items.
At any particular point, some parts of the C++ API will be marked as "deprecated". This is indicated with the XAPIAN_DEPRECATED macro, which will cause compilers with appropriate support (such as GCC 3.1 or later, and MSVC 7.0 or later) to emit warning messages about the use of deprecated features at compile time.
If a feature is marked with one of these markers, you should avoid using it in new code, and should migrate your code to use a replacement when possible. The documentation comments for the feature, or the list at the end of this file, will describe possible alternatives to the deprecated feature.
Within a series of releases with a given major and minor number, we try to maintain API and ABI forwards compatibility. This means that an application written and compiled against version X.Y.a of Xapian should work, without any changes or need to recompile, with a later version X.Y.b, for all a <= b.
It is possible that a feature may be marked as deprecated within a minor release series - that is from version X.Y.c onwards, where c is not zero. The API and ABI will not be changed by this deprecation, since the feature will still be available in the API (though the change may cause the compiler to emit new warnings at compile time).
In general, a feature will be supported after being deprecated for an entire series of releases with a given major and minor number. For example, if a feature is deprecated in release 1.2.0, it will be supported for the entire 1.2.x release series, and removed in release 1.3.0. If a feature is deprecated in release 1.2.5, it will be supported for all remaining releases in the 1.2.x series, and also for all releases in the 1.3.x series, and will be removed in release 1.4.0.
However, this rule may not be followed in all cases. In particular, if a feature was marked as "temporary" in the documentation, it may be removed faster (and possibly, without even passing through a stage of being deprecated).
When the Xapian API changes, the interface provided by the Xapian bindings will usually change in step. In addition, it is sometimes necessary to change the way in which Xapian is wrapped by bindings - for example, to provide a better convenience wrapper for iterators in Python. Again, we aim to ensure that an application written (and compiled, if the language being bound is a compiled language) for version X.Y.a of Xapian should work without any changes or need to recompile, with a later version X.Y.b, for all a <= b.
However, the bindings are a little less mature than the core C++ API, so we don't intend to give the same guarantee that a feature present and not deprecated in version X.Y.a will work in all versions X+1.Y.b. In other words, we may remove features which have been deprecated without waiting for an entire release series to pass.
Any planned deprecations will be documented in the list of deprecations and removed features at the end of this file.
We recommend taking the following steps to avoid depending on deprecated features when writing your applications:
- If at all possible, test compile your project using a compiler which supports warnings about deprecated features (such as GCC 3.1 or later), and check for such warnings. Use the -Werror flag to GCC to ensure that you don't miss any of them.
- Check the NEWS file for each new release for details of any new features which are deprecated in the release.
- Check the documentation comments, or the automatically extracted API documentation, for each feature you use in your application. This documentation will indicate features which are deprecated, or planned for deprecation.
- For applications which are not written in C++, there is currently no equivalent of the XAPIAN_DEPRECATED macro for the bindings, and thus there is no way for the bindings to give a warning if a deprecated feature is used. This would be a nice addition for those languages in which there is a reasonable way to give such warnings. Until such a feature is implemented, all application writers using the bindings can do is to check the list of deprecated features in each new release, or lookup the features they are using in the list at the end of this file.
| Deprecated | Remove | Feature name | Upgrade suggestion and comments |
|---|---|---|---|
| 0.9.6 | 1.1.0 | xapian_version_string() | Use version_string() instead. |
| 0.9.6 | 1.1.0 | xapian_major_version() | Use major_version() instead. |
| 0.9.6 | 1.1.0 | xapian_minor_version() | Use minor_version() instead. |
| 0.9.6 | 1.1.0 | xapian_revision() | Use revision() instead. |
| 1.0.0 | 1.1.0 | Enquire::include_query_terms | Use Enquire::INCLUDE_QUERY_TERMS instead. |
| 1.0.0 | 1.1.0 | Enquire::use_exact_termfreq | Use Enquire::USE_EXACT_TERMFREQ instead. |
| 1.0.0 | 1.1.0 | Error::get_errno() | Use Error::get_error_string() instead. |
| 1.0.0 | 1.1.0 | The Quartz backend | Use the Flint backend instead. |
| 1.0.0 | 1.1.0 | Quartz::open() | Use Flint::open() instead. |
| 1.0.0 | 1.1.0 | quartzcheck | Use xapian-check instead. |
| 1.0.0 | 1.1.0 | quartzcompact | Use xapian-compact instead. |
| 1.0.3 | 1.1.0 | Enquire::register_match_decider() | This method didn't do anything, so just remove calls to it! |
| 1.0.3 | 1.2.0? | Database::positionlist_begin() throwing RangeError if the term specified doesn't index the document specified. | This check is quite expensive, and often you don't care. If you do it's easy to check - just open a TermListIterator for the document and use skip_to() to check if the term is there. |
| 1.0.3 | 1.2.0? | Database::positionlist_begin() throwing DocNotFoundError if the document specified doesn't exist. | This check is quite expensive, and often you don't care. If you do, it's easy to check - just call Database::get_document() with the specified document ID. |
| 1.0.4 | 1.1.0 | Query::Query(Query::op, Query) | This constructor isn't useful for any currently implemented Query::op. |
| Deprecated | Remove | Language | Feature name | Upgrade suggestion and comments |
|---|---|---|---|---|
| 0.9.6 | 1.1.0 | SWIG [1] | xapian_version_string() | Use version_string() instead. |
| 0.9.6 | 1.1.0 | SWIG [1] | xapian_major_version() | Use major_version() instead. |
| 0.9.6 | 1.1.0 | SWIG [1] | xapian_minor_version() | Use minor_version() instead. |
| 0.9.6 | 1.1.0 | SWIG [1] | xapian_revision() | Use revision() instead. |
| 1.0.0 | 1.1.0 | SWIG [1] | ESet::get_termname() | Use ESet::get_term() instead. This change is intended to bring the ESet iterators in line with other term iterators, which all support get_term() instead of get_termname(). |
| 1.0.0 | 1.1.0 | Python | get_description() | All get_description() methods have been renamed to __str__(), so the normal python str() function can be used. |
| 1.0.0 | 1.1.0 | Python | MSetItem.get_*() | All these methods are deprecated, in favour of properties. To convert, just change msetitem.get_FOO() to msetitem.FOO |
| 1.0.0 | 1.1.0 | Python | Enquire.get_matching_terms | Replaced by Enquire.matching_terms, for consistency with rest of Python API. |
| 1.0.0 | 1.1.0 | SWIG [1] | Error::get_errno() | Use Error::get_error_string() instead. |
| 0.9.6 | 1.1.0 | SWIG [2] | MSet::get_document_id() | Use MSet::get_docid() instead. |
| 1.0.4 | 1.2.0 | Python | Non-pythonic iterators | Use the pythonic iterators instead. |
| [1] | (1, 2, 3, 4, 5, 6) This affects all SWIG-generated bindings (currently: Python, PHP, Ruby, Tcl8 and CSharp) |
| [2] | This affects all SWIG-generated bindings except those for Ruby, support for which was added after the function waan-core. |
| Deprecated | Remove | Feature name | Upgrade suggestion and comments |
|---|---|---|---|
| 0.9.5 | 1.1.0 | scriptindex index=nopos | Use indexnopos instead. |
| Removed | Feature name | Upgrade suggestion and comments |
|---|---|---|
| 1.0.0 | QueryParser::set_stemming_options() | Use set_stemmer(), set_stemming_strategy() and/or set_stopper() instead:
If a third parameter is passed, set_stopper(PARAM3) and treat the first two parameters as above. |
| 1.0.0 | Enquire::set_sort_forward() | Use Enquire::set_docid_order() instead:
|
| 1.0.0 | Enquire::set_sorting() | Use Enquire::set_sort_by_relevance(), Enquire::set_sort_by_value(), or Enquire::set_sort_by_value_then_relevance() instead.
|
| 1.0.0 | Stem::stem_word(word) | Use Stem::operator()(word) instead. |
| 1.0.0 | Auto::open(path) | Use the Database(path) constructor instead. |
| 1.0.0 | Auto::open(path, action) | Use the WritableDatabase(path, action) constructor instead. |
| 1.0.0 | Query::is_empty() | Use Query::empty() instead. |
| 1.0.0 | Document::add_term_nopos() | Use Document::add_term() instead. |
| 1.0.0 | Enquire::set_bias() | No replacement yet implemented. |
| 1.0.0 | ExpandDecider::operator() | Return type is now bool not int. |
| 1.0.0 | MatchDecider::operator() | Return type is now bool not int. |
| 1.0.0 | Error::get_type() | Return type is now const char * not std::string. Most existing code won't need changes, but if it does the simplest fix is to write std::string(e.get_type()) instead of e.get_type(). |
| 1.0.0 | <xapian/output.h> | Use cout << obj.get_description(); instead of cout << obj; |
| 1.0.0 | Several constructors marked as explicit. | Explicitly create the object type required, for example use Xapian::Enquire enq(Xapian::Database(path)); instead of Xapian::Enquire enq(path); |
| 1.0.0 | QueryParser::parse_query() throwing const char * exception. | Catch Xapian::QueryParserError instead of const char *, and call get_msg() on the caught object. If you need to build with either version, catch both (you'll need to compile the part which catches QueryParserError conditionally, since this exception isn't present in the 0.9 release series). |
| Removed | Language | Feature name | Upgrade suggestion and comments |
|---|---|---|---|
| 1.0.0 | SWIG [3] | Enquire::set_sort_forward() | Use Enquire::set_docid_order() instead.
|
| 1.0.0 | SWIG [3] | Enquire::set_sorting() | Use Enquire::set_sort_by_relevance(), Enquire::set_sort_by_value() or Enquire::set_sort_by_value_then_relevance() instead.
|
| 1.0.0 | SWIG [3] | Auto::open(path) | Use the Database(path) constructor instead. |
| 1.0.0 | SWIG [3] | Auto::open(path, action) | Use the WritableDatabase(path, action) constructor instead. |
| 1.0.0 | SWIG [4] | MSet::is_empty() | Use MSet::empty() instead. |
| 1.0.0 | SWIG [4] | ESet::is_empty() | Use ESet::empty() instead. |
| 1.0.0 | SWIG [4] | RSet::is_empty() | Use RSet::empty() instead. |
| 1.0.0 | SWIG [4] | Query::is_empty() | Use Query::empty() instead. |
| 1.0.0 | SWIG [3] | Document::add_term_nopos() | Use Document::add_term() instead. |
| 1.0.0 | CSharp | ExpandDecider::Apply() | Return type is now bool instead of int. |
| 1.0.0 | CSharp | MatchDecider::Apply() | Return type is now bool instead of int. |
| 1.0.0 | SWIG [3] | Stem::stem_word(word) | Use Stem::operator()(word) instead. [5] |
| [3] | (1, 2, 3, 4, 5, 6) This affects all SWIG generated bindings (currently: Python, PHP, Ruby, Tcl8 and CSharp) |
| [4] | (1, 2, 3, 4) This affects all SWIG generated bindings except those for Ruby, which was added after the function was deprecated in Xapian-core, and PHP, where empty is a reserved word (and therefore, the method remains "is_empty"). |
| [5] | Python handles this like C++. Ruby renames it to 'call' (idiomatic Ruby). PHP renames it to 'apply'. CSharp to 'Apply' (delegates could probably be used to provide C++-like functor syntax, but that's effort and it seems debatable if it would actually be more natural to a C# programmer). Tcl8 renames it to 'apply' - need to ask a Tcl type if that's the best solution. |
| Removed | Feature name | Upgrade suggestion and comments |
|---|---|---|
| 1.0.0 | $freqs | Use $map{$queryterms,$_: $nice{$freq{$_}}} instead. |
| 1.0.0 | scriptindex -u | -u was ignored for compatibility with 0.7.5 and earlier, so just remove it. |
| 1.0.0 | scriptindex -q | -q was ignored for compatibility with 0.6.1 and earlier, so just remove it. |