An abstract representation of an index.
Concrete subclasses of this class represent abstract index access information: for instance, the basename or IP address/port, flags, etc. It allows to build easily {@linkplain IndexReader index readers} over the index:in turn, index readers provide {@linkplain it.unimi.dsi.mg4j.search.DocumentIterator document iterators}.
In principle, this class should just contain methods declarations, and attributes for all data that is common to any form of index. Note that we use an abstract class, rather than an interface, because interfaces do not allow to declare attributes.
This class provide static factory methods (e.g., {@link #getInstance(CharSequence)}) that return an index given a suitable URI string. If the scheme part is mg4j, then the URI is assumed to point at a remote index. Otherwise, it is assumed to be the basename of a local index. In both cases, a query part introduced by ? can specify additional parameters (key=value pairs separated by ;). For instance, the URI example?inmemory=1 will load the index with basename example, caching its content in core memory. Please have a look at constants in {@link Index.UriKeys} (and analogous enums in subclasses) for additional parameters.
Thread safety
Indices are a natural candidate for multithreaded access. An instance of this class must be thread safe as long as external data structures provided to its constructors are. For instance, the tool {@link it.unimi.dsi.mg4j.tool.IndexBuilder} generatesa {@linkplain StringMaps#synchronize(PrefixMap) synchronized} {@link ImmutableExternalPrefixMap}so that by default the resulting index is thread safe.
For instance, a {@link it.unimi.dsi.mg4j.index.DiskBasedIndex} requires a list ofterm offsets, term maps, etc. As long as all these data structures are thread safe, the same is true of the index. Data structures created by static factory methods such as {@link it.unimi.dsi.mg4j.index.DiskBasedIndex#getInstance(CharSequence)} are thread safe.
Note that {@link it.unimi.dsi.mg4j.index.IndexReader}s returned by {@link #getReader()}are not thread safe (even if the method {@link #getReader()} is). The logic behindthis arrangement is that you create as many reader as you need, and then {@link java.io.Closeable#close()} them. In a multithreadedenvironment, a pool of index readers can be created, and a custom {@link it.unimi.dsi.mg4j.query.nodes.QueryBuilderVisitor}can be used to build {@link it.unimi.dsi.mg4j.search.DocumentIterator}s using the given pool of readers. In this case readers are not closed, but rather reused.
Read-once load
Implementations of this class are strongly encouraged to offer read-once constructors and factory methods: property files and other data related to the index (but not to an {@link it.unimi.dsi.mg4j.index.IndexReader}should be read exactly once, and sequentially. This feature is very useful when {@linkplain it.unimi.dsi.mg4j.tool.Combine combining indices}.
@author Paolo Boldi
@author Sebastiano Vigna
@since 0.9