How Do I Use JDBC_PING For Initial Discovery

Environment

• Red Hat JBoss Enterprise Application Platform (EAP)
  • 7.x
  • 6.x

Issue

• We are setting up a JBoss clustering and would like to use JDBC_PING for initial discovery as opposed to TCPPING, MPING, etc.
• How to configure JDBC_PING?

Resolution

For information on the JDBC_PING protocol one can look Content from community.jboss.org is not included.here.
Process:

• Replace MPING, TCPPING, etc with JDBC_PING within the stack (TCP or UDP) used by the JBoss cluster. There are two approaches that can be used to configure JDBC_PING: via connection properties or JNDI lookup.
• Add the JDBC driver as module

There are two options in regards to setting up jgroups stack, adding JDBC_PING in the current stack Adding JDBC_PING protocol on the TCP/UDP stack, or creating a new stack Creating a JDBC_PING separated stack and for JNDI setting, see section JNDI LookUP.
Finally, see Important notes about important setting details.

Adding JDBC_PING protocol on the TCP/UDP stack

Given the user has JDBC driver installed already as a module, then configure the dependency in JGroups' module.xml. But editing JGroups' module.xml is not recommended because it will cause an issue when patching or upgrading EAP.

JBoss EAP 7.1+ CLI command:

### adding JDBC_PING
/subsystem=jgroups/stack=JDBC_PING/protocol=JDBC_PING:add(data-source=ExampleDS, add-index=1)
### removing MPING
/subsystem=jgroups/stack=tcp/protocol=MPING:remove()

Stack will be as below:

        <subsystem xmlns="urn:jboss:domain:jgroups:1.1" default-stack="tcp">
...
                <stack name="tcp">
                    <transport type="TCP" socket-binding="jgroups-tcp"/>
                    <jdbc-protocol type="JDBC_PING" data-source="ExampleDS"/>
                    <protocol type="MERGE3"/>
                    <socket-protocol type="FD_SOCK" socket-binding="jgroups-tcp-fd"/>
                    <protocol type="FD_ALL"/>
                    <protocol type="VERIFY_SUSPECT"/>
                    <protocol type="pbcast.NAKACK2"/>
                    <protocol type="UNICAST3"/>
                    <protocol type="pbcast.STABLE"/>
                    <protocol type="pbcast.GMS"/>
                    <protocol type="UFC"/>
                    <protocol type="MFC"/>
                    <protocol type="FRAG3"/>
                </stack>
            </stacks>
        </subsystem>

There are two other options for adding JDBC_PING - both should be avoided:

/subsystem=jgroups/stack=tcp:add-protocol(type=JDBC_PING)
/subsystem=jgroups/stack=tcp/protocol=JDBC_PING:add(add-index=1)

Both result in the follow configuration:

### Result:
<protocol type="org.jgroups.protocols.JDBC_PING">

Creating a JDBC_PING separated stack

Another option is to create a completely new stack as described on EAP 7.4 Configuration Guide - HA section - Cli commands for 7.1+:

# Add the JDBC_PING stack
/subsystem=jgroups/stack=JDBC_PING:add
/subsystem=jgroups/stack=JDBC_PING/transport=TCP:add(socket-binding=jgroups-tcp)
/subsystem=jgroups/stack=JDBC_PING/protocol=JDBC_PING:add(data-source=ExampleDS)
/subsystem=jgroups/stack=JDBC_PING/protocol=MERGE3:add
/subsystem=jgroups/stack=JDBC_PING/protocol=FD_SOCK:add
/subsystem=jgroups/stack=JDBC_PING/protocol=FD_ALL:add
/subsystem=jgroups/stack=JDBC_PING/protocol=VERIFY_SUSPECT:add
/subsystem=jgroups/stack=JDBC_PING/protocol=pbcast.NAKACK2:add
/subsystem=jgroups/stack=JDBC_PING/protocol=UNICAST3:add
/subsystem=jgroups/stack=JDBC_PING/protocol=pbcast.STABLE:add
/subsystem=jgroups/stack=JDBC_PING/protocol=pbcast.GMS:add
/subsystem=jgroups/stack=JDBC_PING/protocol=MFC:add
/subsystem=jgroups/stack=JDBC_PING/protocol=FRAG2:add
# Set JDBC_PING as the stack for the ee channel
/subsystem=jgroups/channel=ee:write-attribute(name=stack,value=JDBC_PING)

Below we use the datasource for ExampleDS and the dependency issue is resolved with following configuration:

                <stack name="JDBC_PING">
                    <transport type="TCP" socket-binding="jgroups-tcp"/>
                    <jdbc-protocol type="JDBC_PING" data-source="ExampleDS"/>
                    <protocol type="MERGE3"/>
                    <protocol type="FD_SOCK"/>
                    <protocol type="FD_ALL"/>
                    <protocol type="VERIFY_SUSPECT"/>
                    <protocol type="pbcast.NAKACK2"/>
                    <protocol type="UNICAST3"/>
                    <protocol type="pbcast.STABLE"/>
                    <protocol type="pbcast.GMS"/>
                    <protocol type="MFC"/>
                    <protocol type="FRAG3"/>
                </stack>

EAP 7.1+ - Datasource setting

The above configuration is very simple, as one just sets jdbc-protocol with the respective datasource (via command /subsystem=jgroups/stack=JDBC_PING/protocol=JDBC_PING:add(data-source=ExampleDS, add-index=1)) and the process is done, given the datasource is properly configured.
Previously, it was necessary add the JDBC_PING protocol and each property separately - see example below.

JNDI LookUP:

Note: JBoss EAP 6 does not set up a dependency on the datasource. This can result in errors if the JGroups channel is started before the datasource, or stopped after it. Therefore configuring the datasource through a JNDI lookup is not recommended.

        <subsystem xmlns="urn:jboss:domain:jgroups:1.1" default-stack="tcp">
            <stack name="tcp">
                <transport type="TCP" socket-binding="jgroups-tcp"/>
                <protocol type="JDBC_PING">
                    <property name="datasource_jndi_name">
                        java:jboss/datasources/JDBCPING
                    </property>
                </protocol>
                <protocol type="MERGE2"/>
                <protocol type="FD_SOCK" socket-binding="jgroups-tcp-fd"/>
                <protocol type="FD"/>
                <protocol type="VERIFY_SUSPECT"/>
                <protocol type="pbcast.NAKACK"/>
                <protocol type="UNICAST2"/>
                <protocol type="pbcast.STABLE"/>
                <protocol type="pbcast.GMS"/>
                <protocol type="UFC"/>
                <protocol type="MFC"/>
                <protocol type="FRAG2"/>
                <protocol type="RSVP"/>
            </stack>

Important notes

1. The above is a minimal configuration. One can specify additional properties if desired.
2. Prior to setting up configuration, database jgroups is created.
3. java:jboss/datasources/JDBCPING/ExampleDS is a datasource defined earlier within the configuration.

Root Cause

Configuration like <protocol type="JDBC_PING" data-source="ExampleDS"/> is available from EAP 7.1 and also starting on EAP 7.2+ some properties from JDBC_PING were changed to be compatible with FILE_PING:

The property remove_all_data_on_view_change is recommended to be set to true.

Clear/Restart of DB table

For JDBC_PING is it possible to clear the DB table manually while the JGroups cluster is running. However, the user should not start any new nodes until the running nodes have re-populated their data or if the JGroups cluster is running in a split cluster condition.

Diagnostic Steps

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.