List:Commits« Previous MessageNext Message »
From:tony.bedford Date:October 26 2010 11:08am
Subject:svn commit - mysqldoc@docsrva: r23382 - trunk/refman-common
View as plain text  
Author: tbedford
Date: 2010-10-26 13:08:56 +0200 (Tue, 26 Oct 2010)
New Revision: 23382

Log:
Load balancing failover (thanks Todd Farmer)

Modified:
   trunk/refman-common/connector-j.xml


Modified: trunk/refman-common/connector-j.xml
===================================================================
--- trunk/refman-common/connector-j.xml	2010-10-26 09:33:28 UTC (rev 23381)
+++ trunk/refman-common/connector-j.xml	2010-10-26 11:08:56 UTC (rev 23382)
Changed blocks: 1, Lines Added: 160, Lines Deleted: 0; 6587 bytes

@@ -4176,6 +4176,166 @@
 
         </section>
 
+        <section id="connector-j-usagenotes-j2ee-concepts-load-balancing-failover">
+
+          <title>Load Balancing Failover Policies</title>
+
+          <para>
+            Connector/J provides a useful load-balancing implementation
+            for Cluster or multi-master deployments. As of Connector/J
+            5.1.12, this same implementation is used for balancing load
+            between read-only slaves with
+            <literal>ReplicationDriver</literal>. When trying to balance
+            workload between multiple servers, the driver has to
+            determine when it is safe to swap servers, doing so in the
+            middle of a transaction, for example, could cause problems.
+            It is important not to lose state information. For this
+            reason, Connector/J will only try to pick a new server when
+            one of the following happens:
+          </para>
+
+          <orderedlist>
+
+            <listitem>
+              <para>
+                At transaction boundaries (transactions are explicitly
+                committed or rolled back).
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                A communication exception (SQL State starting with "08")
+                is encountered.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                When a <literal>SQLException</literal> matches
+                conditions defined by user, using the extension points
+                defined by the
+                <literal>loadBalanceSQLStateFailover</literal>,
+                <literal>loadBalanceSQLExceptionSubclassFailover</literal>
+                or <literal>loadBalanceExceptionChecker</literal>
+                properties.
+              </para>
+            </listitem>
+
+          </orderedlist>
+
+          <para>
+            The third condition is new, and revolves around three new
+            properties introduced with Connector/J 5.1.13. It allows you
+            to control which <literal>SQLException</literal>s trigger
+            failover.
+          </para>
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                <literal>loadBalanceExceptionChecker</literal> - The
+                <literal>loadBalanceExceptionChecker</literal> property
+                is really the key. This takes a fully-qualified class
+                name which implements the new
+                <literal>com.mysql.jdbc.LoadBalanceExceptionChecker</literal>
+                interface. This interface is very simple, and you only
+                need to implement the following method:
+              </para>
+
+<programlisting>
+public boolean shouldExceptionTriggerFailover(SQLException ex)
+</programlisting>
+
+              <para>
+                A <literal>SQLException</literal> is passed in, and a
+                boolean returned. <literal>True</literal> triggers a
+                failover, <literal>false</literal> does not.
+              </para>
+
+              <para>
+                You can use this to implement your own custom logic. An
+                example where this might be useful is when dealing with
+                transient errors when using MySQL Cluster, where certain
+                buffers may become overloaded. The following code
+                snippet illustrates this:
+              </para>
+
+<programlisting language="java">
+<![CDATA[
+public class NdbLoadBalanceExceptionChecker
+ extends StandardLoadBalanceExceptionChecker {
+
+ public boolean shouldExceptionTriggerFailover(SQLException ex) {
+  return super.shouldExceptionTriggerFailover(ex)
+    ||  checkNdbException(ex);
+ }
+
+ private boolean checkNdbException(SQLException ex){
+ // Have to parse the message since most NDB errors
+ // are mapped to the same DEMC.
+  return (ex.getMessage().startsWith("Lock wait timeout exceeded") ||
+  (ex.getMessage().startsWith("Got temporary error")
+  && ex.getMessage().endsWith("from NDB")));
+ }
+}
+]]>
+</programlisting>
+
+              <para>
+                The code above extends
+                <literal>com.mysql.jdbc.StandardLoadBalanceExceptionChecker</literal>,
+                which is the default implementation. There are a few
+                convenient shortcuts built into this, for those who want
+                to have some level of control using properties, without
+                writing Java code. This default implementation uses the
+                two remaining properties:
+                <literal>loadBalanceSQLStateFailover</literal> and
+                <literal>loadBalanceSQLExceptionSubclassFailover</literal>.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <literal>loadBalanceSQLStateFailover</literal> - allows
+                you to define a comma-delimited list of
+                <literal>SQLState</literal> code prefixes, against which
+                a <literal>SQLException</literal> is compared. If the
+                prefix matches, failover is triggered. So, for example,
+                the following would trigger a failover if a given
+                <literal>SQLException</literal> starts with "00", or is
+                "12345":
+              </para>
+
+<programlisting>
+loadBalanceSQLStateFailover=00,12345
+</programlisting>
+            </listitem>
+
+            <listitem>
+              <para>
+                <literal>loadBalanceSQLExceptionSubclassFailover</literal>
+                - can be used in conjunction with
+                <literal>loadBalanceSQLStateFailover</literal> or on its
+                own. If you want certain subclasses of
+                <literal>SQLException</literal> to trigger failover,
+                simply provide a comma-delimited list of fully-qualified
+                class or interface names to check against. For example,
+                if you want all
+                <literal>SQLTransientConnectionExceptions</literal> to
+                trigger failover, you would specify:
+              </para>
+
+<programlisting>
+loadBalanceSQLExceptionSubclassFailover=java.sql.SQLTransientConnectionException
+</programlisting>
+            </listitem>
+
+          </itemizedlist>
+
+        </section>
+
       </section>
 
       <section id="connector-j-usagenotes-tomcat">


Thread
svn commit - mysqldoc@docsrva: r23382 - trunk/refman-commontony.bedford26 Oct