PrizmDoc® Viewer v14.0 Release - Updated
PrizmDoc Viewer / Administrator Guide / PrizmDoc Server / Configuring / Adjust Caching Parameters
In This Topic
    Adjust Caching Parameters
    In This Topic

    Introduction

    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.

    The file paths for the Central Configuration file are:

    • Docker: <config_folder>/prizm-services-config.yml, where <config_folder> is the folder that you mapped as /config when creating the container. See Installing / Using Docker for more details.
    • Windows: C:\Prizm\prizm-services-config.yml (assuming the standard install location.)

    Example

    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.

    IMPORTANT: If viewing.sessionConstraints.minSecondsAvailable.max is set to a value greater than viewing.cacheLifetime in the central configuration file the cache lifetime will be overwritten by the minSecondsAvailable.max value. This configuration property provides a maximum value that can be used for the option 'minSecondsAvailable' in the POST /ViewingSession. The value is a positive number and represents seconds. When this value is set to zero, the ViewingSession timeout will be used. The default is 86400 seconds (1 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.

    NOTE: If you set the cache to 1 day, the timer will start over if someone accesses a file that is in the cache.

    To manually delete the cache:

    1. Stop the Prizm service.
    2. Go to the cache folder: (On Windows: C:\Prizm\cache. On Linux: <data_folder>/cache, where <data_folder> is the folder that you mapped as /data when creating the container. See Installing / Using Docker for more details.).
    3. You can delete all files and folders within the cache folder.
    4. Start the Prizm service again. PrizmDoc will generate a new cache.

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

    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

    cache.directory: /data/cache
    
    

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

    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

    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.