Configure a connection to a non-default bootstrap server

A bootstrap server is an application server running in the same cell, specifically the same core group, as the service integration bus.

Connection to a non-default bootstrap server is provided by a JMS connection factory or a JMS activation specification. The connection allows applications to use a bootstrap server with a non-default endpoint address. The provider endpoint syntax example described in this topic is also relevant to bootstrap endpoint configuration in other tasks, for example when configuring a service integration bus link.

To use JMS destinations of the default messaging provider, an application or message-driven bean connects to a messaging engine on the target service integration bus on which the destinations are assigned. For example, a JMS queue is assigned to a queue destination on a service integration bus.

Applications that are running in a server that is part of the same cell as the service integration bus can usually connect to a messaging engine on that bus without requiring provider endpoints to be configured. If the cell has been divided into two core groups, each defined with its own policies, client applications that are running in a client container and client applications that are running outside the WAS environment, cannot automatically locate the required service integration bus so that, unless a core group bridge has been configured between the core groups in the same cell, configure one or more provider endpoints. Similarly, unless a core group bridge has been established between the two cells, an application running on a server in one cell cannot connect to a bus in another cell without the configuration of provider endpoints.

In the scenarios where provider endpoints are required, the clients or the servers in another bus must complete a bootstrap process through a bootstrap server. The bootstrap server does not have to be a member of the service integration bus, and it does not have to contain any messaging engines. For the application to locate the required bootstrap server, configure the provider endpoint property of the JMS connection factory or JMS activation specification used by the client application. When the bootstrap server receives the client request, it selects a messaging engine that matches the criteria specified by the connection factory or activation specification, for example the target transport chain, target group, or connection proximity. It returns the location information for this messaging engine to the client, and the client creates a new connection to the target messaging engine, if necessary.

The following figure shows a client application running outside an application server.

Figure 1. Connection to a messaging engine: Applications running outside an application server

To connect to a messaging engine, the application connects first to a bootstrap server. The bootstrap server selects a messaging engine then tells the client application to connect to that messaging engine.

The following figure shows a message-driven bean running in an application server that is in a different cell to the bus that the message-driven bean needs to be connected to in order to receive messages.

Figure 2. Connection to a messaging engine: message-driven bean application connecting to a destination in a different cell

To connect to a messaging engine, the message-driven bean connects first to a bootstrap server. The bootstrap server selects a messaging engine then tells the message-driven bean to connect to that messaging engine.

A bootstrap server listens on an endpoint defined by the combination of:

• The host name of the host on which the bootstrap server is running

• A specific port that is either SIB_END_POINT or, if security is enabled, SIB_ENDPOINT_SECURE_ADDRESS

• A bootstrap transport chain

JMS connection factory properties control how an application connects to a messaging engine, and which messaging engine is selected. If we deploy the application to an application server on which the service integration bus (SIB) service is enabled, the system uses the SIB service to locate a messaging engine that matches the connection factory criteria. The SIB service is aware of all the messaging engines running on servers in the core group of which the application server to which the application is deployed is a member.

If a suitable messaging engine is found, the application is connected to it, and does not use any provider endpoints specified on the connection factory.

This means that we cannot deploy an application to one cell to connect to a bus with the same name in a different cell. Instead the application connects to the bus in the local cell. The provider endpoints from the connection factory are used to connect to a remote bootstrap server if any of the following conditions are true:

• The application is running as a client application outside of an application server.

• No SIB service is running in the application server to which the application is deployed.

• The SIB service cannot find a suitable messaging engine for the application to connect to.

If we do not specify a value for the provider endpoints in the connection factory, the default value depends on whether the application has supplied a password.

• If the application does not supply a password, a default endpoint address of localhost:7276:BootstrapBasicMessaging is used. That is, by default, applications try to use a bootstrap server on the same host as the client, using port 7276 and the predefined bootstrap transport chain called BootstrapBasicMessaging.

