Configuration

Sparksee allows some configuration variables to be set in order to update or monitorize the behavior of the system, as well as to make the deployment of Sparksee-based applications easier.

Set-up

There are two alternatives for setting-up the configuration:

  1. Using the SparkseeConfig class.
  2. Using a properties file.

Both can even be used at the same time. In case of conflict, the settings from the SparkseeConfig class have a higher priority.

SparkseeConfig class

The SparkseeConfig class defines a setter and a getter for each of the variables that can be specified for Sparksee configuration. If not changed, all the variables are loaded with default values. All these values can be overwritten by the user calling the corresponding setter or loading a properties file.

In order to set up a configuration the user must create an instance of the SparkseeConfig class, which will have the default values. The path to a configuration file can be provided to the SparkseeConfig constructor. If it’s provided it will be used to override the default settings and it will be used to store any changes including the downloaded license key.

The Sparksee license key, by default, will be automatically downloaded when you try to create a Sparksee class with a SparkseeConfig that has valid client id and license id values but no license key already set (or it is expired or close to expire). And if the key can be successfully downloaded, it will be saved to the specified config file (if provided). So providing a path to a config file when creating a SparkseeConfig object is highly recommended to avoid having to donwload the license key every time.

All the variables in SparkseeConfig may be set if the user needs to change them. We strongly recommend understanding each of the variables prior to changing their default values:

[Java]
SparkseeConfig cfg = new SparkseeConfig("sparksee.cfg");
cfg.setClientId("Your client identifier");
cfg.setLicenseId("Your license identifier");
cfg.setCacheMaxSize(2048); // 2 GB
cfg.setLogFile("HelloSparksee.log");
...
Sparksee sparksee = new Sparksee(cfg);
Database db = sparksee.create("HelloSparksee.gdb", "HelloSparksee");
[C#]
SparkseeConfig cfg = new SparkseeConfig("sparksee.cfg");
cfg.SetClientId("Your client identifier");
cfg.SetLicenseId("Your license identifier");
cfg.SetCacheMaxSize(2048); // 2 GB
cfg.SetLogFile("HelloSparksee.log");
...
Sparksee sparksee = new Sparksee(cfg);
Database db = sparksee.Create("HelloSparksee.gdb", "HelloSparksee");
[C++]
SparkseeConfig cfg(L"sparksee.cfg");
cfg.SetClientId(L"Your client identifier");
cfg.SetLicenseId(L"Your license identifier");
cfg.SetCacheMaxSize(2048); // 2 GB
cfg.SetLogFile(L"HelloSparksee.log");
...
Sparksee * sparksee = new Sparksee(cfg);
Database * db = sparksee->Create(L"HelloSparksee.gdb", L"HelloSparksee");
[Python]
cfg = sparksee.SparkseeConfig("sparksee.cfg")
cfg.set_client_id("Your client identifier")
cfg.set_license_id("Your license identifier")
cfg.set_cache_max_size(2048) # 2 GB
cfg.set_log_file("Hellosparksee.log")
...
sparks = sparksee.Sparksee(cfg)
db = sparks.create(u"Hellosparksee.gdb", u"HelloSparksee")
[Objective-C]
STSSparkseeConfig *cfg = [[STSSparkseeConfig alloc] initWithPath: @"sparksee.cfg"];
[cfg setClientId: @"Your client identifier"];
[cfg setLicenseId: @"Your license identifier"];
[cfg setCacheMaxSize: 2048]; // 2 GB
[cfg setLogFile: @"HelloSparksee.log"];
...
STSSparksee *sparksee = [[STSSparksee alloc] initWithConfig: cfg];
//[cfg release];
STSDatabase *db = [sparksee create: @"HelloSparksee.gdb" alias: @"HelloSparksee"];

Properties file

As previously explained, as an alternative to SparkseeConfig methods, the user can load Sparksee configuration variables from a properties file in order to make development of their applications using Sparksee easier.

A properties file is a plain-text file where there is one line per property. Each property is defined by a key and a value as follows: key=value.

This is an example of a Sparksee configuration properties file:

sparksee.clientId="Your client identifier"
sparksee.licenseId="Your license identifier"
sparksee.io.cache.maxsize=2048
sparksee.log.file="HelloSparksee.log"

By default, SparkseeConfig tries to load all the variables defined in the ./sparksee.cfg file (in the execution directory). If the user has not created this file, the default values will be assumed.

Loading Properties through SparkseeConfig

The recommended way of loading properties since Sparksee 6.0 is to provide the configuration file path to the SparkseeConfig class constructor. This way, the settings in the file will be loaded, and the file can be saved either manually or automatically when a new license key is downloaded (when the SparkseeConfig is used at the Sparksee class constructor without having a valid license key but with valid client and license ids).

[Java]
SparkseeConfig cfg = new SparkseeConfig("sparksee/config/dir/mysparksee.cfg");
Sparksee sparksee = new Sparksee(cfg);
Database db = sparksee.create("HelloSparksee.gdb", "HelloSparksee");
[C#]
SparkseeConfig cfg = new SparkseeConfig("sparksee/config/dir/mysparksee.cfg");
Sparksee sparksee = new Sparksee(cfg);
Database db = sparksee.Create("HelloSparksee.gdb", "HelloSparksee");
[C++]
SparkseeConfig cfg(L"sparksee/config/dir/mysparksee.cfg");
Sparksee * sparksee = new Sparksee(cfg);
Database * db = sparksee->Create(L"HelloSparksee.gdb", L"HelloSparksee");
[Python]
cfg = sparksee.SparkseeConfig("sparksee/config/dir/mysparksee.cfg")
sparks = sparksee.Sparksee(cfg)
db = sparks.create(u"Hellosparksee.gdb", u"HelloSparksee")
[Objective-C]
STSSparkseeConfig *cfg = [[STSSparkseeConfig alloc] initWithPath: @"sparksee/config/dir/mysparksee.cfg"];
STSSparksee *sparksee = [[STSSparksee alloc] initWithConfig: cfg];
//[cfg release];
STSDatabase *db = [sparksee create: @"HelloSparksee.gdb" alias: @"HelloSparksee"];

Loading Properties the old way

The old way of loading a properties file was loading them with the SparkseeProperties before the SparkseeConfig class is instantiated. The SparkseeProperties class contains a method for specifying a different file name and path to be loaded.

To load Sparksee configuration variables from a different file rather than the default, the method load must be called before the SparkseeConfig class is instantiated, as we can see in the following examples where the mysparksee.cfg file is used to load Sparksee configuration variables:

[Java]
SparkseeProperties.load("sparksee/config/dir/mysparksee.cfg");
SparkseeConfig cfg = new SparkseeConfig();
Sparksee sparksee = new Sparksee(cfg);
Database db = sparksee.create("HelloSparksee.gdb", "HelloSparksee");
[C#]
SparkseeProperties.Load("sparksee/config/dir/mysparksee.cfg");
SparkseeConfig cfg = new SparkseeConfig();
Sparksee sparksee = new Sparksee(cfg);
Database db = sparksee.Create("HelloSparksee.gdb", "HelloSparksee");
[C++]
SparkseeProperties::Load(L"sparksee/config/dir/mysparksee.cfg");
SparkseeConfig cfg;
Sparksee * sparksee = new Sparksee(cfg);
Database * db = sparksee->Create(L"HelloSparksee.gdb", L"HelloSparksee");
[Python]
sparksee.SparkseeProperties.load("sparksee/config/dir/mysparksee.cfg");
cfg = sparksee.SparkseeConfig()
sparks = sparksee.Sparksee(cfg)
db = sparks.create(u"Hellosparksee.gdb", u"HelloSparksee")
[Objective-C]
[STSSparkseeProperties load: @"sparksee/config/dir/mysparksee.cfg"];
STSSparkseeConfig *cfg = [[STSSparkseeConfig alloc] init];
STSSparksee *sparksee = [[STSSparksee alloc] initWithConfig: cfg];
//[cfg release];
STSDatabase *db = [sparksee create: @"HelloSparksee.gdb" alias: @"HelloSparksee"];

Variables

Here is the list of the existing Sparksee configuration variables divided by categories, with an identifier name, a description, the valid format for the value, the default value and the corresponding method to set each variable in the SparkseeConfig class. Please note that the identifier name is the key to be used in the properties file.

Valid formats for the variables values are:

ClientId

LicenseId

License

Log

Details about logging capabilities & value information are given in the ‘Logging’ section of the ‘Maintenance and monitoring’ chapter.

Rollback

Details about the use of transactions in Sparksee are given in the ‘Transactions’ section of the ‘Graph Database’ chapter.

Recovery

Details about the recovery module are given in the ‘Recovery’ section of the ‘Maintenance and monitoring’ chapter.

Storage

Additionally, AES key and IV can be automatically generated with SparkseeConfig#setAESEncryptionEnabled overload that takes the desired size of the key as a parameter. In such a case, the randomly generated key and IV must be retrieved and stored by means of the SparkseeConfig#getAESKey and SparkseeConfig#getAESIV methods, respectively.

Cache

The cache is split into different areas, the most important being for the persistent data whilst the rest are for the running user’s sessions. The size of these areas is automatic, dynamic and adaptive depending on the requirements of each of the parts. Thus, there is constant negotiation between them. Although default values might be the best configuration, the user can adapt them for very specific requirements, taking into account the fact that negotiation between areas only happens when the pool is using memory in the range [minimum, maximum]. Therefore pools are always guaranteed to have at least the minimum memory of the configuration and never be larger than the maximum.

For development and debugging purposes it may be useful to enable the cache statistics. More details about this can be found in the ‘Statistics’ section of the ‘Maintenance and monitoring’ chapter.

SparkseeHA

High availability configuration is explained in detail in the ‘High availability’ chapter.

Basic configuration

In most cases default values are the best option. In fact, non-advanced users should consider setting only the following variables for a basic configuration:

<< Previous    |    Next >>

Back to Index