Using JNDI with TIBCO Enterprise Message Service


In most cases, client applications use the JNDI interface to look up connection factories and Topic and Queue objects.

Dynamic Topics and Queues

TIBCO Enterprise Message Service allows dynamic creation of topics and queues using the following JMS API methods:

Since dynamic topics and queues do not appear in the configuration files, you cannot use the JNDI interface to look up these topics and queues.

For more information about connecting to the server without the JNDI interface, refer to Connecting Directly to TIBCO Enterprise Message Service Server.

Static Topics and Queues

In order to use JNDI access to TIBCO Enterprise Message Service connection factories and topics and queues, the application should use the following parameters:

Formerly, the syntax for topic and queue lookup was $topic. and $queue.
This syntax is supported for backward compatibility, but the new syntax is preferred.

Using context qualifiers is not required if there are no topics and queues with the same names in the configuration files.

The provider URL host:port value is one of the listen ports of TIBCO Enterprise Message Service. There is no separate port defined for JNDI access.

Example

This section provides an example of accessing JMS administered objects when using TIBCO Enterprise Message Service.

static final String providerContextFactory =  
      "com.tibco.tibjms.naming.TibjmsInitialContextFactory"; 
                             
static final String  defaultProviderURL =  
      "tibjmsnaming://jmshost:7222"; 
