gcs
Class GcsConnection

java.lang.Object
  gcs.GcsConnection

Direct Known Subclasses:

SpreadGcsConnection

public abstract class GcsConnection
extends java.lang.Object

Represents an abstraction of connection with the RestGroups communication system.

Connecting and disconnecting from the RestGroups server can be accomplished by calling connect(GcsSettings, String, boolean, boolean) and disconnect() methods, respectively.

The multicast(GcsMessage) and multicast(GcsMessage[]) methods are used to send messages encapsulated with GcsMessage to other RestGroups users.

To check the availability of new messages the poll() method should be used. receive() and receive(int) are blocking methods which can be used to retrieve new messages from the RestGroups server.

Messages can also be received through a listener. The listener class has to implement GcsAdvancedMessageListener or GcsBasicMessageListener interface and be added to the GcsConnection with add(GcsAdvancedMessageListener) or add(GcsBasicMessageListener) methods, respectively.

Author:

tkob

Constructor Summary

protected

GcsConnection() Empty constructor, provided for convenience.

Method Summary

abstract void	add(GcsAdvancedMessageListener listener) Sets up the GcsAdvancedMessageListener listener.
abstract void	add(GcsBasicMessageListener listener) Sets up the GcsBasicMessageListener listener.
abstract void	connect(GcsSettings settings, java.lang.String privateName, boolean priority, boolean groupMembership) Allows connecting to the RestGroups server.
abstract void	disconnect() Allows disconnecting from the RestGroups server.
abstract GcsGroup	getPrivateGroup() Returns the GcsGroup object representing the private group for this connection.
abstract void	multicast(GcsMessage message) Sends the message encapsulated in the GcsMessage object to groups specified in this object.
abstract void	multicast(GcsMessage[] messages) Sends multiple messages encapsulated in the GcsMessage objects to groups specified inside those objects.
abstract boolean	poll() Checks for unread messages for this connection.
abstract GcsMessage	receive() Returns next unread message for this connection if available.
abstract GcsMessage[]	receive(int numMessages) Returns next numMessages for this connection if available.
abstract void	remove(GcsAdvancedMessageListener listener) Deactivates the GcsAdvancedMessageListener listener for this connection.
abstract void	remove(GcsBasicMessageListener listener) Deactivates the GcsBasicMessageListener listener for this connection.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GcsConnection

protected GcsConnection()

Empty constructor, provided for convenience.

Method Detail

add

public abstract void add(GcsAdvancedMessageListener listener)
                  throws GcsException

Sets up the GcsAdvancedMessageListener listener. Once it is done, every time a membership or regular message is received GcsAdvancedMessageListener.membershipMessageReceived(GcsMessage) or GcsAdvancedMessageListener.regularMessageReceived(GcsMessage) method is called, respectively.

Parameters:

listener - object implementing the GcsAdvancedMessageListener interface

Throws:

GcsException

See Also:

remove(GcsAdvancedMessageListener)

add

public abstract void add(GcsBasicMessageListener listener)
                  throws GcsException

Sets up the GcsBasicMessageListener listener. Once it is done, every time a regular message is received, GcsBasicMessageListener.messageReceived(GcsMessage) method is called. Membership messages are omitted.

Parameters:

listener - object implementing the GcsBasicMessageListener interface

Throws:

GcsException

See Also:

remove(GcsBasicMessageListener)

connect

public abstract void connect(GcsSettings settings,
                             java.lang.String privateName,
                             boolean priority,
                             boolean groupMembership)
                      throws GcsException

Allows connecting to the RestGroups server. Once the connection is established the GcsConnection object can be used to send and receive messages through the RestGroups communication system.

Parameters:

settings - stores parameters concerning the RestGroups server

privateName - name describing this connections user

priority - defines if this is a priority connection

groupMembership - defines if the membership messages are being received on this connection

Throws:

GcsException - if the connection could not be established

disconnect

public abstract void disconnect()
                         throws GcsException

Allows disconnecting from the RestGroups server.

Throws:

GcsException - if difficulties during disconnecting from the RestGroups server were encountered or the connection has not been established

getPrivateGroup

public abstract GcsGroup getPrivateGroup()
                                  throws GcsException

Returns the GcsGroup object representing the private group for this connection.

Returns:

the private group object for this connection

Throws:

GcsException

multicast

public abstract void multicast(GcsMessage message)
                        throws GcsException

Sends the message encapsulated in the GcsMessage object to groups specified in this object.

Parameters:

message - a message to be send

Throws:

GcsException - if errors were encountered during sending the message or the connection is broken

multicast

public abstract void multicast(GcsMessage[] messages)
                        throws GcsException

Sends multiple messages encapsulated in the GcsMessage objects to groups specified inside those objects.

Parameters:

messages - array of messages to be send

Throws:

GcsException - if errors were encountered during sending the messages or the connection is broken

poll

public abstract boolean poll()
                      throws GcsException

Checks for unread messages for this connection.

Returns:

true if there is at least one unread message, false otherwise

Throws:

GcsException - if errors were encountered during checking for new messages or the connection is broken

receive

public abstract GcsMessage receive()
                            throws GcsException,
                                   java.io.InterruptedIOException

Returns next unread message for this connection if available. It blocks otherwise.

Returns:

received message

Throws:

GcsException - if errors were encountered during reception of the message or the connection is broken

java.io.InterruptedIOException

receive

public abstract GcsMessage[] receive(int numMessages)
                              throws GcsException,
                                     java.io.InterruptedIOException

Returns next numMessages for this connection if available. It blocks otherwise.

Parameters:

numMessages - number of messages to be returned

Returns:

array of unread messages

Throws:

GcsException - if errors were encountered during reception of the messages or the connection is broken

java.io.InterruptedIOException

remove

public abstract void remove(GcsAdvancedMessageListener listener)
                     throws GcsException

Deactivates the GcsAdvancedMessageListener listener for this connection. Once its done, both membership and regular messages will be stored on the server until the listener will be setup again or method receive() (receive(int)) called.

Parameters:

listener - the listener to be removed from this connection

Throws:

GcsException - if errors were encountered during removal of the listener or if it was never set up.

See Also:

add(GcsAdvancedMessageListener)

remove

public abstract void remove(GcsBasicMessageListener listener)
                     throws GcsException

Deactivates the GcsBasicMessageListener listener for this connection. Once its done, regular messages will be stored on the server until the listener will be setup again or method (receive() ( receive(int)) called.

Parameters:

listener - the listener to be removed from this connection

Throws:

GcsException - if errors were encountered during removal of the listener or if it was never set up.

See Also:

add(GcsBasicMessageListener)