Client (Narya Core 1.15 API)

java.lang.Object
- com.threerings.presents.client.Client

Direct Known Subclasses:

BureauClient
```
public class Client
extends Object
```
Through the client object, a connection to the system is established and maintained. The client object maintains two separate threads (a reader and a writer) by which all network traffic is managed.

Field Summary

Fields
Modifier and Type	Field and Description
`static int[]`	`DEFAULT_DATAGRAM_PORTS` The default ports on which the server listens for datagrams.
`static int`	`DEFAULT_MSGS_PER_SECOND` Our default maximum outgoing message rate in messages per second.
`static int[]`	`DEFAULT_SERVER_PORTS` The default ports on which the server listens for client connections.
`static int`	`MAX_DATAGRAM_SIZE` The maximum size of a datagram.

Constructor Summary

Constructors
Constructor and Description

Client(Credentials creds, RunQueue runQueue)
Constructs a client object with the supplied credentials and RunQueue.

Constructors
Constructor and Description
`Client(Credentials creds, RunQueue runQueue)` Constructs a client object with the supplied credentials and RunQueue.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addClientObserver(SessionObserver observer)` Registers the supplied observer with this client.
`void`	`addServiceGroup(String group)` Marks this client as interested in the specified bootstrap services group.
`void`	`fieldsToString(StringBuilder builder)` Adds text representation of fields to the builder.
`long`	`fromServerTime(long stamp)` Converts a server time stamp to a value comparable to client clock readings.
`AuthResponseData`	`getAuthResponseData()` Returns the data associated with our authentication response.
`String[]`	`getBootGroups()` Returns the set of bootstrap service groups needed by this client.
`BootstrapData`	`getBootstrapData()` Returns a reference to the bootstrap data provided to this client at logon time.
`ClientObject`	`getClientObject()` Returns a reference to the client object associated with this session.
`int`	`getClientOid()` Returns the oid of the client object associated with this session.
`int`	`getConnectionId()` Returns the unique id of the client's connection to the server.
`Credentials`	`getCredentials()` Returns the credentials with which this client is currently configured to connect to the server.
`int[]`	`getDatagramPorts()` Returns the ports on the server to which the client can send datagrams.
`DObjectManager`	`getDObjectManager()` Returns the distributed object manager associated with this session.
`String`	`getHostname()` Returns the hostname of the server to which this client is currently configured to connect.
`InvocationDirector`	`getInvocationDirector()` Returns the invocation director associated with this session.
`int[]`	`getPorts()` Returns the port on which this client is currently configured to connect to the server.
`PublicKey`	`getPublicKey()` Returns the public key with which this client is currently configured to create a secure authentication channel to the server.
`RunQueue`	`getRunQueue()` Returns the RunQueue in use by this client.
`byte[]`	`getSecret()` Gets the secret key to use with a session.
`<T> T`	`getService(Class<T> sclass)` Returns the first bootstrap service that could be located that implements the supplied `InvocationService` derivation.
`boolean`	`getTransmitDatagrams()` Checks whether we should transmit datagrams.
`String`	`getVersion()` Returns the version string configured for this client.
`boolean`	`isActive()` Returns true if we are in active communication (we may not yet be logged on, but we could be trying to log on).
`boolean`	`isLoggedOn()` Returns true if we are logged on, false if we're not.
`boolean`	`isStandalone()` Checks whether or not this client is operating in a standalone mode.
`boolean`	`logoff(boolean abortable)` Requests that the client log off of the server to which it is connected.
`boolean`	`logon()` Requests that this client connect and logon to the server with which it was previously configured.
`void`	`moveToServer(String hostname, int[] ports, int[] datagramPorts, InvocationService.ConfirmListener obs)` Transitions a logged on client from its current server to the specified new server.
`void`	`moveToServer(String hostname, int[] ports, InvocationService.ConfirmListener obs)` Transitions a logged on client from its current server to the specified new server.
`String[]`	`prepareStandaloneLogon()` Prepares the client for a standalone mode logon.
`void`	`registerFlushDelay(Class<?> objclass, long delay)` Instructs the distributed object manager associated with this client to allow objects of the specified class to linger around the specified number of milliseconds after their last subscriber has been removed before the client finally removes its object proxy and flushes the object.
`void`	`removeClientObserver(SessionObserver observer)` Unregisters the supplied observer.
`boolean`	`requireSecureAuth()` Returns true if we require secure authentication.
`<T> T`	`requireService(Class<T> sclass)` Like `getService(java.lang.Class<T>)` except that a `RuntimeException` is thrown if the service is not available.
`void`	`setClassLoader(ClassLoader loader)` Configures the client with a custom class loader which will be used when reading objects off of the network.
`void`	`setCredentials(Credentials creds)` Sets the credentials that will be used by this client to authenticate with the server.
`void`	`setMessageTracker(MessageTracker tracker)` Installs (or clears) a message tracker that will be notified on message transmission and receipt for the purpose of statistics tracking.
`boolean`	`setPublicKey(PublicKey key)` Sets the public key that will be used by this client to create a secure authentication channel with the server if the ciphers are supported.
`boolean`	`setPublicKey(String key)` Sets the public key that will be used by this client to create a secure authentication channel with the server if the ciphers are supported.
`void`	`setRequireSecureAuth(boolean requireSecureAuth)` Sets if we require a secure authentication.
`void`	`setSecret(byte[] secret)` Sets the secret key to use with a session.
`void`	`setServer(String hostname, int[] ports)` Configures the client to communicate with the server on the supplied hostname and set of ports (which will be tried in succession).
`void`	`setServer(String hostname, int[] ports, int[] datagramPorts)` Configures the client to communicate with the server on the supplied hostname, set of ports (which will be tried in succession), and datagram ports.
`void`	`setVersion(String version)` Sets the version string reported to the server during authentication.
`void`	`standaloneLogoff()` For standalone mode, this notifies observers that the client has logged off and cleans up.
`void`	`standaloneLogon(BootstrapData data, DObjectManager omgr)` Logs this client on in standalone mode with the faked bootstrap data and shared local distributed object manager.
`long`	`toServerTime(long stamp)` Converts a client clock reading to a value comparable to a server time stamp.
`String`	`toString()`

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - DEFAULT_SERVER_PORTS
```
public static final int[] DEFAULT_SERVER_PORTS
```
    The default ports on which the server listens for client connections.
  - DEFAULT_DATAGRAM_PORTS
```
public static final int[] DEFAULT_DATAGRAM_PORTS
```
    The default ports on which the server listens for datagrams.
  - MAX_DATAGRAM_SIZE
```
public static final int MAX_DATAGRAM_SIZE
```
    The maximum size of a datagram.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_MSGS_PER_SECOND
```
public static final int DEFAULT_MSGS_PER_SECOND
```
    Our default maximum outgoing message rate in messages per second.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - Client
```
public Client(Credentials creds,
              RunQueue runQueue)
