Using Custom File Stores

Creating a Custom (User-Defined) File Store

The following sections provide an example of a custom file store and configuration guidelines for choosing a synchronous write policy.

To create a custom file store, you can directly modify the default FileStoreMBean parameters. For instructions on using the WebLogic Server Administration Console to create a custom file store, see Create File Stores in the Oracle WebLogic Server Administration Console Online Help.

Main Steps for Configuring a Custom File Store

The main steps for creating a custom file store are as follows:

Create a directory where the file store's data will be persisted.
Make a note of the following information:
- For stores that may migrate, such as cluster targeted stores with a Migration Policy != Off, stores that are targeted to a migratable target, or stores hosted on a WebLogic Server JVM that may be moved to a different machine, always configure a directory that is centrally accessible from any location that the store may migrate to (do not leave the directory name at the default). This is necessary for migrated stores to recover any data written before the migration - including, for example, queued JMS messages. See Whole Server Migration and Service Migration in Administering Clusters for Oracle WebLogic Server.
- For information about default, absolute, and relative file locations, see File Locations.
Associate the custom file store with the subsystem(s) or migratable target that will be accessing it, such as:
- For JMS servers, select the custom file store on the General Configuration page.
- For Store-and-Forward agents, select the custom file store on the General Configuration page.
- For a Path Service, select the custom file store on the General Configuration page.

Example of a Custom File Store

Here's an example of how a custom file store may look in a domain's configuration file with its files kept in a /disk1/jmslog directory.

<file-store>
  <name>SampleFileStore</name>
  <target>myserver</target>
  <directory>/disk1/jmslog</directory>
</file-store>

Table 5-1 briefly describes the file store configuration parameters that can be modified.

Table 5-1 Custom File Store Configuration Options

Option	Required	What It Does
Name	Yes	The name of the file store, which must be unique across all stores in the domain.
Targets	Yes	The server instance, cluster, or migratable target where a file store is targeted. Multiple subsystems can share the same file store, as long as they are all targeted to the same server instance or migratable target. Note: When using a cluster to host a JMS Server, you must target the file store to the same cluster used by the JMS Server. See Simplified JMS Cluster and High Availability Configuration in Administering JMS Resources for Oracle WebLogic Server. When using migratable targets for JMS services, you must target the file store to the same migratable target used by the JMS service. See Service Migration in Administering Clusters for Oracle WebLogic Server.
Directory	Yes	The path name to the directory on the file system where the file store is kept. Note: For stores that may migrate, such as cluster targeted stores with a Migration Policy != Off, stores that are targeted to a migratable target, or stores hosted on a WebLogic Server JVM that may be moved to a different machine, always configure a directory that is centrally accessible from any location that the store may migrate to (do not leave the directory name at the default). This is necessary for migrated stores to recover any data written before the migration - including, for example, queued JMS messages. See Whole Server Migration and Service Migration in Administering Clusters for Oracle WebLogic Server. For information about default, absolute, and relative file locations, see File Locations. Modifying an existing file store's directory does not necessarily require a server restart, as described in Modifying Custom Persistent Store Parameters.
CacheDirectory	No	This setting only applies for the `Direct-Write-With-Cache` file store synchronous write policy. See Guidelines for Configuring a Synchronous Write Policy.
Logical Name	No	Optionally used with subsystems, like EJBs, when deploying a module to an entire cluster, but also require a different physical store on each server instance in the cluster. In such a configuration, each physical store would have its own name, but all the persistent stores would share the same logical name.
Synchronous Write Policy	No	Defines the IO behavior of a file store including immediate durability of individual write operations. Values are: Direct-Write (default), Direct-Write-With-Cache, Cache-Flush, and Disabled. See Guidelines for Configuring a Synchronous Write Policy.

For instructions on configuring a custom file store using the WebLogic Server Administration Console, see Create File Stores in the Oracle WebLogic Server Administration Console Online Help.

Guidelines for Configuring a Synchronous Write Policy

There are several Synchronous Write Policies available for file stores. The Synchronous Write Policy determines the behavior of the write operation of the file store. You should select a policy that best suits your environment and meets your needs for runtime performance and data integrity after a possible crash. See Tuning the WebLogic Persistent Store in Tuning Performance of Oracle WebLogic Server for more details about tuning and performance specifics of Synchronous Write Policy and other file store options.

Note:

To view a running custom or default file store's synchronous write policy and driver, check the WL-280008 and WL-280009 messages in the server log.

Direct-Write-With-Cache Policy

For most scenarios, Oracle recommends using the Direct-Write-With-Cache policy. When this policy is selected, WebLogic Server writes synchronously to a primary set of files in the location defined by the Directory attribute of the file store configuration using a native I/O wlfileio driver. WebLogic Server also asynchronously writes to a corresponding cache file in the location defined by the CacheDirectory attribute of the file store configuration, which is done implicitly by using OS memory caching the cache file blocks as output buffers for the primary data file. The cache files are used for performance optimizations at runtime and boot time and for recovery. This combination of direct writing with a native file driver and the use of corresponding cache files typically provides the best overall performance with the most safe disk writes.

This option uses approximately twice as much disk space as other policies and stores files in two locations. You may need to consider disk space allocations in these locations and you may need to secure both of these locations.

When configuring file locations with the Direct-Write-With-Cache policy, the location of the CacheDirectory attribute should be a local directory, even when configuring for high availability (Whole Server Migration or Automatic Service Migration). The cache files are used for performance optimizations only. The true persistent storage for messages is defined by the Directory attribute of the file store configuration. Only that directory needs to be available to the migrated WebLogic Server instance or JMS service after migration. The same applies to disaster recovery scenarios: only the files defined in the Directory location need to replicated to the backup site.

Note:

If the file store native wlfileio driver cannot be loaded, the store automatically runs in an alternate specialized Direct-Write policy mode. To view a running custom or default file store's configured and actual synchronous write policy and driver, examine the server log for WL-280008 and WL-280009 messages.

Certain older versions of Microsoft Windows may incorrectly report storage device synchronous write completion if the Windows default Write Cache Enabled setting is used. This violates the transactional semantics of transactional products (not specific to Oracle), including file stores configured with a Direct-Write (default) or Direct-Write-With-Cache policy, as a system crash or power failure can lead to a loss or a duplication of records/messages. One of the visible symptoms is that this problem may manifest itself in high persistent message/transaction throughput exceeding the physical capabilities of your storage device. You can address the problem by applying a Microsoft supplied patch, disabling the Windows Write Cache Enabled setting, or by using a power-protected storage device. See http://support.microsoft.com/kb/281672 and http://support.microsoft.com/kb/332023.

Direct-Write Policy

When the Direct-Write policy is selected, WebLogic Server writes synchronously to a primary set of files in the location defined by the Directory attribute of the file store configuration using a native I/O wlfileio driver. This policy typically performs slower than the Direct-Write-With-Cache policy, but it uses less disk space and may have fewer environmental considerations to manage. The Direct-Write policy is typically faster than the Cache-Flush policy.

Note:

Certain older versions of Microsoft Windows may incorrectly report storage device synchronous write completion if the Windows default Write Cache Enabled setting is used. This violates the transactional semantics of transactional products (not specific to Oracle), including file stores configured with a Direct-Write (default) or Direct-Write-With-Cache policy, as a system crash or power failure can lead to a loss or a duplication of records/messages. One of the visible symptoms is that this problem may manifest itself in high persistent message/transaction throughput exceeding the physical capabilities of your storage device. You can address the problem by applying a Microsoft supplied patch, disabling the Windows Write Cache Enabled setting, or by using a power-protected storage device. See http://support.microsoft.com/kb/281672 and http://support.microsoft.com/kb/332023.

Cache-Flush Policy

When the Cache-Flush policy is selected, WebLogic Server enables the default file write behavior of the operating system and storage device, which typically includes caching and scheduling file writes, but forces a flush of the cache to disk before completing a transaction. Transactions cannot complete until all of their writes have been flushed down to disk. This policy is reliable and scales well as the number of simultaneous users increases. It is transactionally safe, but tends to provide lower runtime performance than the direct-write policies in typical use cases, except in those cases with large numbers of simultaneous producers or consumers.

Disabled Policy

When the Disabled policy is selected, WebLogic Server relies on the default file write behavior of the operating system and storage device. In most cases, file writes are cached in memory and are scheduled for writing instead of being directly written to disk. The Disabled policy generally improves file store performance, often quite dramatically, but at the expense of possibly losing sent messages or generating duplicate received messages (even if messages are transactional) in the event of an operating system crash or a hardware failure. This is because transactions are complete as soon as their writes are cached in memory, instead of waiting for the writes to successfully reach the disk. Simply shutting down an operating system or killing a WebLogic Server process does not generate these failures, as an OS flushes all outstanding writes under these circumstances during a normal shutdown. Instead, these failures can be emulated by abruptly shutting the power off to a busy server.