ie.ncl.msg
Interface Connection

All Known Subinterfaces:

MessageStore, Receiver, Sender

All Known Implementing Classes:

CimdConnection, ConnectionManager, GsmModem, LongMessageReceiver, Loopback, ie.ncl.msg.impl.SimpleConnection, SmppConnection, UCPConnection

public interface Connection

This interface is used to define the basic methods required of a message connection.

A Sender and Receiver interface object extends the Connection interface.

A connection contains methods to specify error callbacks, close a connection and set and get message attribute defaults.

Connection specific message attribute defaults can be added and retrieved from the connection object. They are identified by the message type which is just an arbirary string identifier.

During a send operation, if the type of a message matches the type of a set of defaults, then the associated attributes are used for that message. During a send message operation, defaults DO NOT override message specific attributes.

During a receive message operation, the best matched attribute set with those of the received message defines the type.

See Also:

Sender, Receiver

Field Summary

static int	CONNECTED The link is connected (and not reconnecting).
static int	NOT_CONNECTED The link is not connected (and not reconnecting).
static int	NOT_USED
static int	RECONNECTING The link was connected and is now in the process of reconnecting.

Method Summary

void	close() Close the connection.
void	connect() Connect with the service.
boolean	connected() Deprecated. Use getConnectionStatus instead
int	getConnectionStatus() Query the status of the link.
Attributes	getTypeDefaults(java.lang.String type) Get connection specific message attribute defaults as identified by the type.
void	init(java.util.Properties properties) Initialise the object with settings specified in the properties.
void	init(java.util.Properties properties, java.lang.String prefix) Initialise the object with settings specified in the properties where the relevant property names have been prefixed with the specified prefix.
void	putTypeDefaults(java.lang.String type, Attributes props) Set connection specific message attribute defaults as identified by the type.
void	setErrorListener(ErrorListener listener) Specify a callback called if an connection error occurs in the underlying connection.
void	shutdown() Shutdown the connection.

Field Detail

NOT_USED

static final int NOT_USED

See Also:

Constant Field Values

NOT_CONNECTED

static final int NOT_CONNECTED

The link is not connected (and not reconnecting). The link will be in this state before a connection is established and after it has been closed.

See Also:

getConnectionStatus(), Constant Field Values

CONNECTED

static final int CONNECTED

The link is connected (and not reconnecting). The link is in this state when the a network and session layer has been established.

See Also:

getConnectionStatus(), Constant Field Values

RECONNECTING

static final int RECONNECTING

The link was connected and is now in the process of reconnecting. The link is in this state if it is in the process of reconnecting. A link will be in a connected state before it goes into a RECONNECTING state. The following state will be either CONNECTED if the link was re-established or NOT_CONNECTED if re-establishing the link failed.

See Also:

getConnectionStatus(), Constant Field Values

Method Detail

getTypeDefaults

Attributes getTypeDefaults(java.lang.String type)

Get connection specific message attribute defaults as identified by the type.

See Also:

putTypeDefaults(java.lang.String, ie.ncl.msg.Attributes), Message.getType(), Attributes

putTypeDefaults

void putTypeDefaults(java.lang.String type,
                     Attributes props)

Set connection specific message attribute defaults as identified by the type.

See Also:

getTypeDefaults(java.lang.String), Message.getType(), Attributes

close

void close()

Close the connection. Once a connection is closed, no more messages can be sent. However, all internal pending messages sent prior to calling close will be sent.

setErrorListener

void setErrorListener(ErrorListener listener)

Specify a callback called if an connection error occurs in the underlying connection.

This should be set before the connection is initiated.

Temporary errors (such as connection temporarily down) are sent to this callback even though messages can continue to be sent (and connected() returns true).

See Also:

ErrorListener, TemporaryConnectionException, connected()

init

void init(java.util.Properties properties)
          throws ConnectionException

Initialise the object with settings specified in the properties. The properties will be implementation specific.

Throws:

ConnectionException

init

void init(java.util.Properties properties,
          java.lang.String prefix)
          throws ConnectionException

Initialise the object with settings specified in the properties where the relevant property names have been prefixed with the specified prefix. This is useful where two or more connection objects' properties are specified in the same Properties object.

Throws:

ConnectionException

connect

void connect()
             throws ConnectionException

Connect with the service. Until connect is called, no messages can be sent/received.

Throws:

ConnectionException

connected

boolean connected()

Deprecated. Use getConnectionStatus instead

Query the connection status. This returns true if connected and false otherwise.

If internally a service connection go down and attempts are made to reconnect/rebind etc. this should continue to return true, so that the application continues to function.

If the application wants to be informed of a temporarily down connection/service then the application should register for errors and specifically catch the TemporaryConnectionException.

See Also:

setErrorListener(ie.ncl.msg.ErrorListener), TemporaryConnectionException

getConnectionStatus

int getConnectionStatus()

Query the status of the link. A link can be in one of 3 states; NOT_CONNECTED, CONNECTED, RECONNECTING.

Unlike the connected() method, the getConnectionStatus indicates if the link has gone down and the underlying protocol is in a process of reconnecting.

See Also:

CONNECTED, NOT_CONNECTED, RECONNECTING, setErrorListener(ie.ncl.msg.ErrorListener), TemporaryConnectionException

shutdown

void shutdown()

Shutdown the connection. This is used to shutdown a connection ungracefully.