io.spine.client

Class CommandRequest

java.lang.Object

io.spine.client.ClientRequest

io.spine.client.CommandRequest

All Implemented Interfaces:

io.spine.logging.Logging

public final class CommandRequest
extends ClientRequest
implements io.spine.logging.Logging

Allows to post a command optionally subscribing to events that are immediate results of handling this command.

Usage example:

 Subscription loginSubscription =
     client.asGuest()
           .command(logInUser)
           .observe(UserLoggedIn.class, (event, context) -> { ... })
           .observe(UserAlreadyLoggedIn.class, (rejection, context) -> { ... })
           .onStreamingError((throwable) -> { ... })
           .post();
 

The subscription obtained from the CommandRequest.post() should be cancelled to preserve both client-side and server-side resources. The moment of cancelling the subscriptions depends on the nature of the posted command and the outcome expected by the client application.

Method Summary

Modifier and Type	Method and Description
<E extends io.spine.base.EventMessage> CommandRequest	observe(java.lang.Class<E> type, java.util.function.Consumer<E> consumer) Adds the passed consumer to the subscribers of the event of the passed type.
<E extends io.spine.base.EventMessage> CommandRequest	observe(java.lang.Class<E> type, EventConsumer<E> consumer) Adds the passed event consumer to the subscribers of the event of the passed type.
CommandRequest	onConsumingError(ConsumerErrorHandler<io.spine.base.EventMessage> handler) Assigns a handler for errors occurred in consumers of events.
CommandRequest	onServerError(ServerErrorHandler handler) Assigns a handler for an error occurred on the server-side (such as validation error) in response to posting a command.
CommandRequest	onStreamingError(ErrorHandler handler) Assigns a handler for errors occurred when delivering events.
com.google.common.collect.ImmutableSet<io.spine.client.Subscription>	post() Subscribes the consumers to events to receive events resulting from the command as they happen, then sends the command to the server.
void	postAndForget() Posts the command without subscribing to events that may be generated during the command handling.

Methods inherited from class io.spine.client.ClientRequest

client, command, select, subscribeTo, subscribeToEvent, user

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface io.spine.logging.Logging

_config, _debug, _error, _fine, _finer, _finest, _info, _severe, _trace, _warn, debugLevel, errorLevel, logger, loggerFor

Method Detail

observe

@CanIgnoreReturnValue
public <E extends io.spine.base.EventMessage> CommandRequest observe(java.lang.Class<E> type,
                                                                                           java.util.function.Consumer<E> consumer)

Adds the passed consumer to the subscribers of the event of the passed type.

Type Parameters:

E - the type of the event

Parameters:

type - the type of the event message to be received by the consumer

consumer - the consumer

observe

@CanIgnoreReturnValue
public <E extends io.spine.base.EventMessage> CommandRequest observe(java.lang.Class<E> type,
                                                                                           EventConsumer<E> consumer)

Adds the passed event consumer to the subscribers of the event of the passed type.

Type Parameters:

E - the type of the event

Parameters:

type - the type of the event message to be received by the consumer

consumer - the consumer of the event message and its context

onStreamingError

@CanIgnoreReturnValue
public CommandRequest onStreamingError(ErrorHandler handler)

Assigns a handler for errors occurred when delivering events.

If such an error occurs, no more events resulting from the posted command will be delivered to the consumers.

Overrides:

onStreamingError in class ClientRequest

onConsumingError

@CanIgnoreReturnValue
public CommandRequest onConsumingError(ConsumerErrorHandler<io.spine.base.EventMessage> handler)

Assigns a handler for errors occurred in consumers of events.

After the passed handler is called, remaining event consumers will get the messages as usually. If not specified, the default implementation simply logs the error.

onServerError

@OverridingMethodsMustInvokeSuper
 @CanIgnoreReturnValue
public CommandRequest onServerError(ServerErrorHandler handler)

Assigns a handler for an error occurred on the server-side (such as validation error) in response to posting a command.

Overrides:

onServerError in class ClientRequest

post

public com.google.common.collect.ImmutableSet<io.spine.client.Subscription> post()

Subscribes the consumers to events to receive events resulting from the command as they happen, then sends the command to the server.

The returned Subscription instances should be canceled after the requesting code receives expected events, or after a reasonable timeout.

The method returns subscriptions to events that the handling of the command may produce. A command may not be accepted for processing by the server, e.g. because of a validation error. In such a case, the method would report the error to the configured error handler, and return an empty set.

Returns:

subscription to the observed events if the command was successfully posted, or an empty set if posting caused an error

See Also:

CommandRequest.postAndForget()

API Note:

Subscriptions should be cancelled to free up client and server resources required for their maintenance. It is not possible to cancel the returned subscription in an automatic way because of the following. Subscriptions by nature are asynchronous and infinite requests. Even that we know expected types of the events produced by the command, only the client code "knows" how many of them it expects. Also, some events may not arrive because of communication or business logic reasons. That's why the returned subscriptions should be cancelled by the client code when it no longer needs it.

postAndForget

public void postAndForget()
                   throws java.lang.IllegalStateException

Posts the command without subscribing to events that may be generated during the command handling.

Throws:

java.lang.IllegalStateException - if CommandRequest.observe(Class, EventConsumer) or CommandRequest.observe(Class, Consumer) were called in the command request configuration chain before calling this method

See Also:

CommandRequest.post()