Object configuration (part 1)

These Liberator configuration items define how Liberator deals with objects.

A Liberator object is a piece of data that Liberator manages on behalf of client applications; for example, a financial instrument such as a DataSource record containing a currency pair. Liberator object types include all the DataSource data types, and data types that are additional to StreamLink, such as the Chat type.

Here's a list of all the object-related configuration items; to get more detail, just click on the item you're interested in. The starred items (*) are documented on the page Object configuration (part 2).

The following object configuration items are about throttling and are detailed in Throttling configuration:

add-object

add-object adds an object name to Liberator and defines the object’s characteristics. The object is local to Liberator, which means it's created in Liberator's cache. It isn't updated from any DataSource peers (Integration Adapters or Transformers) unless a) it's a broadcast object that originates from a peer, or b) it's a directory object (see below), in which case the data for the subjects subscribed to under that directory is supplied from the relevant peer(s).

Directories

Use add-object to configure a directory with specific characteristics. For example, to create a directory called /TRADE, define an add-object entry with the name option set to /TRADE and the type option set to directory, and with the other options set as required. Then define a data service with an include-pattern of ^/TRADE (see add-data-service). When Liberator users subscribe to /TRADE they'll receive objects, under the directory /TRADE, that a DataSource peer configured for the data service has sent to the Liberator, such as records with the subjects /TRADE/ABC, /TRADE/DEF, and so on.

If an object is defined as a directory, all objects that are subsequently subscribed to under that directory inherit the configuration options that were defined in the add-object for the directory.

Syntax:

(Click on an option to see its description in the table below.)

add-object
   name            [string]
   type            [integer/string]
   discard-timeout [integer]
   flags           [integer]
   no-batching     [boolean]
   only-changed-fields [boolean]
   purge-age       [integer]
   purge-period    [integer]
   purge-time      [integer]
   record-type3-history-size [integer]
   throttle-times  [array of floats]
   timestamp-field [string]
end-object

The options for add-object are:

Name Type Default Description
discard-timeout integer [See Description]

The time in seconds for which the Liberator holds on to an object in the directory after the last user stops viewing it. After this time, the object is deleted from the Liberator’s cache and Liberator sends a discard instruction to the supplying DataSource peer to cancel the subscription to the object. 

This option overrides any settings of the discard-timeout for the data service that fetches data for the object (see the discard-timeout option of add-data-service). It also overrides the setting of the global item active-discard-timeout for this directory object.

The value defaults to the discard-timeout for the data service that fetches data for the object.

flags integer 32

Flags specifying additional characteristics for the object when it is created.

Valid values are:

  • 32 - Create the object's parent directories as well as the target object.
    For example, if name is /A/B/C, create the parent directories A and B as well as C. This is the default flags setting and it can't be disabled.
  • 128 - Create empty data for the object type. For example, if name is /A and type is record, an empty record with subject /A is created.

To specify both flags, use the value 160 (=32+128).

name string [none] The name of the object. For example, /B/record1
no-batching boolean FALSE

When TRUE, updates to objects that match the name option are not batched.

Normally, when an update to a matching object is received, the update message is added to the queue of batched messages, and all messages in the queue are immediately sent to the client. The no-batching option overrides the burst-min and burst-max configuration settings. 

Warning! Set this item to TRUE for objects that define the subjects of trade messages, since trade messages should be propagated to clients with minimum possible latency and so must never be batched.
For example, if the name option of add-object is set to /TRADE, (thus specifying the subject that identifies trade messages), updates to objects that start with /TRADE/ are immediately sent to the client.

only-changed-fields boolean FALSE

This option only applies to record-based data or directories containing record-based data.

You only need to consider setting this option if the Integration Adapter that supplies updates for the records of interest doesn't itself transmit just the changed fields. Normally you'd implement Adapters so that they only transmit update information about record fields that have changed, so you wouldn't need to set only-changed-fields.

When TRUE, only the fields of the object that have changed since the previous update are forwarded to the client. Liberator compares each update received from its DataSource peers with the previous update for the subject.  If any of the fields are the same as previously received, those fields are not sent out to the client. If no fields have changed in an update, no message is sent to the client. 

Where there are many fields that are infrequently updated, the size of the message transferred to client is reduced. However, this feature might require increased server resources and might not be suitable when the majority of fields are frequently updated.

