Compass must be configured to work with a specific applications domain model. There are a large number of configuration parameters available (with default settings), which controls how Compass works internal and with the underlying Search Engine. This section describes the configuration API and parameters.
An instance of CompassConfiguration represents a set of mappings (one or more OSEM or Resource mappings), Common Meta Data definitions, transaction and Search Engine parameters. CompassConfiguration is used to build an immutable Compass instance.
CompassConfiguration provides several API's for adding OSEM and Resource mapping (suffixed .cpm.xml), as well as Common Meta Data definition (suffixed .cmd.xml). The following table summarizes the most important API's:
Table 2.1. Configuration Mapping API
| API | Description |
|---|---|
| addFile(String) | Loads the mapping file (cpm or cmd) according to the specified file path string. |
| addFile(File) | Loads the mapping file (cpm or cmd) according to the specified file object reference. |
| addClass(Class) | Loads the mapping file (cpm) according to the specified class. test.Author.class will map to test/Author.cpm.xml within the class path. |
| addURL(URL) | Loads the mapping file (cpm or cmd) according to the specified URL. |
| addResource(String) | Loads the mapping file (cpm or cmd) according to the specified resource path from the class path. |
| addInputStream(InputStream) | Loads the mapping file (cpm or cmd) according to the specified input stream. |
| addDirectory(String) | Loads all the files named *.cpm.xml or *.cmd.xml from within the specified directory. |
| addJar(File) | Loads all the files named *.cpm.xml or *.cmd.xml from within the specified Jar file. |
| addMappingResolver(MappingResolver) | Uses a class that implements the MappingResolver to get an InputStream for xml mapping definitions. |
Other than mapping file configuration API (CompassConfiguration), Compass::Core can be configured through the CompassSettings interface. CompassSettings is similar to Java Properties class and is accessible via the CompassConfiguration.getSettings() or the CopmassConfiguration.setSetting(String setting, String value) methods. Compass's many different settings are explained in the Configuration Settings apendix.
Compass setting can also be defined programmatically using the org.compass.core.config.CompassEnvironment and org.compass.core.lucene.LuceneEnvironment classes (hold programmatic manifestation of all the different settings).
In terms of required settings, Compass only requires the compass.engine.connection (which maps to CompassEnvironment.CONNECTION) parameter defined.
Global Converters (classes that implement Compass Converter) can also be registered with the configuration to be used by the created compass instances. The Converters are registered under a logical name, and can be referenced in the mapping definitions. The method to register a global converter is registerConverter.
Again, many words and so little code... . The following code example shows the minimal CompassConfiguration with programmatic control:
CompassConfiguration conf = new CompassConfiguration()
.setSetting(CompassEnvironment.CONNECTION, "my/index/dir")
.addResource(DublinCore.cmd.xml)
.addClass(Author.class);
All of Compass's operational configuration (apart from mapping definitions) can be defined in a single xml configuration file, with the default name compass.cfg.xml. You can define the environmental settings and mapping file locations within this file. The following table shows the different CompassConfiguration API's for locating the main configuration file:
Table 2.2. Compass Configuration API
| API | Description |
|---|---|
| configure() | Loads a configuration file called compass.cfg.xml from the root of the class path. |
| configure(String) | Loads a configuration file from the specified path |
The preferred way to configure Compass (and the simplest way) is to use an Xml configuration file, which validates against a Schema. It allows for richer and more descriptive (and less erroneous) configuration of Compass. The schema is fully annotated, with each element, attribute documented within the schema. Note, that some additional information is explained in the Configuration Settings appendix, even if it does not apply in terms of the name of the setting to be used, it is advisable to read the appropriate section for more fuller explanation (such as converters, highlighters, analyzers, and so on).
Here are a few sample configuration files, the first is a simple file based index with the OSEM definitions for the Author class.
<compass-core-config xmlns="http://www.opensymphony.com/compass/schema/core-config"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.opensymphony.com/compass/schema/core-config
http://www.opensymphony.com/compass/schema/compass-core-config.xsd">
<compass name="default">
<connection>
<file path="target/test-index"/>
</connection>
<mappings>
<class name="test.Author" />
</mappings>
</compass>
</compass-core-config>
The next sample configures a jdbc based index, with a bigger buffer size for default file entries:
<compass-core-config xmlns="http://www.opensymphony.com/compass/schema/core-config"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.opensymphony.com/compass/schema/core-config
http://www.opensymphony.com/compass/schema/compass-core-config.xsd">
<compass name="default">
<connection>
<jdbc dialect="org.apache.lucene.store.jdbc.dialect.HSQLDialect">
<dataSourceProvider>
<driverManager url="jdbc:hsqldb:mem:test" username="sa" password=""
driverClass="org.hsqldb.jdbcDriver" />
</dataSourceProvider>
<fileEntries>
<fileEntry name="__default__">
<indexInput bufferSize="4096" />
<indexOutput bufferSize="4096" />
</fileEntry>
</fileEntries>
</jdbc>
</connection>
</compass>
</compass-core-config>
The next sample configures a jdbc based index, with a JTA transaction (note the managed="true" and commitBeforeCompletion="true"):
<compass-core-config xmlns="http://www.opensymphony.com/compass/schema/core-config"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.opensymphony.com/compass/schema/core-config
http://www.opensymphony.com/compass/schema/compass-core-config.xsd">
<compass name="default">
<connection>
<jdbc dialect="org.apache.lucene.store.jdbc.dialect.HSQLDialect" managed="true">
<dataSourceProvider>
<driverManager url="jdbc:hsqldb:mem:test" username="sa" password=""
driverClass="org.hsqldb.jdbcDriver" />
</dataSourceProvider>
</jdbc>
</connection>
<transaction factory="org.compass.core.transaction.JTASyncTransactionFactory" commitBeforeCompletion="true">
</transaction>
</compass>
</compass-core-config>
Here is another sample, that configures another analyzer, a specialized Converter, and changed the default date format for all Java Dates (date is an internal name that maps to Compass default date Converter).
<compass-core-config xmlns="http://www.opensymphony.com/compass/schema/core-config"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.opensymphony.com/compass/schema/core-config
http://www.opensymphony.com/compass/schema/compass-core-config.xsd">
<compass name="default">
<connection>
<file path="target/test-index"/>
</connection>
<converters>
<converter name="date" type="org.compass.core.converter.basic.DateConverter">
<setting name="format" value="yyyy-MM-dd" />
</converter>
<converter name="myConverter" type="test.Myconverter" />
</converters>
<searchEngine>
<analyzer name="test" type="Snowball" snowballType="Lovins">
<stopWords>
<stopWord value="test" />
</stopWords>
</analyzer>
</searchEngine>
</compass>
</compass-core-config>
The next configuration uses batch_insert transaction, with a higher max buffered documents for faster batch indexing.
<compass-core-config xmlns="http://www.opensymphony.com/compass/schema/core-config"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.opensymphony.com/compass/schema/core-config
http://www.opensymphony.com/compass/schema/compass-core-config.xsd">
<compass name="default">
<connection>
<file path="target/test-index"/>
</connection>
<transaction isolation="batch_insert">
<batchInsertSettings maxBufferedDocs="100" />
</transaction>
</compass>
</compass-core-config>
Compass can be configured using a DTD based xml configuration. The DTD configuration is less expressive than the schema based one, allowing to configure mappings and Compass settings. The Configuration Settings are explained in an appendix.
And here is an example of the xml configuration file:
<!DOCTYPE compass-core-configuration PUBLIC
"-//Compass/Compass Core Configuration DTD 1.0//EN"
"http://www.opensymphony.com/compass/dtd/compass-core-configuration.dtd">
<compass-core-configuration>
<compass>
<setting name="compass.engine.connection">my/index/dir</setting>
<meta-data resource="vocabulary/DublinCore.cmd.xml" />
<mapping resource="test/Author.cpm.xml" />
</compass>
</compass-core-configuration>
After CompassConfiguration has been set (either programmatic or using the XML configuration file), you can now build a Compass instance. Compass is intended to be shared among different application threads. The following simple code example shows how to obtain a Compass reference.
Compass compass = cfg.buildCompass();
Note: It is possible to have multiple Compass instances within the same application, each with a different configuration.