Sun Java System Message Queue 4.3 Developer's Guide for C Clients

Working With Connections

All messaging occurs within the context of a connection: the behavior of the connection is defined by the properties set for that connection. You use the functions listed in Table 2–3 to create, start, stop, and close a connection.

Table 2–3 Functions Used to Work with Connections


Function	Description
MQInitializeSSL	Initializes the SSL library. You must call this function before you create any connection that uses SSL.
MQCreateConnection	Creates a connection and passes back a handle to it.
MQStartConnection	Starts the specified connection and starts or resumes delivery of messages.
MQStopConnection	Stops the specified connection.
MQGetMetaData	Returns a handle to name and version information for the Message Queue product.
MQCloseConnection	Closes the specified connection.

Before you create a connection, you must do the following:

Define the connection properties. See Setting Connection and Message Properties for more information.
Specify a user name and password for the connection. See User Authentication in Sun Java System Message Queue 4.3 Administration Guidefor information on how to set up users.
Write a connection exception listener function. You will need to pass a reference to this listener when you create the connection. This function will be called synchronously when a connection exception occurs for this connection. For more information, see Callback Type for Connection Exception Handling .
If you want a secure connection, call the MQIntitializeSSL function to initialize the SSL library. See Working With Secure Connections for more information.

When you have completed these steps, you are ready to call MQCreateConnection to create a connection. After you create the connection, you can create a session as described in Working With Sessions and Destinations .

When you send a message, you do not need to start the connection explicitly by calling MQStartConnection. You do need to call MQStartConnection before the broker can deliver messages to a consumer.

If you need to halt delivery in the course of processing messages, you can call the MQStopConnection() function.

Defining Connection Properties

Connection properties specify the following information:

The host name and port of the broker to which you want to connect
The transport protocol of the connection service used by the client
How broker and client acknowledgements are handled to support messaging reliability
How message flow is to be managed
How secure messaging should be implemented

The following sections examine the effect of properties used to manage connection handling, reliability, message flow, and security.

Table 4–2 lists and describes all properties of a connection. For information on how to set and change connection properties, see Working With Properties.

Connection Handling

Connections to a message server are specified by a broker host name and port number.

Set MQ_BROKER_NAME_PROPERTY to specify the broker name.
Set MQ_BROKER_PORT_PROPERTY to specify the port of the broker's port mapper service. In this case, the port mapper will dynamically assign the port to which the client connects.
Set MQ_BROKER_SERVICE_PORT_PROPERTY to specify the number of a port to which the client connects. This is a static, fixed port assignment; it bypasses the broker's port mapper service. If you do need to connect to a fixed port on the broker, make sure that the service needed is enabled and available at the specified port by setting the imq.serviceName.protocolType.port broker property.
Set the connection property MQ_CONNECTION_TYPE_PROPERTY to specify the underlying transport protocol. Possible values are TCP or SSL.

Remember that you need to configure the JMS service port on the broker side as well. For example, if you want to connect your client via ssljms to port 1756, you would do the following.
- On the client side: Set the MQ_SERVICE_PORT_PROPERTY to 1756 and set the MQ_CONNECTION_TYPE_PROPERTY to SSL.
- On the broker side: Set the imq.serviceNameType.protocol.port property to 1756 as follows.
```
imq.ssljms.ssl.port=1756
```

The MQ_PING_INTERVAL_PROPERTY also affects connection handling. This property is set to the interval (in seconds) that the connection can be idle before the C client runtime pings the broker to test whether the connection is still alive. This property is useful for either producers who use the connection infrequently or for clients who are exclusive consumers, passively waiting for messages to arrive. The default value is 30 seconds. Setting an interval that is too low may result in some performance loss. The minimum permitted value is 1 second to prevent this from happening.

Currently, the C-API does not support auto-reconnect or failover, which allows the client runtime to automatically reconnect to a broker if a connection fails.

Reliability

