Establishing Connections

This section describes how a JMS client can establish Java Naming and Directory Interface (JNDI) and JMS data connections. It also describes how a connected client can establish a Session through which a JMS client can produce and consume messages.

Working with JMS-Administered Objects

Client applications using the Solace JMS implementation can either look up the required JMS-administered objects in a JNDI store or programmatically create them to avoid relying on JNDI service.

Working with JNDI

The Solace implementation of the JMS API is JNDI-compliant. When JMS clients obtain JNDI service, they can look up Solace implementations of Connection Factory, XA Connection Factory, Queue, and Topic objects either in the JNDI store offered by the event broker or in an LDAP‑based JNDI store on a remote host.

JMS clients can use JNDI service to look up JMS-administered objects through common names. To obtain JNDI service, a JMS client must pass a set of environment properties to the Initial Context constructor, which is used to provide JNDI service.

The environment properties must provide the fully‑qualified class name of the default InitialContextFactory implementation for Solace JMS (com.solacesystems.jndi.SolJNDIInitialContextFactory) to create an Initial Context. A number of standard and Solace‑defined properties can also be optionally configured through the environment. (For information on the properties that can be set through the environment, refer to JMS Properties Reference.)

The InitialContext provides a network connection to a JNDI store from which JMS‑administered objects can be looked up. A JNDI connection between the JMS client and a JNDI store is created when a JNDI lookup is made with that InitialContext.

Clients can look up administered objects from an event broker, which provides a JNDI store, or from an LDAP-based store on another host.

For examples of the process used to look up JMS-administered objects from the Solace JNDI store and an LDAP-based JNDI store, refer to Obtaining Connection Factories.

Working with JMS-Administered Objects on an Event Broker

The process for configuring Connection Factory, Queue, and Topic JNDI objects on an LDAP store depends on the particular LDAP provider that is used. For an example of how to bind JMS-administered objects in an Open LDAP JNDI store, refer to the SolJMSLDAPBind.java sample.

Programmatically Creating JMS-Administered Objects

Client applications can use the SolConnectionFactory, SolXAConnectionFactory, SolQueue, and SolTopic interfaces of the SolJMSUtility class to programmatically create JMS‑administered Connection Factory, XA Connection Factory, Queue, and Topic objects instead of relying on JNDI service to look them up. SolConnectionFactory, SolXAConnectionFactory, SolQueue, and SolTopic objects are Solace proprietary implementations of standard JNDI ConnectionFactory, XA Connection Factory, Queue, and Topic objects.

Programmatically-created JMS objects can be bound to an LDAP‑based JNDI Store so that JMS clients can reuse them. The process for configuring objects on an LDAP store depends on the particular LDAP provider that is used. For an example of how to bind JMS-administered objects in an Open LDAP JNDI store, refer to the SolJMSLDAPBind.java sample.

Programmatically Creating Connection Factory and XA Connection Factory Objects

When programmatically creating a SolConnectionFactory or a SolXAConnectionFactory object, predefined default Connection Factory properties are used unless they are specifically overwritten by property values set through a passed-in environment or through Set operations (for example, SolConnectionFactory.setReconnectRetries and SolXAConnectionFactory.setReconnectRetries). Refer to the JMS API Reference documentation for a list of the Get and Set operations that can be performed for SolConnectionFactory and SolXAConnectionFactory objects.

Host, username, password, and Message VPN properties must be specified for a SolConnectionFactory or SolXAConnectionFactory so that a JMS data connection to an event broker can be made. These properties can be provided through a number of JMS property sources (refer to JMS Property Sources), or they can be provided when the SolConnectionFactory is created.

  • To programmatically create a SolConnectionFactory, call one of the following methods:
    • SolJMSUtility.createConnectionFactory()

      Creates a Connection Factory with the default Connection Factory properties.

    • SolJMSUtility.createConnectionFactory(java.util.Hashtable<?,?> environment)

      Creates a Connection Factory with a given environment. Any connection properties specified by the passed-in environment overwrite the default Connection Factory properties.

    • SolJMSUtility.createConnectionFactory(java.lang.String host, java.lang.String username, java.lang.String password, java.lang.String vpn, java.util.Hashtable<?,?> environment)

      • Creates a Connection Factory with a given environment. The host, username, password, and Message VPN properties required to establish a connection to the event broker are also passed in.

  • To programmatically create a SolXAConnectionFactory, call one of the following methods:
    • SolJMSUtility.createXAConnectionFactory()

      Creates an XA Connection Factory with the default XA Connection Factory properties.

    • SolJMSUtility.createXAConnectionFactory(java.util.Hashtable<?,?> environment)

      Creates an XA Connection Factory with a given environment. Any connection properties specified by the passed-in environment overwrite the default XA Connection Factory properties.

    • SolJMSUtility.createXAConnectionFactory(java.lang.String host, java.lang.String username, java.lang.String password, java.lang.String vpn, java.util.Hashtable<?,?> environment)

      Creates an XA Connection Factory with a given environment. The host, username, password, and Message VPN properties required to establish a connection to the event broker are also passed in.

For an overview on the process of programmatically creating a Connection Factory or an XA Connection Factory to establish a JMS connection to an event broker, refer to Programmatically Creating Connection Factories.

Programmatically Creating Queue Objects

To programmatically create a SolQueue, call SolJMSUtility.createQueue(java.lang.String queueName).

Programmatically Creating Topic Objects

To programmatically create a SolTopic, call SolJMSUtility.createTopic(java.lang.String topicName).