io.spine.client

Class Client

java.lang.Object

io.spine.client.Client

All Implemented Interfaces:

java.lang.AutoCloseable

public class Client
extends java.lang.Object
implements java.lang.AutoCloseable

The gRPC-based gateway for backend services such as CommandService, QueryService, or SubscriptionService.

A connection can be established via host/port combination, or via already available ManagedChannel.

Multitenant applications need to specify TenantId for a new client connection. Single-tenant applications do nothing about it.

Client requests can be created on behalf of a guest user, if the user is not yet authenticated, and on behalf of the current user after the user is authenticated.

Please note that Spine client-side library does not define the authentication process. The Client class simply relies on the fact that UserId passed to the method Client.onBehalfOf(UserId) represents a valid logged-in user, ID of whom the client application got (presumably as field of a UserLoggedIn event) following due authentication process. The server-side code also needs to make sure that the UserId matches security constraints of the backend services. Security arrangements is not a part of the Spine client-side library either.

Subscriptions to entity states or events must be cancelled when no longer needed to preserve both client-side and backend resources.

The client connection must be closed when the application finishes its work.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Client.Builder The builder for the client.

Field Summary

Fields

Modifier and Type	Field and Description
static io.spine.core.UserId	DEFAULT_GUEST_ID Default ID for a guest user.
static io.spine.client.Timeout	DEFAULT_SHUTDOWN_TIMEOUT The default amount of time to wait when closing the client.

Method Summary

Modifier and Type	Method and Description
ClientRequest	asGuest() Creates a builder for posting guest requests.
void	cancel(io.spine.client.Subscription s) Deprecated. please call Subscriptions.cancel(Subscription)
void	close() Closes the client by shutting down the gRPC connection.
static Client.Builder	connectTo(java.lang.String host, int port) Creates a builder for a client connected to the specified address.
static Client.Builder	inProcess(java.lang.String serverName) Creates a client which will be connected to the in-process server with the passed name.
boolean	isOpen() Verifies if the client connection is open.
ClientRequest	onBehalfOf(io.spine.core.UserId user) Creates a builder for requests on behalf of the passed user.
void	shutdown() Same as Client.close().
Subscriptions	subscriptions() Obtains subscriptions created by this client.
java.util.Optional<io.spine.core.TenantId>	tenant() Obtains the tenant of this client connection in a multitenant application, and empty Optional in a single-tenant one.
static Client.Builder	usingChannel(io.grpc.ManagedChannel channel) Creates a builder for a client which will use the passed channel for the communication with the backend services.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_SHUTDOWN_TIMEOUT

public static final io.spine.client.Timeout DEFAULT_SHUTDOWN_TIMEOUT

The default amount of time to wait when closing the client.

DEFAULT_GUEST_ID

public static final io.spine.core.UserId DEFAULT_GUEST_ID

Default ID for a guest user.

Method Detail

connectTo

public static Client.Builder connectTo(java.lang.String host,
                                       int port)

Creates a builder for a client connected to the specified address.

The returned builder will create ManagedChannel with the default configuration. For a channel with custom configuration please use Client.usingChannel(ManagedChannel).

See Also:

Client.usingChannel(ManagedChannel), Client.inProcess(String)

usingChannel

public static Client.Builder usingChannel(io.grpc.ManagedChannel channel)

Creates a builder for a client which will use the passed channel for the communication with the backend services.

Use this method when a channel with custom configuration is needed for your client application.

See Also:

Client.connectTo(String, int), Client.inProcess(String), ManagedChannel

inProcess

public static Client.Builder inProcess(java.lang.String serverName)

Creates a client which will be connected to the in-process server with the passed name.

The client is fully-featured, high performance, and is useful in testing.

See Also:

Client.connectTo(String, int), Client.usingChannel(ManagedChannel)

tenant

public java.util.Optional<io.spine.core.TenantId> tenant()

Obtains the tenant of this client connection in a multitenant application, and empty Optional in a single-tenant one.

See Also:

Client.Builder.forTenant(TenantId)

close

public void close()

Closes the client by shutting down the gRPC connection.

Subscriptions created by this client which were not cancelled directly will be cancelled.

Specified by:

close in interface java.lang.AutoCloseable

See Also:

Client.isOpen()

shutdown

public void shutdown()

Same as Client.close().

isOpen

public boolean isOpen()

Verifies if the client connection is open.

See Also:

Client.close()

onBehalfOf

public ClientRequest onBehalfOf(io.spine.core.UserId user)

Creates a builder for requests on behalf of the passed user.

See Also:

Client.asGuest()

asGuest

public ClientRequest asGuest()

Creates a builder for posting guest requests.

See Also:

Client.onBehalfOf(UserId)

cancel

@Deprecated
public void cancel(io.spine.client.Subscription s)

Deprecated. please call Subscriptions.cancel(Subscription)

Requests cancellation of the passed subscription.

See Also:

ClientRequest.subscribeTo(Class), ClientRequest.subscribeToEvent(Class)

subscriptions

public Subscriptions subscriptions()

Obtains subscriptions created by this client.