Two connection properties enable the acknowledgement of messages sent to the broker and of messages received from the broker. These are described in Message Acknowledgement. In addition to setting these properties, you can also set MQ_ACK_TIMEOUT_PROPERTY, which determines the maximum time that the client runtime will wait for any broker acknowledgement before throwing an exception.

Flow Control

A number of connection properties determine the use of Message Queue control messages by the client runtime. Messages sent and received by Message Queue clients and Message Queue control messages pass over the same client-broker connection. Because of this, delays may occur in the delivery of control messages, such as broker acknowledgements, if these are held up by the delivery of JMS messages. To prevent this type of congestion, Message Queue meters the flow of JMS messages across a connection.

Set MQ_CONNECTION_FLOW_COUNT_PROPERTY to specify the number of Message Queue messages in a metered batch. When this number of messages is delivered to the client runtime, delivery is temporarily suspended, allowing any control messages that had been held up to be delivered. Message delivery is resumed upon notification by the client runtime, and continues until the count is again reached.
MQ_CONNECTION_FLOW_LIMIT_PROPERTY specifies the maximum number of unconsumed messages that can be delivered to a client runtime. When the number of messages reaches this limit, delivery stops and resumes only when the number of unconsumed messages drops below the specified limit. This helps a consuming client that is taking a long time to process messages from being overwhelmed with pending messages that might cause it to run out of memory.
MQ_CONNECTION_FLOW_LIMIT_ENABLED_PROPERTY specifies whether the value MQ_CONNECTION_FLOW_LIMIT_PROPERTY is used to control message flow.

You should keep the value of MQ_CONNECTION_FLOW_COUNT_PROPERTY low if the client is doing operations that require many responses from the broker; for example, the client is using the CLIENT_ACKNOWLEDGE or AUTO_ACKNOWLEDGE modes, persistent messages, transactions, or if the client is adding or removing consumers. You can increase the value of MQ_CONNECTION_FLOW_COUNT_PROPERTY without compromising performance if the client has only simple consumers on a connection using DUPS_OK mode.

The C API does not currently support consumer-based flow control.

Working With Secure Connections

Establishing a secure connection between the client and the broker requires both the administrator and the developer to do some additional work. The administrator’s work is described in the Message Encryption in Sun Java System Message Queue 4.3 Administration Guide. In brief, it requires that the administrator do the following:

Generate certificates (self-signed or signed by a certificate authority) and add those certificates to the broker’s keystore
Enable the ssljms connection service in the broker
Provide the password to the certificate keystore when starting the broker

The developer must also do some work to configure the client for secure messaging. The work required depends on whether the broker is trusted (the default setting) and on whether the developer wants to provide an additional means of verification if the broker is not trusted and the initial attempt to create a secure connection fails.

The MessageQueue C-API library uses NSS to support the SSL transport protocol between the Message Queue C client and the Message Queue broker. The developer must take care if the client application using secure Message Queue connections uses NSS (for other purposes) directly as well and does NSS initialization. For additional information, see Coordinating NSS Initialization.

Configuring the Client for Secure Communication

By default the MQ_SSL_BROKER_IS_TRUSTED property is set to true, and this means that the Message Queue client runtime will accept any certificate that is presented to it. The following procedure explains what you must do to establish a secure connection.

To Establish a Secure Connection

Set the MQ_CONNECTION_TYPE_PROPERTY to SSL .

If you want the runtime to check the broker’s certificate, set the MQ_SSL_BROKER_IS_TRUSTED property to false. Otherwise, you can leave it to its default (true) value.

Generate the NSS files CertN .db, keyN.db, and secmod.db using the certificate database tool certutil . You can find this tool at the following locations:
- Solaris: /usr/sfw/bin
- Linux: /opt/sun/private/bin
- AIX: IMQ_HOME/bin
- Windows: IMQ_HOME\bin
  
  For directions and an example of using this tool, see
  
  http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html

