1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>Permanent Message Handling</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Getting Started with Replicated Berkeley DB Applications" /> 10 <link rel="up" href="repapp.html" title="Chapter��3.��The DB Replication Manager" /> 11 <link rel="prev" href="repmgr_init_example_c.html" title="Adding the Replication Manager to SimpleTxn" /> 12 <link rel="next" href="electiontimes.html" title="Managing Election Times" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Permanent Message Handling</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="repmgr_init_example_c.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��3.��The DB Replication Manager</th> 23 <td width="20%" align="right">��<a accesskey="n" href="electiontimes.html">Next</a></td> 24 </tr> 25 </table> 26 <hr /> 27 </div> 28 <div class="sect1" lang="en" xml:lang="en"> 29 <div class="titlepage"> 30 <div> 31 <div> 32 <h2 class="title" style="clear: both"><a id="fwrkpermmessage"></a>Permanent Message Handling</h2> 33 </div> 34 </div> 35 </div> 36 <div class="toc"> 37 <dl> 38 <dt> 39 <span class="sect2"> 40 <a href="fwrkpermmessage.html#fmwrkpermpolicy">Identifying Permanent Message Policies</a> 41 </span> 42 </dt> 43 <dt> 44 <span class="sect2"> 45 <a href="fwrkpermmessage.html#fmwrkpermtimeout">Setting the Permanent Message Timeout</a> 46 </span> 47 </dt> 48 <dt> 49 <span class="sect2"> 50 <a href="fwrkpermmessage.html#perm2fmwrkexample">Adding a Permanent Message Policy to 51 52 53 <span>RepQuoteExampleGSG</span> 54 </a> 55 </span> 56 </dt> 57 </dl> 58 </div> 59 <p> 60 As described in <a class="xref" href="permmessages.html" title="Permanent Message Handling">Permanent Message Handling</a>, 61 messages are marked permanent if they contain database 62 modifications that should be committed at the replica. 63 DB's replication code decides if it must flush its 64 transaction logs to disk depending on whether it receives 65 sufficient permanent message acknowledgments from the 66 participating replicas. More importantly, the thread 67 performing the transaction commit blocks 68 until it either receives enough acknowledgments, or the 69 acknowledgment timeout expires. 70 </p> 71 <p> 72 The Replication Manager is fully capable of managing permanent messages 73 for you if your application requires it (most do). 74 Almost all of the details of this are handled by the 75 Replication Manager for you. However, you do have to set some policies 76 that tell the Replication Manager how to handle permanent messages. 77 </p> 78 <p> 79 There are two things that you have to do: 80 </p> 81 <div class="itemizedlist"> 82 <ul type="disc"> 83 <li> 84 <p> 85 Determine how many acknowledgments 86 must be received by the master. 87 </p> 88 </li> 89 <li> 90 <p> 91 Identify the amount of time that 92 replicas have to send their 93 acknowledgments. 94 </p> 95 </li> 96 </ul> 97 </div> 98 <div class="sect2" lang="en" xml:lang="en"> 99 <div class="titlepage"> 100 <div> 101 <div> 102 <h3 class="title"><a id="fmwrkpermpolicy"></a>Identifying Permanent Message Policies</h3> 103 </div> 104 </div> 105 </div> 106 <p> 107 108 You identify permanent message policies using the 109 110 111 <span> 112 <code class="classname">ReplicationManagerAckPolicy</code> 113 class which you pass to the environment 114 using the 115 <code class="methodname">EnvironmentConfig.setReplicationManagerAckPolicy</code> 116 method. 117 </span> 118 119 Note that you can set permanent message 120 policies at any time during the life of the 121 application. 122 </p> 123 <p> 124 The following permanent message policies are available when you use 125 the Replication Manager: 126</p> 127 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 128 <h3 class="title">Note</h3> 129 <p> 130 The following list mentions <span class="emphasis"><em>electable peer</em></span> 131 several times. This is simply another environment that can be 132 elected to be a master (that is, it has a priority greater than 0). 133 Do not confuse this with the concept of a peer as used for client 134 to client transfers. See <a class="xref" href="c2ctransfer.html" title="Client to Client Transfer">Client to Client Transfer</a> for more information on client 135 to client transfers. 136 </p> 137 </div> 138 <div class="itemizedlist"> 139 <ul type="disc"> 140 <li> 141 <p> 142 143 <code class="literal">ReplicationManagerAckPolicy.NONE</code> 144 </p> 145 <p> 146 No permanent message acknowledgments are required. If 147 this policy is selected, permanent message handling is 148 essentially "turned off." That is, the master will 149 never wait for replica acknowledgments. In this case, 150 transaction log data is either flushed or not strictly 151 depending on the type of commit that is being performed 152 (synchronous or asynchronous). 153 </p> 154 </li> 155 <li> 156 <p> 157 158 <code class="literal">ReplicationManagerAckPolicy.ONE</code> 159 </p> 160 <p> 161 At least one replica must acknowledge the permanent 162 message within the timeout period. 163 </p> 164 </li> 165 <li> 166 <p> 167 168 <code class="literal">ReplicationManagerAckPolicy.ONE_PEER</code> 169 </p> 170 <p> 171 At least one electable peer must acknowledge the permanent 172 message within the timeout period. 173 </p> 174 </li> 175 <li> 176 <p> 177 178 <code class="literal">ReplicationManagerAckPolicy.ALL</code> 179 </p> 180 <p> 181 All replicas must acknowledge the message within 182 the timeout period. This 183 policy should be selected only if your replication 184 group has a small number of replicas, and those replicas 185 are on extremely reliable networks and servers. 186 </p> 187 <p> 188 When this flag is used, the actual number of 189 replicas that must respond is 190 determined by the value set for 191 192 193 <span><code class="methodname">EnvironmentConfig.setReplicationNumSites()</code>.</span> 194 </p> 195 </li> 196 <li> 197 <p> 198 199 <code class="literal">ReplicationManagerAckPolicy.ALL_PEERS</code> 200 </p> 201 <p> 202 All electable peers must acknowledge the message within the 203 timeout period. This 204 policy should be selected only if your replication 205 group is small, and its various environments 206 are on extremely reliable networks and servers. 207 </p> 208 </li> 209 <li> 210 <p> 211 212 <code class="literal">ReplicationManagerAckPolicy.QUORUM</code> 213 </p> 214 <p> 215 A quorum of electable peers must acknowledge the message within the timeout period. 216 A quorum is reached when acknowledgments are received from the minimum number 217 of environments needed to ensure that the record remains durable 218 if an election is held. That is, the master wants to hear from enough 219 electable replicas that they have committed the record so that if an election 220 is held, the master knows the record will exist even if a new master is selected. 221 </p> 222 </li> 223 </ul> 224 </div> 225 <p> 226 By default, a quorum of electable peers must must acknowledge a permanent 227 message in order for it considered to have been successfully 228 transmitted. The actual number of replicas that must respond is 229 calculated using the value set with 230 231 232 <span><code class="methodname">EnvironmentConfig.setReplicationNumSites()</code>.</span> 233</p> 234 </div> 235 <div class="sect2" lang="en" xml:lang="en"> 236 <div class="titlepage"> 237 <div> 238 <div> 239 <h3 class="title"><a id="fmwrkpermtimeout"></a>Setting the Permanent Message Timeout</h3> 240 </div> 241 </div> 242 </div> 243 <p> 244 The permanent message timeout represents the 245 maximum amount of time the committing thread 246 will block waiting for message 247 acknowledgments. If sufficient 248 acknowledgments arrive before this timeout has 249 expired, the thread continues operations as 250 normal. However, if this timeout expires, the 251 committing thread flushes its transaction log 252 buffer before continuing with normal 253 operations. 254 </p> 255 <p> 256 You set the timeout value using 257 <code class="methodname">Environment.setReplicationTimeout()</code>. 258 You pass this method the 259 <code class="methodname">ReplicationTimeoutType.ACK_TIMEOUT</code> 260 constant and a timeout value in microseconds. 261 </p> 262 <p> 263 For example: 264 </p> 265 <pre class="programlisting"> dbenv.setReplicationTimeout(ReplicationTimeoutType.ACK_TIMEOUT, 100); </pre> 266 <p> 267 This timeout value can be set at anytime during the 268 life of the application. 269 </p> 270 </div> 271 <div class="sect2" lang="en" xml:lang="en"> 272 <div class="titlepage"> 273 <div> 274 <div> 275 <h3 class="title"><a id="perm2fmwrkexample"></a>Adding a Permanent Message Policy to 276 277 278 <span>RepQuoteExampleGSG</span> 279 </h3> 280 </div> 281 </div> 282 </div> 283 <p> 284 For illustration purposes, we will now update 285 286 287 <code class="literal">RepQuoteExampleGSG</code> 288 such that it requires only one acknowledgment from 289 a replica on transactional commits. Also, we will give 290 this acknowledgment a 500 microsecond timeout 291 value. This means that our application's main 292 thread will block for up to 500 microseconds waiting 293 for an acknowledgment. If it does not receive at 294 least one acknowledgment in that amount of time, 295 DB will flush the transaction logs to disk 296 before continuing on. 297 </p> 298 <p> 299 This is a very simple update. We can perform the 300 entire thing in 301 302 <code class="methodname">RepQuoteExampleGSG.init()</code> 303 immediately after we set the application's priority 304 and before we open our environment handle. 305 </p> 306 <pre class="programlisting"> public int init(RepConfig config) 307 throws DatabaseException 308 { 309 int ret = 0; 310 appConfig = config; 311 EnvironmentConfig envConfig = new EnvironmentConfig(); 312 envConfig.setErrorStream(System.err); 313 envConfig.setErrorPrefix(RepConfig.progname); 314 315 envConfig.setReplicationManagerLocalSite(appConfig.getThisHost()); 316 for (ReplicationHostAddress host = appConfig.getFirstOtherHost(); 317 host != null; host = appConfig.getNextOtherHost()) 318 { 319 envConfig.replicationManagerAddRemoteSite(host); 320 } 321 322 if (appConfig.totalSites > 0) 323 envConfig.setReplicationNumSites(appConfig.totalSites); 324 envConfig.setReplicationPriority(appConfig.priority); 325 326 <strong class="userinput"><code>envConfig.setReplicationManagerAckPolicy( 327 ReplicationManagerAckPolicy.ALL); 328 envConfig.setReplicationTimeout(ReplicationTimeoutType.ACK_TIMEOUT, 329 500); </code></strong> 330 331 envConfig.setCacheSize(RepConfig.CACHESIZE); 332 envConfig.setTxnNoSync(true); 333 ... </pre> 334 </div> 335 </div> 336 <div class="navfooter"> 337 <hr /> 338 <table width="100%" summary="Navigation footer"> 339 <tr> 340 <td width="40%" align="left"><a accesskey="p" href="repmgr_init_example_c.html">Prev</a>��</td> 341 <td width="20%" align="center"> 342 <a accesskey="u" href="repapp.html">Up</a> 343 </td> 344 <td width="40%" align="right">��<a accesskey="n" href="electiontimes.html">Next</a></td> 345 </tr> 346 <tr> 347 <td width="40%" align="left" valign="top">Adding the Replication Manager to 348 349 350 <span>SimpleTxn</span> 351 ��</td> 352 <td width="20%" align="center"> 353 <a accesskey="h" href="index.html">Home</a> 354 </td> 355 <td width="40%" align="right" valign="top">��Managing Election Times</td> 356 </tr> 357 </table> 358 </div> 359 </body> 360</html> 361