Interface: ServerlessDb

ServerlessDb

Exposes the functions and constants of the Webcom ServerlessDb service. This service is configured by the ServerlessDb property passed to the configuration of the associated WebcomApp.

This service provides a real time interface to a Webcom database. Under the hood, it works using a websocket between the client and the Webcom back end.

Instances of this interface are provided by the WebcomApp#serverlessDb property.

Since:
  • 2.11 (moved from DatasyncService since 3.0)

Extends

Classes

Callback
Constraint
DataSnapshot
EventDescriptor
LongTermSubscription
Webhook

Interfaces

LongTermSubscriptionService
ServerlessDbNode
Subscription

Members

(static, constant) FORGET :number

Cache-control policy that removes (forgets) the data watched by a canceled subscription from the local cache.

It may be passed to Webcom.Callback or returned by a ServerlessDb.CancelationCallback.
It is available through the FORGET property of the Webcom.ServerlessDb property.

Type:
  • number

(static, constant) KEEP :number

Cache-control policy that keeps a copy of the data watched by a canceled subscription within the local cache.

It may be passed to Webcom.Callback or returned by a ServerlessDb.CancelationCallback.
It is available through the KEEP property of the Webcom.ServerlessDb property.

Type:
  • number

(static, constant) KEEP_UPDATING :number

Cache-control policy that keeps the data watched by a canceled subscription within the local cache and keeps updating them, even if the corresponding data node is no longer explicitly watched.

It may be passed to Webcom.Callback or returned by a ServerlessDb.CancelationCallback.
It is available through the KEEP_UPDATING property of the Webcom.ServerlessDb property.

Type:
  • number

(static, constant) NEXT_DISCONNECTION :number

Write policy consisting in deferring writing data until the next disconnection (intentional or accidental) from the ServerlessDb when invoked by ServerlessDb.ServerlessDbNode#clear, ServerlessDb.ServerlessDbNode#set or ServerlessDb.ServerlessDbNode#merge methods.
It is available through the NEXT_DISCONNECTION property of the Webcom.ServerlessDb property.

Type:
  • number

(static, constant) NOW :number

Write policy consisting in writing data immediately when invoked by ServerlessDb.ServerlessDbNode#clear, ServerlessDb.ServerlessDbNode#set or ServerlessDb.ServerlessDbNode#merge methods.
It is available through the NOW property of the Webcom.ServerlessDb property.

Type:
  • number

(static, constant) ON_DISCONNECTION :number

Write policy consisting in writing data recurrently at each disconnection (intentional or accidental) from the ServerlessDb when invoked by ServerlessDb.ServerlessDbNode#clear, ServerlessDb.ServerlessDbNode#set or ServerlessDb.ServerlessDbNode#merge methods.
By difference with NEXT_DISCONNECTION the request(s) executed with ON_DISCONNECTION policy will be replayed at each disconnection. Unlike NEXT_DISCONNECTION, the ON_DISCONNECTION policy will replay the requests at each disconnection. The only way to stop such scheduled operations is to explicitly invoke the ServerlessDb.ServerlessDbNode#cancelNextDisconnectionOps method.

Type:
  • number
Since:
  • 3.3

(protected) _ltsAuth :Authentication.State

Internal authentication state associated with ongoing ServerlessDb.LongTermSubscriptions.

Type:
Inherited From:

(readonly) currentState :ServerlessDb.State

The current state of the real-time connection to the Webcom back end managed by this instance of ServerlessDb. This property returns the same value as the virtual data node at the special ".info" path.

Type:

(readonly) offlineData :string

Returns the currently available data in the local cache, encoded into a string. It is intended to be saved somewhere by the client before shutting down the application, and then provided back to the application at start, through the "offlineData" property of the ServerlessDb.Configuration passed to the WebcomApp constructor.

Type:
  • string

rootNode :ServerlessDb.ServerlessDbNode

Get the root data node managed by this ServerlessDb.

Type:
Since:
  • 3.0

(readonly) shouldBeConnected :boolean

Returns the current expected connection state to the Webcom back end managed by this ServerlessDb instance:

  • true means it should be connected, however it may not be the case if the device network connectivity is down. The actual connection state is given by the connection.connected property of the ServerlessDb#currentState member.
  • false means it should be disconnected. The value of this property is driven by calls to the ServerlessDb#connect and ServerlessDb#disconnect methods.
Type:
  • boolean

Methods

cleanLongTermSubscriptions()

Clears all the ongoing long term subscriptions associated with the current authenticated user from the client local storage.

