Creating a JNDI Provider Alias

About this task

Each JMS provider can store JMS administered objects in a standardized namespace called the Java Naming and Directory Interface (JNDI). JNDI is a Java API that provides naming and directory functionality to Java applications.

As the JMS client, API Gateway uses a JNDI provider alias to encapsulate the information needed to look up an administered object. When you create a JMS connection alias, you can specify the JNDI provider alias that API Gateway should use to look up administered objects (that is, Connection Factories and Destinations).

To create a JNDI provider alias

Procedure

Expand the menu options icon , in the title bar, and select Administration.
Select General > Messaging.
API Gateway displays a list of all the currently defined JNDI provider alias definitions.
Click Add JNDI provider alias.

Provide the following information for the JNDI provider alias

Field	Description
JNDI alias name	The alias name that you want to assign to the JNDI provider.
Description	A description for the JNDI alias.
Predefined JNDI Templates	Select the JNDI template that you want to use. The JNDI templates provide information that you can use to complete alias configuration for a specific provider. The available templates are: Broker, UM, filesystem, LDAP, JBoss, WebLogic, Qpid-AMQP (0-x)
Initial context factory	The class name of the JNDI provider. The JNDI provider uses the initial context as the starting point for resolving names for naming and directory operations. API Gateway displays the initial context factory for the provider depending on the predefined JNDI template selected.
Provider URL	The primary URL of the initial context for sessions with the JNDI provider. The URL specifies the JNDI directory in which the JNDI provider stores JMS administered objects. If you are using Software AG Universal Messaging, this is the Universal Messaging realm server in the format nsp:// UM_host : UM_port (for example, nsp://127.0.0.1:9000). If you are using a cluster of Universal Messaging realm servers, supply a list of the URLs to each realm server in the cluster. Use a colon or semi-colon to separate each URL: Separate the URLs using a comma if API Gateway always attempts to connect to the first Universal Messaging server in the list, only trying the second Universal Messaging server in the list if the first server becomes unavailable. Separate the URLs using a semicolon if API Gateway connects to a randomly chosen URL from the list. This may result in better distribution of clients across the servers in the cluster. If you are using the filesystem you have to provide the filepath of the location of the file to be used. If you are using Qpid-AMQP option you have to provide the file path location where the amqp.properties file is saved.
Provider URL failover list	A list of the failover URLs of the initial context for sessions with the JNDI provider. If the connection to the primary JNDI provider becomes unavailable, API Gateway automatically attempts a connection to a JNDI provider specified in this list. Specify one URL per line. Keep the following points in mind when adding JNDI provider URLs to the failover list: The JNDI providers must be the same type as the primary provider. For example, if the primary provider is a webMethods Broker, then the JNDI providers in the failover list must also be webMethods Brokers. The administered objects on the providers must be identical to the each other. Once Integration Server connects to a JNDI provider, it continues to use that JNDI provider until the connection is lost or interrupted. When you start or restart a connection alias, Integration Server attempts to connect to the primary JNDI provider. If the connection fails, Integration Server immediately attempts to connect to the first JNDI provider in the failover list. If the connection fails, Integration Server attempts to connect to the next JNDI provider in the list. When using webMethods Broker as a JNDI provider, you can keep objects in sync between webMethods Brokers using a webMethods Broker territory. That way objects can automatically forward from on webMethods Broker to another within the territory. When using a cluster of Universal Messaging realm servers as the JNDI provider, Software AG recommends that you do not specify a Provider URL Failover List value. The realm URLS specified in Provider URL function as the failover list.
Security principal	The principal name, or user name supplied by API Gateway to the JNDI provider, if the provider requires one for accessing the JNDI directory. For information about whether or not the JNDI provider requires security principal information, consult the product documentation for the JNDI provider.
Security credentials	The credentials, or password, that API Gateway provides to the JNDI provider, if the provider requires security credentials to access the JNDI directory. For information about whether or not the JNDI provider requires security credentials, consult the product documentation for the JNDI provider.
Other properties	Any additional properties the JNDI provider requires for configuration. For example, you might need to specify the classpath for any additional .jar or class files that the JNDI provider needs to connect to the JNDI. When you select a predefined JNDI template, API Gateway populates this field with any additional properties and placeholder information required by the JNDI provider. For more information about additional properties or classes required by a JNDI provider and the location of those files, see the product documentation for the JNDI provider.

Click Add.
The JNDI provider alias created is listed in a table under JNDI provider alias definitions in the Messaging page.

What to do next

You can edit, export the alias definition or delete the JNDI provider alias as required. You can also perform a test lookup for a JNDI provider to ascertain it is working as expected.

Considerations while using Software AG Universal Messaging as a JMS provider

Keep the following points in mind when using Universal Messaging as the JMS provider:

When using Universal Messaging, if the version of Universal Messaging is equivalent to or higher than the version of API Gateway, you do not need to add any client libraries to the Integration Server classpath.
When using Universal Messaging, if the version of Universal Messaging is lower than the version of API Gateway, you have to add the JMS provider's client libraries to the Integration Server classpath. You can do it in one of the following ways:
- Place the libraries in the server's classpath by placing them in the Install directory\instances\ instance_name\lib\jars\custom directory. For details on the procedure, see webMethods Integration Server Administrator’s Guide.
- Make the libraries available to all server instances by placing them in the Install directory\IntegrationServer\instances\lib\jars directory.
- Isolate the jars within a package classloader by placing them in the following directory: packageName\code\jars. If you place the files in the package classloader, make sure to set the Class Loader property when configuring a JMS connection alias to this JMS provider.
Note: If you have configured and are using Software AG Universal Messaging, on migration from an earlier version of API Gateway to API Gateway 10.5, for example, if you are migrating from API Gateway 10.3 to 10.5, then the JNDI provider alias created in the 10.3 version is found to point to the 10.3 Universal Messaging endpoint. You can resolve this by either copying the 10.3 Universal Messaging client jars to 10.5 Integration Server's classpath or by manually changing the Provider URL of the JNDI Provider Alias in 10.5 Integration Server to point to the 10.5 Universal Messaging endpoint.
Keep the Universal Messaging client libraries up to date. If you install a Universal Messaging fix that updates the client libraries, make sure to copy the updated Universal Messaging client library files to the Software AG_directory /common/lib directory used by API Gateway.

For details on other supported JMS providers, see webMethods Integration Server Administrator’s Guide.