Note the path name of the directory that contains the NSS files you generated in Configuring the Client for Secure Communication.

If you have set the MQ_SSL_BROKER_IS_TRUSTED property to false, use the certutil tool to import the root certificate of the authority certifying the broker into the database files you generated in Configuring the Client for Secure Communication .

Make sure that the MQ_BROKER_HOST_PROPERTY value is set to the same value as the (CN) common name in the broker’s certificate.

If you have set the MQ_SSL_BROKER_IS_TRUSTED property to false, you have the option of enabling broker fingerprint-based verification in case authorization fails. For details, see Verification Using Fingerprints.

Call the function MQInitializeSSL once (and only once) before creating the connection, and pass the name of the directory that contains the NSS files you generated in Configuring the Client for Secure Communication. If the broker is trusted, these files can be empty.

You must call this function before you create any connection to the broker, including connections that do not use SSL.

Verification Using Fingerprints

If certificate authorization fails when the broker is using a certificate authority, it is possible to give the client runtime another means of establishing a secure connection by comparing broker certificate fingerprints. If the fingerprints match, the connection is granted; if they do not match, the attempt to create the connection will fail.

To Set Up Fingerprint Certification

Set the broker connection property MQ_SSL_CHECK_BROKER_FINGERPRINT to true.

Retrieve the broker’s certificate fingerprint by using the java keytool -list option on the broker’s keystore file:

You will use the output of this command as the value for the connection property MQ_SSL_BROKER_CERT_FINGERPRINT in Verification Using Fingerprints. For example, if the output contains a value like the following:
Certificate fingerprint (MD5): F6:A5:C1:F2:E6:63:40:73:97:64:39:6C:1B:35:0F:8E
You would specify this value for MQ_SSL_BROKER_CERT_FINGEPRINT.

Set the connection property MQ_SSL_BROKER_CERT_FINGEPRINT to the value obtained in Verification Using Fingerprints.

Coordinating NSS Initialization

If your application uses NSS directly, other than to support Message Queue secure communication, you need to coordinate NSS initialization with the Message Queue C-API library. There are two cases to consider:

Your application does not use secure Message Queue connections.

In this case, you should do your application’s NSS initialization before calling MQCreateConnection to create any connection to the Message Queue broker.
Your application does use secure Message Queue connections.

In this case, you should follow the procedure outlined below before calling MQCreateConnection to create any Message Queue connection.

To Coordinate NSS Initialization

Call the function MQInitializeSSL. (You must specify the path to the directory containing the NSS files as the certdbpath parameter to this function.)

Your application’s use of NSS must specify the same certdbpath value for the location of its NSS files. (That is, the certificates needed by your application must be located in the same directory as the certificates needed by Message Queue.)

Internally, the function MQInitializeSSL does the following:
- Calls the function NSS_Init(certdbpath).
- Sets DOMESTIC cipher policy using the function NSS_SetDomesticPolicy().
- Enables all cipher suites, including RSA_NULL_MD5 by calling the function SSL_CipherPrefSetDefault(SSL_RSA_WITH_NULL_MD5, PR_TRUE) .
- Calls the function SSL_ClearSessionCache().

If your application needs different cipher suite settings, after you call the MQInitializeSSL() function, you can modify the cipher suites by calling the function SSL_CipherPrefSetDefault. However, note that these changes will affect your secure connection to the Message Queue broker as well.

Shutting Down Connections

In order to do an orderly shutdown, you need to close the connection by calling MQCloseConnection() and then to free the memory associated with the connection by calling the MQFreeConnection() function.

Closing the connection closes all sessions, producers, and consumers created from this connection. This also forces all threads associated with this connection that are blocking in the library to return.
After all the application threads associated with this connection and its descendant sessions, producers, and consumers have returned, the application can call the MQFreeConnection() function to release all resources associated with the connection.

To get information about a connection, call the MQGetMetaData() function. This returns name and version information for the Message Queue product.