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 internally and with the underlying Search Engine. This section describes the configuration API.
In order to create a Compass instance, it first must be configured. CompassConfiguration can be used in order to configure a Compass instance, by having the ability to add different mapping definitions, configure Compass based on xml configuration files, and expose a programmatic configuration options.
For Java 5 based applications (mainly ones that use OSEM annotations), CompassAnnotationsConfiguration can be used (which extends CompassConfiguration). For simplicity, Compass comes with CompassConfigurationFactory, which tries to be smart and detect based on the JVM version and the included compass modules, which configuration to create. Here is an example of the preferred way to obtain a CompassConfiguration instance:
CompassConfiguration conf =
CompassConfigurationFactory.newConfiguration();
A Compass instance can be programatically configured using CompassConfiguration. Two main configuration aspects are adding mapping definitions, and setting different settings.
CompassConfiguration provides several API's for adding mapping definitions (xml mapping files suffixed .cpm.xml or annotated classes), as well as Common Meta Data definition (xml mapping files suffixed .cmd.xml). The following table summarizes the most important API's:
Table 3.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. Can also add annotated classes if using Compass annotations support. |
| 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. |
| addScan(String basePackage, String pattern) | Scans for all the mappings that exist wihtin the base backage recursively. An optioal ant style pattern can be provided as well. The mappings detected are all the xml based mappings. Annotation based mappings will be detected automatically if either ASM or Javassist exists within the classpath. |
| addMappingResolver(MappingResolver) | Uses a class that implements the MappingResolver to get an InputStream for xml mapping definitions. |
Other than mapping file configuration API, Compass 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 Appendix A, Configuration Settings.
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 names).
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);
An important aspect of settings (properties like) configuration is the notion of group settings. Similar to the way log4j properties configuration file works, different aspects of Compass need to be configured in a grouped nature. If we take Compass converter configuration as an example, here is an example of a set of settings to configure a custom converter called test:
org.compass.converter.test.type=eg.TestConverter org.compass.converter.test.param1=value1 org.compass.converter.test.param2=value2
Compass defined prefix for all converter configuration is org.compass.converter. The segment that comes afterwards (up until the next '.') is the converter (group) name, which is set to test. This will be the converter name that the converter will be registered under (and referenced by in different mapping definitions). Within the group, the following settings are defined: type, param1, and param2. type is one of the required settings for a custom Compass converter, and has the value of the fully qualified class name of the converter implementation. param1 and param2 are custom settings, that can be used by the custom converter (it should implement CompassConfigurable).
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 3.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 and 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, just to get a feeling of the structure and nature of the configuration file. The first is a simple file based index with the OSEM definitions for the Author class.
<compass-core-config xmlns="http://www.compass-project.org/schema/core-config"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.compass-project.org/schema/core-config
http://www.compass-project.org/schema/compass-core-config-2.0.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.compass-project.org/schema/core-config"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.compass-project.org/schema/core-config
http://www.compass-project.org/schema/compass-core-config-2.0.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.compass-project.org/schema/core-config"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.compass-project.org/schema/core-config
http://www.compass-project.org/schema/compass-core-config-2.0.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.compass-project.org/schema/core-config"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.compass-project.org/schema/core-config
http://www.compass-project.org/schema/compass-core-config-2.0.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.compass-project.org/schema/core-config"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.compass-project.org/schema/core-config
http://www.compass-project.org/schema/compass-core-config-2.0.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 Appendix A, Configuration Settings.
And here is an example of the xml configuration file:
<!DOCTYPE compass-core-configuration PUBLIC
"-//Compass/Compass Core Configuration DTD 2.0//EN"
"http://www.compass-project.org/dtd/compass-core-configuration-2.0.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.
Compass allows to configure events that will be fired once certain operations occur in using Compass, for example, save operation.
Configuring event listener can be done settings. For example, to configure a pre save event listener, the following setting should be used: compass.event.preSave.mylistener.type and its value can be the actual class name of the listener.
More information for each listener can be found in the javadoc under the org.compass.events package. An important note with regards to pre listener is the fact that they can filter out certain operations.