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)
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.
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.
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.
In the case of a vault server cache installation, the VaultClient properties file pertaining to VaultClientZ could contain the following:
Client Properties File with
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:
Lock reservation procedure
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:
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:
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.
Change the Vault Server you just installed into a Vault Server Cache. Two operations have to be done in order to do that:
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).
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:
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:
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.
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:
These keys may be modified and reloaded without stopping the VaultServer Cache process.
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:
For instance, the line VaultServer_Cache_MaxSize = 10000 means that the maximum size of the cache is ten mega bytes.
Threshold for cleaning
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
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:
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.