```
    Constructs a client object with the supplied credentials and RunQueue. The creds will be used to authenticate with any server to which this client attempts to connect. The RunQueue is used to operate the distributed object event dispatch mechanism. To allow the dobj event dispatch to coexist with threads like the AWT thread, the client will request that the RunQueue queue up a runnable whenever there are distributed object events that need to be processed. The RunQueue can then queue that runnable up on the AWT thread if it is so inclined to make life simpler for the rest of the application.
    
    Parameters:
    
    creds - the credentials to use when logging on to the server. These can be null, but setCredentials must then be called before any call to logon.
    
    runQueue - a RunQueue that can be used to process incoming events.
- Method Detail
  - addClientObserver
```
public void addClientObserver(SessionObserver observer)
```
    Registers the supplied observer with this client. While registered the observer will receive notifications of state changes within the client. The function will refuse to register an already registered observer.
    
    See Also:
    
    ClientObserver, SessionObserver
  - removeClientObserver
```
public void removeClientObserver(SessionObserver observer)
```
    Unregisters the supplied observer. Upon return of this function, the observer will no longer receive notifications of state changes within the client.
  - isStandalone
```
public boolean isStandalone()
```
    Checks whether or not this client is operating in a standalone mode.
  - setServer
```
public void setServer(String hostname,
                      int[] ports)
```
    Configures the client to communicate with the server on the supplied hostname and set of ports (which will be tried in succession).
    
    See Also:
    
    logon(), moveToServer(java.lang.String, int[], com.threerings.presents.client.InvocationService.ConfirmListener)
  - setServer
```
public void setServer(String hostname,
                      int[] ports,
                      int[] datagramPorts)
```
    Configures the client to communicate with the server on the supplied hostname, set of ports (which will be tried in succession), and datagram ports.
    
    See Also:
    
    logon(), moveToServer(java.lang.String, int[], com.threerings.presents.client.InvocationService.ConfirmListener)
  - getRunQueue
```
public RunQueue getRunQueue()
```
    Returns the RunQueue in use by this client. This can be used to queue up event dispatching stints.
  - getHostname
```
public String getHostname()
```
    Returns the hostname of the server to which this client is currently configured to connect.
  - getPorts
```
public int[] getPorts()
```
    Returns the port on which this client is currently configured to connect to the server.
  - getDatagramPorts
```
public int[] getDatagramPorts()
```
    Returns the ports on the server to which the client can send datagrams. Returns an empty array if datagrams are not supported.
  - getCredentials
```
public Credentials getCredentials()
```
    Returns the credentials with which this client is currently configured to connect to the server.
  - setCredentials
```
public void setCredentials(Credentials creds)
```
    Sets the credentials that will be used by this client to authenticate with the server. This should be done before any call to logon.
  - getPublicKey
```
public PublicKey getPublicKey()
```
    Returns the public key with which this client is currently configured to create a secure authentication channel to the server.
  - setPublicKey
```
public boolean setPublicKey(PublicKey key)
```
    Sets the public key that will be used by this client to create a secure authentication channel with the server if the ciphers are supported. This should be done before any call to logon.
    
    Returns:
    
    true if the key is set
  - setPublicKey
```
public boolean setPublicKey(String key)
```
    Sets the public key that will be used by this client to create a secure authentication channel with the server if the ciphers are supported. This should be done before any call to logon.
    
    Returns:
    
    true if the key is set
  - setRequireSecureAuth
```
public void setRequireSecureAuth(boolean requireSecureAuth)
```
    Sets if we require a secure authentication.
  - requireSecureAuth
```
public boolean requireSecureAuth()
```
    Returns true if we require secure authentication.
  - setSecret
```
public void setSecret(byte[] secret)
```
    Sets the secret key to use with a session.
  - getSecret
```
public byte[] getSecret()
```
    Gets the secret key to use with a session.
  - getVersion
```
public String getVersion()
```
    Returns the version string configured for this client.
  - setVersion
```
public void setVersion(String version)
```
    Sets the version string reported to the server during authentication. Some server implementations may wish to refuse connections by old or invalid client versions.
  - setClassLoader
```
public void setClassLoader(ClassLoader loader)
```
    Configures the client with a custom class loader which will be used when reading objects off of the network.
  - setMessageTracker
```
public void setMessageTracker(MessageTracker tracker)
```
    Installs (or clears) a message tracker that will be notified on message transmission and receipt for the purpose of statistics tracking.
    
    Parameters:
    
    tracker - the new tracker to install, or null to clear the tracker.
  - getAuthResponseData
```
public AuthResponseData getAuthResponseData()
```
    Returns the data associated with our authentication response. Users of the Presents system may wish to communicate authentication related information to their client by extending and augmenting AuthResponseData.
  - getDObjectManager
```
public DObjectManager getDObjectManager()
```
    Returns the distributed object manager associated with this session. This reference is only valid for the duration of the session and a new reference must be obtained if the client disconnects and reconnects to the server.
    
    Returns:
    
    the dobjmgr in effect or null if we have no established connection to the server.
  - registerFlushDelay
```
public void registerFlushDelay(Class<?> objclass,
                               long delay)
```
    Instructs the distributed object manager associated with this client to allow objects of the specified class to linger around the specified number of milliseconds after their last subscriber has been removed before the client finally removes its object proxy and flushes the object. Normally, objects are flushed immediately following the removal of their last subscriber.
    Note: the delay will be applied to derived classes as well as exact matches. Note also: this method cannot be called until after the client has established a connection with the server and the distributed object manager is available.
  - getConnectionId
```
public int getConnectionId()
```
    Returns the unique id of the client's connection to the server. It is only valid for the duration of the session.
  - getClientOid
```
public int getClientOid()
```
    Returns the oid of the client object associated with this session. It is only valid for the duration of the session.
  - getClientObject
```
public ClientObject getClientObject()
```
    Returns a reference to the client object associated with this session. It is only valid for the duration of the session.
  - getInvocationDirector
```
public InvocationDirector getInvocationDirector()
```
    Returns the invocation director associated with this session. This reference is only valid for the duration of the session.
  - addServiceGroup
```
public void addServiceGroup(String group)
```
    Marks this client as interested in the specified bootstrap services group. Any services registered as bootstrap services with the supplied group name will be included in this clients bootstrap services set. This must be called before logon().
  - getBootGroups
```
public String[] getBootGroups()
```
    Returns the set of bootstrap service groups needed by this client.
  - getService
```
public <T> T getService(Class<T> sclass)
```
    Returns the first bootstrap service that could be located that implements the supplied InvocationService derivation. null is returned if no such service could be found.
  - requireService
```
public <T> T requireService(Class<T> sclass)
```
    Like getService(java.lang.Class<T>) except that a RuntimeException is thrown if the service is not available. Useful to avoid redundant error checking when you know that the shit will hit the fan if a particular invocation service is not available.
  - getBootstrapData
```
public BootstrapData getBootstrapData()
```
    Returns a reference to the bootstrap data provided to this client at logon time.
  - fromServerTime
```
public long fromServerTime(long stamp)
```
    Converts a server time stamp to a value comparable to client clock readings.
  - toServerTime
```
public long toServerTime(long stamp)
```
    Converts a client clock reading to a value comparable to a server time stamp.
  - isActive
```
public boolean isActive()
```
    Returns true if we are in active communication (we may not yet be logged on, but we could be trying to log on).
  - getTransmitDatagrams
```
public boolean getTransmitDatagrams()
```
    Checks whether we should transmit datagrams.
  - isLoggedOn
```
public boolean isLoggedOn()
```
    Returns true if we are logged on, false if we're not.
  - logon
```
public boolean logon()
```
    Requests that this client connect and logon to the server with which it was previously configured.
    
    Returns:
    
    false if we're already logged on, true if a logon attempt was initiated.
  - moveToServer
```
public void moveToServer(String hostname,
                         int[] ports,
                         InvocationService.ConfirmListener obs)
