NetcodeClient (ch.awae.netcode 2.0.0 API)

```
public interface NetcodeClient
```
The client instance for the Netcode system. The client can receive messages synchronously and asynchronously. In any case the messages are read from the network asynchronously. If a MessageHandler is defined it gets invoked. If no such handler is specified the messages enter the message queue for synchronous reception using receive() or tryReceive(). The client can be switched between synchronous and asynchronous operation at any time. When switching from synchronous to asynchronous mode all the messages from the synchronous message queue are pushed into the message handler. During this phase it is possible that messages arrive out of order or multiple concurrent invocations of the handler exit. It is therefore recommended to avoid frequent mode switching. Threads blocked in receive() during the transition to asynchronous operation remain blocked indefinitely. Channel events can only be processed asynchronously. For this a ChannelEventHandler must be specified.

Since:

netcode 0.1.0

Author:

Andreas Wälchli

See Also:

NetcodeClientFactory

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`java.io.Serializable`	`ask(java.lang.String userId, java.io.Serializable data)` Sends a question to another client and awaits its response.
`void`	`disconnect()` Disconnect and terminate the client.
`ChannelConfiguration`	`getChannelConfiguration()` Get the configuration of the connected channel.
`ChannelInformation`	`getChannelInformation()` Requests channel information for the current channel from the server.
`ChannelEventHandler`	`getEventHandler()` Returns the current event handler or `null` if none is currently set.
`MessageHandler`	`getMessageHandler()` Returns the current message handler or `null` if none is currently set.
`ChannelInformation[]`	`getPublicChannels()` Requests a list of all public channels from the server.
`ClientQuestionHandler`	`getQuestionHandler()` Returns the current question handler or `null` if none is currently set.
`long`	`getTimeout()` returns the current timeout value in milliseconds
`java.lang.String`	`getUserId()` Get the userId of this client.
`java.lang.String[]`	`getUsers()` Get a list of all members of the channel.
`Message`	`receive()` Receive the next message synchronously and wait if no message is ready.
`void`	`send(java.io.Serializable payload)` Send the given object to all members of the channel
`void`	`sendPrivately(java.lang.String userId, java.io.Serializable payload)` Send the given object to the member of the channel with the given userId.
`void`	`setEventHandler(ChannelEventHandler handler)` Replaces the event handler.
`void`	`setMessageHandler(MessageHandler handler)` Replaces the message handler.
`void`	`setQuestionHandler(ClientQuestionHandler handler)` Replaces the question handler.
`void`	`setTimeout(long millis)` Sets a new timeout for server commands and client questions.
`Message`	`tryReceive()` Receive the next message synchronously if it exists.

- Method Detail
  - disconnect
```
void disconnect()
         throws java.io.IOException
```
    Disconnect and terminate the client. After this method returns this instance may no longer be used.
    
    Throws:
    
    java.io.IOException - an i/o exception occurred while disconnecting the client.
  - send
```
void send(java.io.Serializable payload)
```
    Send the given object to all members of the channel
  - sendPrivately
```
void sendPrivately(java.lang.String userId,
                   java.io.Serializable payload)
```
    Send the given object to the member of the channel with the given userId. Only the specified user will receive the message. It will not be transmitted to any other clients.
    
    Throws:
    
    java.lang.NullPointerException - the userId is null
    
    java.lang.IllegalArgumentException - the userId is not known
  - getUserId
```
java.lang.String getUserId()
```
    Get the userId of this client.
  - getChannelConfiguration
```
ChannelConfiguration getChannelConfiguration()
```
    Get the configuration of the connected channel.
  - getUsers
```
java.lang.String[] getUsers()
```
    Get a list of all members of the channel. This list is automatically kept up to date.
  - getMessageHandler
```
MessageHandler getMessageHandler()
```
    Returns the current message handler or null if none is currently set.
    
    Since:
    
    netcode 2.0.0
  - setMessageHandler
```
void setMessageHandler(MessageHandler handler)
```
    Replaces the message handler. If the handler is set to null the client switches into synchronous operation and messages can be accessed using receive() or tryReceive().
    
    Parameters:
    
    handler - the new message handler. may be null.
  - getEventHandler
```
ChannelEventHandler getEventHandler()
```
    Returns the current event handler or null if none is currently set.
    
    Since:
    
    netcode 2.0.0
  - setEventHandler
