5.3. Directory Configuration

⁠5.3. Directory Configuration

As we have seen in Section 5.2, “Configuring the IndexManager” the default index manager uses Lucene's notion of a Directory to store the index files. The Directory implementation can be customized and Lucene comes bundled with a file system and an in-memory implementation. DirectoryProvider is the Hibernate Search abstraction around a Lucene Directory and handles the configuration and the initialization of the underlying Lucene resources. Table 5.1, “List of built-in DirectoryProvider” shows the list of the directory providers available in Hibernate Search together with their corresponding options.

To configure your DirectoryProvider you have to understand that each indexed entity is associated to a Lucene index (except of the case where multiple entities share the same index - Section 11.5, “Sharing Indexes”). The name of the index is given by the index property of the @Indexed annotation. If the index property is not specified the fully qualified name of the indexed class will be used as name (recommended).

Knowing the index name, you can configure the directory provider and any additional options by using the prefix hibernate.search.<indexname>. The name default (hibernate.search.default) is reserved and can be used to define properties which apply to all indexes. Example 5.2, “Configuring Directory Providers” shows how hibernate.search.default.directory_provider is used to set the default directory provider to be the filesystem one. hibernate.search.default.indexBase sets then the default base directory for the indexes. As a result the index for the entity Status is created in /usr/lucene/indexes/org.hibernate.example.Status.

The index for the Rule entity, however, is using an in-memory directory, because the default directory provider for this entity is overridden by the property hibernate.search.Rules.directory_provider.

Finally the Action entity uses a custom directory provider CustomDirectoryProvider specified via hibernate.search.Actions.directory_provider.

⁠

Example 5.1. Specifying the Index Name

package org.hibernate.example;

@Indexed
public class Status { ... }

@Indexed(index="Rules")
public class Rule { ... }

@Indexed(index="Actions")
public class Action { ... }

⁠

Example 5.2. Configuring Directory Providers

hibernate.search.default.directory_provider = filesystem
hibernate.search.default.indexBase=/usr/lucene/indexes
hibernate.search.Rules.directory_provider = ram
hibernate.search.Actions.directory_provider = com.acme.hibernate.CustomDirectoryProvider

Note

Using the described configuration scheme you can easily define common rules like the directory provider and base directory, and override those defaults later on a per index basis.

⁠

Table 5.1. List of built-in DirectoryProvider

Name and description	Properties
ram: Memory based directory, the directory will be uniquely identified (in the same deployment unit) by the `@Indexed.index` element	none
filesystem: File system based directory. The directory used will be <indexBase>/< indexName >	`indexBase` : base directory `indexName`: override @Indexed.index (useful for sharded indexes) `locking_strategy` : optional, see Section 5.6, “LockFactory Configuration” `filesystem_access_type`: allows to determine the exact type of `FSDirectory` implementation used by this `DirectoryProvider`. Allowed values are `auto` (the default value, selects `NIOFSDirectory` on non Windows systems, `SimpleFSDirectory` on Windows), `simple` (`SimpleFSDirectory`), `nio` (`NIOFSDirectory`), `mmap` (`MMapDirectory`). Make sure to refer to Javadocs of these `Directory` implementations before changing this setting. Even though `NIOFSDirectory` or `MMapDirectory` can bring substantial performance boosts they also have their issues.
filesystem-master: File system based directory. Like `filesystem`. It also copies the index to a source directory (aka copy directory) on a regular basis. The recommended value for the refresh period is (at least) 50% higher that the time to copy the information (default 3600 seconds - 60 minutes). Note that the copy is based on an incremental copy mechanism reducing the average copy time. DirectoryProvider typically used on the master node in a JMS back end cluster. The `buffer_size_on_copy` optimum depends on your operating system and available RAM; most people reported good results using values between 16 and 64MB.	`indexBase`: base directory `indexName`: override @Indexed.index (useful for sharded indexes) `sourceBase`: source (copy) base directory. `source`: source directory suffix (default to `@Indexed.index`). The actual source directory name being `<sourceBase>/<source>` `refresh`: refresh period in seconds (the copy will take place every `refresh` seconds). If a copy is still in progress when the following `refresh` period elapses, the second copy operation will be skipped. `buffer_size_on_copy`: The amount of MegaBytes to move in a single low level copy instruction; defaults to 16MB. `locking_strategy` : optional, see Section 5.6, “LockFactory Configuration” `filesystem_access_type`: allows to determine the exact type of `FSDirectory` implementation used by this `DirectoryProvider`. Allowed values are `auto` (the default value, selects `NIOFSDirectory` on non Windows systems, `SimpleFSDirectory` on Windows), `simple` (`SimpleFSDirectory`), `nio` (`NIOFSDirectory`), `mmap` (`MMapDirectory`). Make sure to refer to Javadocs of these `Directory` implementations before changing this setting. Even though `NIOFSDirectory` or `MMapDirectory` can bring substantial performace boosts they also have their issues.
filesystem-slave: File system based directory. Like `filesystem`, but retrieves a master version (source) on a regular basis. To avoid locking and inconsistent search results, 2 local copies are kept. The recommended value for the refresh period is (at least) 50% higher that the time to copy the information (default 3600 seconds - 60 minutes). Note that the copy is based on an incremental copy mechanism reducing the average copy time. If a copy is still in progress when `refresh` period elapses, the second copy operation will be skipped. DirectoryProvider typically used on slave nodes using a JMS back end. The `buffer_size_on_copy` optimum depends on your operating system and available RAM; most people reported good results using values between 16 and 64MB.	`indexBase`: Base directory `indexName`: override @Indexed.index (useful for sharded indexes) `sourceBase`: Source (copy) base directory. `source`: Source directory suffix (default to `@Indexed.index`). The actual source directory name being `<sourceBase>/<source>` `refresh`: refresh period in second (the copy will take place every refresh seconds). `buffer_size_on_copy`: The amount of MegaBytes to move in a single low level copy instruction; defaults to 16MB. `locking_strategy` : optional, see Section 5.6, “LockFactory Configuration” `retry_marker_lookup` : optional, default to 0. Defines how many times we look for the marker files in the source directory before failing. Waiting 5 seconds between each try. `retry_initialize_period` : optional, set an integer value in seconds to enable the retry initialize feature: if the slave can't find the master index it will try again until it's found in background, without preventing the application to start: fullText queries performed before the index is initialized are not blocked but will return empty results. When not enabling the option or explicitly setting it to zero it will fail with an exception instead of scheduling a retry timer. To prevent the application from starting without an invalid index but still control an initialization timeout, see `retry_marker_lookup` instead. `filesystem_access_type`: allows to determine the exact type of `FSDirectory` implementation used by this `DirectoryProvider`. Allowed values are `auto` (the default value, selects `NIOFSDirectory` on non Windows systems, `SimpleFSDirectory` on Windows), `simple` (`SimpleFSDirectory`), `nio` (`NIOFSDirectory`), `mmap` (`MMapDirectory`). Make sure to refer to Javadocs of these `Directory` implementations before changing this setting. Even though `NIOFSDirectory` or `MMapDirectory` can bring substantial performance boosts they also have their issues.

Note

If the built-in directory providers do not fit your needs, you can write your own directory provider by implementing the org.hibernate.store.DirectoryProvider interface. In this case, pass the fully qualified class name of your provider into the directory_provider property. You can pass any additional properties using the prefix hibernate.search.<indexname>.

Report a bug