Configuration

Version:4.3.0 +

Applicable to:Futurama Website/Futurama Webservice

Description

In case Futurama is running in Website or Webservice mode it is possible to configure settings for the caching of information. These settings are set in the cache-section.

Configuration

Settings

Within the configuration element the next code has to be included:

<configSections>
	<sectionGroup name="futuramaSettings">
		<section name="cache" type="ActuIT.Futurama.Config.CacheSection, ActuIT.Futurama.Engine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"/>
	</sectionGroup>
</configSections>

Next to this code, also within the configuration element the next code has to be included:

<futuramaSettings>
    <cache enabled="{true/false}" enableHistory="{true/false}" expirationInMinutes="{value}" GCLargeObjectHeapCompactionModeInterval="{value}" 
	numberOfDocuments="{value}" secondsBetweenLoad="{value}" webServiceDocumentCachingMode="OneDocPerSession">
        <warmUpDocuments>
            <file pattern="^(document.xml){1}$"/>
        </warmUpDocuments>
    </cache>
</futuramaSettings>

The futuramaSettings element is the general part for more configuration settings. Within this element the cache element is set.

Explanation

Within the cache element some attributes can be set. Below the possible values of these attributes.

enabled

Indicates whether the caching of documents/sessions is enabled or disabled. Notes:

this attribute is required;
this attribute is only used in Website mode or Webservice mode;

enableHistory

Indicates whether the use of the back button in the browser is enabled. This option is available from Futurama 17.10.

Notes:

this attribute not is required; The default value is false.
enabling this attribute is only possible in combination with Html5 rendering.
enabling this attribute will increase the memory usage for a Futurama session .
this attribute is only used in Website mode or Webservice mode.

numberOfDocuments

Indicates the number of documents that Futurama stores in the cache. When starting a new web session, the loading of a Futurama document can take some time. This depends on the size of the Futurama document. With the ‘numberOfDocuments’ setting, Futurama can read in advance a number of empty documents in memory. If a new session starts, one of these empty documents can be used to speed up the loading process. The number of documents Futurama has to read in advance can be defined with the ‘numberOfDocuments’ setting. Another important setting is the ‘secondsBetweenLoad’ setting (see described below). System administrators can use these two settings to find a good balance between performance (many documents in cache, combined with few seconds between loading new cache-documents will result in fast loading of new web sessions) and the memory use (few documents in cache, combined with many seconds between loading new cache-documents causes limited memory use). Notes:

the default value is '0';
this attribute is optional. If this attribute is not included the default value is used;
this attribute is only used in Website mode;
this attribute should be used in combination with the 'secondsBetweenLoad' attribute;

secondsBetweenLoad

Indicates the number of seconds before a new Futurama document will be read in cache. For more information see the description of 'numberOfDocuments'. Notes:

the default value is '0';
this attribute is optional. If this attribute is not included the default value is used;
this attribute is only used in Website mode;
this attribute should be used in combination with the 'numberOfDocuments' attribute;

expirationInMinutes

Indicates the number of minutes a document is kept in the cache after a webservice call. Basically, webservice calls are stateless. That means that every webservice call is an independant call, unrelated to any previous calls. This differs from sessions, that occur at websites. Nevertheless, with Futurama it is possible to store webservice documents. The advantage of this is that calculations, or part of calculations, don’t have to be executed everytime. This improves the performance significantly. An example is a webservice that has to read information from a database or an external webservice. In case the input remains the same, it isn’t necessary to read the information again with every webservice call. Notes:

the default value is '0';
this attribute is optional. If this attribute is not included the default value is used;
this attribute is only used in Webservice mode;

GCLargeObjectHeapCompactionModeInterval (from version 5.3.1)

This setting is available for version 5.3.1+. It is only used in batch mode. You can use this setting to determine how often Futurama will clean up the memory to avoid fragmentation. The value specifies the interval in seconds at which Futurama clean up the memory it uses. The default value is 0 which means that cleaning up the memory is disabled. We recommend to only use this property if you perform very calculation intensive long running jobs and you experience performance degradation as the job runs longer.

warmUpDocuments (from version 5.3.1)

This setting is available for version 5.3.1+. It is only used in webservice mode. You can use the warmUpDocuments configuration to specify which documents Futurama should load at startup. For each document that Futurama loads the warmUpXmlBuilder is executed. In this way you can make sure that when a service is restarted all Futurama documents are pre-cached and all the static data that the Futurama documents use is read into memory. In that way you can make sure that the first call to a webservice is not delayed by loading static data.

Within warmUpDocuments you can specify an unlimited number of files with a pattern. A pattern is a regular expression that determines if a file is loaded into cache. In the example above all files in the path for the webservice documents are searched. If a filename matches the regular expression, then it is loaded into cache. For more information about warmUp, see this page

To be able to use this setting you need to make sure that the application is started automatically when IIS is restarted. The pictures underneath show how to do this.

webServiceDocumentCachingMode="OneDocPerSession" (from version 21.11)

Normally webservices are stateless. That means that every webservice call is an independant call, unrelated to any previous calls. This differs from sessions, that occur at websites. From Futurama 21.11 it is possible to also make webservices stateful. This means that it is possible to perform subsequent requests each of which are related to preceding requests, similar to the use of sessions in websites. In order to use this functionality this setting has to be added to the web.config. To work with sessions in webservice calls, three new methods are available: StartSession, KeepSessionAlive and SessionEnd. See paragraph Methods of the Overview Futurama Webservice page for more information of these methods.

Windows Server

On Windows Server the feature ‘Application Initialization’ has to be installed. You can find this feature by going through the following steps. Go to Server Manager –> Dashboard –> Add roles and features –> Next –> check “Role-based or feature-based installation” –> Next –> check “Select a server from the server pool” –> Next. In the “Roles” screen unfold Web Server (IIS) –> Web Server –> Application Development.

Windows

On Windows the feature ‘Application Initialization’ (Control Panel –> Programs –> Turn Windows features on or off –> Internet Information Services -> World Wide Web Services -> Application Development Features) has to be installed as is shown in the following picture:

IIS_feature_installation

IIS

You have to set the Start Mode on ‘AlwaysRunning’ for the application pool, as shown in the following picture:

ApplicationPoolConfig

In the Basic Settings of the application in IIS you have to set the property 'Enable Preload' as is shown in the following picture.

See for an example using the property warmUpDocuments this page.

Feedback

If you have any questions about this subject or if you want to provide us feedback please send us an e-mail.

Updated: 2015-12-07