```
void setEventHandler(ChannelEventHandler handler)
```
    Replaces the event handler. may be null.
  - getQuestionHandler
```
ClientQuestionHandler getQuestionHandler()
```
    Returns the current question handler or null if none is currently set.
    
    Since:
    
    netcode 2.0.0
  - setQuestionHandler
```
void setQuestionHandler(ClientQuestionHandler handler)
```
    Replaces the question handler. may be null. If the handler is set to null client questions will always be responded to with an UnsupportedOperationException.
    
    Since:
    
    netcode 2.0.0
    
    See Also:
    
    ask(String, Serializable)
  - receive
```
Message receive()
         throws java.lang.InterruptedException
```
    Receive the next message synchronously and wait if no message is ready. Note: if this method is called while a MessageHandler is present the call will block indefinitely.
    
    Throws:
    
    java.lang.InterruptedException - the calling thread has been interrupted before a message became available
  - tryReceive
```
Message tryReceive()
```
    Receive the next message synchronously if it exists. Otherwise returns null.
    
    See Also:
    
    receive()
  - getTimeout
```
long getTimeout()
```
    returns the current timeout value in milliseconds
    
    Since:
    
    netcode 2.0.0
  - setTimeout
```
void setTimeout(long millis)
```
    Sets a new timeout for server commands and client questions. If this is set to 0 the timeout will be disabled.
    
    Parameters:
    
    millis - the new timeout in milliseconds
    
    Throws:
    
    java.lang.IllegalArgumentException - the timeout value is negative
    
    Since:
    
    netcode 2.0.0
  - ask
```
java.io.Serializable ask(java.lang.String userId,
                         java.io.Serializable data)
                  throws java.lang.InterruptedException,
                         java.util.concurrent.TimeoutException
```
    Sends a question to another client and awaits its response. Questions are handled through a ClientQuestionHandler.
    
    Parameters:
    
    userId - the client to send the question to
    
    data - the question payload
    
    Returns:
    
    the response
    
    Throws:
    
    java.lang.InterruptedException - the calling thread was interrupted before a response has been received.
    
    java.util.concurrent.TimeoutException - the timeout has expired before a response has been received.
    
    java.lang.IllegalArgumentException - the provided userId is unknown
    
    java.lang.NullPointerException - the provided userId is null.
    
    See Also:
    
    ClientQuestionHandler, setQuestionHandler(ClientQuestionHandler), setTimeout(long)
  - getChannelInformation
```
ChannelInformation getChannelInformation()
                                  throws java.lang.InterruptedException,
                                         ConnectionException,
                                         java.util.concurrent.TimeoutException
```
    Requests channel information for the current channel from the server. This requires that server commands are enabled on the server. This blocks the thread until the data becomes available or the timeout has expired.
    
    Throws:
    
    UnsupportedFeatureException - the server does not support server commands
    
    java.lang.InterruptedException - the thread has been interrupted while waiting on the data
    
    java.util.concurrent.TimeoutException - the client has not received a response before the timeout has expired
    
    ConnectionException - the request has been rejected by the server
    
    Since:
    
    netcode 2.0.0
    
    See Also:
    
    setTimeout(long)
  - getPublicChannels
```
ChannelInformation[] getPublicChannels()
                                throws java.lang.InterruptedException,
                                       ConnectionException,
                                       java.util.concurrent.TimeoutException
```
    Requests a list of all public channels from the server. This requires that server commands are enabled on the server. This blocks the thread until the data becomes available or the timeout has expired.
    
    Throws:
    
    UnsupportedFeatureException - the server does not support server commands
    
    java.lang.InterruptedException - the thread has been interrupted while waiting on the data
    
    java.util.concurrent.TimeoutException - the client has not received a response before the timeout has expired.
    
    ConnectionException - the request has been rejected by the server
    
    Since:
    
    netcode 2.0.0
    
    See Also:
    
    setTimeout(long)

Interface NetcodeClient

Method Summary

Method Detail

disconnect

send

sendPrivately

getUserId

getChannelConfiguration

getUsers

getMessageHandler

setMessageHandler

getEventHandler

setEventHandler

getQuestionHandler

setQuestionHandler

receive

tryReceive

getTimeout

setTimeout

ask

getChannelInformation

getPublicChannels