com.cafesoft.core.message
Interface Connection

All Superinterfaces:

LifecycleListener, Recyclable

All Known Implementing Classes:

StandardConnection

public interface Connection

extends LifecycleListener, Recyclable

A client's active network connection to its Message Service Provider.

A Connection object encapsulates an open connection with a MessageServiceProvider. The open connection is designed to be protocol independent however, typically it is a TCP/IP socket. In addition, the Connection object is a factory for creating both MessageSender and MessageReceiver objects. The Connection object is responsible for authenticating itself with the server that it is connecting to.

The Connection object has a finite state attached to it.

State Chart:

• CREATED: The Connection object has been created and several objects required by the Connection have been instantiated
• STARTED: The Connection object has created and initiated all of its threads that are required for operation.
• AUTHENTICATED: The Connection object has been authenticated by the "Authenticating Authority"
• READY: Access to the Connection object has been checked and approved by the "Access Control Authority"
• CLOSED: The Connection object has sent to the other side a KILL packet to initiate the closure of the Connection
• STOPPED: The Connection object's threads have all been stopped and destroyed.
• DESTROYED: The Connection object's recycle method has been called and all objects have been cleaned up and readied for the garbage collector

State Transitions Allowed:

• CREATED State:
  • CREATED --> STARTED
  • CREATED --> STOPPED
  • CREATED --> DESTROYED
• STARTED State:
  • STARTED --> AUTHENTICATED
  • STARTED --> CLOSED
  • STARTED --> STOPPED
• AUTHENTICATED State:
  • AUTHENTICATED --> READY
  • AUTHENTICATED --> CLOSED
  • AUTHENTICATED --> STOPPED
• READY State:
  • READY --> CLOSED
  • READY --> STOPPED
• CLOSED State:
  • CLOSED --> STOPPED
• STOPPED State:
  • STOPPED --> DESTROYED
• DESTROYED State:
  • DESTROYED --> END OF CONNECTION STATE

Since:

1/31/02

Method Summary

void	addConnectionEventListener(ConnectionEventListener listener) Add a ConnectionEventListener to this connection.
void	authenticate(String type, Object principal, Object credential, int timeout) Authenticate the Connection This method will send a Packet message to the Server side to authenticate the usage of this Connection with the system.
void	checkAccess(int timeout) Check the Connection's access This method will send a Packet message to the Server side to check access on the Connection with the system.
void	close() Closes the Connection.
MessageReceiver	createMessageReceiver(String contentType) Create a generic MessageReceiver on the Connection.
MessageSender	createMessageSender(String contentType) Create a MessageSender on the Connection.
void	destroy() Destroy the Connection This method will recycle the Connection object and will invoke recycle on all objects used by the Connection object
ConnectionMetaData	getConnectionMetaData() Get the ConnectionMetaData object This object will contain all pertinant meta data about the Connection Object
ConnectionStatus	getStatus() Get the status of the Connection
void	removeConnectionEventListener(ConnectionEventListener listener) Remove a ConnectionEventListener from this connection.
void	sendMessageToReceiver(Message message) Sends a message to a remote MessageReceiver.
void	sendMessageToReceiver(Message message, RemoteEndPoint receiver) Sends a message to the specified remote MessageReceiver EndPoint.
void	start() Start the Connection.

Methods inherited from interface com.cafesoft.core.lifecycle.LifecycleListener

lifecycleEvent

Methods inherited from interface com.cafesoft.core.util.Recyclable

recycle

Method Detail

start

public void start()
           throws MessageServiceException,
                  IllegalConnectionStateException

Start the Connection.

Once started the Connection object can be used to send "low" level messages to the connecting side. No "high" level Message Framework objects such as MessageSenders and MessageReceivers can be created or used.

Throws:

MessageServiceException - thrown if Connection unable to connect with the message server

IllegalConnectionStateException - thrown if the Connection object is in ANY state other than the CREATED state.

close

public void close()
           throws MessageServiceException,
                  IllegalConnectionStateException

Closes the Connection.

This method signifies the "graceful" closure of a Connection object. It gives the Connection object a chance to instantiate a shutdown protocol. In addition, this method will change the state of the Connection to that of CLOSED. This will make the usage of MessageSenders and MessageReceivers useless.

Throws:

MessageServiceException - if the Message Provider fails to close the connection due to some internal error. For example, a failure to release resources or to close the socket associated with the Connection.

IllegalConnectionStateException - thrown if the Connection object is in any state other than the STARTED or READY state.

destroy

