B Using Rule Author and Rules SDK with Repositories

This appendix contains information about using Rule Author and Rules SDK with repositories.

This appendix includes the following sections:

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 about setting up and configuring a WebDAV repository.

B.1.1 Setting up a WebDAV Repository

Oracle Business Rules supports using a WebDAV repository as the persistent storage for rule sets, the data model, and rules. This section describes how to set up a WebDAV repository and presents basic instructions for setting up a file system based WebDAV repository in Oracle HTTP Server. Oracle HTTP Server supports WebDAV with the mod_oradav module.

The WebDAV protocol is an extension to the HTTP protocol that enables remote users to write content to the Web server. Using this configuration, it is important that the Web server is properly configured to prevent undesirable consequences and to ensure the that a secure system is maintained.

It is strongly recommended that you employ some or all of the following security features on the Web server:

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 you can use to establish a WebDAV based repository 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:port.

Note:

Only use this example configuration for the WebDAV repository for internal testing and not for an actual production environment. This configuration does not include access control, and therefore allows anyone to access or modify the WebDAV repository. Please refer to Section B.2 for information about configuring a WebDAV repository with security.

Navigate to the Apache/Apache/htdocs directory (folder).
Create a directory named rule_repository.
Ensure that Oracle HTTP Server can read and write to the rule_repository directory.
Navigate to the Apache/oradav/conf directory.

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

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

Restart Oracle HTTP Server.

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

http://www.fully_qualified_host_name.com:port/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

When you select the WebDAV repository type 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.
`User Name`	Specifies the user authorized for WebDAV access.
`Password`	Specifies the password for the WebDAV user associated with the specified User Name.

Note:

In Rule Author when you supply both the user name and password and other required properties, and also specify an Oracle Wallet, the properties that you specify in the dialog take precedence over the Oracle Wallet information.

B.1.3 Connecting to a WebDav Repository Using a Proxy

Rule Author looks for the http.proxyHost system property. If this property is set, then the Rule Author picks up the http proxy system properties and uses them for the WebDAV connection. There are three properties you can set to specify that the http protocol handler uses a proxy:

http.proxyHost: the host name of the proxy server
http.proxyPort: the port number, the default value being 80
http.nonProxyHosts: a list of hosts that should be reached directly, bypassing the proxy. This is a list of regular expressions separated by '|'. Any host matching one of these regular expressions will be reached through a direct connection instead of through a proxy.

When a proxy is required to access the WebDAV repository, Rule Author displays the parameters shown in Table B-2, as well as those shown in Table B-1.

Table B-2 Configuration Parameters for Connecting to WebDAV Repository with Proxy

Parameter	Description
`Proxy User Name`	Specifies the proxy user name. This is required if the proxy server is configured with security.
`Proxy Password`	Specifies the proxy password. This is required if the proxy server is configured with security.

B.2 WebDAV Repository Security

WebDAV allows read and write access to a WebDAV enabled Web server. It is highly recommended that you take the appropriate steps to secure the WebDAV Web server. To this end, you should encrypt, using SSL, connections to a WebDAV Web Server and you should also require authentication.

This section covers the following topics:

Communicating with a WebDAV Repository Over SSL from Rule Author
Setting the Location of Your Oracle Wallet
Configuring Rule Author for WebDAV Repository Authentication
Storing Data in an Oracle Wallet for WebDAV Repository Authentication

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:

Login to Enterprise Manager and go to the OC4J home page.
Click the Applications tab.
Click the link to your Rule Author application (the name of this link was defined when you first deployed the Rule Author application).
Click the ruleauthor link in the "Modules" table.
Click the Administration tab.
In the "Mappings" task, find row labeled "Environment Entry Mappings," then click the corresponding icon in the "Go to Task" column.
Specify your desired wallet location in the "Deployed Value" column for walletStorePath entry.
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:

Store the appropriate WebDAV repository user name and password in an Oracle Wallet.
If a proxy server is present and it also requires authentication, store the proxy server user name and password in the Oracle Wallet.
Configure the Rule Author environment entry to point to the Oracle Wallet (see Section B.2.2, "Setting the Location of Your Oracle Wallet").
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, 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.

You can also create a new file repository by clicking Create on the repository connect page, when the Repository type selected is File. If you enter an existing repository path and click Create, the create behaves as if you clicked Connect, and connects you to the existing repository.

B.3.2 File Repository Updates and Temporary Files

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

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.
The content is written to the temporary file.
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.
The temporary file is renamed as the name of repository (for example, myRepository).
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 repository, you should add the repository to the OracleAS Recovery Manager configuration so that the repository is included in the backup and recovery process.

For more information about OracleAS Recovery Manager, see Oracle Application Server Administrator's Guide.