Skip Headers

Oracle® Business Rules User's Guide 10g Release 3 (10.1.3) B15986-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# B Using Rule Author and Rules SDK with Repositories

This appendix contains information on using Rule Author and Rules SDK with repositories. The following topics are covered:

- "Working with a WebDAV Repository"

- "WebDAV Repository Security"

- "Working with a File Repository"

- "High Availability for your Repository"

## B.1 Working with a WebDAV Repository

This section contains information on setting up and configuring a WebDAV rules repository.

### B.1.1 Setting up a WebDAV Repository

The Oracle Business Rules SDK supports the use of a WebDAV repository as the persistent storage for rules constructed with the SDK. This appendix briefly mentions some issues for consideration in setting up a WebDAV repository and presents some basic instructions for setting up a file system based WebDAV repository in an Oracle HTTP Server. WebDAV is supported in the Oracle HTTP Server by the `mod_oradav` module. Documentation on configuring and using `mod_oradav` can be found in the Oracle HTTP Server Administrator's Guide.

The WebDAV protocol is an extension to the HTTP protocol which enables remote users to write content to the web server. The server should be configured properly to prevent undesirable consequences. For more details, see the section titled "WebDAV Security Considerations" in Chapter 9 of the Oracle HTTP Server Administrator's Guide.

It is strongly recommended that some or all of the following be employed:

- Require authentication for access to WebDAV enabled areas.

- Use of SSL, at least during authentication (for the entire session if Basic Authentication is used).

- Use of the `ForceType` directive to prevent execution for URLs that reference content in WebDAV enabled areas.

The following example demonstrates the steps required to establish a WebDAV based rules repository in Oracle HTTP Server where the content is stored in the file system. All file system paths in this example are relative to the `ORACLE_HOME` in which the Oracle HTTP Server is installed. This example also assumes that the user is logged in as the user who installed Oracle Application Server, and that Oracle HTTP Server can be accessed with the URL `http://www.``myserver``.com:7777`.

Note: This example configuration for the WebDAV repository should only be used for internal testing and not for an actual production environment. This configuration does not configure access control and therefore allows anyone to access and modify the WebDAV repository. Please refer to Section B.2 for information about configuring WebDAV repository security.

1. Navigate to the `Apache/Apache/htdocs` directory (folder).

2. Create a directory named `rule_repository`.

3. Ensure that Oracle HTTP Server can read and write to the `rule_repository` directory.

4. Navigate to the `Apache/oradav/conf` directory.

5. Edit the `moddav.conf` file and add the following lines:

       <Location /rule_repository>
           DAV on
           ForceType text/plain
       </Location>