• If the application does supply a password, the default secure port of 7286 and the transport chain BootstrapSecureMessaging is used to prevent the transmission of an unencrypted password to the server.

(iseries) Note: For the IBM i platform, you must (at least) change the default host name from localhost to your.server.name.

If we want an application to use a bootstrap server with a different endpoint address, specify the required endpoint address on the Provider endpoints property of the JMS connection factories or JMS activation specifications that the client application or message-driven bean uses. We can specify one or more endpoint addresses of bootstrap servers by using a comma-separated list.

The endpoint addresses for bootstrap servers must be specified in every JMS connection factory used by applications outside of an application server. To avoid having to specify a long list of bootstrap servers, we can provide a few highly-available servers as dedicated bootstrap servers. Then we can specify a short list of bootstrap servers on each connection factory.

This task is based on an application that uses a unified JMS connection factory. We can use the same task to configure a JMS queue connection factory or JMS topic connection factory, but during the task you must select the appropriate type of connection factory instead of a JMS queue connection factory. We can also use this task to configure a JMS activation specification instead of a JMS connection factory.

When you configure a connection to a non-default bootstrap server, specify the required values and use colons as separators. The syntax is as follows:

[ [host] [ ":" [ port_number] [ ":" chain_name] ] ]

Specifying host : chain_name instead of host : : chain_name (with two colons) is incorrect. The default value applies if we do not specify a value, but you must separate the fields with ":"s.

For an application to use a bootstrap server with a non-default endpoint address...

1. Identify the endpoint address of the application server to use as the bootstrap server. The endpoint address has the form host:port_number:chain_name.

   host

   The name of the host on which the server runs. It can be an IP address. For an IPv6 address, put square braces ([]) around host.The default is localhost.

   (iseries) Note: We must (at least) change the default host name from localhost to your.server.name.

   port_number

   Where specified, one of the following addresses of the messaging engine hosting the remote end of the link:

   • If security is not enabled: SIB_ENDPOINT_ADDRESS

   • If security is enabled, for secure connections: SIB_ENDPOINT_SECURE_ADDRESS

   This value is mandatory. The default is 7276 if the application has not specified a password, or 7286 if a password has been specified.

   To find either of the port_number values using the console, click Servers -> Server Types -> WebSphere application servers -> server_name -> [Communications] Ports.

   chain_name

   The name of a predefined bootstrap transport chain used to connect to the bootstrap server. If not specified, the default is BootstrapBasicMessaging if a password has not been provided, or BootstrapSecureMessaging if a password has been provided.

   The following predefined bootstrap transport chains are provided:

   BootstrapBasicMessaging

   The server transport chain InboundBasicMessaging (JFAP-TCP/IP).

   BootstrapSecureMessaging

   The server transport chain InboundSecureMessaging (JFAP-SSL-TCP/IP).

   BootstrapTunneledMessaging

   Before we can use this bootstrap transport chain, define a corresponding server transport chain on the bootstrap server. To do this, click Servers -> Server Types -> WebSphere application servers -> server_name -> [Server messaging] Messaging engine inbound transports. This transport chain tunnels JFAP and uses HTTP wrappers.

   BootstrapTunneledSecureMessaging

   Before we can use this bootstrap transport chain, define a corresponding server transport chain on the bootstrap server. To do this, click Servers -> Server Types -> WebSphere application servers -> server_name -> [Server messaging] Messaging engine inbound transports. This transport chain tunnels JFAP and uses HTTP wrappers.

   To provide more than one bootstrap server, identify all the required endpoint addresses. Separate each endpoint address with a comma. You should be able to specify the endpoint address for each bootstrap server; for example, for a server assigned non-secure port 7278, on host boothost1, and using the default transport chain BootstrapBasicMessaging:

   boothost1:7278:BootstrapBasicMessaging

   or

   boothost1:7278

   or, for a server assigned secure port 7289, on host boothost2, and using the predefined transport chain BootstrapTunneledSecureMessaging:

   boothost2:7289:BootstrapTunneledSecureMessaging

