com.sun.sgs.protocol.simple
Class SimpleSgsProtocol

java.lang.Object
  extended by com.sun.sgs.protocol.simple.SimpleSgsProtocol

public class SimpleSgsProtocol
extends Object

SGS Protocol constants.

A protocol message is constructed as follows:

A ByteArray is encoded in a context dependent fashion. If the ByteArray is the only content, or if the ByteArray is the last piece of content (that is, if the length of the ByteArray can be determined by the payload length and the length of what has come before), the ByteArray is encoded as

If there is other content that follows the ByteArray, then the ByteArray is encoded as

A String is encoded as follows:

Note that these encodings only apply to those data items that are specified explicitly in the protocol. Application data, passed as a ByteArray, may contain any information, but will need to be parsed (and, if necessary, converted to and from a network representation) by the application or client.

The total length of a message must not be greater than 65535 bytes; given the header information this means that the payload of a message cannot be greater than 65532 bytes. If a message larger than this must be sent, it is the responsibility of the sender to break the message into pieces and of the receiver to re-assemble those pieces.

Behavior not specified in this document is left as an implementation decision for the particular client and server. Information on the implementation characteristics of the Project Darkstar server can be found in the overview for the implementation.


Field Summary
static byte CHANNEL_JOIN
          Channel join.
static byte CHANNEL_LEAVE
          Channel leave.
static byte CHANNEL_MESSAGE
          Channel message.
static byte LOGIN_FAILURE
          Login failure.
static byte LOGIN_REDIRECT
          Login redirect.
static byte LOGIN_REQUEST
          Login request from a client to a server.
static byte LOGIN_SUCCESS
          Login success.
static byte LOGOUT_REQUEST
          Logout request from a client to a server.
static byte LOGOUT_SUCCESS
          Logout success.
static int MAX_MESSAGE_LENGTH
          The maximum length of a protocol message: 65535 bytes.
static int MAX_PAYLOAD_LENGTH
          The maximum payload length: 65532 bytes.
static byte RECONNECT_FAILURE
          Reconnect failure.
static byte RECONNECT_REQUEST
          Reconnection request.
static byte RECONNECT_SUCCESS
          Reconnect success.
static byte SESSION_MESSAGE
          Session message.
static byte VERSION
          The version number, currently 0x04.
 
Method Summary
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MAX_MESSAGE_LENGTH

public static final int MAX_MESSAGE_LENGTH
The maximum length of a protocol message: 65535 bytes.

See Also:
Constant Field Values

MAX_PAYLOAD_LENGTH

public static final int MAX_PAYLOAD_LENGTH
The maximum payload length: 65532 bytes.

See Also:
Constant Field Values

VERSION

public static final byte VERSION
The version number, currently 0x04.

See Also:
Constant Field Values

LOGIN_REQUEST

public static final byte LOGIN_REQUEST
Login request from a client to a server. This message should only be sent to a server; if received by a client it should be ignored.
Opcode: 0x10
Payload: The protocol version will be checked by the server to insure that the client and server are using the same protocol or versions of the protocol that are compatible. If the server determines that the protocol version used by the sender and the protocol version or versions required by the server are not compatible, the server will disconnect the client. In cases where the protocols being used are not compatible, no other communication between the client and the server is guaranteed to be understood.

The name and password strings are passed to the server's authentication mechanism. After the server processes the login request, the server sends one of the following acknowledgments to the client:

If a client is currently logged in, the result of receiving a LOGIN_REQUEST is not defined by the protocol, but is an implementation-dependent detail of the server.

See Also:
Constant Field Values

LOGIN_SUCCESS

public static final byte LOGIN_SUCCESS
Login success. Server response to a client's LOGIN_REQUEST.
Opcode: 0x11
Payload: The reconnectionKey is an opaque reference that can be held by the client for use in case the client is disconnected and wishes to reconnect to the server with the same identity using a RECONNECT_REQUEST.

See Also:
Constant Field Values

LOGIN_FAILURE

public static final byte LOGIN_FAILURE
Login failure. Server response to a client's LOGIN_REQUEST.
Opcode: 0x12
Payload: This message indicates that the server rejects the LOGIN_REQUEST for some reason, for example

See Also:
Constant Field Values

LOGIN_REDIRECT

