4 Using Custom File Stores
- Creating a Custom (User-Defined) File Store
The following section provides an example of a custom file store and configuration guidelines for choosing a synchronous write policy. - Main Steps for Configuring a Custom File Store
This section describes the main steps to create a custom file store. - Example of a Custom File Store
This section provides 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. - 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.
Creating a Custom (User-Defined) File Store
The following section provides 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 Remote Console to create a custom file store, see Create a File Store in the Oracle WebLogic Remote Console Online Help.
Parent topic: Using Custom File Stores
Main Steps for Configuring a Custom File Store
This section describes the main steps to create a custom file store.
Perform the following steps to create a custom file store:
Parent topic: Using Custom File Stores
Example of a Custom File Store
This section provides 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 4-1 briefly describes the file store configuration parameters that can be modified.
Table 4-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:
|
Directory |
Yes |
The path name to the directory on the file system where the file store is kept. Note:
|
CacheDirectory |
No |
This setting only applies for the |
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. |
For instructions on configuring a custom file store using the WebLogic Remote Console, see Create a File Store in the Oracle WebLogic Remote Console Online Help.
Parent topic: Using Custom File Stores
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.
Parent topic: Using Custom File Stores
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.
Parent topic: Guidelines for Configuring a Synchronous Write Policy
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.
Parent topic: Guidelines for Configuring a Synchronous Write Policy
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.
Parent topic: Guidelines for Configuring a Synchronous Write Policy
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.
Parent topic: Guidelines for Configuring a Synchronous Write Policy