Setting Up the Vault Server Cache

Introduction to Vault Server Cache

The purpose of the vault server cache is to improve performance when accessing vault documents over a wide area network (WAN). To be efficient, the mechanism is based on the assumption that most users perform read access rather than modification to vault documents. The vault server cache mechanism creates a local copy of a remote vault document the first time it is accessed. Once in the cache, it is accessed locally in the cache and not remotely. The document in the cache is refreshed when needed.

This functionality applies only to a multi-site deployment with a vault cache.

To understand how a vault server cache works, compare the differences between a standard vault server and a vault server cache installation.
 

Standard Vault Server Installation

The following drawing illustrates a standard vault server installation:
 

Read/Write Mechanism for the Standard Vault Server Installation

In the case of a standard vault server installation, where a cache is not used, each vault client application connects directly to the standard vault server for any read/write operation.

Thus, for the sample above, in case of the standard vault server installation, the VaultClient properties file pertaining to VaultClientA could contain the following:

## Standard Vault Client Properties File (VaultClientA)

## We suppose the VaultServer Vault1OrbSrv is running
## on a workstation called laureen and the Orbix
## daemon listen port on this workstation is 1570

VaultClient_DefaultAliasName  =  Vault1
VaultClient_ReadProtocol       =  2
VaultClient_ReadProtocol_0    =  CORBA
VaultClient_ReadProtocol_1    =  NFS
VaultClient_WriteProtocol      =  2
VaultClient_WriteProtocol_0   =  CORBA
VaultClient_WriteProtocol_0   =  NFS
VaultClient_BlockSize            =  262144
VaultClient_Trace                 =  OFF

## Vault1 alias entry

## Server for read operations

VaultClient_Vault1_ReadVaultServerName           =  Vault1OrbSrv
VaultClient_Vault1_ReadVaultServerHostName     =  laureen
VaultClient_Vault1_ReadVaultServerDaemonPort   =  1570

## Server for write operations

VaultClient_Vault1_WriteVaultServerName          =  Vault1OrbSrv
VaultClient_Vault1_WriteVaultServerHostName    =  laureen
VaultClient_Vault1_WriteVaultServerDaemonPort  =  1570

Note: the vault alias name is the same as the Orbix service name, but you can modify the alias.

One benefit of activating the cache via a properties file is that it is very easy to plug in or unplug a vault server cache. You only have to modify a VaultClient.properties file once the vault server cache is installed. Another benefit is that the client application does not waste time in managing a cache application.
 

Vault Server Cache Mechanism

The example below illustrates how a vault server cache works:

Note: If there is a single Vault Master, the VaultClientA VaultClient.properties file is the same as VaultCacheOrbSrv VaultClient.properties file.
 

Read Mechanism

In a vault server cache installation, when a client application using a vault server cache tries to access a document, it asks the vault server cache to retrieve the document. Then, the vault server cache checks if the requested document is already in the cache. If the document is found, it checks if it is up-to-date. If this is the case, it transmits the document to the client application. But if the document is not up-to-date, it retrieves the latest version of the document from the vault server, stores it in the local cache, then sends it to the client.

In order to do so, a vault server cache embeds its own vault client application. This is why a vault server cache needs a VaultClient.properties file. This properties file has to be different from the one used by the VaultClientZ application in the illustration. It is due to the fact that read operations are done on the standard vault server instead of the vault server cache.

Vault Client Properties File with VaultServer Cache (VaultClientZ)

In the case of a vault server cache installation, the VaultClient properties file pertaining to VaultClientZ could contain the following:

## Vault Client Properties File with
## VaultServer Cache (VaultClientZ)

## We suppose the VaultServer Vault1OrbSrv is running
## on a workstation called laureen and the Orbix
## daemon listening port on this workstation is 1570.

## We assume the VaultServer Cache VaultCacheOrbSrv
## is running on a workstation called glenn and the Orbix
## daemon listening port on this workstation is 1572.

VaultClient_DefaultAliasName  =  Vault1
VaultClient_ReadProtocol      =  2
VaultClient_ReadProtocol_0    =  CORBA
VaultClient_ReadProtocol_1    =  NFS
VaultClient_WriteProtocol     =  2
VaultClient_WriteProtocol_0   =  CORBA
VaultClient_WriteProtocol_0   =  NFS
VaultClient_BlockSize         =  262144
VaultClient_Trace             =  OFF

## Vault1 alias entry

## Server for read operations

