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