Configuring WebLogic Server Environments

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Using the WebLogic Persistent Store

The following sections explain how to configure and monitor the persistent store, which provides a built-in, high-performance storage solution for WebLogic Server subsystems and services that require persistence.

 


Overview of the Persistent Store

The persistent store provides a built-in, high-performance storage solution for WebLogic Server subsystems and services that require persistence. For example, it can store persistent JMS messages or temporarily store messages sent using the Store-and-Forward feature. The persistent store supports persistence to a file-based store or to a JDBC-enabled database.

Table 6-1 defines many of the WebLogic services and subsystems that can create connections to the persistent store. Each subsystem that uses the persistent store specifies a unique connection ID that identifies that subsystem.

Table 6-1 Persistent Store Users 
Subsystem/Service
What It Stores
More Information
Diagnostic Service
Log records, data events, and harvested metrics.
Understanding WLDF Configuration in Configuring and Using the WebLogic Diagnostic Framework
JMS Messages
Persistent messages and durable subscribers.
Understanding the Messaging Models in Programming WebLogic JMS
JTA Transaction Log (TLOG)
Information about committed transactions coordinated by the server that may not have been completed.
Managing Transactions in Programming WebLogic JTA
Path Service
The mapping of a group of messages to a messaging resource.
Using the WebLogic Path Service in Configuring and Managing WebLogic JMS
Store-and-Forward (SAF) Service Agents
Messages for a sending SAF agent for retransmission to a receiving SAF agent
Understanding the Store-and-Forward Service in Configuring and Managing WebLogic Store-and-Forward
Web Services
Request and response SOAP messages from an invocation of a reliable WebLogic Web Service.
Using Reliable SOAP Messaging in Programming Web Services for WebLogic Server
EJB Timer Services
EJB Timer objects.
Understanding Enterprise JavaBeans in Programming WebLogic Enterprise JavaBeans

For more information about the store connection IDs, see Monitoring Store Connections.

Features of the Persistent Store

The key features of the persistent store include:

High-Performance Throughput and Transactional Support

Throughput is the main performance goal of the persistent store. Multiple subsystems can share the same persistent store, as long as they are all targeted to the same server instance or migratable target.

This is a performance advantage because the persistent store is treated as a single resource by the transaction manager for a particular transaction, even if the transaction involves multiple services that use the same store. For example, if JMS and EJB timers share a store, and a JMS message and an EJB timer are created in a single transaction, the transaction will be one-phase and incur a single resource write, rather than two-phase, which incurs four resource writes (two on each resource), plus a transaction entry write (on the transaction log).

Both the file store and the JDBC store can survive a process crash or hardware power failure without losing any committed updates. Uncommitted updates may be retained or lost, but in no case will a transaction be left partially complete after a crash.

Comparing File Stores and JDBC Stores

The following are some similarities and differences between file stores and JDBC stores:

Securing File Store Data

In order to properly secure file store data, you must set appropriate directory permissions on all your file store directories. If you require data encryption, you must use appropriate third-party encryption software.

High Availability For Persistent Stores

For high availability, a persistent file-based store (default or custom) can be migrated along with its parent server as part of the "server-level" migration feature, which provides both automatic and manual migration at the server-level, rather than on the service level. For more information, see Server Migration section of Using WebLogic Server Clusters. However, file-based stores must be configured on a shared disk that is available to the migratable target servers in the cluster.

File-based stores can also be migrated as part of a "service-level" migration for JMS servers and the JTA transaction recovery service, which can be moved from one server to another within a cluster. For more information on service-level migration, see Service Migration in Using WebLogic Server Clusters. However, file-based stores must still be configured on a shared disk that is available to the migratable target servers in the cluster.

Therefore, if you have applications that need access to persistent stores that reside on remote machines after the migration of a JMS server or JTA transaction log, then you must implement one of the following highly-available storage solutions:

 


Using the Default Persistent Store

Each server instance, including the administration server, has a default persistent store that requires no configuration. The default store is a file-based store that maintains its data in a group of files in a server instance's data\store\default directory. A directory for the default store is automatically created if one does not already exist. This default store is available to subsystems that do not require explicit selection of a particular store and function best by using the system's default storage mechanism. For example, a JMS Server with no persistent store configured will use the default store for its Managed Server and will support persistent messaging.

The default store can be configured by directly manipulating the DefaultFileStoreMBean parameters. If this MBean is not defined in the domain's configuration file, then the configuration subsystem ensures that the DefaultFileStoreMBean always exists with the default values.

