Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 13 Using the EMS Implementation of JNDI : Looking up Administered Objects Stored in EMS

Looking up Administered Objects Stored in EMS
This section describes how to lookup objects from an EMS server by name.
All clients can lookup objects in the EMS naming service. Alternatively, Java applications can lookup objects in a third-party JNDI server, and C and C# clients can lookup objects in a third-party LDAP server.
To lookup administered objects stored in EMS, you need to create the initial context that identifies the URL of the naming service provider and any other properties, such as the username and password to authenticate the client to the service. The naming service provider URL has form:
    tibjmsnaming://host:port
The following examples demonstrate how to access JMS administered objects when using TIBCO Enterprise Message Service. Each of these examples assume that a connection factory, named ConFac, exists in the factories.conf file, a topic.sample topic exists in topics.conf, and a queue.sample queue exists in queues.conf.
Java
Create an InitialContext object for the initial context, which consists of the provider context factory and JNDI provider URL, as well as the username and password to authenticate the client to the EMS server:
Hashtable env = new Hashtable();
  env.put(Context.INITIAL_CONTEXT_FACTORY,
        "com.tibco.tibjms.naming.TibjmsInitialContextFactory");
  env.put(Context.PROVIDER_URL,"tibjmsnaming://localhost:7222");
  env.put(Context.SECURITY_PRINCIPAL, "userName");
  env.put(Context.SECURITY_CREDENTIALS, "password");
InitialContext jndiContext = new InitialContext(env);
Look up a connection factory, named ConFac, and destinations, named topic.sample and queue.sample, from the initial context:
ConnectionFactory factory =
      (javax.jms.ConnectionFactory)
      jndiContext.lookup("ConFac");
 
javax.jms.Topic sampleTopic =
          (javax.jms.Topic)jndiContext.lookup("topic.sample");
javax.jms.Queue sampleQueue =
          (javax.jms.Queue)jndiContext.lookup("queue.sample");
See the tibjmsJNDI.java sample client located in the EMS_HOME/samples/java/JNDI directory.
C
Create a tibemsLookupContext object for the initial context, which consists of the JNDI provider URL and the username and password to authenticate the client to the EMS server:
tibemsLookupContext* contextstatus = NULL;
status = tibemsLookupContext_Create(
                           &context,
                           "tibjmsnaming://localhost:7222",
                           "userName",
                           "password");
Use the tibemsLookupContext_LookupConnectionFactory function to look up a connection factory, named ConFac, and use the tibemsLookupContext_LookupDestination function to look up the destinations, named topic.sample and queue.sample, from the initial context:
tibemsConnectionFactory factory = NULL;
tibemsDestination sampleTopic = NULL;
tibemsDestination sampleQueue = NULL;
 
status = tibemsLookupContext_Lookup(context,
                                    "ConFac",
                                    (void**)&factory);
 
status = tibemsLookupContext_Lookup(context,
                                    "sample.queue",
                                    (void**)&sampleQueue);
 
