PresentsSession (Narya Core 1.15 API)

java.lang.Object
- com.threerings.presents.server.PresentsSession

All Implemented Interfaces:

ClientResolutionListener, PresentsConnection.MessageHandler

Direct Known Subclasses:

BureauSession, CrowdSession, PeerSession
```
public class PresentsSession
extends Object
implements PresentsConnection.MessageHandler, ClientResolutionListener
```
Represents a client session in the server. It is associated with a connection instance (while the client is connected) and acts as the intermediary for the remote client in terms of passing along events forwarded by the client, ensuring that subscriptions are maintained on behalf of the client and that events are forwarded to the client.
A note on synchronization: the client object is structured so that its Subscriber implementation (which is called from the dobjmgr thread) can proceed without synchronization. This does not overlap with its other client duties which are called from the conmgr thread and therefore also need not be synchronized.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`PresentsSession.UserChangeListener` Used by `setUsername(com.threerings.util.Name, com.threerings.presents.server.PresentsSession.UserChangeListener)` to report success or failure.

Constructor Summary

Constructors
Constructor and Description

PresentsSession()

Constructors
Constructor and Description
`PresentsSession()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`checkExpired(long now)` Returns true if this session has been disconnected for sufficiently long that it should be forcibly ended.
`void`	`clientResolved(Name username, ClientObject clobj)` Called when resolution completed successfully.
`void`	`endSession()` Forcibly terminates a client's session.
`Name`	`getAuthName()` Returns the username with which this client authenticated.
`ClientObject`	`getClientObject()` returns the client object that is associated with this client.
`Credentials`	`getCredentials()` Returns the credentials used to authenticate this session.
`InetAddress`	`getInetAddress()` Returns the address of the connected client or null if this client is not connected.
`long`	`getNetworkStamp()` Returns the time at which this client most recently connected or disconnected.
`byte[]`	`getSecret()` Returns the shared secret for this session.
`long`	`getSessionStamp()` Returns the time at which this client started their network session.
`TimeZone`	`getTimeZone()` Returns the time zone in which the client is operating.
`boolean`	`getTransmitDatagrams()` Checks whether the client has requested that datagram transmission be enabled.
`void`	`handleMessage(Message message)` Called when a complete message has been parsed from incoming network data.
`void`	`resolutionFailed(Name username, Exception reason)` Called when resolution fails.
`void`	`setClassLoader(ClassLoader loader)` Configures this session with a custom class loader that will be used when unserializing classes from the network.
`void`	`setIncomingMessageThrottle(int messagesPerSec)` Configures the rate at which incoming messages are throttled for this client.
`void`	`setUsername(Name username, PresentsSession.UserChangeListener ucl)` Danger: this method is not for general consumption.
`void`	`shutdown()` This is called when the server is shut down in the middle of a client session.
`String`	`toString()`
`boolean`	`updateUsername(Name username)` Double Danger: this method is not for general consumption.

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

- Constructor Detail
  - PresentsSession
```
public PresentsSession()
```
- Method Detail
  - getCredentials
```
public Credentials getCredentials()
```
    Returns the credentials used to authenticate this session.
  - getTimeZone
```
public TimeZone getTimeZone()
```
    Returns the time zone in which the client is operating.
  - getSecret
```
public byte[] getSecret()
```
    Returns the shared secret for this session.
  - checkExpired
```
public boolean checkExpired(long now)
```
    Returns true if this session has been disconnected for sufficiently long that it should be forcibly ended.
  - getSessionStamp
```
public long getSessionStamp()
```
    Returns the time at which this client started their network session.
  - getNetworkStamp
```
public long getNetworkStamp()
```
    Returns the time at which this client most recently connected or disconnected.
  - getAuthName
```
public Name getAuthName()
```
    Returns the username with which this client authenticated. Note: if setUsername(com.threerings.util.Name, com.threerings.presents.server.PresentsSession.UserChangeListener) has been called this may differ from getClientObject().username.
  - getInetAddress
```
public InetAddress getInetAddress()
```
    Returns the address of the connected client or null if this client is not connected.
  - getTransmitDatagrams
```
public boolean getTransmitDatagrams()
```
    Checks whether the client has requested that datagram transmission be enabled.
  - setClassLoader
```
public void setClassLoader(ClassLoader loader)
```
    Configures this session with a custom class loader that will be used when unserializing classes from the network.
  - setIncomingMessageThrottle
```
public void setIncomingMessageThrottle(int messagesPerSec)
```
    Configures the rate at which incoming messages are throttled for this client. This will communicate the new limit to the client and begin enforcing the limit when the client has acknowledged the new limit.
    Note: this means that a hacked client can refuse to ACK message rate reductions and continue to use the most generous rate ever assigned to it. Don't increase the throttle beyond the default for untrusted clients. This mechanism exists so that trusted clients can have their throttle relaxed in a robust manner which will not result in disconnects if the client happens to be at or near the throttle limit when the throttle is reduced.
  - setUsername
```
public void setUsername(Name username,
                        PresentsSession.UserChangeListener ucl)
```
    Danger: this method is not for general consumption. This changes the username of the client, but should only be done very early in a user's session, when you know that no one has mapped the user based on their username or has in any other way made use of their username in a way that will break. However, it should not be done too early in the session. The client must be fully resolved.
    It exists to support systems wherein a user logs in with an account username and then chooses a "screen name" by which they will play (often from a small set of available "characters" available per account). This will take care of remapping the username to client object mappings that were made by the Presents services when the user logs on, but anything else that has had its grubby mits on the username will be left to its own devices, hence the care that must be exercised when using this method.
    
    Parameters:
    
    ucl - an entity that will (optionally) be notified when the username conversion process is complete.
  - updateUsername
```
public boolean updateUsername(Name username)
```
    Double Danger: this method is not for general consumption. Like #setUsername, this changes the username of the client, but unlike setUsername, it does it in the existing client object. Care must be taken to ensure that any client or server code either doesn't map things based on username before this call, or that it's updated to reflect the change.
    
    Returns:
    
    - true if the client was successfully renamed, false otherwise
  - getClientObject
```
public ClientObject getClientObject()
```
    returns the client object that is associated with this client.
  - endSession
```
public void endSession()
```
    Forcibly terminates a client's session. This must be called from the dobjmgr thread.
  - shutdown
```
public void shutdown()
```
    This is called when the server is shut down in the middle of a client session. In this circumstance, endSession() will not be called and so any persistent data that might normally be flushed at the end of a client's session should likely be flushed here.
  - clientResolved
```
public void clientResolved(Name username,
                           ClientObject clobj)
```
    Description copied from interface: ClientResolutionListener
    
    Called when resolution completed successfully.
    
    Specified by:
    
    clientResolved in interface ClientResolutionListener
  - resolutionFailed
```
public void resolutionFailed(Name username,
                             Exception reason)
```
    Description copied from interface: ClientResolutionListener
    
    Called when resolution fails.
    
    Specified by:
    
    resolutionFailed in interface ClientResolutionListener
  - handleMessage
```
public void handleMessage(Message message)
```
    Description copied from interface: PresentsConnection.MessageHandler
    
    Called when a complete message has been parsed from incoming network data.
    
    Specified by:
    
    handleMessage in interface PresentsConnection.MessageHandler
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class PresentsSession

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

PresentsSession

Method Detail

getCredentials

getTimeZone

getSecret

checkExpired

getSessionStamp

getNetworkStamp

getAuthName

getInetAddress

getTransmitDatagrams

setClassLoader

setIncomingMessageThrottle

setUsername

updateUsername

getClientObject

endSession

shutdown

clientResolved

resolutionFailed

handleMessage

toString