VaultClient_Vault1_ReadVaultServerName         =  VaultCacheOrbSrv
VaultClient_Vault1_ReadVaultServerHostName     =  glenn
VaultClient_Vault1_ReadVaultServerDaemonPort   =  1572

## Server for write operations

VaultClient_Vault1_WriteVaultServerName        =  VaultCacheOrbSrv
VaultClient_Vault1_WriteVaultServerHostName    =  glenn
VaultClient_Vault1_WriteVaultServerDaemonPort  =  1572
 

Mechanism for Writing Documents to the Local Vault Cache

Now, the vault client application can write documents to the local vault cache, as illustrated by the diagram below:

In more details, the mechanism is as follows:

  • the vault client begins a write operation
  • the vault cache sends a lock reservation to the remote vault server with the vault cache name (as seen by the vault client, the document is reserved for writing but is still available in read mode)
  • the vault client writes the document in the local vault cache
  • the vault server is informed in which vault cache the document is: later, the vault server will retrieve the document through an asynchronous replication process
  • once saved, the document can then be read and saved again by vault clients
  • document deletion is performed synchronously in both the vault server and the vault cache.
 

Lock reservation procedure

  1. The vault client begins an open write operation.
  2. The vault cache requests the lock reservation from the vault server.
  3. The vault server performs the lock reservation.
  4. The vault server returns the new Vault ID and Timestamp information to the vault cache.
  5. The vault cache does a reservation with the vault server parameters in its database.
  6. The vault client writes the document in the vault cache.
  7. The vault client requests a close from the vault cache.
  8. The vault cache requests a close from the vault server.
  9. The vault server commits the lock.

Vault Master Refresh Mechanism

The vault server replicates through an external thread when the vault server is inactive or via a command line.

Asynchronous replication step by step:

  1. The vault server requests the document by block from the vault cache.
  2. The vault server publishes the document when the document is completely transferred.
  3. The vault server suppresses the reservation.
  4. The vault server commits steps 2 and 3.

Note: The vault cache could interrupt the asynchronous vault server transfer if its vault client modifies the document.

Other Vault Cache or Vault Client

Vault server clients and others vault cache clients cannot access the new document version until the document is on the vault server. In read mode, these vault clients will have access to the previous version of the document being modified.

Vault server clients and others vault cache clients cannot access the document in write mode until the document is on the vault server.
 

Vault Server Cache Installation Setup

Now that you understand the differences between the standard vault server installation and the local vault server cache, you are ready to begin the vault server cache installation.

This setup is implemented in four steps:

Step one

Install the Vault Server Cache as you install a standard Vault Server. Then, change this Vault Server installation into a Vault Server Cache installation by following steps two and three below. Keep in mind that just like a standard Vault Server, a Vault Server Cache needs its own database structures and its own VaultServer.properties file. For information about how to install a standard vault server, refer to Setting Up the Vault Server.

Beware: do not share database structures or server properties file between Vault Servers, it is neither supported nor allowed. In order to avoid any misunderstanding, assume the name of the Vault Cache server properties file is VaultCacheServer.properties in the following steps.

Step two

Change the Vault Server you just installed into a Vault Server Cache. Two operations have to be done in order to do that:

  1. Add the following line to the VaultCacheServer.properties file to enable the Cache working mode:

    VaultServer_Cache = true

    This converts a standard vault server into a vault cache.

  2. Create a VaultClient.properties file for the Vault Server Cache to setup read/write connection parameters between the Vault Server Cache and the remote standard Vault Server. In the file VaultClient.properties for the vault server cache, declare the same vault alias name as in the VaultClient.properties file used for the ENOVIA VPM Product Editor.

    The host/port/Orbix service name for a given alias must be different between the VaultClient.properties file of the ENOVIA VPM Product Editor client and the VaultClient.properties file of the vault server cache. The host/port/Orbix service name for the ENOVIA VPM Product Editor client reference the vault cache, whereas the host/port/Orbix service name for the vault cache reference the cached vault.

The VaultClient properties file pertaining to VaultCacheOrbSrv illustrated above in the section Vault Server Cache Mechanism could be:

## Vault Client Properties File for
## VaultServer Cache (VaultCacheOrbSrv)

## We suppose the VaultServer Vault1OrbSrv is running
## on a workstation called laureen and the Orbix
## daemon listen port on this workstation is 1570.

