greg/je
1
0
Fork 0
mirror of https://github.com/berkeleydb/je.git synced 2024-11-15 01:46:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
je/docs/ReplicationGuide/exceptions.html

319 lines
17 KiB
HTML
Raw Normal View History

Initial import.
2021-06-06 17:46:45 +00:00
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>HA Exceptions</title>
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
<link rel="start" href="index.html" title="Getting Started with Berkeley DB, Java Edition High Availability Applications" />
<link rel="up" href="progoverview.html" title="Chapter 2. Replication API First Steps" />
<link rel="prev" href="progoverview.html" title="Chapter 2. Replication API First Steps" />
<link rel="next" href="repenvironmentopen.html" title="Opening a Replicated Environment" />
</head>
<body>
<div xmlns="" class="navheader">
<div class="libver">
<p>Library Version 12.2.7.5</p>
</div>
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">HA Exceptions</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="progoverview.html">Prev</a> </td>
<th width="60%" align="center">Chapter 2. Replication API First Steps</th>
<td width="20%" align="right"> <a accesskey="n" href="repenvironmentopen.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="exceptions"></a>HA Exceptions</h2>
</div>
</div>
</div>
<div class="toc">
<dl>
<dt>
<span class="sect2">
<a href="exceptions.html#master-exceptions">Master-Specific HA Exceptions</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="exceptions.html#replica-exceptions">Replica-Specific HA Exceptions</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="exceptions.html#handleexception">Replicated Environment Handle-Specific Exceptions</a>
</span>
</dt>
</dl>
</div>
<p>
JE HA requires you to manage more error situations that you
would have to if you were writing a non-replicated application.
These error situations translate to additional exceptions that
you must contend with in your code. Before continuing with our
description of how to write a replicated application, it is
useful to review the HA-specific exceptions that your
application must manage.
</p>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="master-exceptions"></a>Master-Specific HA Exceptions</h3>
</div>
</div>
</div>
<p>
There are two exceptions that you can see on a Master node,
and which you will not see anywhere else. They are:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
<a class="ulink" href="../java/com/sleepycat/je/rep/InsufficientReplicasException.html" target="_top">InsufficientReplicasException</a>
</p>
<p>
This exception can be raised on a transaction begin or commit. It means that the
Master cannot successfully commit a transaction, or begin one, because it is not in contact
with enough Electable Replicas. The number of Electable Replicas required to successfully commit
the transaction is a function of the durability policy that
you have set for the transaction. See
<a class="xref" href="txn-management.html#durability" title="Managing Durability">Managing Durability</a>
for more information.
</p>
<p>
If raised on a transaction commit operation, this
exception means that the transaction has not been
committed. Instead, it has been marked as invalid.
In response to this exception, your application
must at a minimum abort the transaction. It is up
to you whether you want to retry the transaction at
some later time when more Replicas are in contact
with the Master.
</p>
<p>
If raised on a transaction begin operation, this
exception means that the transaction has not begun.
If the application intended to initiate a read-only
transaction on a Master, it can avoid this
exception by ensuring that the transaction is
configured to not require any acknowledgments. For
information on configuring acknowledgments, see
<a class="xref" href="txn-management.html#managingacks" title="Managing Acknowledgements">Managing Acknowledgements</a>.
</p>
</li>
<li>
<p>
<a class="ulink" href="../java/com/sleepycat/je/rep/InsufficientAcksException.html" target="_top">InsufficientAcksException</a>
</p>
<p>
This exception can be raised on a transaction commit. It means that the
Master has successfully committed the transaction locally, but it has not
received enough acknowledgements from its Electable Replicas in the timeframe
allocated for acknowledgements to be received.
</p>
<p>
The application should respond to this exception in such a way as to alert
the administrator that there might be a problem with the health of the
network or the nodes participating in the replication group.
</p>
<p>
For information on how to manage acknowledgement policies, see
<a class="xref" href="txn-management.html#managingacks" title="Managing Acknowledgements">Managing Acknowledgements</a>.
</p>
</li>
</ul>
</div>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="replica-exceptions"></a>Replica-Specific HA Exceptions</h3>
</div>
</div>
</div>
<p>
The exceptions that you can see on a Replica, and nowhere else, are:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
<a class="ulink" href="../java/com/sleepycat/je/rep/ReplicaConsistencyException.html" target="_top">ReplicaConsistencyException</a>
</p>
<p>
Indicates that the Replica was unable to meet the defined consistency
requirements in the allocated period of time.
</p>
<p>
If this exception is encountered frequently, it indicates that the
consistency policy requirements are too strict and cannot be met routinely
given the load being placed on the system and the hardware resources that
are available to service the load. The exception may also indicate that
there is a network related issue that is preventing the Replica from
communicating with the Master and keeping up with the replication stream.
</p>
<p>
In response to this exception, your application can either attempt to retry
the transaction, or you can relax your application's consistency
requirements until the transaction can successfully complete.
</p>
<p>
For information on managing consistency policies, see
<a class="xref" href="consistency.html" title="Managing Consistency">Managing Consistency</a>.
</p>
</li>
<li>
<p>
<a class="ulink" href="../java/com/sleepycat/je/rep/ReplicaWriteException.html" target="_top">ReplicaWriteException</a>
</p>
<p>
An attempt was made to perform a write operation on a Replica. The exception
typically indicates an error in the application logic. In some extremely
rare cases it could be the result of a transition of the node from Master to
Replica, while a transaction was in progress.
</p>
<p>
The application must abort the current transaction and redirect all
subsequent update operations to the Master. For
example code that performs this action, see
<a class="xref" href="runtransaction.html" title="Example Run Transaction Class">Example Run Transaction Class</a>.
</p>
</li>
<li>
<p>
<a class="ulink" href="../java/com/sleepycat/je/rep/LockPreemptedException.html" target="_top">LockPreemptedException</a>
</p>
<p>
A read lock currently held by a Replica has been preempted by an HA write
operation. The Replica should abort and retry the read operation in response
to this exception.
</p>
<p>
Note that your application should attempt to catch the
<a class="ulink" href="../java/com/sleepycat/je/LockConflictException.html" target="_top">LockConflictException</a> base class rather than this class because all of the
locking exceptions are managed in the same way (abort and retry the
transaction).
</p>
</li>
<li>
<p>
<a class="ulink" href="../java/com/sleepycat/je/rep/DatabasePreemptedException.html" target="_top">DatabasePreemptedException</a>
</p>
<p>
The database handle on a Replica was forcibly closed due to the replay of an
<a class="ulink" href="../java/com/sleepycat/je/Environment.html#truncateDatabase(com.sleepycate.je.Transaction,java.lang.String,boolean)" target="_top">Environment.truncateDatabase()</a>, <a class="ulink" href="../java/com/sleepycat/je/Environment.html#removeDatabase(com.sleepycate.je.Transaction,java.lang.String)" target="_top">Environment.removeDatabase()</a> or
<a class="ulink" href="../java/com/sleepycat/je/Environment.html#renameDatabase(com.sleepycate.je.Transaction,java.lang.String,java.lang.String)" target="_top">Environment.renameDatabase()</a> operation in the
replication stream.
</p>
<p>
When this exception occurs, the application must close any open Cursors and
abort any open Transactions that are using the database, and then close the
Database handle. If the application wishes, it may reopen the database if it
still exists.
</p>
</li>
<li>
<p>
<a class="ulink" href="../java/com/sleepycat/je/rep/RollbackException.html" target="_top">RollbackException</a>
</p>
<p>
A new master has been selected, this Replica's log is ahead of the current
Master, but the Replica was unable to rollback without a
recovery. As a consequence, one or more of the most recently committed
transactions may need to be rolled back, before the Replica can synchronize
its state with that of the current Master. This
exception can happen if the electable Replica with the most
recent log files was unable to participate in the
election of the Master, perhaps because the node
had been shut down.
</p>
<p>
For details on how to handle this exception, see
<a class="xref" href="txnrollback.html" title="Managing Transaction Rollbacks">Managing Transaction Rollbacks</a>.
</p>
</li>
<li>
<p>
<a class="ulink" href="../java/com/sleepycat/je/rep/InsufficientLogException.html" target="_top">InsufficientLogException</a>
</p>
<p>
Indicates that the log files constituting the Environment are insufficient
and cannot be used as the basis for continuing with the replication stream
provided by the current master.
</p>
<p>
This exception generally means that the node has been down for a long enough
time that it can not be brought up-to-date by the Master. For information on
how to respond to this condition, see
<a class="xref" href="logfile-restore.html" title="Restoring Log Files">Restoring Log Files</a>.
</p>
</li>
</ul>
</div>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="handleexception"></a>Replicated Environment Handle-Specific Exceptions</h3>
</div>
</div>
</div>
<p>
In addition to Master- and Replica-specific exceptions, it is possible for a
<a class="ulink" href="../java/com/sleepycat/je/rep/ReplicatedEnvironment.html" target="_top">ReplicatedEnvironment</a> handle to throw an <a class="ulink" href="../java/com/sleepycat/je/rep/UnknownMasterException.html" target="_top">UnknownMasterException</a>. This exception
indicates that the operation being tried requires communication with a Master, but
the Master is not available.
</p>
<p>
This exception typically indicates that there is a problem with your physical
infrastructure. It might mean that an insufficient number of electable nodes are available to
elect a Master, or that the current node is unable to communicate with other nodes
due to, for example, network problems.
</p>
<p>
In response to this exception, your application can try any number of corrective
actions, from immediately retrying the operation, to logging the problem and then
abandoning the operation, to waiting some predetermined period of time before
attempting the operation again. Your application can also
use the <a class="ulink" href="../java/com/sleepycat/je/rep/monitor/Monitor.html" target="_top">Monitor</a> or the <a class="ulink" href="../java/com/sleepycat/je/rep/StateChangeListener.html" target="_top">StateChangeListener</a> to be
notified when a Master becomes available. For more
information see <a class="xref" href="monitors.html" title="Chapter 5. Writing Monitor Nodes">Writing Monitor Nodes</a>
or <a class="xref" href="replicawrites.html#using-statechangelistener" title="Using the StateChangeListener">Using the StateChangeListener</a>.
</p>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="progoverview.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="progoverview.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="repenvironmentopen.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 2. Replication API First Steps </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Opening a Replicated Environment</td>
</tr>
</table>
</div>
</body>
</html>
Reference in a new issue Copy permalink