A Connection object is a client's active connection to TIBCO EMS Server. More...

Inheritance diagram for TIBCO.EMS.UFO.Connection:

Public Member Functions
virtual Session	CreateSession (bool transacted, int acknowledgeMode)
	Creates a Session object. More...

virtual Session	CreateSession (bool transacted, TIBCO.EMS.SessionMode acknowledgeMode)
	Creates a Session object. More...

virtual void	Start ()
	Starts (or restarts) a connection's delivery of incoming messages. More...

virtual void	Stop ()
	Temporarily stops a connection's delivery of incoming messages. More...

virtual void	Close ()
	Closes the connection and reclaims resources. More...

override string	ToString ()
	A String representation of the conneciton object More...

void	RecoverConnection ()
	Recover the broken connection on another available server. The session, message producer, message consumer, temporary destinations created by this broken connection are transparently recreated once the connection is recovered. More...

Properties
string	ActiveURL `[get]`
	Get URL of the server this connection is currently connected to More...

bool	IsClosed `[get]`
	Return true if connection is closed; otherwise false. More...

string	ClientID `[get, set]`
	Gets and Set the Client Id More...

TIBCO.EMS.ConnectionMetaData	MetaData `[get]`
	Gets the metadata for this connection. More...

IExceptionListener	ExceptionListener `[get, set]`
	Get and set the exception event listener More...

TIBCO.EMS.EMSExceptionHandler	ExceptionHandler
	The exception event handler More...

Detailed Description

A Connection object is a client's active connection to TIBCO EMS Server.

Connections support concurrent use.

A connection serves several purposes:

It encapsulates an open connection with a TIBCO EMS Server. It typically represents an open TCP/IP socket between a client and the TIBCO EMS Server.
Its creation is where client authentication takes place.
It can specify a unique client identifier.
It provides a TIBCO.EMS.ConnectionMetaData object.
It supports an optional TIBCO.EMS.IExceptionListener object.

Because the creation of a connection involves setting up authentication and communication, a connection is a relatively heavyweight object. Most clients will do all their messaging with a single connection. Other more advanced applications may use several connections.

A client typically creates a connection, one or more sessions, and a number of message producers and consumers. When a connection is created, it is in stopped mode. That means that no messages are being delivered.

It is typical to leave the connection in stopped mode until setup is complete and all message consumers have been created. At that point, the client calls the connection's Start method, and messages begin arriving at the connection's consumers. (Outbound messages flow even before calling Start.) This setup convention minimizes any client confusion that may result from asynchronous message delivery while the client is still in the process of setting itself up.

A connection can be started immediately and the setup can be done afterwards. Clients that do this must be prepared to handle asynchronous message delivery while they are still in the process of setting up.

A message producer can send messages while a connection is stopped

Asynchronous Exceptions

When a program uses a connection to send messages, the send calls can detect problems with the connection, and notify the client program (synchronously) by throwing exceptions.

However, when a program uses a connection only to receive messages, the client cannot catch such exceptions. Instead, programs can handle such exceptions asynchronously in one of two idioms. Programmers may select either idiom, but not both (which would cause duplicate exception processing, with undefined behavior).

TIBCO.EMS.EMSExceptionHandler events detect this type of problem in a .NET programming idiom.
In contrast, the TIBCO.EMS.IExceptionListener property mimics the way in which Jakarta Messaging provides similar functionality in a Java programming idiom.

Note: The EMS .NET API does not support the optional methods createConnectionConsumer and createDurableConnectionConsumer.

Member Function Documentation

virtual void TIBCO.EMS.UFO.Connection.Close ( )

inlinevirtual

Closes the connection and reclaims resources.

Closing the connection causes all temporary destinations to be deleted; you need not separately close the sessions, producers, and consumers associated with the connection.

Closing a connection deletes all temporary destinations associated with the connection.

Blocking

If any message listener or receive call associated with the connection is processing a message when the program calls this method, all facilities of the connection and its sessions remain available to those listeners until they return. In the meantime, this method blocks until that processing completes, that is, until all message listeners and receive calls have returned.

Acknowledge

Closing a connection does not force acknowledgment in client-acknowledged sessions. When the program still has a message that it received from a connection that has since closed, its Message.Acknowledge method throws IllegalStateException.

Transactions

Closing a connection rolls back all open transactions in all sessions associated with the connection. When an external transaction manager coordinates transactions, it determines the final disposition of its open transactions.

virtual Session TIBCO.EMS.UFO.Connection.CreateSession	(	bool	transacted,
		int	acknowledgeMode
	)

inlinevirtual

Creates a Session object.

The new session uses the connection for all server communications. It will be recreated during connection recovery.

Parameters

transacted Indicates whether the session is transacted.

When true, the new session has transaction semantics.

When false, it has non-transaction semantics.

Parameters

acknowledgeMode Indicates whether and how the consumer is to acknowledge received messages. This version of CreateSession accepts an integer value associated with the acknowledge mode described by a Session member and should only be used for backward compatibility.This parameter is ignored if the session is transacted.

Returns: A newly created session.

virtual Session TIBCO.EMS.UFO.Connection.CreateSession	(	bool	transacted,
		TIBCO.EMS.SessionMode	acknowledgeMode
	)

inlinevirtual

Creates a Session object.

The new session uses the connection for all server communications. It will be recreated during connection recovery.

Parameters

transacted Indicates whether the session is transacted.

When true, the new session has transaction semantics.

When false, it has non-transaction semantics.

Parameters

acknowledgeMode Indicates whether and how the consumer is to acknowledge received messages. Legal values are listed under TIBCO.EMS.SessionMode. This parameter is ignored if the session is transacted.

Returns: A newly created session.

void TIBCO.EMS.UFO.Connection.RecoverConnection ( )

inline

Recover the broken connection on another available server. The session, message producer, message consumer, temporary destinations created by this broken connection are transparently recreated once the connection is recovered.

virtual void TIBCO.EMS.UFO.Connection.Start ( )

inlinevirtual

Starts (or restarts) a connection's delivery of incoming messages.

When a connection is created, it is stopped. It does not deliver inbound messages until the program calls this method to explicitly start it.

If the connection has already been started and is not stopped, this call has no effect.

Outbound messages flow even before calling Start.

virtual void TIBCO.EMS.UFO.Connection.Stop ( )

inlinevirtual

Temporarily stops a connection's delivery of incoming messages.

This call temporarily stops the connection from delivering inbound messages. A program can restart delivery by calling Start.

When a connection is created, it is stopped. It does not deliver inbound messages until the program calls this method to explicitly start it.

If the connection is already stopped, this call has no effect.

Effect

When this call returns, the connection has stopped delivery to all consumers associated with the connection:

Messages do not arrive to trigger asynchronous message handler events, nor message listeners.
Synchronous receive methods block. If their timeout intervals expire, they return null.

Blocking

If any message listener or receive call associated with the connection is processing a message when the program calls this method, all facilities of the connection and its sessions remain available to those listeners until they return. In the meantime, this method blocks until that processing completes, that is, until all message listeners and receive calls have returned.

However, the stopped connection prevents the client program from processing any new messages.

Sending

A stopped connection can still send outbound messages.

override string TIBCO.EMS.UFO.Connection.ToString ( )

inline

A String representation of the conneciton object

Returns: The String representation

Property Documentation

string TIBCO.EMS.UFO.Connection.ActiveURL

get

Get URL of the server this connection is currently connected to

This property holds the URL of the server at the other endpoint of the connection. When the connection interacts with several servers in a fault-tolerant arrangement, this property indicates the current active server.

string TIBCO.EMS.UFO.Connection.ClientID

getset

Gets and Set the Client Id

This property holds the unique client ID of the connection.

Client IDs partition the namespace of durable subscribers (see Session.CreateDurableSubscriber).

Administrators can configure ConnectionFactory objects to assign client IDs to new connections. Alternatively, administrators can allow client programs to assign their own IDs. If the factory does not assign an ID, the program may dynamically set this property by calling the setClientID method. However, it is illegal to overwrite an existing client ID value, and or to set this property after using the connection in any way (for example, after creating a session, or starting the connection); attempting to set this property in these situations results in IllegalStateException.

Returns: the unique client identifier

Exceptions

TIBCO.EMS.IllegalStateException Attempt to overwrite existing ClientID or to set the ClientID after using the connection.

TIBCO.EMS.EMSExceptionHandler TIBCO.EMS.UFO.Connection.ExceptionHandler

addremove

The exception event handler

The client library raises an event if it detects a problem with the connection. The program implements a handler delegate to processes it asynchronously and registers the delegate here.

Delegate declaration for exception handler is as follows:

public delegate void EMSExceptionHandler(object sender, EMSExceptionEventArgs args);
sender: The source of the event, the connection in this case.
args: The event argument, <see cref="EMSExceptionEventArgs"/>

Example of using the exception event handler:

...
connection.ExceptionHandler += new EMSExceptionHandler(handleEx);
...
private void handleEx(object sender, EMSExceptionEventArgs arg)
{
   EMSException e = arg.Exception;
   Console.WriteLine("Exception: " + e.Message);
}
...

Note: Use either ExceptionHandler or IExceptionListener to handle exceptions, but not both. Setting up both will cause the exception to be handled more than once which can result in undefined behavior

Exceptions

TIBCO.EMS.IllegalStateException If the connection is closed

IExceptionListener TIBCO.EMS.UFO.Connection.ExceptionListener

getset

Get and set the exception event listener

This is an alternate pathway for alerting a client program of connection problems. The program implements the exception listener interface, and registers an exception listener object by setting this property. When the client library detects a connection problem, it calls the listener's onException method with an exception argument that details the problem.

Note: Use either TIBCO.EMS.EMSExceptionHandler or TIBCO.EMS.IExceptionListener to handle exceptions, but not both. Setting up both will cause the exception to be handled more than once which can result in undefined behavior.

Exceptions

TIBCO.EMS.IllegalStateException If the connection is closed

bool TIBCO.EMS.UFO.Connection.IsClosed

get

Return true if connection is closed; otherwise false.

TIBCO.EMS.ConnectionMetaData TIBCO.EMS.UFO.Connection.MetaData

get

Gets the metadata for this connection.

Returns: the connection metadata

Public Member Functions

Properties

Detailed Description

Member Function Documentation

Property Documentation