This method requires a user to be authenticated.

WARNING: this method doesn't cancel the subscriptions!
It only removes them from the local storage, so that the ServerlessDb#getLongTermSubscriptions method can no longer retrieve them. Use ServerlessDb.ServerlessDbNode#unsubscribe or ServerlessDbLite.ServerlessDbLiteNode#unsubscribe to actually cancel them (otherwise they may still persist in the Webcom back end).

Inherited From:

cleanOfflineData()

Removes from the local cache all data that don't result from a currently ongoing subscription.

This means that all data preserved until now, which results from past subscriptions with a ServerlessDb.KEEP or ServerlessDb.ServerlessDbNode#KEEP_UPDATING policy, are lost and will no longer be available offline.

connect()

Forces the establishment of the real-time connection to the Webcom back end managed by this ServerlessDb instance and enables the retry connection feature.

If the device has network connectivity, calling this method should end in switching the connection.connected property of ServerlessDb#currentState to true. However, this property will remain false as long as the network or the Webcom back end is unavailable.

disconnect()

Forces the interruption of the real-time connection to the Webcom back end managed by this ServerlessDb instance and disables the retry connection feature. The connection will not be reestablished until ServerlessDb#connect is called.

generateUniqueKey() → {string}

Returns a unique key (which can typically be used to get a relativeNode of a ServerlessDb.ServerlessDbNode).

The generated key is guaranteed to be lexicographically ordered after any previously generated key (even on another client device) and can be used to store sub-nodes from several clients at a time.

The timestamp when the returned key has been generated may be further retrieved using the ServerlessDb.ServerlessDbNode#timestamp property on a ServerlessDb.ServerlessDbNode with this key.

See:
Returns:
Type
string

getLongTermSubscriptions() → {Array.<ServerlessDb.LongTermSubscription>}

Retrieves the list of the ongoing long term subscriptions associated with the current authenticated user, which are stored in the client local storage.

Such subscriptions are stored when invoking the ServerlessDb.ServerlessDbNode#subscribe method with a ServerlessDb.Webhook or the ServerlessDbLite.ServerlessDbLiteNode#subscribe method.

This method requires a user to be authenticated.

Inherited From:
Returns:
Type
Array.<ServerlessDb.LongTermSubscription>

persist() → {boolean}

Persists the content of the local cache. It actually stores the value returned by ServerlessDb#offlineData into the local storage.

Note: if the persist option of this ServerlessDb instance is not set to true or the running client is not a regular browser, this method has no effect.

Returns:

true if the local cache could be persisted, or false otherwise.

Type
boolean

Type Definitions

API

Constants and static methods associated to the ServerlessDb service.

Such an object is available through the Webcom.ServerlessDb property.

Properties:
Name Type Description
FORGET ServerlessDb.FORGET

Cache-control policy that removes (forgets) the data watched by a canceled subscription from the local cache.
KEEP ServerlessDb.KEEP

Cache-control policy that keeps a copy of the data watched by a canceled subscription within the local cache.
KEEP_UPDATING ServerlessDb.KEEP_UPDATING

Cache-control policy that keeps the data watched within the local cache and keeps updating them.
NOW ServerlessDb.NOW

Write policy consisting in writing data immediately.
NEXT_DISCONNECTION ServerlessDb.NEXT_DISCONNECTION

Write policy consisting in deferring writing data until the next disconnection.
ON_DISCONNECTION ServerlessDb.ON_DISCONNECTION

Write policy consisting in writing data recurrently at each disconnection.
ServerValue Object

Dictionary of special objects intended to be replaced by a value computed by the Webcom back end when written into a ServerlessDb.ServerlessDbNode:

Properties
Name Type Description
TIMESTAMP Object

Gives a value that will be replaced with the actual timestamp of the Webcom back end.
Event ServerlessDb.EventDescriptor

Convenient link to the EventDescriptor class. This property is intended to access the ServerlessDb.EventDescriptor.ValueChange and ServerlessDb.EventDescriptor.Child static members to build instances of this class.
Callback ServerlessDb.Callback.Factory

Function that creates an instance of ServerlessDb.Callback notification channel, which is intended to be registered with the ServerlessDb.ServerlessDbNode#subscribe method and to receive notifications of data changes in real time (through the ServerlessDb websocket).
Constraint ServerlessDb.Constraint

Convenient link to the Constraint class. This property is intended to access the static members None, First, Last, StartAt, EndAt and Between to build instances of this class.
Since:
  • 3.5

