org.jdesktop.wonderland.client.comms
Interface WonderlandSession

All Known Implementing Classes:
CellClientSession, JmeClientSession, WonderlandSessionImpl

public interface WonderlandSession

The WonderlandSession is the base class for communicating with a given Wonderland server. The session encapsulates the work of login and maintaining the state of the connection with the given server.

Author:
jkaplan

Nested Class Summary
static class WonderlandSession.Status
          possible states of the client
 
Method Summary
 void addSessionStatusListener(SessionStatusListener listener)
          Add a listener that will be notified when the status of this session changes.
 void connect(ClientConnection client)
          Connect a new client to this session, with no properties.
 void connect(ClientConnection client, java.util.Properties properties)
          Connect a new client to this session.
 void disconnect(ClientConnection client)
          Disconnect a previously connected client from this session.
 ClientConnection getConnection(ConnectionType type)
          Get the connected ClientConnection for the given ConnectionType.
<T extends ClientConnection>
T
getConnection(ConnectionType type, java.lang.Class<T> clazz)
          Get the attched ClientConnection for the given ConnectionType.
 java.util.Collection<ClientConnection> getConnections()
          Get all clients connected to this session
 java.math.BigInteger getID()
          Get the ID of this session.
 WonderlandServerInfo getServerInfo()
          Get the server this client is connected to
 ServerSessionManager getSessionManager()
          Get the session manager that handles login for this session.
 com.sun.sgs.client.simple.SimpleClient getSimpleClient()
          Get the simple client connected to the Darkstar server.
 WonderlandSession.Status getStatus()
          Get the status of this client.
 WonderlandIdentity getUserID()
          Get the user ID associated with this session.
 void login(LoginParameters loginParams)
          Log in to the server.
 void logout()
          Logout from the server.
 void removeSessionStatusListener(SessionStatusListener listener)
          Remove a listener that will be notified when the status of this session changes.
 void send(ClientConnection client, Message message)
          Send a message to the server over the session channel on behalf of the given client.
 

Method Detail

getServerInfo

WonderlandServerInfo getServerInfo()
Get the server this client is connected to

Returns:
the server

getSessionManager

ServerSessionManager getSessionManager()
Get the session manager that handles login for this session.

Returns:
the session manager

getStatus

WonderlandSession.Status getStatus()
Get the status of this client.

Returns:
the current status of the client

getSimpleClient

com.sun.sgs.client.simple.SimpleClient getSimpleClient()
Get the simple client connected to the Darkstar server. This will only be valid after the login method succeeds.

Returns:
the darkstar client

login

void login(LoginParameters loginParams)
           throws LoginFailureException
Log in to the server. This will connect to the given server, and wait for the login to succeed. If the login succeeds, negotiate a protocol using the Wonderland protocol negotiation mechanism. This method blocks until both the login and protocol selection have been verified by the server.

If this method returns normally, then the login and protocol selection succeeded. If it throws a LoginFailureException, the login has failed.

Parameters:
loginParams - the parameters required for login
Throws:
LoginFailureException - if the login fails

logout

void logout()
Logout from the server.


getID

java.math.BigInteger getID()
Get the ID of this session. The ID is a unique identifier for this particular session that is globally unique across all sessions attached to the same server.

The ID is only valid when the client status is CONNECTED. Attempting to read the ID when the status is anything else will cause an IllegalStateException.

The ID is generated on the server and communicated as part of the login process. It is available at the time that the client is notified of the state change.


getUserID

WonderlandIdentity getUserID()
Get the user ID associated with this session. This ID is maintained byt the server based on the user's login credentials.

The ID is generated on the server and communicated as part of the login process. It is available at the time that the client is notified of the state change.


connect

void connect(ClientConnection client)
             throws ConnectionFailureException
Connect a new client to this session, with no properties. This is identical to calling connect(client, null).

Parameters:
client - the client to connect
Throws:
ConnectionFailureException - of the connection fails
See Also:
connect(ClientConnect, Properties)

connect

void connect(ClientConnection client,
             java.util.Properties properties)
             throws ConnectionFailureException
Connect a new client to this session. When a client is connected to this session, it will interact with the server associated with this session.

Only one client of any given ConnectionType may be connected to the server at any time. Attempting to connect a second client of the same type will result in an ConnectionFailureException.

Clients may only be connected when a session is in the DISCONNECTED state. If the session is in any other state, an ConnectionFailureException will be thrown. When a session disconnects, all clients are disconnected, and must be re-connected to start working again.

A client may optionally specify properties to use when making the given connection. If properties are specified, the client will send the properties to the server, where they will be available in the ClientConnectionManager.clientConnected(). If null is passed in for the properties argument, and empty properties will be sent to the server.

Parameters:
client - the client to connect
properties - the properties object to send to the server
Throws:
ConnectionFailureException - of the connection fails

disconnect

void disconnect(ClientConnection client)
Disconnect a previously connected client from this session.

Parameters:
client - the client to logout

getConnection

ClientConnection getConnection(ConnectionType type)
Get the connected ClientConnection for the given ConnectionType.

Parameters:
type - the client type to get
Returns:
the connected client for the given type, or null if no client of the given type is connected

getConnection

<T extends ClientConnection> T getConnection(ConnectionType type,
                                             java.lang.Class<T> clazz)
Get the attched ClientConnection for the given ConnectionType.

Parameters:
type - the client type to get
clazz - the class of client to return
Returns:
the connected client for the given type, or null if no client of the given type is connected
Throws:
java.lang.ClassCastException - if the client for the given client type is not assignable to the given type

getConnections

java.util.Collection<ClientConnection> getConnections()
Get all clients connected to this session

Returns:
the clients connected to this session

send

void send(ClientConnection client,
          Message message)
Send a message to the server over the session channel on behalf of the given client. The client must be successfully connected to this session in order for the send to work.

Parameters:
client - the client that is sending the message
message - the message to send
Throws:
MessageException - if there is an error getting the bytes for the message
java.lang.IllegalStateException - if the client is not connected to this session or the session is not connected

addSessionStatusListener

void addSessionStatusListener(SessionStatusListener listener)
Add a listener that will be notified when the status of this session changes.

Parameters:
listener - the listener to add

removeSessionStatusListener

void removeSessionStatusListener(SessionStatusListener listener)
Remove a listener that will be notified when the status of this session changes.

Parameters:
listener - the listener to remove


Open Wonderland - http://openwonderland.org