# 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](../datasource/datasource-records.md) containing a currency pair. Liberator object types include all the [DataSource data types](../datasource/datasource-data-types.md), and data types that are additional to [StreamLink](../streamlink/index.md), such as the [Chat](#chat) type. More object-related configuration can be found in [Object configuration (part 2)](liberator-object-configuration-part-2.md), [Throttling](liberator-throttling.md) and [Throttling configuration](liberator-throttling-configuration.md). ## 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](../platform-architecture/putting-data-into-the-platform.md) or [Transformers](../transformer/index.md)) unless a) it’s a [_broadcast_](../datasource/datasource-broadcasting-data.md) object that originates from a peer, or b) it’s a directory object (see [Directories](#directories), below, and [DataSource > Directories](../datasource/datasource-directories.md)), in which case the data for the [subjects](../datasource/datasource-subjects-symbols-and-fields.md) subscribed to under that directory is supplied from the relevant peer(s). **Syntax** ``` add-object xref:discard-timeout[discard-timeout] [integer] xref:disable-generic-throttling[disable-generic-throttling] [boolean] xref:flags[flags] [integer] xref:name[name] [string] xref:no-batching[no-batching] [boolean] xref:only-changed-fields[only-changed-fields] [boolean] xref:purge-age[purge-age] [integer] xref:purge-period[purge-period] [integer] xref:purge-time[purge-time] [integer] xref:record-type3-history-size[record-type3-history-size] [integer] xref:throttle-times[throttle-times] [array of floats] xref:timestamp-field[timestamp-field] [string] xref:type[type] [integer/string] end-object ``` **Options** * **discard-timeout** **Type:** integer | **Default:** _see description below_ 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](../datasource/datasource-data-services-configuration.md#discard-timeout) option of [add-data-service](../datasource/datasource-data-services-configuration.md#add-data-service)). It also overrides the setting of the global item [active-discard-timeout](liberator-object-configuration-part-2.md#active-discard-timeout) for this directory object. The value defaults to the `discard-timeout` for the data service that fetches data for the object. * **disable-generic-throttling** **Type:** boolean | **Default:** _null_ Updates from generic objects are throttled by default from Liberator 7.1.24. To reverse this change in behaviour for a specific namespace, set the option `disable-generic-throttling` to `true` on an object of [type](#type) `directory`. Alternatively, to reverse this change in behaviour for _all_ namespaces, set the global configuration item [object-disable-generic-throttling](liberator-throttling-configuration.md#object-disable-generic-throttling) to `true`. To disable throttling for _all_ objects in a specific namespace, see the option [throttle-times](#throttle-times). To disable throttling for _all_ objects in _all_ namespaces, set the global option [object-throttle-off](liberator-throttling-configuration.md#object-throttle-off) to `true`. * **flags** **Type:** integer | **Default:** `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](#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](#name) is `/A` and [type](#type) is record, an empty record with subject `/A` is created. To specify both flags, use the value `160` (`=32+128`). * **name** **Type:** string | **Default:** _null_ The name of the object. For example, `/B/record1` * **no-batching** **Type:** boolean | **Default:** `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](liberator-bursting-configuration.md#burst-min) and [burst-max](liberator-bursting-configuration.md#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** **Type:** boolean | **Default:** `FALSE` This option applies only to objects of [type](#type) `record` and, from Liberator 6.1.0, [type](#type) `generic`. It can be defined directly on these objects or inherited from the definition of an object of [type](#type) `directory`. **📌 NOTE**\ When objects of [type](#type) `generic` are [throttled](liberator-throttling.md) (supported from Liberator 7.1.24), Liberator always sends only changed fields. Setting `only-changed-fields` to `FALSE` for throttled generic objects has no effect. This option takes a boolean value: * `FALSE` (default): client updates contain all _updated_ fields * `TRUE`: client updates contain only updated fields that have _changed_ in value You only need to consider setting this option if the Integration Adapter that supplies updates for the objects of interest doesn’t itself transmit just the changed fields. Normally you’d implement Adapters so that they only transmit update information about object fields that have changed, so you wouldn’t need to set `only-changed-fields`. Where there are many fields that are infrequently updated, the size of the messages transferred to clients is reduced. However, this feature might require increased server resources and might not be suitable when the majority of fields are frequently updated. **add-object for a record** 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 ``` **add-object for a directory** 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** **Type:** integer | **Default:** `0` This option applies only to objects of [type](#type) `directory`. How old in minutes objects in the directory need to be before they can be removed from Liberator’s cache. Every [purge-period](#purge-period) minutes past [purge-time](#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](#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](liberator-control-when-liberator-purges-its-object-cache.md). * **purge-period** **Type:** integer | **Default:** `1440` This option applies only to objects of [type](#type) `directory`. How often in minutes, relative to [purge-time](#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](#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](liberator-control-when-liberator-purges-its-object-cache.md). * **purge-time** **Type:** integer | **Default:** `-1` This option applies only to objects of [type](#type) `directory`. 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 number of minutes past midnight on a Sunday. Set `purge-time` to `-1` to never purge the directory on a timed basis, so [purge-age](#purge-age) and [purge-period](#purge-period) are ignored. At `purge-time`, and subsequently every [purge-period](#purge-period) minutes past `purge-time`, Liberator checks its cache and deletes any objects in the directory that are older than [purge-age](#purge-age) and have no clients subscribed to them. Use this option in conjunction with [purge-period](#purge-period) and optionally [purge-age](#purge-age), to purge directories at regular intervals. For more about this, see How can I... [Control when Liberator purges its object cache](liberator-control-when-liberator-purges-its-object-cache.md). * **record-type3-history-size** **Type:** integer | **Default:** _value of [record-type3-history-size](liberator-object-configuration-part-2.md#record-type3-history-size)_ This option applies only to objects of [type](#type) `record` containing [type 3](../datasource/datasource-type-3-data.md) data. This option only applies to record objects containing [type 3 data](../datasource/datasource-type-3-data.md) (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](liberator-object-configuration-part-2.md#record-type3-history-size). * **throttle-times** **Type:** array of floats and strings | **Default:** _value of [object-throttle-times](liberator-throttling-configuration.md#object-throttle-times)_ This option applies only to objects of [type](#type) `record` and `generic`. It can be defined directly on these objects or inherited from the definition of an object of [type](#type) `directory`. This option overrides the value of global item [object-throttle-times](liberator-throttling-configuration.md#object-throttle-times). This configuration item is overridden by [add-data-service::throttle-time](../datasource/datasource-data-services-configuration.md#throttle-time) (Liberator 8), and [add-provided-data-service::throttle-time](../datasource/datasource-data-services-configuration.md#throttle-time-2) (DataSource 8). A space-separated array of throttle times (seconds), followed by an optional "stopped" or "paused": ```+attributes" throttle-times _time_ ... [stopped|paused] ``` ...where _time_ is a floating point number or 0. Specifying multiple times in the array allows client applications to choose the throttle time most suited to their network bandwidth and use case. This is called 'levelling', and the initial level for clients is set by the global item [object-throttle-default-level](liberator-throttling-configuration.md#object-throttle-default-level). Updates from generic objects are throttled from Liberator 7.1.24. Generic objects do not support 'levelling', and throttled updates from generic objects only use the first value in the `throttle-times` array. To disable update throttling for this object, set `throttle-times` to `0`. To disable throttling for all subjects, see [object-throttle-off](liberator-throttling-configuration.md#object-throttle-off). * **timestamp-field** **Type:** string | **Default:** _null_ The name of a field into which Liberator adds a 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](../datasource/datasource-latency-chains-configuration.md), and it isn’t controlled by the setting of the [latency-chain-enable](../datasource/datasource-latency-chains-configuration.md#latency-chain-enable) configuration item. This option overrides the global [timestamp-field](liberator-latency-configuration.md#timestamp-field) configuration item for this object only. For information on timestamp precision, see the documentation for the global [timestamp-field](liberator-latency-configuration.md#timestamp-field) configuration item. * **type** **Type:** string or integer | **Default:** _null_ 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](#object-types-and-object-numbers) below. Examples: * `type record` * `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](#type) option of [add-object](#add-object): | Object type name | Object type number | Description | | --- | --- | --- | | chat | 27 | [Chat](../streamlink/streamlink-streamlink-data-types.md) object | | container | 28 | [Container](../datasource/datasource-containers.md) object | | directory | 20 | [Directory](../datasource/datasource-directories.md) object | | generic | 31 | [Generic](../datasource/datasource-generic-data.md) object | | json^1^ | 32^2^ | [JSON](../datasource/datasource-json-data.md) data | | list^3^ | 33^3^ | [List](../datasource/datasource-list.md) data | | binary^4^ | 34^4^ | [Binary](../datasource/datasource-binary.md) data | | news | 23 | [News headline](../datasource/datasource-news-headlines-and-news-stories.md) object | | page | 21 | [Page](../datasource/datasource-pages.md) object | | permission | 30 | [Permission](../datasource/datasource-permissions.md) object | | record | 22 | [Record](../datasource/datasource-records.md) object | | story | 24 | [News story](../datasource/datasource-news-headlines-and-news-stories.md) object | #1. JSON object type name available from Liberator 7.1.25#\ #2. JSON object type number available from Liberator 7.1.8#\ #3. List object type name and number available from Liberator 8.0.5#\ #4. Binary object type name and number available from Liberator 8.0.15# + ## Directories Use `add-object` to configure a [directory](../datasource/datasource-directories.md) with specific characteristics. For example, to create a directory called `/TRADE`, define an `add-object` entry with the [name](#name) option set to `/TRADE` and the [type](#type) option set to `directory`, and with the other options set as required. Then define a [data service](../datasource/datasource-data-services.md) with an [include-pattern](../datasource/datasource-data-services-configuration.md#include-pattern) of `^/TRADE` (see [add-data-service](../datasource/datasource-data-services-configuration.md#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](../datasource/datasource-directories.md), all objects that are subsequently subscribed to under that directory inherit the configuration options that were defined in the `add-object` for the directory. --- **See also:** * Reference: [Object configuration (part 2)](liberator-object-configuration-part-2.md) * How can I... [Control when Liberator purges its object cache.](liberator-control-when-liberator-purges-its-object-cache.md) * [DataSource > Directories](../datasource/datasource-directories.md)