2. Optional: Configure the endpoint address of the bootstrap server on the Provider endpoint property of the connection factory.

   If the client application uses a JMS connection factory in the client container, use the Application Client Resource Configuration tool (ACRCT).

   1. Start the tool and open the EAR file for which to configure the JMS connection factory. The EAR file contents are displayed in a tree view.

   2. From the tree, select the JAR file in which to configure the JMS connection factory.

   3. Expand the JAR file to view its contents.

   4. Expand Messaging Providers > Default Provider > Connection Factories.

   5. Display the general properties of the connection factory.

      • To use an existing JMS connection factory, click the name of the connection factory.

      • To create a new JMS connection factory, click New.

        For more information about configuring a JMS connection factory in the JMS provider configuration for the application client, see Configure Java messaging client resources.

   6. On the General tab, ensure that the Provider Endpoints property includes the provider endpoint address for each bootstrap server. Type the value as a comma-separated list of endpoint addresses, for example:
      boothost1:7278,boothost2:7289:BootstrapTunneledSecureMessaging

   7. Click OK.

   8. Save the changes to the master configuration..

   If the client application uses a JMS connection factory on the server, use the WAS console.

   1. Start the WAS console.

   2. To display the default messaging provider, click Resources -> JMS -> JMS providers.

   3. Change the Scope check box to set the level at which the connection factory is to be visible, according to the needs.

   4. In the content pane click Default messaging provider to display a table of properties for the default messaging provider, including links to the types of JMS resources that it provides.

   5. In the content pane, under Additional properties, click Connection factories to display any existing connection factories in the content pane.

   6. Display the general properties of the connection factory.

      • To use an existing JMS connection factory, click the name of the connection factory.

      • To create a new JMS connection factory, click New.

      For more information about configuring a JMS connection factory, see Configure a unified connection factory for the default messaging provider.

   7. Ensure that the Provider Endpoints property includes the provider endpoint address for each bootstrap server. Type the value as a comma-separated list of endpoint addresses; for example:
      boothost1:7278,boothost2:7289:BootstrapTunneledSecureMessaging

   8. Click OK.

   9. Save the changes to the master configuration.

3. Optional: Configure the endpoint address of the bootstrap server on the Provider endpoint property of the activation specification.

   If the client application uses a JMS activation specification on the server, use the WAS console.

   1. Start the WAS console.

   2. To display the default messaging provider, click Resources -> JMS -> JMS providers.

   3. Select the default provider for which to configure an activation specification.

   4. Optional: Change the Scope check box to the scope level at which the activation specification is visible to applications, according to the needs.

   5. In the content pane, under the Additional properties heading , click Activation specifications to list any existing JMS activation specifications for the default messaging provider in the content pane.

   6. Display the properties of the JMS activation specification.

      • To use an existing JMS activation specification, click one of the names listed.

      • To create a new JMS activation specification, click New.

      For more information about configuring a JMS activation specification, see Configure an activation specification for the default messaging provider.

   7. Ensure that the Provider Endpoints property includes the provider endpoint address for each bootstrap server. Type the value as a comma-separated list of endpoint addresses; for example:
      boothost1:7278,boothost2:7289:BootstrapTunneledSecureMessaging

   8. Click OK.

   9. Save the changes to the master configuration.

Related concepts

How JMS applications connect to a messaging engine on a bus

JNDI namespaces and connecting to different JMS provider environments

Service integration configurations

Related tasks

Configure a unified connection factory for the default messaging provider

Configure a queue connection factory for the default messaging provider

Configure a topic connection factory for the default messaging provider

Configure an activation specification for the default messaging provider

createSIBJMSActivationSpec command

modifySIBJMSActivationSpec command

Related information:

JMS activation specification [Settings]

Permitted transports [Collection]