Examples:

1) This setting applies to a single record, whose subject is /B/Record1:

add-object

   name                /B/Record1
   type                record
   only-changed-fields TRUE
end-object

2) This setting applies to all the records under a single directory called /Dir1:

add-object 
   name                /Dir1
   type                directory 
   only-changed-fields TRUE
end-object

purge-age integer 0

This option only applies to directory objects.

How old in minutes objects in the directory need to be before they can be removed from Liberator's cache. Every purge-period minutes past purge-time, Liberator checks its cache to see which of the directory's objects can be deleted.

When purge-age is not zero, objects in the directory that have not been updated for purge-period x purge-age minutes are purged (provided no clients are subscribed to them).

When purge-age is zero, all objects in the directory that have no clients subscribed to them are purged, regardless of when they were last updated.

For more about purging directories, see How can I... Control when Liberator purges its object cache.

purge-period integer 1440
(= 24 hours)

This option only applies to directory objects.

How often in minutes, relative to purge-time, objects in the directory are removed from Liberator's cache. Every purge-period minutes past purge-time, Liberator checks its cache and deletes any objects in the directory that are older than purge-age and also have no clients subscribed to them. 

For more about purging directories, see How can I... Control when Liberator purges its object cache.

purge-time integer -1
(meaning never  purge the directory on a timed basis, so purge-age and purge-period are ignored)

This option only applies to directory objects.

The time when the Liberator is to start purging the objects in the directory by deleting them from its cache. This time is the number of minutes after midnight (local time) on the day the Liberator was started, or if the time's greater than or equal to 1440 (24 hours), it's the the number of minutes past midnight on a Sunday.

At purge-time, and subsequently every purge-period minutes past purge-time, Liberator checks its cache and deletes any objects in the directory that are older than purge-age and have no clients subscribed to them.

Use this option in conjunction with purge-period and optionally purge-age, to purge directories at regular intervals. For more about this, see How can I... Control when Liberator purges its object cache.

record-type3-history-size integer Value of 
record-type3-history-size

This option only applies to record objects containing type 3 data (the history of updates to the record).

Maximum number of type 3 data updates to keep for this object / object hierarchy.
This option overrides (for this object or object hierarchy only) the setting of
record-type3-history-size.

throttle-times

array of floats and strings

Value of object-throttle-times

An array of throttle times in seconds that apply to the object defined by this add-object entry. If the object specifies a hierarchy of child objects (for example, it's a directory object), the throttle times apply to the children as well. To learn more about Liberator's throttling feature, see Throttling.

Note: Although this option can accept multiple throttle times, more than one throttle time is rarely required.

This option overrides the default object throttle time configured by object-throttle-times. The default object throttling time is 1.0 second. To turn off object throttling by default, set object-throttle-off to TRUE.

Valid values:

  • positive decimal numbers
  • 0
  • stopped
  • paused

​The array must be in ascending order of throttle times. If you use stopped or paused, it must be the last entry in the array.  Setting the level to stopped or paused means that clients are allowed to pause the object, therefore receiving no updates until it's unpaused.

Example use:

throttle-times 0.25

timestamp-field string No timestamp field is defined for this object

The name of a field into which Liberator adds a millisecond timestamp to this object for the purposes of latency measurement. The timestamp allows a client application to calculate the time taken for the record represented by the object to be transmitted to it from this Liberator.

Liberator only adds the timestamp-field, and the timestamp within it, if the object doesn't already contain a field of that name.

This timestamping facility is independent of, the latency chain timestamps, and it isn't controlled by the setting of the latency-chain-enable configuration item.

This option overrides the global timestamp-field configuration item for this object only.

type string or integer [none]

The object type, as either the object type name or the object type number.

For the list of valid values, see Object types and object numbers below.

Examples:
type record
or
type 22

Object types and object numbers

Here's the list of valid object type names, and their corresponding object numbers, that can be specified in the type option of add-object:

Object type name Object type number Description For more information, See:
chat 27 Chat object StreamLink Chat data type
container 28 Container object DataSource Containers
directory 20 Directory object DataSource Directories
news 23 News headline object DataSource News headlines and news stories
page 21 Page object DataSource Pages
permission 30 Permission object DataSource Permissions
record 22 Record object DataSource Records
story 24 News story object DataSource News headlines and news stories

See also: