nl.inl.blacklab.search

Class BlackLab

java.lang.Object

nl.inl.blacklab.search.BlackLab

public final class BlackLab
extends Object

Main BlackLab class, from which indexes can be opened. You can either open indices using the static methods in this class, or you can create() a BlackLabEngine and use that to open indices. The first approach will implicitly create a default BlackLabEngine in the background, with 4 search threads. If you want a different number of search threads, call create() to create your own instance of BlackLabEngine. Don't try to mix these two methods; if an implicit engine exists and you call create(), or if you call e.g. BlackLab.open() when you've already created an engine explicitly, an exception will be thrown. If you explicitly create an engine, make sure to close it when you're done. For the implicit engine, this is done automatically when you close your last index.

Method Summary

Modifier and Type	Method and Description
static void	applyConfigToIndex(BlackLabIndex index) Configure the index according to the blacklab configuration.
static BlackLabConfig	config() Get the BlackLab config.
static BlackLabIndexWriter	create(File indexDir, ConfigInputFormat config) Create an empty index.
static BlackLabEngine	createEngine()
static BlackLabEngine	createEngine(int searchThreads, int maxThreadsPerSearch)
static List<File>	defaultConfigDirs() Return a list of directories that should be searched for BlackLab-related configuration files.
static BlackLabIndex	fromIndexReader(org.apache.lucene.index.IndexReader reader)
static BlackLabEngine	implicitInstance() Return the implicitly created instance of BlackLab.
static BlackLabIndex	open(File dir)
static BlackLabIndexWriter	openForWriting(File indexDir, boolean createNewIndex) Open an index for writing ("index mode": adding/deleting documents).
static BlackLabIndexWriter	openForWriting(File indexDir, boolean createNewIndex, ConfigInputFormat config) Open an index for writing ("index mode": adding/deleting documents).
static BlackLabIndexWriter	openForWriting(File indexDir, boolean createNewIndex, File indexTemplateFile) Open an index for writing ("index mode": adding/deleting documents).
static void	setConfig(BlackLabConfig config) Set the BlackLab configuration to use.
static void	setConfigFromFile() Read blacklab.yaml and set the configuration from that.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

createEngine

public static BlackLabEngine createEngine(int searchThreads,
                                          int maxThreadsPerSearch)

createEngine

public static BlackLabEngine createEngine()

open

public static BlackLabIndex open(File dir)
                          throws ErrorOpeningIndex

Throws:

ErrorOpeningIndex

openForWriting

public static BlackLabIndexWriter openForWriting(File indexDir,
                                                 boolean createNewIndex)
                                          throws ErrorOpeningIndex

Open an index for writing ("index mode": adding/deleting documents).

Parameters:

indexDir - the index directory

createNewIndex - if true, create a new index even if one existed there

Returns:

index writer

Throws:

ErrorOpeningIndex - if the index could not be opened

openForWriting

public static BlackLabIndexWriter openForWriting(File indexDir,
                                                 boolean createNewIndex,
                                                 File indexTemplateFile)
                                          throws ErrorOpeningIndex

Open an index for writing ("index mode": adding/deleting documents).

Parameters:

indexDir - the index directory

createNewIndex - if true, create a new index even if one existed there

indexTemplateFile - JSON template to use for index structure / metadata

Returns:

index writer

Throws:

ErrorOpeningIndex - if index couldn't be opened

openForWriting

public static BlackLabIndexWriter openForWriting(File indexDir,
                                                 boolean createNewIndex,
                                                 ConfigInputFormat config)
                                          throws ErrorOpeningIndex

Open an index for writing ("index mode": adding/deleting documents).

Parameters:

indexDir - the index directory

createNewIndex - if true, create a new index even if one existed there

config - input format config to use as template for index structure / metadata (if creating new index)

Returns:

index writer

Throws:

ErrorOpeningIndex - if the index couldn't be opened

create

public static BlackLabIndexWriter create(File indexDir,
                                         ConfigInputFormat config)
                                  throws ErrorOpeningIndex

Create an empty index.

Parameters:

indexDir - where to create the index

config - format configuration for this index; used to base the index metadata on

Returns:

a BlackLabIndexWriter for the new index, in index mode

Throws:

ErrorOpeningIndex - if the index couldn't be opened

implicitInstance

public static BlackLabEngine implicitInstance()

Return the implicitly created instance of BlackLab. Only used by BlackLabIndex if no BlackLab instance is provided during opening. The instance will have 4 search threads.

Returns:

implicitly instantiated BlackLab instance

fromIndexReader

public static BlackLabIndex fromIndexReader(org.apache.lucene.index.IndexReader reader)

defaultConfigDirs

public static List<File> defaultConfigDirs()

Return a list of directories that should be searched for BlackLab-related configuration files. May be used by applications to locate BlackLab-related configuration, such as input format definition files or other configuration files. IndexTool and BlackLab Server use this. The directories returned are (in decreasing priority): - $BLACKLAB_CONFIG_DIR (if env. var. is defined) - $HOME/.blacklab - /etc/blacklab - /vol1/etc/blacklab (legacy, will be removed) - /tmp (legacy, will be removed) A convenient method to use with this is FileUtil.findFile(List, String, List).

Returns:

list of directories to search in decreasing order of priority

config

public static BlackLabConfig config()

Get the BlackLab config. If no config has been set, return a default configuration.

Returns:

currently set config

setConfigFromFile

public static void setConfigFromFile()

Read blacklab.yaml and set the configuration from that. This must be called before you open the first index, or an exception will be thrown, because another default config has been applied already.

setConfig

public static void setConfig(BlackLabConfig config)

Set the BlackLab configuration to use. This must be called before you open the first index, or an exception will be thrown, because another default config has been applied already.

Parameters:

config - configuration to use

applyConfigToIndex

public static void applyConfigToIndex(BlackLabIndex index)
                               throws IOException

Configure the index according to the blacklab configuration.

Parameters:

index -

Throws:

IOException