public static final byte LOGIN_REDIRECT
Login redirect. Server response to a client's LOGIN_REQUEST.
Opcode: 0x13
Payload: This message indicates a redirection from the node to which the LOGIN_REQUEST was sent to another node. The client receiving this request should shut down the connection to the original node and establish a connection to the node indicated by the hostname and port in the payload. The client should then attempt to log in to the node to which it has been redirected by sending a LOGIN_REQUEST to that node.

See Also:
Constant Field Values

RECONNECT_REQUEST

public static final byte RECONNECT_REQUEST
Reconnection request. Client requesting reconnect to a server.
Opcode: 0x20
Payload: This message requests that the client be reconnected to an existing client session with the server. The reconnectionKey must match the one that the client received in the previous LOGIN_SUCCESS or RECONNECT_SUCCESS message (if reconnection was performed subsequent to login). If reconnection is successful, the server acknowledges the request with a RECONNECT_SUCCESS message containing a new reconnectionKey. If reconnection is not successful, a RECONNECT_FAILURE message is sent to the client. If the client receives a RECONNECT_FAILURE message, the client should disconnect from the server.

See Also:
Constant Field Values

RECONNECT_SUCCESS

public static final byte RECONNECT_SUCCESS
Reconnect success. Server response to a client's RECONNECT_REQUEST.
Opcode: 0x21
Payload: Indicates that a RECONNECT_REQUEST has been successful. The message will include a reconnectionKey that can be used in a subsequent reconnect requests from the client. Reciept of this message indicates that the client session has been re-established.

See Also:
Constant Field Values

RECONNECT_FAILURE

public static final byte RECONNECT_FAILURE
Reconnect failure. Server response to a client's RECONNECT_REQUEST.
Opcode: 0x22
Payload: This response indicates that a reconnect request could not be honored by the server. This could be because of an invalid reconnect key, or because too much time has elapsed between the session disconnection and the reconnect request (which, in turn, may cause the server to discard the session state). The string returned details the reason for the denial of reconnection.

See Also:
Constant Field Values

SESSION_MESSAGE

public static final byte SESSION_MESSAGE
Session message. May be sent by the client or the server. Maximum length is 65532 bytes. Larger messages require fragmentation and reassembly above this protocol layer.
Opcode: 0x30
Payload: This message allows information to be sent between the client and the server. The content of the message is application dependent, and the mechanisms for constructing and parsing these messages is an application-level task.

See Also:
Constant Field Values

LOGOUT_REQUEST

public static final byte LOGOUT_REQUEST
Logout request from a client to a server.
Opcode: 0x40
No payload.
This message will cause the client to be logged out of the server. The server will remove all of the client's channel memberships. Any message (other than LOGIN_REQUEST) sent by the client after sending this message will be ignored, and any message will need to be sent on a new connection to the server.

See Also:
Constant Field Values

LOGOUT_SUCCESS

public static final byte LOGOUT_SUCCESS
Logout success. Server response to a client's LOGOUT_REQUEST.
Opcode: 0x41
No payload.
This message is sent from the server to the client to indicate that a LOGOUT_REQUEST has been received and that the client has been logged out of the current session. On receipt of this message, the client should shut down any networking resources that are used to communicate with the server.

See Also:
Constant Field Values

CHANNEL_JOIN

public static final byte CHANNEL_JOIN
Channel join. Server notifying a client that it has joined a channel.
Opcode: 0x50
Payload: This message is sent from the server to the client to indicate that the client has been added to the channel identified by the channel name and channel ID contained in the message.

See Also:
Constant Field Values

CHANNEL_LEAVE

public static final byte CHANNEL_LEAVE
Channel leave. Server notifying a client that the client has left a channel.
Opcode: 0x51
Payload: This message is sent from the server indicating to the client that the client has been removed from the channel with the indicated channel ID. The client can no longer send messages on the channel.

See Also:
Constant Field Values

CHANNEL_MESSAGE

public static final byte CHANNEL_MESSAGE
Channel message. May be sent by the client or the server. Maximum length is 65532 bytes minus the sum of the channel ID size and two bytes (the size of the unsigned short indicating the channel Id size). Larger messages require fragmentation and reassembly above this protocol layer.
Opcode: 0x52
Payload: This message requests that the specified message be sent to all members of the specified channel. If the client sending the request is not a member of the channel, the message will be rejected by the server. The server may also refuse to send the message, or alter the message, because of application-specific logic.

See Also:
Constant Field Values

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

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