com.sun.sgs.client.simple
Class SimpleClient

java.lang.Object
  extended by com.sun.sgs.client.simple.SimpleClient
All Implemented Interfaces:
ServerSession

public class SimpleClient
extends Object
implements ServerSession

An implementation of ServerSession that clients can use to manage logging in and communicating with the server. A SimpleClient is used to establish (or re-establish) a login session with the server, send messages to the server, and log out.

A SimpleClient is constructed with a SimpleClientListener which receives connection-related events as well as messages from the server application.

If the server session associated with a simple client becomes disconnected, then its send method will throw IllegalStateException. A disconnected client can use the login method to log in again.


Constructor Summary
SimpleClient(SimpleClientListener listener)
          Creates an instance of this class with the specified listener.
 
Method Summary
 boolean isConnected()
          Returns true if this session is connected, otherwise returns false.
 void login(Properties props)
          Initiates a login session with the server.
 void logout(boolean force)
          Initiates logging out from the server.
 void send(ByteBuffer message)
          Sends the message contained in the specified ByteBuffer to the server.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SimpleClient

public SimpleClient(SimpleClientListener listener)
Creates an instance of this class with the specified listener. Once this client is logged in (by using the login method), the specified listener receives connection-related events, receives messages from the server, and also receives notification of each channel the client is joined to. If this client becomes disconnected for any reason, it may use the login method to log in again.

Parameters:
listener - a listener that will receive events for this client
Method Detail

login

public void login(Properties props)
           throws IOException
Initiates a login session with the server. A session is established asynchronously with the server as follows:

First, this client attempts to establish a connection with the server. If the client fails to establish a connection, then the client listener's disconnected method is invoked with a String indicating the reason for the failure.

If a connection with the server is successfully established, this client's login credential is obtained by invoking its listener's getPasswordAuthentication method with a login prompt.

Next, this client sends a login request to the server. If the login request is malformed, the client listener's disconnected method is invoked with a String indicating the reason for the failure or null if no reason can be determined.

If the client's login credential (as obtained above) is verified, then the client listener's loggedIn method is invoked. If, however, the login fails due to a login authentication failure or some other failure on the server while processing the login request, the client listener's loginFailed method is invoked with a String indicating the reason for the failure.

If this client is disconnected for any reason (including login failure), this method may be used again to log in.

The supported connection properties are:

Key Description of Associated Value
host SGS host address (required)
port SGS port (required)

Parameters:
props - the connection properties to use in creating the client's session
Throws:
IOException - if a synchronous IO error occurs
IllegalStateException - if this session is already connected or connecting
SecurityException - if the caller does not have permission to connect to the remote endpoint

isConnected

public boolean isConnected()
Returns true if this session is connected, otherwise returns false.

Specified by:
isConnected in interface ServerSession
Returns:
true if this session is connected, and false otherwise

logout

public void logout(boolean force)
Initiates logging out from the server. If force is true then this session is forcibly terminated, for example, by terminating the associated client's network connections. If force is false, then this session is gracefully disconnected, notifying the server that the client logged out. When a session has been logged out, gracefully or otherwise, the disconnected method is invoked on this session's associated ServerSessionListener passing a boolean indicating whether the disconnection was graceful.

If this server session is already disconnected, then an IllegalStateException is thrown.

Specified by:
logout in interface ServerSession
Parameters:
force - if true, this session is forcibly terminated; otherwise the session is gracefully disconnected

send

public void send(ByteBuffer message)
          throws IOException
Sends the message contained in the specified ByteBuffer to the server. 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 specified message is sent asynchronously to the server; therefore, a successful invocation of this method does not indicate that the given message was successfully sent. Messages that are received by the server are delivered in sending order.

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 server by this invocation.

Note: The server does not guarantee delivery of any session message (sent via this method) that is received by the server before the sending client is logged in. Therefore messages sent before this client is logged in, that is, before the SimpleClientListener.loggedIn method is invoked, may be dropped by the server.

Specified by:
send in interface ServerSession
Parameters:
message - a message
Throws:
IOException - if this session is disconnected or an IO error occurs

RedDwarf, Version 0.10.0
2010-02-12 09:11:07

Copyright © 2010 The RedDwarf Authors. All rights reserved
Copyright © 2007-2010 Sun Microsystems, Inc. All rights reserved