ch.awae.netcode

Class NetcodeClientFactory

java.lang.Object

ch.awae.netcode.NetcodeClientFactory

public final class NetcodeClientFactory
extends java.lang.Object

Factory for creating Netcode clients. By default clients are created in synchronous mode, without a ChannelEventHandler and using an anonymous TLS cipher. Every client provides an application id to the Netcode server. This application id is used to ensure that only compatible clients join a single channel. The server may also choose to accept only certain application ids. Most methods return the object itself to allow easy method chaining.

Since:

netcode 0.1.0

Author:

Andreas Wälchli

See Also:

NetcodeClient

Constructor Summary

Constructors

Constructor and Description
NetcodeClientFactory(java.lang.String host, int port, java.lang.String appId) Creates a new factory with the given host and port information and appId.

Method Summary

Modifier and Type	Method and Description
NetcodeClient	createChannel(java.lang.String userId, ChannelConfiguration configuration) Creates a new Netcode channel.
NetcodeClient	joinChannel(java.lang.String userId, java.lang.String channelId) Joins an existing Netcode channel.
ChannelInformation[]	listPublicChannels() get a list of all public Netcode channels with at least one free slot.
NetcodeClientFactory	runAfterBind(java.util.function.Consumer<java.net.Socket> runner) Adds a function to the post-bind queue.
NetcodeClientFactory	setEventHandler(ChannelEventHandler eventHandler)
NetcodeClientFactory	setMessageHandler(MessageHandler messageHandler)
NetcodeClientFactory	setMode(SocketMode socketMode, SecurityMode securityMode) Specifies both the socket mode and the security mode to use for new connections.
NetcodeClientFactory	setQuestionHandler(ClientQuestionHandler questionHandler)
NetcodeClientFactory	setTimeout(long timeout) Sets a new timeout value to be used for server commands and client questions.

Methods inherited from class java.lang.Object

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

Constructor Detail

NetcodeClientFactory

public NetcodeClientFactory(java.lang.String host,
                            int port,
                            java.lang.String appId)

Creates a new factory with the given host and port information and appId.

Parameters:

host - the server address. may not be null.

port - the port number of the server. must be in the range 0-65535.

appId - the application id to use for this client. may not be null.

Method Detail

runAfterBind

public NetcodeClientFactory runAfterBind(java.util.function.Consumer<java.net.Socket> runner)

Adds a function to the post-bind queue. The post-bind queue allows access to the Socket or SSLSocket as soon as it is created (but for SSLSockets before the handshake). This allows arbitrary modification of the socket configuration. This is especially useful for SSLSockets where more control over the security configuration may be desired. If the socket mode is set to SocketMode.PLAIN, the passed socket will be of type Socket, for all other modes it will be a SSLSocket.

Parameters:

runner - the runner to add to the post-bind queue. may not be null.

setMode

public NetcodeClientFactory setMode(SocketMode socketMode,
                                    SecurityMode securityMode)

Specifies both the socket mode and the security mode to use for new connections. The socket mode specifies if a plain (unencrypted) connection, SSL, TLS or both (SSL or TLS) should be used. The security mode specifies for secured (TLS/SSL) sockets if an anonymous cipher, a certificate-based cipher (or both) is acceptable. This information is used to negociate a cipher that is acceptable to both the server and the client. If socketMode is set to SocketMode.PLAIN, then the securityMode must be set to SecurityMode.ANY.

Throws:

java.lang.IllegalArgumentException - an illegal combination has been provided

java.lang.NullPointerException - any parameter is null

createChannel

public NetcodeClient createChannel(java.lang.String userId,
                                   ChannelConfiguration configuration)
                            throws java.io.IOException,
                                   ConnectionException

Creates a new Netcode channel. This does not consume this factory and it can therefore be re-used.

Parameters:

userId - the userId for this client. may not be null.

configuration - the channel configuration to use.

Returns:

an initialised client instance.

Throws:

java.io.IOException - an exception occured in the unterlying I/O elements.

ConnectionException - a netcode connection could not be established. Usually this indicates that some client data was rejected by the server. See the exception type and message for more information.

joinChannel

public NetcodeClient joinChannel(java.lang.String userId,
                                 java.lang.String channelId)
                          throws java.io.IOException,
                                 ConnectionException

Joins an existing Netcode channel. This does not consume this factory and it can therefore be re-used.

Parameters:

userId - the userId for this client. may not be null.

channelId - the id of the channel to join. Channel IDs are generated by the server upon channel generation.

Returns:

an initialised client instance.

Throws:

java.io.IOException - an exception occured in the unterlying I/O elements.

ConnectionException - a netcode connection could not be established. Usually this indicates that some client data was rejected by the server. See the exception type and message for more information.

listPublicChannels

public ChannelInformation[] listPublicChannels()
                                        throws java.io.IOException,
                                               ConnectionException

get a list of all public Netcode channels with at least one free slot.

Returns:

Throws:

java.io.IOException

ConnectionException - if the server does not support SIMPLE_QUERY (v1 servers) or the server has disabled public channels (v2 servers and above)

Since:

netcode 2.0.0

setTimeout

public NetcodeClientFactory setTimeout(long timeout)

Sets a new timeout value to be used for server commands and client questions. If this is set to 0, the timeout is disabled.

Parameters:

timeout - the new timeout in milliseconds

Throws:

java.lang.IllegalArgumentException - the timeout is negative

See Also:

NetcodeClient.ask(String, java.io.Serializable)

setMessageHandler

public NetcodeClientFactory setMessageHandler(MessageHandler messageHandler)

setEventHandler

public NetcodeClientFactory setEventHandler(ChannelEventHandler eventHandler)

setQuestionHandler

public NetcodeClientFactory setQuestionHandler(ClientQuestionHandler questionHandler)