Also, the Administration Console enables you to change the default store parameters, such as its default directory location and Synchronous Write Policy, as described in Modify the Default Store Settings in the Administration Console Online Help.

In addition to using the default file store, you can also configure a custom file store or JDBC store to suit your specific needs, as explained in Using Custom File Stores and JDBC Stores. One exception, however, is the transaction log (TLOG), which always uses the default store. This is because the transaction log must always be available early in the server boot process.

Default Store Location

The default store maintains its data in a data\store\default directory inside the servername subdirectory of a domain's root directory

For example, if no directory name is specified for the default file store, it defaults to:

   bea_home\user_projects\domains\domain-name\servers\server-name\data\store\default

where domainname is the root directory of your domain, typically c:\bea\user_projects\domains\domainname, which is parallel to the directory in which WebLogic Server program files are stored, typically c:\bea\weblogic90.

You can, however, specify another location for the default store by directly manipulating the DefaultFileStoreMBean parameters or by using the Administration Console, as described in Modify the Default Store Settings in the Administration Console Online Help.

Example of a Default File Store

Here's an example of how a default file store may look in a domain's configuration file, with the default directory location and Synchronous Write Policy settings overridden:

<server>
<name>myserver</name>
<default-file-store>
<directory>C:/store</directory>
<synchronous-write-policy>Disabled</synchronous-write-policy>
</default-file-store>
</server>

 


Using Custom File Stores and JDBC Stores

In addition to using the default file store, you can also configure a file store or JDBC store to suit your specific needs. A custom file store, like the default file store, maintains its data in a group of files in a directory. However, you may want to create a custom file store so that the file store's data is persisted to a particular storage device. When configuring a file store directory, the directory must be accessible to the server instance on which the file store is located.

A JDBC store can be configured when a relational database is used for storage. A JDBC store enables you to store persistent messages in a standard JDBC-capable database, which is accessed through a designated JDBC data source. The data is stored in the JDBC store's database table, which has a logical name of WLStore. It is up to the database administrator to configure the database for high availability and performance.

For more information about configuring a persistent store, see When to Use a Custom Persistent Store.

When to Use a Custom Persistent Store

WebLogic Server provides configuration options for creating a custom file store or JDBC store. For example, you may want to:

Methods of Creating a Persistent Store

A customized persistent store can be configured in the following ways:

 


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 Administration Console to create a custom file store, see Create File Stores in the Administration Console Online Help.

Main Steps for Configuring a Custom File Store

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

  1. Create a directory where the file store's data will be persisted.
  2. Create a custom file store and specify the directory location that you created.
  3. Associate the custom file store with the subsystem(s) that will be using 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.

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 6-2 briefly describes the file store configuration parameters that can be modified.

Table 6-2 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 where a file store is targeted. Multiple subsystems can share the same store, as long as they are all targeted to the same server instance or migratable target.
Directory
Yes
The path name to the directory on the file system where the file store is kept.
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
Optionally defines how hard a file store will try to flush records to the disk. Values are: Direct-Write (default), Cache-Flush, and Disabled.

For instructions on configuring a custom file store using the Administration Console, see Create file stores in the Administration Console Online Help.

Guidelines for Configuring a Synchronous Write Policy

The default Direct-Write policy is supported on most platforms, and this policy generally performs faster than the Cache-Flush option. For a potential performance boost, stores in direct I/O mode will automatically load a native I/O wlfileio2 driver. This driver is available on Windows, Solaris, HP, AIX, and Linux platforms.

Changing the default policy to Disabled 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 does not generate these failures, as an OS flushes all outstanding writes during a normal shutdown. Instead, these failures can be emulated by abruptly shutting the power off to a busy server.

Tip: To view a running file store's synchronous write policy and driver, check the BEA-280050 message in the server log.

 


Creating a JDBC Store

The following sections provide an example of a JDBC store, and information about creating a database table for a JDBC store, either using existing DDL or It also includes instruction on enabling Oracle blob record columns in a DDL file.

To create a JDBC store, you can directly modify the default JDBCStoreMBean parameters. For instructions on using the Administration Console to create a JDBC store, see Create JDBC Stores in the Administration Console Online Help.

For configuration guidelines on using prefixes with JDBC stores and recommended JDBC data source settings, see Guidelines for Configuring a JDBC Store.

