com.mixer.interactive

Class GameClient

java.lang.Object

com.mixer.interactive.GameClient

public class GameClient
extends Object

A GameClient is used to connect to a Interactive integration that is hosted on the Interactive service. A client can only connect to the integration that was specified when the client was created.

Once connected a client has the ability to query information on the integration from the Interactive service, as well as manipulate resources in the integration by making requests to the Interactive service.

Since:

1.0.0

Author:

Microsoft Corporation

Field Summary

Fields

Modifier and Type	Field and Description
static Class<ControlServiceProvider>	CONTROL_SERVICE_PROVIDER
static Class<GroupServiceProvider>	GROUP_SERVICE_PROVIDER
static com.google.gson.Gson	GSON Gson singleton used for serialization/deserialization.
static Class<ParticipantServiceProvider>	PARTICIPANT_SERVICE_PROVIDER
static Class<RemoteProcedureCallServiceProvider>	RPC_SERVICE_PROVIDER Collection of service providers
static Class<SceneServiceProvider>	SCENE_SERVICE_PROVIDER
static Class<TransactionServiceProvider>	TRANSACTION_SERVICE_PROVIDER

Constructor Summary

Constructors

Constructor and Description
GameClient(Number projectVersionId) Initializes a new GameClient.
GameClient(Number projectVersionId, boolean useStateManager) Initializes a new GameClient.

Method Summary

Modifier and Type	Method and Description
CompletableFuture<Boolean>	connect(String token) Connects the game client to it's associated Interactive integration on the Interactive service, using either an OAuth Bearer token or an xtoken to authenticate itself with the Interactive service.
CompletableFuture<Boolean>	connect(String authToken, String shareCode) Connects the game client to it's associated Interactive integration on the Interactive service, using either an OAuth Bearer token or an xtoken to authenticate itself with the Interactive service and the appropriate share code for the integration.
CompletableFuture<Boolean>	connectTo(String authToken, String shareCode, URI interactiveHost) Connects the game client to it's associated Interactive integration on a specific Interactive service host, using either an OAuth Bearer token or a xtoken to authenticate itself with the Interactive service and the appropriate share code for the integration.
CompletableFuture<Boolean>	connectTo(String authToken, URI interactiveHost) Connects the game client to it's associated Interactive integration on a specific Interactive service host, using either an OAuth Bearer token or a xtoken to authenticate itself with the Interactive service.
CompletableFuture<Void>	disconnect() Disconnects the client from the Interactive service.
com.google.common.eventbus.EventBus	getEventBus() Returns the EventBus associated with the client.
ScheduledExecutorService	getExecutorService() Returns the thread executor service used for creating CompletableFutures.
CompletableFuture<InteractiveMemoryStatistic>	getMemoryStats() Retrieves the current memory usage for the Interactive integration this client is connected to on the Interactive service.
Number	getProjectVersionId() Returns the project version ID for the Interactive integration the client connects to.
ServiceManager<AbstractServiceProvider>	getServiceManager() Returns the ServiceManager associated with the client.
StateManager	getStateManager() Gets the StateManager for this game client.
CompletableFuture<Map<InteractiveMethod,ThrottleState>>	getThrottleState() Retrieves statistics on the state of throttling rules set up in InteractiveMethod.SET_BANDWIDTH_THROTTLE method requests.
CompletableFuture<Long>	getTime() Retrieves the current server time from the Interactive service, given as a milliseconds UTC unix timestamp.
InteractiveWebSocketClient	getWebSocketClient() Returns the web socket client that this game client uses to communicate with the Interactive service.
boolean	isConnected() Returns true if this client is currently connected to the Interactive service, false otherwise.
void	ready(boolean isReady) Notifies the Interactive service whether or not this client is ready to have clients connect and start interacting.
CompletableFuture<Boolean>	setBandwidthThrottle(Map<InteractiveMethod,BandwidthThrottle> throttleMap) Sets up throttling for certain server-to-client method calls, such as InteractiveMethod.GIVE_INPUT, which could become problematic in very high-traffic scenarios.
CompletableFuture<CompressionScheme>	setCompression(Collection<String> schemes) Changes the compression algorithm the client uses to encode/decode messages to/from the Interactive service.
CompletableFuture<CompressionScheme>	setCompression(CompressionScheme... schemes) Changes the compression algorithm the client uses to encode/decode messages to/from the Interactive service.
CompletableFuture<CompressionScheme>	setCompression(String... schemes) Changes the compression algorithm the client uses to encode/decode messages to/from the Interactive service.
<T extends AbstractServiceProvider> T	using(Class<T> clazz) Retrieves the service provider specified by the provided class from the service manager.