6. Restart Oracle HTTP Server (see the section titled "Starting, Stopping, and Restarting Oracle HTTP Server" in Chapter 1 of the Oracle HTTP Server Administrator's Guide.

These instructions establish a WebDAV repository accessible with the following URL:

    http://www.fully_qualified_host_name.com:7777/rule_repository/

Note: In order for authentication to work, you must use a fully qualified host name in the URL.

### B.1.2 Connecting to a WebDAV Repository

Selecting WebDAV as the repository type in Rule Author presents the configuration parameters shown in Table B-1:

Table B-1 Configuration Parameters for Connecting to a WebDAV Repository

Parameter | Description
--- | ---
URL | The URL for the desired WebDAV rule repository. This is a required parameter. The host name must be a fully qualified host name.
Proxy Host | The host name of the proxy server. This is required only if a proxy server is present between Rule Author and the WebDAV server.
Proxy Port | The port number to use on the proxy server. This is required only if a proxy server is present between Rule Author and the WebDAV server.

## B.2 WebDAV Repository Security

WebDAV allows read and write access to a WebDAV enabled server. It is highly recommended that steps are taken to secure the WebDAV server. To this end, it is likely that connections to a WebDAV server will need to be encrypted using SSL, thus requiring authentication in order to establish the connection.

### B.2.1 Communicating with a WebDAV Repository Over SSL from Rule Author

Basic SSL connections to a WebDAV repository are supported in Rule Author when Rule Author has been deployed in an Oracle Application Server environment. All that is required is that the WebDAV URL entered specify `https`.

If Rule Author is deployed in a standalone OC4J environment, or is deployed in a non-Oracle container that supports only HTTP, then SSL connections to a WebDAV repository are not supported.

Oracle Application Server comes with a test SSL certificate that is self-signed. This certificate should be replaced with your own certificate because it is not secure to use this test certificate in a production environment. If you use a certificate from a trusted authority, WebDAV access is available from both within and outside of the OC4J container. If you choose to use a self-signed certificate of your own, access from within the container is available but from outside the container, your default JSSE trust store must be modified in order to gain access. Refer to the JSSE Reference Guide included in the JDK for details.

Additionally, the Oracle SSL implementation must not be present in the classpath of the J2SE application.

### B.2.2 Setting the Location of your Oracle Wallet

To customize the location of your Oracle wallet for Rule Author:

1. Login to Enterprise Manager and go to the OC4J home page.

2. Click the Applications tab.

3. Click the link to your Rule Author application (the name of this link was defined when you first deployed the Rule Author application).

4. Click the ruleauthor link in the "Modules" table.

5. Click the Administration tab.

6. In the "Mappings" task, find row labeled "Environment Entry Mappings," then click the corresponding icon in the "Go to Task" column.

7. Specify your desired wallet location in the "Deployed Value" column for `walletStorePath` entry.

8. Restart Rule Author.

You can also set your wallet location at the time you deploy Rule Author by clicking on "Edit Deployment Plan" and then expanding the navigation tree on the left until "env-entry" is visible. Expand "env-entry" and then select `walletStorePath`. Be sure to restart Rule Author after you specify your desired wallet location.

### B.2.3 Configuring Rule Author for WebDAV Repository Authentication

When Rule Author attempts to connect to a WebDAV repository that has been configured to require authentication, Rule Author must be able to respond to the authentication request. Configuring Rule Author for repository authentication consists of the following steps:

1. Store the appropriate WebDAV repository user name and password in an Oracle Wallet.

2. If a proxy server is present and it also requires authentication, store the proxy server user name and password in the Oracle Wallet.

3. Configure the Rule Author environment entry to point to the Oracle Wallet (see Section B.2.2, "Setting the Location of your Oracle Wallet").

4. Restart the Rule Author application.

### B.2.4 Storing Data in an Oracle Wallet for WebDAV Repository Authentication

When a request for authentication from a WebDAV repository is received, the following information is provided:

- The host name of the server requesting authentication.

- The port on the server.

- The realm (or `AuthName` in Oracle HTTP Server configuration).

- An indication of whether or not this is proxy server authentication.

This information is used to construct keys for retrieving the user name and password for authentication. If there is a proxy server present and it requires authentication, multiple authentication requests may be processed: one for the proxy server and one for the WebDAV server.

If the request is for proxy authentication, the keys begins with "proxy-". This is followed by the host name, port, and realm (in that order) with a "-" separating each field. Finally, "-u" is appended to the key for the user name and "-p" is appended for the password. For example, given the following:

- Host is `myserver.myco.com`

- Port 443

- Realm is "Authorized WebDAV Users Only"

- A proxy server is present: `wwwproxy.myco.com`

- Proxy port is 80

- Proxy realm is "Authorized Proxy Users Only"

The keys for proxy authentication would be:

- For the user: "proxy-wwwproxy.myco.com-80-Authorized Proxy Users Only-u"

- For the password: "proxy-wwwproxy.myco.com-80-Authorized Proxy Users Only-p"

The keys for WebDAV authentication would be:

- For the user: "myserver.myco.com-443-Authorized WebDAV Users Only-u"

- For the password: "myserver.myco.com-443-Authorized WebDAV Users Only-p"

The user name and password are entered into an Oracle wallet with the `mkstore` command which is in the `bin` directory of the `$ORACLE_HOME`. Creating and modifying the Oracle wallet requires a password which is specified when the wallet is created. However, the wallet is constructed such that a password is not required at runtime to lookup the user name and password. Therefore, in order to protect this sensitive data, file system permissions must be used to restrict access. Access should be granted to only the user that must access the wallet at run time. The `mkstore` command creates the wallet with restricted permissions by default.

The following commands create a wallet in a the `/wallets` directory and store the user names and passwords for the example shown above where the user names and passwords are `proxyUser`, `proxyPassword`, `webdavUser`, and `webdavPassword`:

    mkstore -wrl /wallets/rules_wallet -create
    mkstore -wrl /wallets/rules_wallet -createEntry 'proxy-wwwproxy.myco.com-80-Authorized Proxy Users Only-u' proxyUser
    mkstore -wrl /wallets/rules_wallet -createEntry 'proxy-wwwproxy.myco.com-80-Authorized Proxy Users Only-p' proxyPassword
    mkstore -wrl /wallets/rules_wallet -createEntry 'www.myco.com-80-Authorized WebDAV Users Only-u' webdavUser
    mkstore -wrl /wallets/rules_wallet -createEntry 'www.myco.com-80-Authorized WebDAV Users Only-p' webdavPassword

Each command prompts you for the wallet password and, if needed, creates the directory for the wallet (`rules_wallet` is a directory).

The following command prints a usage message listing various capabilities of the `mkstore` command:

    mkstore -help

## B.3 Working with a File Repository

This section contains information about setting up and working with file repositories.

### B.3.1 Setting up a File Repository

Oracle Business Rules supplies a blank file repository that does not contain a dictionary. This file repository is named `emptyFileRepository` and is located in the `$ORACLE_HOME``/rules/lib` directory.

To setup a new file repository, copy and rename the `emptyFileRepository` file. Then, provide this file name and location in the Repository Connect page (see Section 2.4.1, "Connecting to a Rule Author Repository").

After you create a new file repository, you can connect to the new file repository and then create and save dictionaries in the repository.

### B.3.2 File Repository Updates and Temporary Files

When the SDK invokes the `RepositoryConnection` interface to update repository content, the following occurs:

1. A temporary file is created that contains the updated content. This temporary file is required as the process of rewriting the JAR file may involve reading unread entries from the current repository. It also provides a measure of safety should something go wrong writing the new content. The temporary file is created using the `File.createTempFile` method. If the name of the repository is less than three characters long, "_tmp_" is appended. The `File.createTempFile` method requires that the name be at least three characters long. The Sun JDK appends a number to the name; the behavior of other JVMs may differ. The file name extension is ".tmp" and the file is created in the same directory as the existing repository. In summary, the temporary file name of a repository called `myRepository` would be `myRepository65146.tmp`, and the temporary file name of a repository called `rr` would be `rr_tmp_65147.tmp`.

2. The content is written to the temporary file.

3. The existing repository is renamed as the name of the existing repository appended with "_o_r_i_g_" and the current time (UTC) in milliseconds.

4. The temporary file is renamed as the name of repository (for example, `myRepository`).

5. The renamed repository (containing the previous content) is removed.

If an error occurs in this process, cleanup is attempted. If the temporary file was created and still exists, an attempt is made to delete it. If the existing repository was renamed, an attempt is made to restore its original name.

In the event that the temporary file is left behind, the file repository prior to the update attempt should still exist. The temporary file should be deleted as the state of its contents is unknown.

In the event that the renamed repository file is left and the repository file is no longer exists, the renamed repository file contains the content prior to the update and a manual step is required to restore it (namely, renaming or copying the renamed file back to the correct name).

## B.4 High Availability for your Repository

After configuring your WebDAV or file repository, you should add the repository to the OracleAS Recover Manager configuration so that the repository is included in the backup and recovery process.

For more information about this tool, see Oracle Application Server Administrator's Guide.