public void destroy()
             throws IllegalConnectionStateException

Destroy the Connection

This method will recycle the Connection object and will invoke recycle on all objects used by the Connection object

Throws:

IllegalConnectionStateException - thrown if the Connection object is in any state other than the CREATED or STOPPED.

authenticate

public void authenticate(String type,
                         Object principal,
                         Object credential,
                         int timeout)
                  throws MessageServiceException,
                         IllegalConnectionStateException,
                         ConnectionAuthenticationException

Authenticate the Connection

This method will send a Packet message to the Server side to authenticate the usage of this Connection with the system. This method can only be called once and is a one-time try. If authentication fails the Connection will be closed.

Parameters:

type - the type of authentication the server side should perform

principal - the Principal object

credential - the Credential object

timeout - the length in seconds to wait before declaring authentication failed

Throws:

IllegalConnectionStateException - thrown if the Connection object is in any state other than STARTED

MessageServiceException - thrown if there is an error trying to use the Message Framework to send the Authentication packet

ConnectionAuthenticationException - thrown if the client trying to authenticate does not get a response back from the server within the given timeout period

checkAccess

public void checkAccess(int timeout)
                 throws MessageServiceException,
                        IllegalConnectionStateException,
                        ConnectionAccessException

Check the Connection's access

This method will send a Packet message to the Server side to check access on the Connection with the system. This method can only be called once and is a one-time try. If access fails the Connection will be closed.

Parameters:

timeout - the length of time for which the Connection object should wait before timing out and abort checking access on the Connection

Throws:

MessageServiceException - thrown if an error occurs with the Message Framework that prevents the access check from being performed.

IllegalConnectionStateException - thrown if the Connection Object is not in the proper state to perform an access check

ConnectionAccessException - thrown if the client does not receive a response from the server within the given timeout period

getStatus

public ConnectionStatus getStatus()

Get the status of the Connection

Returns:

returns a ConnectionStatus object that contains the status of the Connection

getConnectionMetaData

public ConnectionMetaData getConnectionMetaData()

Get the ConnectionMetaData object

This object will contain all pertinant meta data about the Connection Object

Returns:

the ConnectionMetaData Object

addConnectionEventListener

public void addConnectionEventListener(ConnectionEventListener listener)

Add a ConnectionEventListener to this connection.

Parameters:

listener - The listener to add

removeConnectionEventListener

public void removeConnectionEventListener(ConnectionEventListener listener)

Remove a ConnectionEventListener from this connection.

Parameters:

listener - The listener to remove

createMessageSender

public MessageSender createMessageSender(String contentType)
                                  throws MessageServiceException,
                                         IllegalConnectionStateException

Create a MessageSender on the Connection.

Parameters:

contentType - the content type for the messages that the MessageSender will send.

Returns:

a MessageSender through which messages may be sent

Throws:

MessageServiceException - if an error while attempting to create the MessageSender

IllegalConnectionStateException - thrown if the Connection object is in any state other than READY

createMessageReceiver

public MessageReceiver createMessageReceiver(String contentType)
                                      throws MessageServiceException,
                                             IllegalConnectionStateException

Create a generic MessageReceiver on the Connection.

Parameters:

contentType - the content type for the messages that the MessageReceiver will receive

Returns:

a MessageReceiver through which messages may be received

Throws:

MessageServiceException - if an error while attempting to create the MessageReceiver

IllegalConnectionStateException - thrown if the Connection object is in any state other than READY

sendMessageToReceiver

public void sendMessageToReceiver(Message message)
                           throws MessageServiceException,
                                  IllegalConnectionStateException

Sends a message to a remote MessageReceiver.

The message is asynchronously sent to a MessageReceiver specified by setting the receiver id message header.

Parameters:

message - the message to send

Throws:

MessageServiceException - if the Connection fails to send the message due to some internal error or if an invalid Message or receiver id is specified

IllegalConnectionStateException - thrown if the Connection object is in any state other than READY

sendMessageToReceiver

public void sendMessageToReceiver(Message message,
                                  RemoteEndPoint receiver)
                           throws MessageServiceException,
                                  IllegalConnectionStateException

Sends a message to the specified remote MessageReceiver EndPoint.

The message is asynchronously sent to a MessageReceiver specified by the RemoteEndPoint.

Parameters:

message - the message to send

receiver - the remote MessageReceiver endpoint

Throws:

MessageServiceException - the Connection fails to send the message due to some internal error or if an invalid Message or receiver id is specified

IllegalConnectionStateException - thrown if the Connection object is in any state other than READY