Methods inherited from class java.lang.Object

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

Field Detail

GSON

public static final com.google.gson.Gson GSON

Gson singleton used for serialization/deserialization.

RPC_SERVICE_PROVIDER

public static final Class<RemoteProcedureCallServiceProvider> RPC_SERVICE_PROVIDER

Collection of service providers

PARTICIPANT_SERVICE_PROVIDER

public static final Class<ParticipantServiceProvider> PARTICIPANT_SERVICE_PROVIDER

GROUP_SERVICE_PROVIDER

public static final Class<GroupServiceProvider> GROUP_SERVICE_PROVIDER

SCENE_SERVICE_PROVIDER

public static final Class<SceneServiceProvider> SCENE_SERVICE_PROVIDER

CONTROL_SERVICE_PROVIDER

public static final Class<ControlServiceProvider> CONTROL_SERVICE_PROVIDER

TRANSACTION_SERVICE_PROVIDER

public static final Class<TransactionServiceProvider> TRANSACTION_SERVICE_PROVIDER

Constructor Detail

GameClient

public GameClient(Number projectVersionId)

Initializes a new GameClient.

Parameters:

projectVersionId - The project version ID for the Interactive integration the client will use

Since:

1.0.0

GameClient

public GameClient(Number projectVersionId,
                  boolean useStateManager)

Initializes a new GameClient.

Parameters:

projectVersionId - The project version ID for the Interactive integration the client will use

useStateManager - Whether or not to use built in caching for the game client

Since:

2.1.0

Method Detail

getProjectVersionId

public Number getProjectVersionId()

Returns the project version ID for the Interactive integration the client connects to.

Returns:

The project version ID for the Interactive integration the client connects to

Since:

1.0.0

getServiceManager

public ServiceManager<AbstractServiceProvider> getServiceManager()

Returns the ServiceManager associated with the client.

Returns:

The ServiceManager associated with the client

Since:

2.1.0

getStateManager

public StateManager getStateManager()

Gets the StateManager for this game client.

Returns:

The StateManager for this game client

Since:

2.1.0

getEventBus

public com.google.common.eventbus.EventBus getEventBus()

Returns the EventBus associated with the client.

Returns:

The EventBus associated with the client

Since:

1.0.0

getWebSocketClient

public InteractiveWebSocketClient getWebSocketClient()

Returns the web socket client that this game client uses to communicate with the Interactive service.

Returns:

The web socket client that this game client uses to communicate with the Interactive service.

Since:

1.0.0

getExecutorService

public ScheduledExecutorService getExecutorService()

Returns the thread executor service used for creating CompletableFutures.

Returns:

The thread executor service used for creating CompletableFutures.

Since:

1.0.0

using

public <T extends AbstractServiceProvider> T using(Class<T> clazz)

Retrieves the service provider specified by the provided class from the service manager. If there does not exist a service provider instance for the provided class, null is returned.

Type Parameters:

T - Type of service provider to be used

Parameters:

clazz - Class of service provider to be used

Returns:

The service provider instance from the service manager. If there does not exist a service provider instance for the provided class, null is returned.

Since:

1.0.0

isConnected

public boolean isConnected()

Returns true if this client is currently connected to the Interactive service, false otherwise.

Returns:

true if this client is currently connected to the Interactive service, false otherwise

Since:

1.0.0

connect

public CompletableFuture<Boolean> connect(String token)

Connects the game client to it's associated Interactive integration on the Interactive service, using either an OAuth Bearer token or an xtoken to authenticate itself with the Interactive service.

Parameters:

token - Authentication token

Returns:

A CompletableFuture that completes when the connection attempt is finished

