PrizmDoc v13.0 - Updated
Adjust Caching Parameters for PrizmDoc Server
Administrator Guide > System Configuration > Configure the PrizmDoc Server > Adjust Caching Parameters for PrizmDoc Server

When PrizmDoc Server receives a request to view a new document, also called a viewing session, it begins creating various artifacts associated with it and stores these artifacts on disk for a specified amount of time. These artifacts include such things as the original document, document metadata, and converted content used for viewing the document in a browser. We collectively refer to these artifacts as the PrizmDoc Server cache. This topic discusses various cache parameters that control things like cache lifetime, location, and reuse.

Cache Lifetime

The cache lifetime, or the amount of time cached files will exist on disk before being deleted for each new document, is controlled by two parameters, viewing.sessionLifetime and viewing.cacheLifetime. These parameters are found in the central configuration file.

Example
Copy Code
viewing.sessionLifetime: 20m
viewing.cacheLifetime: 1d

The session lifetime is the length of time that a viewing session remains usable. For example, this is the amount of time that a user can view and interact with a document in their browser before the document becomes unavailable. This value must be an integer followed by "s", "m", "h", or "d". The suffixes stand for second, minute, hour, or day, respectively. There should not be any space characters between the number and suffix. The example above indicates viewing sessions will timeout after 20 minutes.

The cache lifetime is the length of time that a document is cached and can be potentially reused by other new viewing sessions. This value must be an integer followed by "s", "m", "h", or "d". The suffixes stand for second, minute, hour, or day, respectively. There should not be any space characters between the number and suffix. The example above indicates that document data will be cached for one day.

The total cache lifetime of a document can be calculated by adding the session lifetime value to the maximum of either the session lifetime or cache lifetime.

This can be expressed as the following formula:

Total Cache Lifetime = Session Lifetime + max(Session Lifetime, Cache Lifetime)

The above formula will provide the approximate lifetime of a cached document because there is scheduling variability that can increase the actual time. This variability is caused partly by the periodic nature of which the cache cleanup processes are run. Also, if the server is under high load, the cleanup processes may be delayed so as not to consume additional resources.

See the Caching Strategies topic for details and recommendations for the viewing session timeout and cache expiration period values in your application.

The following configuration properties have been deprecated and will be removed in a future release. Alter these properties only if not using the central configuration file.

The cache lifetime, or the amount of time cached files will exist on disk before being deleted for each new document is controlled by two parameters, ViewingSessionTimeout and CacheExpirationPeriod. These parameters are found in the main PrizmDoc Server configuration file located in the following default directories:

Example
Copy Code
<ViewingSessionTimeout>20m</ViewingSessionTimeout>
<CacheExpirationPeriod>1d</CacheExpirationPeriod>

The viewing session timeout is the length of time that a viewing session remains usable.

The cache expiration period is the length of time that a document is cached and can be potentially reused by other new viewing sessions.

The cache lifetime of a document can be calculated by adding the viewing session timeout value to the maximum of either the viewing session timeout or cache expiration period.

This can be expressed as the following formula:

Cache Lifetime = Viewing Session Timeout + max(Viewing Session Timeout, Cache Expiration Period)

Cache Location

The directories that PrizmDoc Server uses for caching are user-configurable. To change them, you will need to set the cache.directory parameter in the central configuration file. Cached files will be stored in subdirectories of this location.

Example
Copy Code
cache.directory: /usr/share/prizm/cache

See the Caching Strategies topic for details and recommendations on cache locations and types of storage media.

The following configuration properties have been deprecated and will be removed in a future release. Alter these properties only if not using the central configuration file.

The directories that PrizmDoc Server uses for caching are user-configurable. To change them you will need to set a few different parameters in different configuration files. Mentioned already in the Cache Lifetime section above, the main PrizmDoc Server configuration file contains the bulk of the cache location parameters and can be found in the following default directories:

Example
Copy Code
<DocumentPath>/usr/share/prizm/cache/DocumentCache</DocumentPath>
<GroupStateFolder>/usr/share/prizm/cache/GroupState</GroupStateFolder>
<TempcachePath>/usr/share/prizm/cache/TempCache</TempcachePath>

To be noted:

Cache Reuse

Consider the case where a viewing session is created in PrizmDoc Server, and PrizmDoc Server performs the work to convert the original source document to a format that is suitable for viewing in a browser. Now consider the case where multiple users are viewing the same document one or more times. PrizmDoc Server can leverage the cache in this case so that the document is converted only once but can be served for future viewing sessions using identical documents. The result is very fast viewing times for users and decreased processing time for servers.

PrizmDoc Server enables cache reuse by default. This property can be controlled per viewing session and is adjustable using the JSON properties of the initial POST request sent to PrizmDoc Server to create a viewing sessions.

Example
Copy Code
POST http://localhost:18681/Prizm Services/V1/ViewingSession
{    
     "externalId":"MyDocumentName.pdf",    
     "serverCaching":"Full",    
     "render":    
     {        
          "html5":        
          {            
               "alwaysUseRaster":false        
          }    
     }
}

In the example above, the serverCaching property is set to a value of Full, which enables the reuse of the cache for multiple viewing sessions. This is the default value, so not including serverCaching at all would yield the same result. We recommend this feature to obtain the best performance.

To disable reuse of the cache, set serverCaching to a value of None. This means that any new viewing sessions will need to convert the source document into viewable content even if the same document has been converted during a previous viewing session. Also, because no other viewing session will be reusing the converted document, the document data associated with viewing session will typically be deleted immediately after the viewing session expires.