VaultClient_DefaultAliasName  =  Vault1
VaultClient_ReadProtocol      =  2
VaultClient_ReadProtocol_0    =  CORBA
VaultClient_ReadProtocol_1    =  NFS
VaultClient_WriteProtocol     =  2
VaultClient_WriteProtocol_0   =  CORBA
VaultClient_WriteProtocol_0   =  NFS
VaultClient_BlockSize         =  262144
VaultClient_Trace             =  OFF

## Vault1 alias entry

## Server for read operations

VaultClient_Vault1_ReadVaultServerName         =  Vault1OrbSrv
VaultClient_Vault1_ReadVaultServerHostName     =  laureen
VaultClient_Vault1_ReadVaultServerDaemonPort   =  1570

## Server for write operations

VaultClient_Vault1_WriteVaultServerName        =  Vault1OrbSrv
VaultClient_Vault1_WriteVaultServerHostName    =  laureen
VaultClient_Vault1_WriteVaultServerDaemonPort  =  1570

In this example, the vault cache is a client of the vault master Vault1OrbSrv illustrated above.

Step three

Note: an old configuration (read on Vault Cache, write on Vault Server) is no longer supported and has been replaced by the Vault Cache write operation support.

Modify the VaultClient.properties used by Vault Client applications that are to use the VaultServer Cache. You have to update the read/write parameters for the right VaultAliasName in order to use the Vault Server Cache in place of the standard Vault Server, as illustrated in Vault Client Properties File with VaultServer Cache (VaultClientZ).

Step four

Set up the remote Vault Server to enable it to retrieve the documents from the VaultServer Cache. Add the following line to the VaultServer.properties file to enable the Vault Server to get documents from the Vault Server Cache:

VaultServer_VSForWCV = true

The VaultServer will check every 300 seconds if it has a document to retrieve from a Vault Server Cache. You can change that default behavior by setting the following optional VaultServer key:

VaultServer_TimeoutForDocsCatcher: time between two checks if there is a document to get from a VaultServer Cache (unit: millisecond).

If there are several documents to retrieve from one or several Vault Server Caches, the Vault Server retrieves them and then waits for the timeout above.
 

Vault Server Cache Administration

Vault Cache Clean Behaviour

Whenever a client application connects with the Vault Server, a Vault session is created. When a Vault client such as CATIA V5 uses the Vault Server to retrieve data about a specific document, that document is kept in the Vault session. Documents remain in the Vault Cache as long as they are in a Vault session. Saving a document will remove it from the Vault session, and closing the Vault client application will remove opened documents from the Vault session. Only documents removed from the Vault session can be cleaned from the Vault Cache, if the VaultCacheClean property is enabled.

Keys

In order to be able to manage cache size and cleaning policy, the following keys can be added to the VaultServer.properties file used by Vault Server Cache:

Optional Keys for a Cache VaultServer administration:

VaultServer_Cache_CleanEnabled                       :  trigger cleaning mode on (default: true).

VaultServer_Cache_MaxSize                              :  Maximum size of Vault Cache (unit: kb).

VaultServer_Cache_CleanThreshold                     :  threshold for cleaning files (percent of cache max size).

VaultServer_Cache_CleanRate                            :  targeted size after cleaning (percent of cache max size)

VaultServer_Cache_TimeoutForClean                  :  time between two cleaning (unit: milli second).

These keys may be modified and reloaded without stopping the VaultServer Cache process.

Key explanation

Cleaning functionality enabling: VaultServer_Cache_CleanEnabled

For instance, the line VaultServer_Cache_CleanEnabled = true means that a specialized thread is launched inside the VaultServer Cache process in order to manage cache size and cleaning operations. If this key is set to false, it disables the whole set of cache size management functionality.

Maximum cache size: VaultServer_Cache_MaxSize

For instance, the line VaultServer_Cache_MaxSize = 10000 means that the maximum size of the cache is ten mega bytes.

Threshold for cleaning files: VaultServer_Cache_CleanThreshold

For instance, the line VaultServer_Cache_CleanThreshold = 80 means that if there is less than 80 per cent of maximum cache size in use, then there is no cleaning operation done. But, if it is not the case, a cleaning operation is launched.

Targeted size after cleaning: VaultServer_Cache_CleanRate

For instance, the line VaultServer_Cache_CleanRate = 50 means that after a cleaning operation, the new current cache size should be 50 per cent of the maximum cache size.

Time between two checks if a cache cleaning is needed: VaultServer_Cache_TimeoutForClean

For instance, the line VaultServer_Cache_TimeoutForClean = 300000 means that every five minutes a check is done to know if a cleaning operation should be launched or not.