try  
{ 
  Hashtable env = new Hashtable(); 
  env.put(Context.INITIAL_CONTEXT_FACTORY,providerContextFactory); 
  env.put(Context.PROVIDER_URL,providerURL); 
  jndiContext = new InitialContext(env); 
}  
catch (NamingException e)  
{ 
  System.out.println("Failed to create InitialContext”); 
  e.printStackTrace(); 
} 
 
ConnectionFactory factory = 
      (javax.jms.ConnectionFactory) 
      jndiContext.lookup("ConnectionFactory"); 
 
TopicConnectionFactory topicFactory = 
      (javax.jms.TopicConnectionFactory)         
      jndiContext.lookup("TopicConnectionFactory"); 
 
QueueConnectionFactory queueFactory = 
      (javax.jms.QueueConnectionFactory)  
      jndiContext.lookup("QueueConnectionFactory"); 
 
Topic topic = (javax.jms.Topic)jndiContext.lookup("topic.sample"); 
Queue queue = (javax.jms.Queue)jndiContext.lookup("queue.sample"); 
Looking Up Objects Using Full URL Names

Administered objects can also be looked up using full URL names. In this case, the Context.PROVIDER_URL property is not provided to the InitialContext. Instead, the Context.URL_PKG_PREFIXES property is provided using the statement:

env.put(Context.URL_PKG_PREFIXES, "com.tibco.tibjms.naming"); 

If using full URL names, you can look up topics or queues like the following example:

Topic topic = (javax.jms.Topic)jndiContext.lookup(
      "tibjmsnaming://jmshost:7222/topic.sample"); 
Queue queue = (javax.jms.Queue)jndiContext.lookup(
      "tibjmsnaming://jmshost:7222/queue.sample"); 

For further information on how to use JNDI access, refer to the tibjmsJNDI.java example included with TIBCO Enterprise Message Service.

Using SSL with JNDI Lookups

TIBCO Enterprise Message Service client programs can perform secure JNDI lookups using the Secure Sockets Layer (SSL) protocol. To accomplish this, the client program must set SSL properties in the environment when the InitialContext is created. The SSL properties are similar to the SSL properties for the TIBCO Enterprise Message Service server. See Chapter 12, Using the SSL Protocol for more information about using SSL in the TIBCO Enterprise Message Service server.

Table 38 describes the properties for configuring SSL when using JNDI. Refer to TIBCO Enterprise Message Service Java API Reference included in the online documentation for more information about using JNDI and configuring the InitialContext.

Table 38 SSL properties for client applications using JNDI (Sheet 1 of 6)
Property
Datatype
Description
TibjmsContext.SECURITY_PROTOCOL
String
The security protocol for the connection to the JNDI server. The value of this property must be ssl.
TibjmsContext.SSL_CIPHER_SUITES
String
Specifies the cipher suites used by the server; each suite in the list is separated by a colon (:). This parameter can use the OpenSSL name for cipher suites or the longer, more descriptive names.
See Specifying Cipher Suites for more information about the cipher suites available in TIBCO Enterprise Message Service and the OpenSSL names and longer names for the cipher suites.
TibjmsContext.SSL_DEBUG_TRACE
Boolean
When set to true, enables more detailed SSL tracing. This property is used for debugging only; it is not for use in production systems.
TibjmsContext.SSL_ENABLE_VERIFY_HOST
Boolean
Specifies whether the client should verify the server’s certificate. By default, this property is set to true, signifying the client should verify the server’s certificate.
When this property is set to false, the client establishes secure communication with the server, but does not verify the server’s identity.
TibjmsContext.SSL_ENABLE_VERIFY_HOST_NAME
Boolean
Specifies whether the client should verify the name in the CN field of the server’s certificate. By default, this property is set to true, signifying the client should verify the name of the connected host or the name specified in the SSL_EXPECTED_HOST_NAME property against the value in the server’s certificate. If the names do not match, the connection is rejected.
When this property is set to false, the client establishes secure communication with the server, but does not verify the server’s name.
TibjmsContext.SSL_EXPECTED_HOST_NAME
String
Specifies the name the server is expected to have in the CN field of its certificate. If this parameter is not set, the expected name is the hostname of the server.
This parameter is used when the SSL_ENABLE_VERIFY_HOST_NAME parameter is set to enabled.
TibjmsContext.SSL_HOST_NAME_VERIFIER
String
Constant that holds the name of SSL property specifying the custom host name verifier for JNDI lookups.
TibjmsContext.SSL_IDENTITY
String
The client’s digital certificate.
PEM and PSCS#12 formats allow the digital certificate to include the private key. If these formats are used and the private key is part of the digital certificate, then setting SSL_PRIVATE_KEY is optional.
See File Names for Certificates and Keys for more information on file types for digital certificates.
TibjmsContext.SSL_IDENTITY_ENCODING
String
The encoding of the client’s certificate.
TibjmsContext.SSL_ISSUER_CERTIFICATES
Vector
Certificate chain member for the client. Supply the entire chain, including the CA root certificate. The client reads the certificates in the chain in the order they are presented in this property.
See File Names for Certificates and Keys for more information on file types for digital certificates.
TibjmsContext.SSL_PASSWORD
String
Password for client’s private key.
TibjmsContext.SSL_PRIVATE_KEY
String
The name and location of the client’s private key file.
TibjmsContext.SSL_PRIVATE_KEY_ENCODING
String
The encoding of the client’s private key file.
TibjmsContext.SSL_RENEGOTIATE_INTERVAL
Key renegotiation is deprecated in release 4.3; it is not supported in release 5.0.
Integer
The client renegotiates for a new symmetric key when the cumulative size (in bytes) of the data that the client exchanges with a server reaches this threshold.
The minimum value for this parameter is 64Kb. You can specify Kb, Mb, or Gb for the units. For example:
ssl_renegotiate_size = 10Gb 
When neither of the two renegotiation parameters are set, the client does not initiate key renegotiation.
For more information, see Renegotiating the Session Key.
TibjmsContext.SSL_RENEGOTIATE_SIZE
Key renegotiation is deprecated in release 4.3; it is not supported in release 5.0.
Integer
The client renegotiates for a new symmetric key when the time (in seconds) since the last key negotiation reaches this threshold.
The minimum value is 15 seconds. For example, you can set this parameter as follows to renegotiate every 24 hours:
ssl_renegotiate_interval = 
86400 
When neither of the two renegotiation parameters are set, the client does not initiate key renegotiation.
For more information, see Renegotiating the Session Key.
TibjmsContext.SSL_TRACE
Boolean
When set to true, enables tracing of loaded certificates.
This prints a message to the console during startup of the server that describes each loaded certificate.
TibjmsContext.SSL_TRUSTED_CERTIFICATES
Vector
List of trusted certificates. This sets which Certificate Authority certificates should be trusted as issuers of the JNDI server certificates.
See File Names for Certificates and Keys for more information on file types for digital certificates.
TibjmsContext.SSL_VENDOR
String
The SSL provider name. The value of this property must be one of the following:
  • j2se-default
  • j2se (Supported only with Sun JCE/JSSE, not IBM JCE/JSSE.)
  • entrust61 (The EMS Java client library works only with Entrust 7.1, and not with earlier versions. Nonetheless, the vendor constant is still entrust61.)

Example of Using SSL for JNDI Lookups

The following is an example of how to create an InitialContext that can be used to perform JNDI lookups using the SSL protocol.

Hashtable env = new Hashtable(); 
env.put(Context.INITIAL_CONTEXT_FACTORY, 
       "com.tibco.tibjms.naming.TibjmsInitialContextFactory"); 
env.put(Context.PROVIDER_URL, tibjmsnaming://jmshost:7223); 
env.put(Context.URL_PKG_PREFIXES, "com.tibco.tibjms.naming") 
env.put(TibjmsContext.SECURITY_PROTOCOL, "ssl"); 
env.put(TibjmsContext.SSL_ENABLE_VERIFY_HOST,  
       new Boolean("false")); 
Context context = new InitialContext(env); 

In this example, the port number specified for the Context.PROVIDER_URL is set to the SSL listen port that was specified in the server configuration file tibjsmd.conf. The value for TibjmsContext.SECURITY_PROTOCOL is set to ssl. Finally, the value of TibjmsContext.ENABLE_VERIFY_HOST is set to "false" to turn off server authentication. Because of this, no trusted certificates need to be provided and the client will then not verify the server it is using for the JNDI lookup against the server’s certificate.

Performing Fault-Tolerant JNDI Lookups

TIBCO Enterprise Message Service can perform fault-tolerant JNDI lookups. If the primary server fails and the backup server becomes the primary, the JNDI provider automatically uses the new primary server for JNDI lookups. You accomplish this by providing multiple URLs in the Context.PROVIDER_URL property when creating the InitialContext. Specify more than one URL separated by commas (,) in the property.

Example

The following illustrates setting up the Context.PROVIDER_URL property with the URLs of a primary EMS server on the machine named emshost and a backup EMS server on the machine named backuphost.

env.put(Context.PROVIDER_URL, "tibjmsnaming://jmshost:7222, 
tibjmsnaming://backuphost:7222"); 

If at any time the first EMS server fails, the JNDI provider will automatically switch to the EMS server on the host backuphost for JNDI lookups. If emshost is repaired and restarted, it then becomes the backup EMS server.

Limitations of Fault-Tolerant JNDI Lookups

Fault-tolerant JNDI lookups do not occur in the following scenarios:


TIBCO Enterprise Message Service™ User’s Guide
Software Release 4.3, February 2006
Copyright © TIBCO Software Inc. All rights reserved
www.tibco.com