Methods
cancelAllSubscriptions()
Immediately cancels all active subscriptions.
This endpoint is handy to use when an end-user chooses to end her session
with the web app. E.g. all subscriptions should be cancelled upon user sign-out.
- Source:
command(commandMessagenon-null) → {CommandRequest}
Creates a new command request which allows to post a command to the Spine server and
configures the command handling callbacks.
Parameters:
| Name | Type | Description |
|---|---|---|
commandMessage |
Message | a command to post to the server |
- Source:
Returns:
a new command request
- Type
- CommandRequest
execute(querynon-null) → {Promise.<Array.<Message>>}
Executes the given `Query` instance specifying the data to be retrieved from
Spine server fulfilling a returned promise with an array of received objects.
Parameters:
| Name | Type | Description |
|---|---|---|
query |
spine.client.Query | a query instance to be executed |
- Deprecated:
- Please use Client#read() instead
- Source:
Returns:
a promise to be fulfilled with a list of Protobuf
messages of a given type or with an empty list if no entities matching given query
were found; rejected with a `SpineError` if error occurs;
- Type
- Promise.<Array.<Message>>
newQuery() → {QueryFactory}
Creates a new QueryFactory for creating `Query` instances specifying
the data to be retrieved from Spine server.
- Source:
- See:
Returns:
a factory for creating queries to the Spine server
- Type
- QueryFactory
Examples
// Build a query for `Task` domain entity, specifying particular IDs.
newQuery().select(Task)
.byIds([taskId1, taskId2])
.build()// Build a query for `Task` domain entity, selecting the instances which assigned to the
// particular user.
newQuery().select(Task)
.where([Filters.eq('assignee', userId)])
.build()
To execute the resulting `Query` instance pass it to the Client#execute().
Alternatively, the `QueryRequest` API can be used. See Client#select().newTopic() → {TopicFactory}
Creates a new TopicFactory for building subscription topics specifying
the state changes to be observed from Spine server.
- Source:
- See:
Returns:
a factory for creating subscription topics to the Spine server
- Type
- TopicFactory
Examples
// Build a subscription topic for `UserTasks` domain entity.
newTopic().select(Task)
.build()// Build a subscription topic for `UserTasks` domain entity, selecting the instances
// with over 3 tasks.
newTopic().select(UserTasks)
.where(Filters.gt('tasksCount', 3))
.build()
To turn the resulting `Topic` instance into a subscription pass it
to the Client#subscribe().
Alternatively, the `SubscriptionRequest` API can be used. See Client#subscribeTo(),
Client#subscribeToEvents().post(commandnon-null, onAcknon-null)
Posts a given command to the Spine server.
Parameters:
| Name | Type | Description |
|---|---|---|
command |
spine.core.Command | a Command sent to Spine server |
onAck |
AckCallback | a command acknowledgement callback |
- Source:
read(querynon-null) → {Promise.<Array.<Message>>}
Executes the given `Query` instance specifying the data to be retrieved from
Spine server fulfilling a returned promise with an array of received objects.
Parameters:
| Name | Type | Description |
|---|---|---|
query |
spine.client.Query | a query instance to be executed |
- Source:
Returns:
a promise to be fulfilled with a list of Protobuf
messages of a given type or with an empty list if no entities matching given query
were found; rejected with a `SpineError` if error occurs
- Type
- Promise.<Array.<Message>>
select(entityTypenon-null) → {QueryRequest}
Creates a query request that allows to configure and post a new query.
Parameters:
| Name | Type | Description |
|---|---|---|
entityType |
Class.<Message> | a Protobuf type of the query target entities |
- Source:
Returns:
the builder to construct and post a new query
- Type
- QueryRequest
sendCommand(commandMessagenon-null, acknowledgedCallbacknon-null, errorCallbacknullable, rejectionCallbacknullable)
Sends the provided command to the server.
After sending the command to the server the following scenarios are possible:
- the `acknowledgedCallback` is called if the command is acknowledged for further processing
- the `errorCallback` is called if sending of the command failed
Invocation of the `acknowledgedCallback` and the `errorCallback` are mutually exclusive.
If the command sending fails, the respective error is passed to the `errorCallback`. This error
is always the type of `CommandHandlingError`. Its cause can be retrieved by `getCause()` method
and can be represented with the following types of errors:
- `ConnectionError` – if the connection error occurs;
- `ClientError` – if the server responds with `4xx` HTTP status code;
- `ServerError` – if the server responds with `5xx` HTTP status code;
- `spine.base.Error` – if the command message can't be processed by the server;
- `SpineError` – if parsing of the response fails;
If the command sending fails due to a command validation error, an error passed to the
`errorCallback` is the type of `CommandValidationError` (inherited from
`CommandHandlingError`). The validation error can be retrieved by `validationError()` method.
The occurrence of an error does not guarantee that the command is not accepted by the server
for further processing. To verify this, call the error `assuresCommandNeglected()` method.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
commandMessage |
Message | a Protobuf message representing the command | |
acknowledgedCallback |
parameterlessCallback | a no-argument callback invoked if the command is acknowledged | |
errorCallback |
consumerCallback.<CommandHandlingError> |
<nullable> |
a callback receiving the errors executed if an error occurred when sending command |
rejectionCallback |
consumerCallback.<Rejection> |
<nullable> |
a callback executed if the command is denied processing due to a business rejection |
- Deprecated:
- Please use Client#command()
- Source:
- See:
subscribe(topicnon-null) → {Promise.<EntitySubscriptionObject.<Message>>}
Subscribes to the given `Topic` instance.
The topic should have an entity type as target. Use #subscribeToEvents to subscribe to
the topic that targets events.
Parameters:
| Name | Type | Description |
|---|---|---|
topic |
spine.client.Topic | a topic to subscribe to |
- Source:
Returns:
the subscription object which exposes entity changes via its callbacks
- Type
- Promise.<EntitySubscriptionObject.<Message>>
subscribeTo(entityTypenon-null) → {SubscriptionRequest}
Creates a subscription request that allows to configure and post a new entity subscription.
Parameters:
| Name | Type | Description |
|---|---|---|
entityType |
Class.<Message> | a Protobuf type of the target entities |
- Source:
Returns:
the builder for the new entity subscription
- Type
- SubscriptionRequest
subscribeToEvent(eventTypenon-null) → {EventSubscriptionRequest}
Creates an event subscription request that allows to configure and post a new event
subscription.
Parameters:
| Name | Type | Description |
|---|---|---|
eventType |
Class.<Message> | a Protobuf type of the target events |
- Source:
Returns:
the builder for the new event subscription
subscribeToEvents(topicnon-null) → {Promise.<EventSubscriptionObject>}
Subscribes to the given `Topic` instance.
The given topic should target an event type. To perform an entity subscription, use
#subscribe.
Parameters:
| Name | Type | Description |
|---|---|---|
topic |
spine.client.Topic | a topic to subscribe to |
- Source:
Returns:
- Type
- Promise.<EventSubscriptionObject>