CancelationCallback(reasonnullable) → {ServerlessDb.FORGET|ServerlessDb.KEEP|ServerlessDb.KEEP_UPDATING}

Callback function called to notify that a subscription (previously started using the ServerlessDb.ServerlessDbNode#subscribe method) is canceled, that is, either explicitly aborted by the app, or revoked by the Webcom back end.

Parameters:
Name Type Attributes Description
reason Error <nullable>

The reason why the subscription is canceled: either null for an explicit abortion or an Error for a revocation (which contains the reason of the revocation).
See:
Returns:

The cache-control policy to apply to the data hold by the canceled subscription. If the callback returns nothing (undefined), then the default cache-control policy setup when the subscription was started is applied.

Type
ServerlessDb.FORGET | ServerlessDb.KEEP | ServerlessDb.KEEP_UPDATING

Configuration

Properties:
Name Type Attributes Default Description
baseUrl URL | string <optional>

Since 3.0
Base URL for a ServerlessDb.
If not set, the Webcom standard one is used.
offlineData string | Object <optional>

Initial value of the local cache. If not set, either persist is true and the last persisted data is used as initial local cache, or persist is false and an empty local cache is used.
persist boolean <optional>
 false

Indicates whether the local cache content can be persisted using the ServerlessDb#persist method. When true, the local cache content is also restored from the client local storage at startup.
Cannot be true for non-browser clients.
connect boolean <optional>
 true

Indicates whether the real-time connection to the Webcom back end should be established at startup. If false, then the application starts working offline.
completeSubscriptionOnCancelation boolean <optional>
 true

Since 2.14.1
Indicates whether the completeCallback of callback subscriptions must be called (with null) when they are explicitly aborted by the app (by calling the ServerlessDb.ServerlessDbNode#unsubscribe method).
websocket Object <optional>

Specifies the options that control the establishment of the real-time connection to the Webcom back end (advanced use only):

Properties
Name Type Attributes Default Description
protocol number <optional>
 5

Version of the protocol to use. Available versions are 5 or 6.
keepAliveDelayMs number <optional>
 45000

Maximum delay (expressed in milliseconds) between issuing of 2 consecutive messages to the back end. The range of allowed values is between 30 seconds and 5 minutes.
pongDelayMs number <optional>
 5000

Maximum delay (expressed in milliseconds) to receive acknowledgement of ping messages from the back end.
statPeriodMs number <optional>
 300_000

Period (in milliseconds) which usage statistics are sent to the Webcom back end with.
Since:
  • 2.11

State

Represents the current state of a ServerlessDb instance. It can be retrieved by either getting the ServerlessDb#currentState property or watching the ".info" virtual data node (using the ServerlessDb.ServerlessDbNode#subscribe method).

Properties:
Name Type Attributes Description
reachable boolean <optional>

Indicates whether the hosting device has network connectivity, independently of the establishment of the real-time connection to the Webcom back end.
connected boolean

Deprecated
Use the connection.connected property instead.
serverTimeOffset number <optional>

Deprecated
Use the connection.serverTimeOffsetMs property instead.
connection Object

Gives some information about the real-time connection to the Webcom back end:

Properties
Name Type Attributes Description
connected boolean

Indicates whether the connection is successfully established and available. Typically, this property switches to false when going offline.
serverTimeOffsetMs number <optional>

As soon as the real-time connection is established, indicates the number of milliseconds between the Webcom back end time and the device time (not including the network delay between them) such that: serverTime = deviceTime + offset.
The number may be positive (device time is earlier than back end time) or negative (device time is later than back end time).
authenticated boolean

Deprecated
Use the authentication.state property instead.
true if and only if authentication reports an authenticated state (as stated by the Authentication.State#isAuthenticated method).
authentication Authentication.State

Reports the authentication state validated on the real-time connection to the Webcom back end. This property may be slightly delayed wrt. Authentication#currentState when authenticating or slightly early when the authentication token is revoked by the back end.
Since:
  • 2.11

SubscriptionCallback(snapshot, precedingChildKeyopt, nullable)

Callback function called to notify that an event, which has been subscribed using the ServerlessDb.ServerlessDbNode#subscribe method, has just been raised.

Parameters:
Name Type Attributes Description
snapshot ServerlessDb.DataSnapshot

The data associated with the raised event.
precedingChildKey string <optional>
<nullable>

When subscribed to child-related events (see ServerlessDb.EventDescriptor.Child), this parameter gives the key of the child node that precedes the one the raised event relates to. It is null if the child node that raised the event is the first one.
When not subscribed to child-related events, this parameter is not valued.
show
deprecated