Introduction

Persistent cache uses a database server to store Penrose directory tree entries. This helps reducing the memory requirement. Also with persistent cache, if Penrose Server needs to be restarted, the cache does not need to be recreated. This configuration is recommended if you have a large database.

The way it works, Penrose will maintain a copy of your entire data source in a local database, and use the local database to serve client requests. If your data is already stored in a fast database or LDAP server, you don't need this feature. If you need to join different data sources (different database systems, or database with LDAP), you probably need this feature to speed up the process.

Prepare Cache Database

Prepare an empty database for the persistent cache. You should be able to use any database server.

Create Connection

Add a JDBC connection configuration in connections.xml pointing to the above database. For example:

<connection name="Cache">
  <adapter-name>JDBC</adapter-name>
  <parameter>
    <param-name>driver</param-name>
    <param-value>com.mysql.jdbc.Driver</param-value>
  </parameter>
  <parameter>
    <param-name>url</param-name>
    <param-value>jdbc:mysql://localhost/cache?autoReconnect=true</param-value>
  </parameter>
  <parameter>
    <param-name>user</param-name>
    <param-value>penrose</param-value>
  </parameter>
  <parameter>
    <param-name>password</param-name>
  <param-value>penrose</param-value>
  </parameter>
</connection>

Configure Persistent Cache

Suppose you have the following source in sources.xml:

<source name="users">
  <connection-name>Remote Database</connection-name>
  <field name="username" primaryKey="true"/>
  <field name="firstName"/>
  <field name="lastName"/>
  <field name="password"/>
  <parameter>
    <param-name>table</param-name>
    <param-value>users</param-value>
  </parameter>
</source>

Create an exact copy of the source for the cache, then map each field to the original field in the original source.

<source name="users_cache">
  <connection-name>Cache</connection-name>
  <field name="username" primaryKey="true">
    <variable>users.username</variable>
  </field>
  <field name="firstName">
    <variable>users.firstName</variable>
  </field>
  <field name="lastName">
    <variable>users.lastName</variable>
  </field>
  <field name="password">
    <variable>users.password</variable>
  </field>
  <parameter>
    <param-name>table</param-name>
    <param-value>users_cache</param-value>
  </parameter>
</source>

Initialize Cache

First you will need to create tree nodes and the database tables. Go to PENROSE_SERVER_HOME/bin then execute:

cache.bat create

Then you need to load the initial data:

cache.bat load

This could take a while depending on the size of your data. Make your mapped data source are not being updated during this time.

Start Penrose Server

Start Penrose Server. Now you can use Penrose as usual.

Cache Synchronization

To synchronize cache, execute:

cache.bat sync

Cache Clean-Up

If you need to empty the tree nodes and the database tables:

cache.bat clean

If you no longer need to use the persistent cache you can drop the tree nodes and database tables:

cache.bat drop