Main Steps for Configuring a JDBC Store

The main steps for creating a JDBC store are as follows:

  1. Create a JDBC data source or multi data source to interface with the JDBC store.
  2. Create a JDBC store and associate it with the JDBC data source or multi data source.
  3. It is highly recommended that you configure the Prefix option to a unique value for each configured JDBC store table.
  4. Associate the JDBC store with the subsystem(s) that will be using it, such as:
    • For JMS servers, select the JDBC store on the General Configuration page.
    • For Store-and-Forward agents, select the JDBC store on the General Configuration page.

Example of a JDBC Store

Here's an example of how a JDBC store may look in the configuration file, using the JDBC data source MyDataSource, and with a logical name specified:

<jdbc-store>
<name>SampleJDBCStore</name>
<target>yourserver</target>
<data-source>MyDataSource</data-source>
<logical-name>Baz</logical-name>
</jdbc-store>

Table 6-3 describes the JDBC store configuration parameters that can be modified.

Table 6-3 JDBC Store Configuration Option
Option
Required
What it does. . .
Name
Yes
The name of the JDBC store, which must be unique across all stores in the domain.
Targets
Yes
The server instance where a JDBC store is targeted. Multiple subsystems can share the same store, as long as they are all targeted to the same server instance or migratable target.
Data Source
Yes
The JDBC data source or multi data source used by this JDBC store to access the store's database table (WLStore). This data source or multi data source must be targeted to the same server instance as the JDBC store.

Note: You cannot specify a JDBC data source that is configured to support global transactions. Therefore, the specified JDBC data source must use a non-XA JDBC driver. You also cannot enable Logging Last Resource or Emulate Two-Phase Commit in the data source.

Prefix Name
No
The prefix for the JDBC store's table is generally entered in the following format: [[[catalog.]schema.]prefix]
When using multiple JDBC stores, it is required to set this option to a unique value for each configured JDBC store. When no prefix is specified, the JDBC store table name is simply WLStore and the database implicitly determines the schema according the current user of the JDBC connection. Also, two JDBC stores cannot share the same database table. For more information, see Using Prefixes with a JDBC Store.
Logical Name
No
Optionally used with WebLogic Server 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.
Create Table from DDL File
No
Optionally used with supported DDL (data definition language) files to create the JDBC store's database table (WLStore). This option is ignored when the JDBC store's database table already exists. For more information, see Automatically Creating a JDBC Store Table Using Default and Custom DDL Files.

For instructions on configuring a JDBC store using the Administration Console, see " Create JDBC stores" in the Administration Console Online Help.]

Supported JDBC Drivers

When using a JDBC store, the backing database can be any database that is accessible through a JDBC driver. WebLogic Server detects some drivers for supported databases.

For each of these databases, there are corresponding DDL (data definition language) files within the WL_HOME\server\lib\weblogic.jar file, in the weblogic/store/io/jdbc/ddl directory, where WL_HOME is the top-level directory of your WebLogic Server installation.

Table 6-4 Supported JDBC Drivers and Corresponding DDL Files
Database
DDL Files
Cloudscape
cloudscape.ddl
IBM DB2
db2.ddl
db2v6.ddl
Informix
informix.ddl
Microsoft SQL (MSSQL) Server
msssql.ddl
HP NonStop SQL
nssql.ddl
MySQL
mysql.ddl
Oracle
oracle.ddl
oracle_blob.ddl
Pointbase
pointbase.ddl
Sybase
sysbase.ddl
Times Ten
timesten.ddl

The DDL files are actually text files containing the SQL commands (terminated by semicolons) that create the JDBC store's database table (WLStore). Therefore, if you are using a database that is not included in this list, you can copy and edit any one of the existing DDL files to suit your specific database, as described in Creating a JDBC Store Table Using a Custom DDL File.

Automatically Creating a JDBC Store Table Using Default and Custom DDL Files

The JDBC Store Configuration page provides an optional Create Table from DDL File option, through which you can access a pre-configured DDL file that is used to create the JDBC store's backing table (WLStore). This option is ignored when the JDBC store's backing table already exists. It is mainly used to specify a custom DDL file created for an unsupported database, or when upgrading JMS JDBC store tables from a prior release to a current JDBC Store table.

If a DDL file name is not specified in the Create Table from DDL File field, and the JDBC store detects that its backing table does not already exist, the JDBC store automatically creates the table by executing a pre-configured DDL file that is specific to the database vendor (see Supported JDBC Drivers).