status = tibemsLookupContext_Lookup(context,
                                    "topic.sample,                                     (void**)&sampleTopic);
C#
Create a ILookupContext object for the initial context, which consists of the JNDI provider URL and the username and password to authenticate the client to the EMS server:
Hashtable env = new Hashtable();
  env.Add(LookupContext.PROVIDER_URL,
          "tibjmsnaming://localhost:7222");
  env.Add(LookupContext.SECURITY_PRINCIPAL", "myUserName");
  env.Add(LookupContext.SECURITY_CREDENTIALS", "myPassword");
 
LookupContextFactory factory = new LookupContextFactory();
 
ILookupContext searcher = factory.CreateContext(
                           LookupContextFactory.TIBJMS_NAMING_CONT
                          EXT,
                          env);
Use the ILookupContext.Lookup method to look up a connection factory, named ConFac, and destinations, named topic.sample and queue.sample, from the initial context:
ConnectionFactory factory =
      (ConnectionFactory) searcher.Lookup("ConFac");
 
Topic sampleTopic =
      (Topic)searcher.Lookup("topic.sample");
 
TIBCO.EMS.Queue sampleQueue =
      (TIBCO.EMS.Queue)searcher.Lookup("queue.sample");
 
Looking Up Objects Using Full URL Names
Java clients can look up administered objects using full URL names. In this case, the Context.URL_PKG_PREFIXES property is used in place of the Context.PROVIDER_URL property. For example:
Hashtable env = new Hashtable();
  env.put(Context.URL_PKG_PREFIXES,"com.tibco.tibjms.naming");
  env.put(Context.PROVIDER_URL,"tibjmsnaming://localhost:7222");
  env.put(Context.SECURITY_PRINCIPAL,"userName");
  env.put(Context.SECURITY_CREDENTIALS,"password");
jndiContext = new InitialContext(env);
When using full URL names, you can look up objects like the following example:
Topic sampleTopic = (javax.jms.Topic)jndiContext.lookup(
      "tibjmsnaming://jmshost:7222/topic.sample");
Queue sampleQueue = (javax.jms.Queue)jndiContext.lookup(
      "tibjmsnaming://jmshost:7222/queue.sample");
For further information on how to use full URL names, refer to the tibjmsJNDIRead.java example located in the EMS_HOME/samples/java/JNDI directory.
Performing Secure 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 18, Using the SSL Protocol for more information about using SSL in the TIBCO Enterprise Message Service server.
The following examples illustrate how to create an InitialContext that can be used to perform JNDI lookups using the SSL protocol.
Java
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.SSL_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.
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);
C
Create a tibemsSSLParams object and use the tibemsSSLParams_SetIdentityFile function to establish the client identity by means of a pkcs12 file. Use the tibemsLookupContext_CreateSSL function to create a tibemsLookupContext object that uses an SSL connection for the initial context.
tibemsLookupContext*     context   = NULL;
tibemsConnection_Factory factory   = NULL;
tibemsSSLParams          sslParams = NULL;
tibems_status            status    = TIBEMS_OK;
 
sslParams = tibemsSSLParams_Create();
 
status = tibemsSSLParams_SetIdentityFile(
                                 ssl_params,
                                 "client_identity.p12",
                                 TIBEMS_SSL_ENCODING_AUTO);
 
status = tibemsLookupContext_CreateSSL(
                                 &context,
                                  "tibjmsnaming://localhost:7222",
                                 "userName",
                                 "password",
                                 sslParams,
                                 "pk_password");
C#
Create a ILookupContext object for the initial context over an SSL connection. The SSL Store Info consists of a pkcs12 file that identifies the client and the client’s password, which are stored in an EMSSSLFileStoreInfo object.
string ssl_identity = client_identity.p12;
string ssl_target_hostname = "server";
string ssl_password = "password";
 
EMSSSLFileStoreInfo StoreInfo = new EMSSSLFileStoreInfo();
  info.SetSSLClientIdentity(ssl_identity);
  info.SetSSLPassword(ssl_password.ToCharArray());
 
Hashtable env = new Hashtable();
  env.Add(LookupContext.PROVIDER_URL, "adc1.na.tibco.com:10636");
  env.Add(LookupContext.SECURITY_PRINCIPAL", "myUserName");
  env.Add(LookupContext.SECURITY_CREDENTIALS", "myPassword");
  env.Add(LookupContext.SECURITY_PROTOCOL, "ssl");
  env.Add(LookupContext.SSL_TARGET_HOST_NAME,                      ssl_target_hostname);
  env.Add(LookupContext.SSL_STORE_TYPE,                      EMSSSLStoreType.EMSSSL_STORE_TYPE_FILE);
  env.Add(LookupContext.SSL_STORE_INFO, StoreInfo);
Performing Fault-Tolerant Lookups
TIBCO Enterprise Message Service can perform fault-tolerant JNDI lookups. If the active server fails and the standby server becomes active, the JNDI provider automatically uses the new active 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 secondary EMS server on the machine named backuphost.
env.put(Context.PROVIDER_URL, "tibjmsnaming://jmshost:7222, tibjmsnaming://backuphost:7222");
Assuming emshost starts out as active, if at any time it fails the JNDI provider automatically switches to the EMS server on the host backuphost for JNDI lookups. If emshost is repaired and restarted, it then becomes the standby EMS server.
Limitations of Fault-Tolerant JNDI Lookups
Fault-tolerant JNDI lookups do not occur in the following scenarios:

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved