com.sun.sgs.app
Interface ClientSession

All Superinterfaces:
ManagedObject

public interface ClientSession
extends ManagedObject

Interface representing a single, connected login session between a client and the server. Classes that implement ClientSession must also implement Serializable.

When a client logs in, the application's AppListener.loggedIn method is invoked with a new ClientSession instance which represents the current connection between that client and the server. By returning a unique ClientSessionListener from the loggedIn method for each given client session, the application will receive notification when a client session sends a message, is disconnected, or logs out. To explicitly disconnect a ClientSession, remove the associated ClientSession object from the data manager using the DataManager.removeObject method.

A ClientSession is used to identify a client that is logged in, to send messages to that client, and to forcibly disconnect that client from the server.

A session is considered disconnected if one of the following occurs:

If a client associated with a ClientSession becomes disconnected due to one of these conditions, the disconnected method is invoked on that session's registered ClientSessionListener with a boolean that if true indicates the client logged out gracefully.

Once a client becomes disconnected, its ClientSession becomes invalid and can no longer be used to communicate with that client and should be removed from the data manager. When that client logs back in again, a new session is established with the server.


Method Summary
 int getMaxMessageLength()
          Return the maximum message length supported by this session.
 String getName()
          Returns the login name used to authenticate this session.
 boolean isConnected()
          Returns true if the client is connected, otherwise returns false.
 ClientSession send(ByteBuffer message)
          Sends a message contained in the specified ByteBuffer to this session's client with the delivery guarantee of Delivery.RELIABLE.
 ClientSession send(ByteBuffer message, Delivery delivery)
          Sends a message contained in the specified ByteBuffer to this session's client in a manner that satisfies the specified delivery guarantee.
 Set<Delivery> supportedDeliveries()
          Returns a set containing the delivery guarantees supported by this session.
 

Method Detail

getName

String getName()
Returns the login name used to authenticate this session.

Returns:
the name used to authenticate this session
Throws:
IllegalStateException - if this session is disconnected
TransactionException - if the operation failed because of a problem with the current transaction

supportedDeliveries

Set<Delivery> supportedDeliveries()
Returns a set containing the delivery guarantees supported by this session. The returned set is serializable.

Returns:
a set containing the supported delivery guarantees

getMaxMessageLength

int getMaxMessageLength()
Return the maximum message length supported by this session.

Returns:
the maximum message length.

send

ClientSession send(ByteBuffer message)
Sends a message contained in the specified ByteBuffer to this session's client with the delivery guarantee of Delivery.RELIABLE. The message starts at the buffer's current position and ends at the buffer's limit. The buffer's position is not modified by this operation.

The ByteBuffer may be reused immediately after this method returns. Changes made to the buffer after this method returns will have no effect on the message sent to the client by this invocation.

This method is equivalent to invoking send with the specified message and Delivery.RELIABLE.

Parameters:
message - a message
Returns:
this client session
Throws:
IllegalStateException - if this session is disconnected
IllegalArgumentException - if the specified message length exceeds getMaxMessageLength()
MessageRejectedException - if there are not enough resources to send the specified message
DeliveryNotSupportedException - if this client session does not support reliable delivery
TransactionException - if the operation failed because of a problem with the current transaction

send

ClientSession send(ByteBuffer message,
                   Delivery delivery)
Sends a message contained in the specified ByteBuffer to this session's client in a manner that satisfies the specified delivery guarantee. The message starts at the buffer's current position and ends at the buffer's limit. The buffer's position is not modified by this operation.

When possible, the message should be delivered using the most efficient means to satisfy the delivery guarantee. However, a stronger delivery guarantee may be used to deliver the message if the underlying protocol only supports stronger delivery guarantees. If the protocol is not able to satisfy the specified delivery guarantee (e.g., only supports weaker delivery guarantees than the one specified), then a DeliveryNotSupportedException will be thrown.

The ByteBuffer may be reused immediately after this method returns. Changes made to the buffer after this method returns will have no effect on the message sent to the client by this invocation.

Parameters:
message - a message
delivery - a delivery guarantee
Returns:
this client session
Throws:
IllegalStateException - if this session is disconnected
IllegalArgumentException - if the specified message length exceeds getMaxMessageLength()
MessageRejectedException - if there are not enough resources to send the specified message
DeliveryNotSupportedException - if the specified delivery guarantee cannot be satisfied
TransactionException - if the operation failed because of a problem with the current transaction

isConnected

boolean isConnected()
Returns true if the client is connected, otherwise returns false.

Returns:
true if the client is connected, otherwise returns false
Throws:
TransactionException - if the operation failed because of a problem with the current transaction

Project Darkstar, Version 0.9.9.6
2009-05-08 15:39:40

Copyright © 2007-2009 Sun Microsystems, Inc. All rights reserved