If a DDL file name is specified in the Create Table from DDL File field, and the JDBC store detects that its backing table does not already exist, the JDBC store searches for the specified DDL file in the file path first, and then, if not found, searches for the DDL file in the CLASSPATH. Once found, the SQL within the DDL file is executed to create the JDBC store's backing table. If the configured file is not found and the table doesn't already exist, the JDBC store will fail to boot.

Creating a JDBC Store Table Using a Custom DDL File

To use a different database from those listed in Supported JDBC Drivers, you can copy and edit any one of the existing DDL template files to suit your specific database.

  1. Use the JAR utility supplied with the JDK to extract the DDL files to the /weblogic/store/io/jdbc/ddl directory using the following command:
  2. jar xf weblogic.jar /weblogic/store/io/jdbc/ddl
    Note: If you omit the weblogic/store/io/jdbc/ddl parameter, the entire jar file is extracted.
  3. Edit the DDL file for your database. An SQL command can span several lines and is terminated with a semicolon (;). Lines beginning with pound signs (#) are comments.
  4. Save your changes and rename the new DDL appropriately (for example, mydatabase.ddl)
  5. Create a JDBC store, as explained in Create JDBC Stores in the Administration Console Online Help.
  6. Use the Create Table from DDL File option on the General Configuration page to specify your custom DDL file (for example, /mydatabase.ddl
  7. Note: On Windows systems, for full path names always include the drive letter.

Enabling Oracle BLOB Record Columns

For Oracle databases, you can use the oracle_blob.ddl file to create a JDBC store table with a BLOB record column type rather than the default LONG RAW record column type. The oracle_blob.ddl file is pre-configured and supplied in the WebLogic CLASSPATH, as described in Supported JDBC Drivers.

To use the Oracle BLOB DDL with a JDBC store:

  1. Shut down the server instance that uses the JDBC store.
  2. Delete the current JDBC table, as explained in Managing JDBC Store Tables.
  3. Reboot the server instance.
  4. Create a new JDBC store, as explained in Create JDBC Stores in the Administration Console Online Help.
  5. In the Create Table from DDL File field on the General Configuration page, enter the location of the oracle_blob.ddl file, as follows: /oracle_blob.ddl
  6. Click Finish to create the JDBC store's backing table.

If you need to preserve data already in a Oracle LONG RAW column, but still want to switch the column to BLOB, do not use this method. Instead, consult the Oracle documentation for the SQL ALTER TABLE command.

Managing JDBC Store Tables

The JDBC utils.Schema utility allows you to regenerate a new JDBC store database table (WLStore) by deleting the existing version. Running this utility is usually not necessary, since WebLogic Server automatically creates this table for you. However, if your existing JDBC store database table somehow becomes corrupted, you can delete it using the utils.Schema utility.

The utils.Schema utility is a Java program that takes command-line arguments to specify the following:

Using the utils.Schema Utility to Delete a JDBC Store Table

Enter the utils.Schema command, as follows:

   $ java utils.Schema url JDBC_driver [options] DDL_file
Note: To execute utils.Schema, your CLASSPATH must contain the weblogic.jar file.

Table 6-5 lists the utils.Schema command-line arguments.

Table 6-5 Command-line arguments for utils.Schema
Argument
Description
url
Database connection URL. This value must be a colon-separated URL as defined by the JDBC specification.
JDBC_driver
Full package name of the JDBC Driver class.
options
Optional command options.
If required by the database, you can specify:
  • The user name and password as follows:
    -u <username> -p <password>
  • The Domain Name Server (DNS) name of the JDBC database server as follows:
    -s <dbserver>
You can also specify the -verbose option, which causes utils.Schema to echo SQL commands as they are executed.
DDL_file
The full pathname of the DDL text file containing the SQL commands that you want to execute. For more information, see Supported JDBC Drivers.

For example, the following command deletes a JDBC table named MYWLStore in an Oracle server named DEMO, with the user name user1 and password foobar:

$ echo "drop MYWLStore;" > drop.ddl
$ java utils.Schema 
jdbc:weblogic:oracle:DEMO \
weblogic.jdbc.oci.Driver -u user1 -p foobar -verbose \
drop.ddl

 


Guidelines for Configuring a JDBC Store

The following sections provide guidelines for using JDBC store prefixes, recommended WebLogic JDBC data source settings for JDBC stores, and handling JMS transactions with JDBC stores.

Using Prefixes with a JDBC Store

The JDBC store database contains a database table, named WLStore, that is generated automatically and is used internally by WebLogic Server. The JDBC store provides an optional Prefix Name parameter, which can be used to provide more precise access to the database table.

It is always a best practice to configure a prefix for the JDBC WLStore table name, especially when:

JDBC Store Table Rules

To avoid potential data loss, follow these rules:

Prefix Name Format Guidelines

For most databases, the Prefix Name option for the JDBC store's backing database table should be set in the following format for each configured JDBC store, which will result in a valid table name when prepended to the JDBC store table name:

   [[[catalog.]schema.]prefix]

Note that each period in the [[[catalog.]schema.]prefix] format is significant. Generally, catalog identifies the set of system tables being referenced by the DBMS, and schema generally corresponds to ID of the table owner (username). When no prefix is specified, the JDBC store table name is simply WLStore and the database implicitly determines the schema according the current user of the JDBC connection.

For example, in a production database, the database administrator could maintain a unique table for the Sales department, as follows:

   [[[Production.]JMSAdmin.]Sales]

The resulting table will be created in the Production catalog, under the JMSAdmin schema, and will be named SalesWLStore.

For some DBMS vendors, such as Oracle, there is no catalog to set or choose, so the format simplifies to [[schema.]prefix]. For more information, refer to your DBMS documentation for instructions on fully-qualified table names, but note that the syntax specified by the DBMS may differ from the format required for this option.

Caution: If the Prefix Name setting is changed, but the WLStore database table already exists in the database, take care to preserve existing table data. In this case, the existing database table must be renamed by a database administrator to match the new configured table name.

Recommended JDBC Data Source Settings for JDBC Stores

The following settings are recommended when you use a JDBC data source or multi data source for JDBC stores.

Automatic Reconnection to Failed Databases

WebLogic Server provides robust JDBC data sources that can automatically reconnect to failed databases after they come back online, without requiring you to restart WebLogic Server. To take advantage of this capability, and make your use of JDBC stores more robust, configure the following options on the JDBC data source associated with the JDBC store:

TestConnectionsOnReserve="true"
TestTableName="SYSTABLES"
ConnectionCreationRetryFrequencySeconds="600"

For more information about JDBC default Test Table Names, see Connection Testing Options for a Data Source in the Configuring and Managing WebLogic JDBC. For more information about setting the number of database reconnection attempts, see the Enabling Connection Creation Retries section in Configuring and Managing WebLogic JDBC.

Required Setting for WebLogic Type 4 JDBC DB2 Drivers

For data sources used as a JDBC store that use the WebLogic Type 4 JDBC driver for DB2, the BatchPerformanceWorkaround property must be set to "true" due to internal JMS batching requirements.

For more information, see the Performance Workaround for Batch Inserts and Updates section in the WebLogic Type 4 JDBC Drivers documentation.

Handling JMS Transactions with JDBC Stores

You cannot configure a JDBC store to use a JDBC data source that is configured to support global transactions. The JDBC store must use a JDBC data source that uses a non-XA JDBC driver. You also cannot enable Logging Last Resource or Emulate Two-Phase Commit in the data source.

Because the JDBC store implements the XAResource interface, it acts as it's own resource manager and handles the transactions above the JDBC driver level. That is, the store itself implements the XAResource and handles the transactions without depending on the database (even when the messages are stored in the database).

This means that whenever you are using a JDBC store and a database (even if it is the same database where the JMS messages are stored), then it is two-phase commit transaction.

For more information about using JMS transactions with a JDBC store, see Using Transactions with WebLogic JMS in Programming WebLogic JMS.

From a performance perspective, you may also boost your performance as follows:

 


Monitoring a Persistent Store

You can monitor statistics for each existing persistent store and for each open store connection.

Monitoring Stores

Each persistent store is represented at runtime by an instance of the PersistentStoreRuntimeMBean, which provides the following options.

Table 6-6 Persistent Store Run-time Options
Option
What it does. . .
CreateCount
Number of create requests issued to this persistent store.
ReadCount
Number of read requests issued to this persistent store.
UpdateCount
Number of update requests issued by this persistent store.
DeleteCount
Number of delete requests issued by this persistent store.
ObjectCount
Number of objects contained in the persistent store.
Connections
Number of active connections in the persistent store.
PhysicalWriteCount
Number of times the persistent store flushes its data to durable storage.

Monitoring Store Connections

For each open persistent store connection, the persistent store also registers a PersistentStoreConnectionRuntimemMBean, which provides the following options.

Table 6-7 Persistent Store Connection Runtime Options
Option
What it does. . .
CreateCount
Number of create requests issued to this connection.
ReadCount
Number of read requests issued to this connection.
UpdateCount
Number of update requests issued by this connection.
DeleteCount
Number of delete requests issued by this connection.
ObjectCount
Number of objects contained in the connection.

Table 6-8 defines most of the runtime prefix names of the WebLogic services and subsystems that can create a connection to the persistent store.

Table 6-8 Persistent Store Runtime Prefix Names 
Subsystem/Service
Runtime Prefix Name
Deployment
weblogic.deploy.internal
where internal is the name of the deployment connection
Diagnostic Service
weblogic.diagnostics.internal
where internal is the logical name of the diagnostic archive connection
EJB Timer Services
weblogic.ejb.timer.internal
where internal uniquely identifies EJB deployments in a server instance
JMS Service
JMS server:
weblogic.messaging.jmsServer.internal
where internal is the name of the JMS server connection
JMS durable subscriber:
weblogic.messaging.jmsServer.durablesubs.internal
where internal is the name of the durable subscriber connection
JTA Transaction Log (TLOG)
weblogic.transaction.internal
where internal is the name of the TLOG connection
Path Service
weblogic.messaging.PathService.internal
where internal is the name of the path service connection
SAF Service
SAF agent
weblogic.messaging.SAFAgent@server1.internal
where internal is the name of the SAF agent's connection
SAF durable subscriber:
weblogic.messaging.SAFAgent@server1.durablesubs.internal
where internal is the name of the durable subscriber connection
Web Services
weblogic.wsee.server.store.internal
where internal is the name of the Web Service's connection

 


Administering a Persistent Store

The WebLogic Store administration utility enables administrators to troubleshoot a WebLogic persistent store. The store utility operates only on a store that is not currently opened by a running server instance. This utility can be run from a Java command-line or from WLST (WebLogic Scripting Tool), as described in Store Administration Using a Java Command-line and Store Administration Using WLST.

The most common uses-cases for store administration are for compacting a file store to reduce its size and for dumping the contents of a file store of JDBC store to an XML file for troubleshooting purposes. Examples of these use cases are provided later in this section.

Table 6-9 defines the available store administration commands for Java and WLST.

Table 6-9 Persistent Store Administration Options
Java Command
WLST Method
What it does. . .
help
helpstore
Displays available commands, usage, and examples.
compact
compactstore
Compacts and defragments the space occupied by a file store. This command only works offline and does not work for JDBC stores.

Note: Running file stores are optimized for speed without regard for space. Therefore, running compact will reduce the store's size and utilize its allocated space more efficiently.

openfile
openfilestore
Opens an existing file store for further operations. If a file store does not exist, a new one is created in an open state using the -create parameter.
openjdbc
openjdbcstore
Opens an existing JDBC store for further operations. If a JDBC store does not exist, a new one is created in an open state
dump
dumpstore
Dumps store or connection contents in a human-readable format to user-specified XML file. The XML file format is the same format used by the diagnostic image of the persistent store.
list
liststore
Lists store names, open stores, or connections in a store.
n/a
getstoreconns
Returns a list of connections in the specified store (for script access)
n/a
getopenstores
Returns a list of opened stores (for script access).
opts
n/a
Lists invocation options for the store administration tool.
verbose
n/a
Controls display of additional information, such as stack traces.
close
closestore
Closes a previously opened store.
quit
exit
Ends the store administration session.

A persistent store can be backed by the file system (file store) or by a JDBC-capable database (JDBC store). Except for the openfile/openfilestore() and openjdbc/openjdbcstore() options, there is no difference in the options to operate on these two different types of stores.

Most commands and methods work in terms of store names, while others also work in terms of connection names. Store connections are logical groups of records within persistent stores. For example, the JMS and JTA subsystems persist their respective records in different connections in the same store.

Store Administration Using a Java Command-line

To open the persistent store administration utility from a Java command-line, type the following:

  > java weblogic.store.Admin
> storeadmin->

Accessing Store Administration Help

Type help for detailed descriptions on available store administration commands, as well as examples of typical command usage. For example, the following comprehensive help is provided for the list command, which lists store names, open stores, or connections in a store.

  storeadmin->help list
Command:
list
Description:
lists store names, open stores, or connections in a store
Usage:
list [-store storename|-dir dir]
Examples:
list #lists all opened stores by storename
list -store store1 #lists all connections in store1
list -dir dir1 #lists all storenames found in dir1

Dumping the Contents of a File Store

Here's an example of using a series of store administration commands to ultimately export the contents of a file store named myfilestore into a human-readable XML file format in a temporary directory. This does not include store connection names or the actual record contents, which require the optional -conn and -deep parameters.

  > storeadmin-> list -dir .
> storeadmin-> openfile -store myfilestore -dir .
> storeadmin-> dump -store myfilestore -out d:\tmp\filestore1-out
> storeadmin-> close -store myfilestore

The list command shows all the store names in the current directory. The openfile and openjdbc commands must be used to open and/or create a file or JDBC store first before calling certain administration functions, like dump and list (only when listing open stores). After administering an open store, you must close it using the close command.

Compacting a File Store

Here's an example of using the compact command to compact the space occupied by a file store in the mystores directory.

  > storeadmin->compact -dir c:\mystores -tempdir c:\tmp

Since the compact command can only be used on an unopened file store, none of the stores that have files in the source -dir directory should be open. Also, the temporary -tempdir directory should have at least enough extra space as the source directory and should also not be under the source directory. When compact successfully completes, the newly compacted store files will be in the mystores directory. In addition, a new, uniquely-named directory will be created under tmp containing the original uncompacted store files.

Store Administration Using WLST

The WLST interface has a couple of additional methods (compared to the Java command-line) such as getopenstores and getstoreconns, that return relevant Java objects and can be used for scripting in WLST.

Accessing Store Administration Help

To access the persistent store administration utility from WLST, type the following command:

> java weblogic.WLST

Type helpstore() for detailed descriptions on available store administration commands, as well as examples of typical command usage. For example, the following help is provided for the list command, which lists store names, open stores, or connections in a store.

  > wls:/offline> helpstore(liststore)
lists storenames, opened stores, or connections (for interactive access)
Parameters store and dir cannot both be specified concurrently.
    Usage: liststore(store='null',dir='null')
    @param store [optional] a previously opened JDBC or File store's name.
If store is specified, all connections in the store are listed.
@param dir [optional] directory for which to list available store names
If dir is specified, all store names in the directory are listed.
    If neither store nor dir are specified, all open store names are listed.
@return 1 on success, 0 on failure

Note that the parameters with an equal sign "=" are optional. For example, the compactstore method can be invoked as either compactstore(dir='storename', tempdir='/tmp') or compactstore(store='storename'), where tempdir takes the default value. Default values for optional parameters are listed in the command-specific help.

Dumping the Contents of a JDBC Store Using WLST

Here's an example of using the dumpstore method (store, outfile, conn='null', deep='false') to export the contents of a JDBC store named myJDBCStore in a human-readable XML file format out to a file named mystoredump-out.xml. This does not include store connection names or the actual record contents, which require the optional conn and deep parameters.

  > wls:/offline>
(openjdbcstore('myJDBCStore', 'oracle.jdbc.OracleDriver',
'jdbc:oracle:thin:@test2k31:1521:test120a', './wlstoreadmin-dump.props',
'jmstest', 'jmstest', '', 'jdbcstoreprefix')
dumpstore('myJDBCStore', 'mystoredump-out')
closestore('myJDBCStore')

The openjdbcstore and openfilestore methods must be used to open and/or create a store first before calling certain administration functions, like dumpstore and liststore (only when listing open stores). After administering an open store, you must close it using the closestore method.

Compacting a File Store Using WLST

Here's an example of a WLST script that uses the compactstore method (dir,tempdir='null') to compact the space occupied by a file store files in the mystores directory.

  > wls:/offline> compactstore('c:\mystores','c:\tmpmystore.dir')

Since the compactstore() method can only be used on unopened file stores, none of the stores that have files in the source `dir' directory should be open. Also, the temporary `tempdir' directory should have at least enough extra space as the source directory and should also not be under the source directory. When compact successfully completes, the newly compacted store files will be in the mystores directory. In addition, a new, uniquely-named directory will be created under tmpmystore containing the original uncompacted store files.

 


Limitations of the Persistent Store

The following limitations apply to the persistent store:


  Back to Top       Previous  Next