Since:

1.0.0

connect

public CompletableFuture<Boolean> connect(String authToken,
                                          String shareCode)

Connects the game client to it's associated Interactive integration on the Interactive service, using either an OAuth Bearer token or an xtoken to authenticate itself with the Interactive service and the appropriate share code for the integration. Connections to Interactive hosts are attempted in the order of hosts that are returned from the interactive/hosts endpoint. If no connection succeeds, then the future returns an InteractiveConnectionException.

Parameters:

authToken - Authentication token

shareCode - The share code provided by the author of the Interactive integration

Returns:

A CompletableFuture that completes when the connection attempt is finished

Since:

2.1.0

connectTo

public CompletableFuture<Boolean> connectTo(String authToken,
                                            URI interactiveHost)

Connects the game client to it's associated Interactive integration on a specific Interactive service host, using either an OAuth Bearer token or a xtoken to authenticate itself with the Interactive service.

Parameters:

authToken - Authentication token

interactiveHost - URI for an Interactive service host

Returns:

A CompletableFuture that completes when the connection attempt is finished

Since:

1.0.0

connectTo

public CompletableFuture<Boolean> connectTo(String authToken,
                                            String shareCode,
                                            URI interactiveHost)

Connects the game client to it's associated Interactive integration on a specific Interactive service host, using either an OAuth Bearer token or a xtoken to authenticate itself with the Interactive service and the appropriate share code for the integration.

Parameters:

authToken - Authentication token

shareCode - The share code provided by the author of the Interactive integration

interactiveHost - URI for an Interactive service host

Returns:

A CompletableFuture that completes when the connection attempt is finished

Since:

1.0.0

disconnect

public CompletableFuture<Void> disconnect()

Disconnects the client from the Interactive service.

Returns:

A CompletableFuture that completes when the client has been disconnected from the Interactive service

Since:

1.0.0

ready

public void ready(boolean isReady)

Notifies the Interactive service whether or not this client is ready to have clients connect and start interacting.

The parameters of the request (isReady: true or isReady: false) determine whether or not the Interactive integration this client is connected to is ready to have clients connect and start interacting or not, respectively.

Parameters:

isReady - The value to pass along in the ready method call

Since:

1.0.0

setCompression

public CompletableFuture<CompressionScheme> setCompression(CompressionScheme... schemes)

Changes the compression algorithm the client uses to encode/decode messages to/from the Interactive service.

Developers supply a collection of preferred schemes in order of preference, from greatest to least preference, from which the Interactive service will select a preferred common one. All subsequent requests and replies will be sent in using the new compression scheme.

If no preferred common scheme is found, the Interactive server will fall back to the plain text scheme.

Parameters:

schemes - An array of preferred CompressionSchemes in order of preference, from greatest to least preference

Returns:

The new CompressionScheme that the client is to use to communicate with the Interactive service

Since:

1.0.0

See Also:

CompressionScheme

setCompression

public CompletableFuture<CompressionScheme> setCompression(String... schemes)

Changes the compression algorithm the client uses to encode/decode messages to/from the Interactive service.

Developers supply a collection of preferred schemes in order of preference, from greatest to least preference, from which the Interactive service will select a preferred common one. All subsequent requests and replies will be sent in using the new compression scheme.

If no preferred common scheme is found, the Interactive server will fall back to the plain text scheme.

Parameters:

schemes - An array of preferred compression schemes in order of preference, from greatest to least preference

Returns:

The new CompressionScheme that the client is to use to communicate with the Interactive service

Since:

1.0.0

See Also:

CompressionScheme

setCompression

public CompletableFuture<CompressionScheme> setCompression(Collection<String> schemes)

Changes the compression algorithm the client uses to encode/decode messages to/from the Interactive service.

Developers supply a collection of preferred schemes in order of preference, from greatest to least preference, from which the Interactive service will select a preferred common one. All subsequent requests and replies will be sent in using the new compression scheme.

If no preferred common scheme is found, the Interactive server will fall back to the plain text scheme.

Parameters:

schemes - An Collection of preferred CompressionSchemes in order of preference, from greatest to least preference

Returns:

The new CompressionScheme that the client is to use to communicate with the Interactive service

Since:

1.0.0

See Also:

CompressionScheme

getTime

public CompletableFuture<Long> getTime()

Retrieves the current server time from the Interactive service, given as a milliseconds UTC unix timestamp.

The result of the CompletableFuture may include checked exceptions that were thrown in the event that there was a problem with the reply from the Interactive service. Specifically, two types of checked exceptions may be thrown:

• InteractiveRequestNoReplyException may be thrown if no reply is received from the Interactive service.
• InteractiveReplyWithErrorException may be thrown if the reply received from the Interactive service contains an InteractiveError.

Considerations should be made for these possibilities when interpreting the results of the returned CompletableFuture.

Returns:

A CompletableFuture that when complete returns the Interactive service's current server time, given as a UTC unix timestamp (in milliseconds)

Since:

1.0.0

getMemoryStats

public CompletableFuture<InteractiveMemoryStatistic> getMemoryStats()

Retrieves the current memory usage for the Interactive integration this client is connected to on the Interactive service. The memory usage returned is a dump of information regarding current memory allocations, as well as a breakdown of how much memory is allocated where. This information is provided for debugging purposes.

The result of the CompletableFuture may include checked exceptions that were thrown in the event that there was a problem with the reply from the Interactive service. Specifically, two types of checked exceptions may be thrown:

• InteractiveRequestNoReplyException may be thrown if no reply is received from the Interactive service.
• InteractiveReplyWithErrorException may be thrown if the reply received from the Interactive service contains an InteractiveError.

Considerations should be made for these possibilities when interpreting the results of the returned CompletableFuture.

Returns:

A CompletableFuture that when complete returns a InteractiveMemoryStatistic representing the current memory usage of the Interactive integration the client is connected to

Since:

1.0.0

See Also:

InteractiveMemoryStatistic

getThrottleState

public CompletableFuture<Map<InteractiveMethod,ThrottleState>> getThrottleState()

Retrieves statistics on the state of throttling rules set up in InteractiveMethod.SET_BANDWIDTH_THROTTLE method requests. It returns the number of sent packets (ones inserted into the bucket) and the number of rejected packets for each method that has a throttle set.

The result of the CompletableFuture may include checked exceptions that were thrown in the event that there was a problem with the reply from the Interactive service. Specifically, two types of checked exceptions may be thrown:

• InteractiveRequestNoReplyException may be thrown if no reply is received from the Interactive service.
• InteractiveReplyWithErrorException may be thrown if the reply received from the Interactive service contains an InteractiveError.

Considerations should be made for these possibilities when interpreting the results of the returned CompletableFuture.

Returns:

A CompletableFuture that when complete returns a Map of InteractiveMethods and their associated ThrottleState

Since:

1.0.0

See Also:

BandwidthThrottle, InteractiveMethod, ThrottleState

setBandwidthThrottle

public CompletableFuture<Boolean> setBandwidthThrottle(Map<InteractiveMethod,BandwidthThrottle> throttleMap)

Sets up throttling for certain server-to-client method calls, such as InteractiveMethod.GIVE_INPUT, which could become problematic in very high-traffic scenarios.

The Interactive service implements a leaky bucket algorithm; the client specifies the total bucket capacity in bytes and its drain rate in bytes per second. The client supplies a map of method names and their associated throttle rules. Throttling previously enabled on a method can be disabled by setting it to null.

The result of the CompletableFuture may include checked exceptions that were thrown in the event that there was a problem with the reply from the Interactive service. Specifically, two types of checked exceptions may be thrown:

• InteractiveRequestNoReplyException may be thrown if no reply is received from the Interactive service.
• InteractiveReplyWithErrorException may be thrown if the reply received from the Interactive service contains an InteractiveError.

Considerations should be made for these possibilities when interpreting the results of the returned CompletableFuture.

Parameters:

throttleMap - A Map of InteractiveMethods and their associated BandwidthThrottle

Returns:

A CompletableFuture that when complete returns true if the setBandwidthThrottle method call completes with no errors

Since:

1.0.0

See Also:

BandwidthThrottle, InteractiveMethod