```
    Transitions a logged on client from its current server to the specified new server. Currently this simply logs the client off of its current server (if it is logged on) and logs it onto the new server, but in the future we may aim to do something fancier.
    If we fail to connect to the new server, the client will not be automatically reconnected to the old server. It will be in a logged off state. However, it will be reconfigured with the hostname and ports of the old server so that the caller can notify the user of the failure and then simply call logon() to attempt to reconnect to the old server.
    
    Parameters:
    
    obs - an observer that will be notified when we have successfully logged onto the other server, or if the move failed.
  - moveToServer
```
public void moveToServer(String hostname,
                         int[] ports,
                         int[] datagramPorts,
                         InvocationService.ConfirmListener obs)
```
    Transitions a logged on client from its current server to the specified new server. Currently this simply logs the client off of its current server (if it is logged on) and logs it onto the new server, but in the future we may aim to do something fancier.
    If we fail to connect to the new server, the client will not be automatically reconnected to the old server. It will be in a logged off state. However, it will be reconfigured with the hostname and ports of the old server so that the caller can notify the user of the failure and then simply call logon() to attempt to reconnect to the old server.
    
    Parameters:
    
    obs - an observer that will be notified when we have successfully logged onto the other server, or if the move failed.
  - logoff
```
public boolean logoff(boolean abortable)
```
    Requests that the client log off of the server to which it is connected.
    
    Parameters:
    
    abortable - If true, the client will call clientWillDisconnect on all of the client observers and abort the logoff process if any of them return false. If false, clientWillDisconnect will not be called at all.
    
    Returns:
    
    true if the logoff succeeded, false if it failed due to a disagreeable observer.
  - prepareStandaloneLogon
```
public String[] prepareStandaloneLogon()
```
    Prepares the client for a standalone mode logon. Returns the set of bootstrap service groups that should be supplied to the invocation manager to create our fake bootstrap record.
  - standaloneLogon
```
public void standaloneLogon(BootstrapData data,
                            DObjectManager omgr)
```
    Logs this client on in standalone mode with the faked bootstrap data and shared local distributed object manager.
  - standaloneLogoff
```
public void standaloneLogoff()
```
    For standalone mode, this notifies observers that the client has logged off and cleans up.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - fieldsToString
```
public void fieldsToString(StringBuilder builder)
```
    Adds text representation of fields to the builder. The results will be placed between brackets by toString.

Class Client

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_SERVER_PORTS

DEFAULT_DATAGRAM_PORTS

MAX_DATAGRAM_SIZE

DEFAULT_MSGS_PER_SECOND

Constructor Detail

Client

Method Detail

addClientObserver

removeClientObserver

isStandalone

setServer

setServer

getRunQueue

getHostname

getPorts

getDatagramPorts

getCredentials

setCredentials

getPublicKey

setPublicKey

setPublicKey

setRequireSecureAuth

requireSecureAuth

setSecret

getSecret

getVersion

setVersion

setClassLoader

setMessageTracker

getAuthResponseData

getDObjectManager

registerFlushDelay

getConnectionId

getClientOid

getClientObject

getInvocationDirector

addServiceGroup

getBootGroups

getService

requireService

getBootstrapData

fromServerTime

toServerTime

isActive

getTransmitDatagrams

isLoggedOn

logon

moveToServer

moveToServer

logoff

prepareStandaloneLogon

standaloneLogon

standaloneLogoff

toString

fieldsToString