releasenotes.html 17.2 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta content="Apache Forrest" name="Generator">
<meta name="Forrest-version" content="0.8">
<meta name="Forrest-skin-name" content="pelt">
<title>ZooKeeper 3.0.0 Release Notes</title>
<link type="text/css" href="skin/basic.css" rel="stylesheet">
<link media="screen" type="text/css" href="skin/screen.css" rel="stylesheet">
<link media="print" type="text/css" href="skin/print.css" rel="stylesheet">
<link type="text/css" href="skin/profile.css" rel="stylesheet">
<script src="skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="skin/fontsize.js" language="javascript" type="text/javascript"></script>
<link rel="shortcut icon" href="images/favicon.ico">
</head>
<body onload="init()">
<script type="text/javascript">ndeSetTextSize();</script>
<div id="top">
<!--+
    |breadtrail
    +-->
<div class="breadtrail">
<a href="http://www.apache.org/">Apache</a> &gt; <a href="http://hadoop.apache.org/">Hadoop</a> &gt; <a href="http://hadoop.apache.org/zookeeper/">ZooKeeper</a><script src="skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
</div>
<!--+
    |header
    +-->
<div class="header">
<!--+
    |start group logo
    +-->
<div class="grouplogo">
<a href="http://hadoop.apache.org/"><img class="logoImage" alt="Hadoop" src="images/hadoop-logo.jpg" title="Apache Hadoop"></a>
</div>
<!--+
    |end group logo
    +-->
<!--+
    |start Project Logo
    +-->
<div class="projectlogo">
<a href="http://hadoop.apache.org/zookeeper/"><img class="logoImage" alt="ZooKeeper" src="images/zookeeper_small.gif" title="The Hadoop database"></a>
</div>
<!--+
    |end Project Logo
    +-->
<!--+
    |start Search
    +-->
<div class="searchbox">
<form action="http://www.google.com/search" method="get" class="roundtopsmall">
<input value="hadoop.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">&nbsp; 
                    <input name="Search" value="Search" type="submit">
</form>
</div>
<!--+
    |end search
    +-->
<!--+
    |start Tabs
    +-->
<ul id="tabs">
<li>
<a class="unselected" href="http://hadoop.apache.org/zookeeper/">Project</a>
</li>
<li>
<a class="unselected" href="http://wiki.apache.org/hadoop/ZooKeeper">Wiki</a>
</li>
<li class="current">
<a class="selected" href="index.html">ZooKeeper Documentation</a>
</li>
</ul>
<!--+
    |end Tabs
    +-->
</div>
</div>
<div id="main">
<div id="publishedStrip">
<!--+
    |start Subtabs
    +-->
<div id="level2tabs"></div>
<!--+
    |end Endtabs
    +-->
<script type="text/javascript"><!--
document.write("Last Published: " + document.lastModified);
//  --></script>
</div>
<!--+
    |breadtrail
    +-->
<div class="breadtrail">

             &nbsp;
           </div>
<!--+
    |start Menu, mainarea
    +-->
<!--+
    |start Menu
    +-->
<div id="menu">
<div onclick="SwitchMenu('menu_selected_1.1', 'skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('skin/images/chapter_open.gif');">Overview</div>
<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
<div class="menuitem">
<a href="index.html">Welcome</a>
</div>
<div class="menuitem">
<a href="zookeeperOver.html">Overview</a>
</div>
<div class="menuitem">
<a href="zookeeperStarted.html">Getting Started</a>
</div>
<div class="menupage">
<div class="menupagetitle">Release Notes</div>
</div>
</div>
<div onclick="SwitchMenu('menu_1.2', 'skin/')" id="menu_1.2Title" class="menutitle">Developer</div>
<div id="menu_1.2" class="menuitemgroup">
<div class="menuitem">
<a href="api/index.html">API Docs</a>
</div>
<div class="menuitem">
<a href="zookeeperProgrammers.html">Programmer's Guide</a>
</div>
<div class="menuitem">
<a href="javaExample.html">Java Example</a>
</div>
<div class="menuitem">
<a href="zookeeperTutorial.html">Barrier and Queue Tutorial</a>
</div>
<div class="menuitem">
<a href="recipes.html">Recipes</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.3', 'skin/')" id="menu_1.3Title" class="menutitle">Admin &amp; Ops</div>
<div id="menu_1.3" class="menuitemgroup">
<div class="menuitem">
<a href="zookeeperAdmin.html">Administrator's Guide</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.4', 'skin/')" id="menu_1.4Title" class="menutitle">Contributor</div>
<div id="menu_1.4" class="menuitemgroup">
<div class="menuitem">
<a href="zookeeperInternals.html">ZooKeeper Internals</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.5', 'skin/')" id="menu_1.5Title" class="menutitle">Informal Documentation</div>
<div id="menu_1.5" class="menuitemgroup">
<div class="menuitem">
<a href="http://wiki.apache.org/hadoop/ZooKeeper">Wiki</a>
</div>
<div class="menuitem">
<a href="http://wiki.apache.org/hadoop/ZooKeeper/FAQ">FAQ</a>
</div>
<div class="menuitem">
<a href="http://hadoop.apache.org/zookeeper/mailing_lists.html">Mailing Lists</a>
</div>
<div class="menuitem">
<a href="zookeeperOtherInfo.html">Other Info</a>
</div>
</div>
<div id="credit"></div>
<div id="roundbottom">
<img style="display: none" class="corner" height="15" width="15" alt="" src="skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
<!--+
  |alternative credits
  +-->
<div id="credit2"></div>
</div>
<!--+
    |end Menu
    +-->
<!--+
    |start content
    +-->
<div id="content">
<div title="Portable Document Format" class="pdflink">
<a class="dida" href="releasenotes.pdf"><img alt="PDF -icon" src="skin/images/pdfdoc.gif" class="skin"><br>
        PDF</a>
</div>
<h1>ZooKeeper 3.0.0 Release Notes</h1>
<div id="minitoc-area">
<ul class="minitoc">
<li>
<a href="#migration">Migration Instructions when Upgrading to 3.0.0</a>
<ul class="minitoc">
<li>
<a href="#migration_code">Migrating Client Code</a>
<ul class="minitoc">
<li>
194
195
196
<a href="#Watch+Management">Watch Management</a>
</li>
<li>
197
198
199
200
201
202
203
204
205
206
<a href="#Java+API">Java API</a>
</li>
<li>
<a href="#C+API">C API</a>
</li>
</ul>
</li>
<li>
<a href="#migration_data">Migrating Server Data</a>
</li>
207
208
209
<li>
<a href="#migration_config">Migrating Server Configuration</a>
</li>
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
</ul>
</li>
<li>
<a href="#changes">Changes Since ZooKeeper 2.2.1</a>
</li>
</ul>
</div>
  

  


<p>
These release notes include new developer and user facing incompatibilities, features, and major improvements.
</p>


<ul>
  
<li>
<p>
<a href="#migration">Migration Instructions</a>
</p>
</li>
  
<li>
<p>
<a href="#changes">Changes</a>
</p>
</li>

</ul>


<a name="N1001B"></a><a name="migration"></a>
<h2 class="h3">Migration Instructions when Upgrading to 3.0.0</h2>
<div class="section">
<p>

<em>You should only have to read this section if you are upgrading from a previous version of ZooKeeper to version 3.0.0, otw skip down to <a href="#changes">changes</a></em>

</p>
<p>
A small number of changes in this release have resulted in non-backward compatible Zookeeper client user code and server instance data. The following instructions provide details on how to migrate code and date from version 2.2.1 to version 3.0.0.
</p>
<p>
Note: ZooKeeper increments the major version number (major.minor.fix) when backward incompatible changes are made to the source base. As part of the migration from SourceForge we changed the package structure (com.yahoo.zookeeper.* to org.apache.zookeeper.*) and felt it was a good time to incorporate some changes that we had been withholding. As a result the following will be required when migrating from 2.2.1 to 3.0.0 version of ZooKeeper.
</p>
<ul>
  
<li>
<p>
<a href="#migration_code">Migrating Client Code</a>
</p>
</li>
  
<li>
<p>
<a href="#migration_data">Migrating Server Data</a>
</p>
</li>
271
272
273
274
275
276
  
<li>
<p>
<a href="#migration_config">Migrating Server Configuration</a>
</p>
</li>
277
278

</ul>
279
<a name="N10045"></a><a name="migration_code"></a>
280
<h3 class="h4">Migrating Client Code</h3>
281
282
283
284
285
286
287
288
<p>
  The underlying client-server protocol has changed in version 3.0.0
  of ZooKeeper. As a result clients must be upgraded along with
  serving clusters to ensure proper operation of the system (old
  pre-3.0.0 clients are not guaranteed to operate against upgraded
  3.0.0 servers and vice-versa).
</p>
<a name="N1004E"></a><a name="Watch+Management"></a>
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
<h4>Watch Management</h4>
<p>
In previous releases of ZooKeeper any watches registered by clients were lost if the client lost a connection to a ZooKeeper server.
This meant that developers had to track watches they were interested in and reregister them if a session disconnect event was recieved.
In this release the client library tracks watches that a client has registered and reregisters the watches when a connection is made to a new server.
Applications that still manually reregister interest should continue working properly as long as they are able to handle unsolicited watches.
For example, an old application may register a watch for /foo and /goo, lose the connection, and reregister only /goo.
As long as the application is able to recieve a notification for /foo, (probably ignoring it) the applications does not to be changes.
One caveat to the watch management: it is possible to miss an event for the creation and deletion of a znode if watching for creation and both the create and delete happens while the client is disconnected from ZooKeeper.
</p>
<p>
This release also allows clients to specify call specific watch functions.
This gives the developer the ability to modularize logic in different watch functions rather than cramming everything in the watch function attached to the ZooKeeper handle.
Call specific watch functions receive all session events for as long as they are active, but will only receive the watch callbacks for which they are registered.
</p>
304
<a name="N1005B"></a><a name="Java+API"></a>
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
<h4>Java API</h4>
<ol>
  
<li>
<p>The java package structure has changed from <strong>com.yahoo.zookeeper*</strong> to <strong>org.apache.zookeeper*</strong>. This will probably effect all of your java code which makes use of ZooKeeper APIs (typically import statements)</p>
</li>
  
<li>
<p>A number of constants used in the client ZooKeeper API were re-specified using enums (rather than ints). See <a href="https://issues.apache.org/jira/browse/ZOOKEEPER-7">ZOOKEEPER-7</a>, <a href="https://issues.apache.org/jira/browse/ZOOKEEPER-132">ZOOKEEPER-132</a> and <a href="https://issues.apache.org/jira/browse/ZOOKEEPER-139">ZOOKEEPER-139</a> for full details</p>
</li>
  
<li>
<p>
<a href="https://issues.apache.org/jira/browse/ZOOKEEPER-18">ZOOKEEPER-18</a> removed KeeperStateChanged, use KeeperStateDisconnected instead</p>
</li>

</ol>
<p>
Also see <a href="http://hadoop.apache.org/zookeeper/docs/current/api/index.html">the current java API</a>

</p>
326
<a name="N1008D"></a><a name="C+API"></a>
327
328
329
330
331
332
333
334
<h4>C API</h4>
<ol>
  
<li>
<p>A number of constants used in the client ZooKeeper API were renamed in order to reduce namespace collision, see <a href="https://issues.apache.org/jira/browse/ZOOKEEPER-6">ZOOKEEPER-6</a> for full details</p>
</li>

</ol>
335
<a name="N100A0"></a><a name="migration_data"></a>
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
<h3 class="h4">Migrating Server Data</h3>
<p>
The following issues resulted in changes to the on-disk data format (the snapshot and transaction log files contained within the ZK data directory) and require a migration utility to be run. 
</p>
<ul>
  
<li>
<p>
<a href="https://issues.apache.org/jira/browse/ZOOKEEPER-27">ZOOKEEPER-27 Unique DB identifiers for servers and clients</a>
</p>
</li>
  
<li>
<p>
<a href="https://issues.apache.org/jira/browse/ZOOKEEPER-32">ZOOKEEPER-32 CRCs for ZooKeeper data</a>
</p>
</li>
  
<li>
<p>
<a href="https://issues.apache.org/jira/browse/ZOOKEEPER-33">ZOOKEEPER-33 Better ACL management</a>
</p>
</li>
  
<li>
<p>
<a href="https://issues.apache.org/jira/browse/ZOOKEEPER-38">ZOOKEEPER-38 headers (version+) in log/snap files</a>
</p>
</li>

</ul>
<p>
368
369
370
  
<strong>The following must be run once, and only once, when upgrading the ZooKeeper server instances to version 3.0.0.</strong>

371
</p>
372
373
374
375
376
377
378
<div class="note">
<div class="label">Note</div>
<div class="content">
  
<p>
    The &lt;dataLogDir&gt; and &lt;dataDir&gt; directories referenced
    below are specified by the <em>dataLogDir</em>
379
    and <em>dataDir</em> specification in your
380
381
382
383
384
385
386
387
388
    ZooKeeper config file
    respectively. <em>dataLogDir</em> defaults to the
    value of <em>dataDir</em> if not specified explicitly
    in the ZooKeeper server config file (in which case provide the
    same directory for both parameters to the upgrade utility).
  </p>

</div>
</div>
389
390
391
<ol>
  
<li>
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
<p>Shutdown the ZooKeeper server cluster.</p>
</li>
  
<li>
<p>Backup your &lt;dataLogDir&gt; and &lt;dataDir&gt; directories</p>
</li>
  
<li>
<p>Run upgrade using</p>
    
<ul>
      
<li>
<p>
<span class="codefrag computeroutput">bin/zkServer.sh upgrade &lt;dataLogDir&gt; &lt;dataDir&gt;</span>
</p>
</li>
    
</ul>
    
<p>or</p>
    
<ul>
      
<li>
<p>
<span class="codefrag computeroutput">java -classpath pathtolog4j:pathtozookeeper.jar UpgradeMain &lt;dataLogDir&gt; &lt;dataDir&gt;</span>
</p>
</li>
    
</ul>
    
<p>where &lt;dataLogDir&gt; is the directory where all transaction logs (log.*) are stored. &lt;dataDir&gt; is the directory where all the snapshots (snapshot.*) are stored.</p>
  
</li>
  
<li>
<p>Restart the cluster. </p>
430
</li>
431
432
433
434
435
436
437
 
</ol>
<p>
 If you have any failure during the upgrade procedure keep reading to sanitize your database. 
 </p>
<p>This is how upgrade works in ZooKeeper. This will help you troubleshoot in case you have problems while upgrading</p>
<ol>
438

439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
<li>
<p>Upgrade moves files from &lt;dataLogDir&gt; and &lt;dataDir&gt; to &lt;dataLogDir&gt;/version-1/ and &lt;dataDir&gt;/version-1 respectively (version-1 sub-directory is created by the upgrade utility). </p>
</li>
 
<li>
<p>Upgrade creates a new version sub-directory &lt;dataDir&gt;/version-2 and &lt;dataLogDir&gt;/version-2</p>
</li>
 
<li>
<p>Upgrade reads the old database from &lt;dataDir&gt;/version-1 and &lt;dataLogDir&gt;/version-1 into the memory and creates a new upgraded snapshot. </p>
</li>
 
<li>
<p>Upgrade writes the new database in &lt;dataDir&gt;/version-2.  </p>
</li>
 
</ol>
<p>Troubleshooting.</p>
<ol>
 
<li>
<p>In case you start ZooKeeper 3.0 without upgrading from 2.0 on a 2.0 database - the servers will start up with an empty database.
 This is because the servers assume that &lt;dataDir&gt;/version-2 and &lt;dataLogDir&gt;/version-2 will have the database to start with. Since this will be empty
 in case of no upgrade, the servers will start with an empty database. In such a case, shutdown the ZooKeeper servers, remove the version-2 directory (remember
 this will lead to loss of updates after you started 3.0.)
 and then start the upgrade procedure.</p>
</li>
 
<li>
<p>If the upgrade fails while trying to rename files into the version-1 directory, you should try and move all the files under &lt;dataDir&gt;/version-1
 and &lt;dataLogDir&gt;/version-1 to &lt;dataDir&gt; and &lt;dataLogDir&gt; respectively. Then try upgrade again.
 </p>
 
</li>
 
<li>
<p> If you do not wish to run with ZooKeeper 3.0 and prefer to run with ZooKeeper 2.0 and have already upgraded - you can run ZooKeeper 2 with 
 the &lt;dataDir&gt; and &lt;dataLogDir&gt; directories changed to &lt;dataDir&gt;/version-1 and &lt;dataLogDir&gt;/version-1. Remember that you will lose all the updates that you made after the upgrade.
</p>
</li> 
 
480
</ol>
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
<a name="N10135"></a><a name="migration_config"></a>
<h3 class="h4">Migrating Server Configuration</h3>
<p>
There is a significant change to the ZooKeeper server configuration file.
</p>
<p>The default election algorithm, specified by
  the <em>electionAlg</em> configuration attribute, has
  changed from a default of <em>0</em> to a default
  of <em>3</em>. See
  <a href="zookeeperAdmin.html#sc_clusterOptions">Cluster
  Options</a> section of the administrators guide, specifically
  the <em>electionAlg</em>
  and <em>server.X</em> properties.
</p>
<p>
  You will either need to explicitly
  set <em>electionAlg</em> to it's previous default value
  of <em>0</em> or change
  your <em>server.X</em> options to include the leader
  election port.
</p>
502
503
504
</div>


505
<a name="N10162"></a><a name="changes"></a>
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
<h2 class="h3">Changes Since ZooKeeper 2.2.1</h2>
<div class="section">
<p>
Version 2.2.1 code, documentation, binaries, etc... are still accessible on <a href="http://sourceforge.net/projects/zookeeper">SourceForge</a>

</p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<caption>Changes Since ZooKeeper 2.2.1</caption>

<title>Changes Since ZooKeeper 2.2.1</title>


<tr>
  
<th>Issue</th>
  <th>Notes</th>

</tr>


<tr>
  
<td>
    <a href="https://issues.apache.org/jira/browse/ZOOKEEPER-1">
      ZOOKEEPER-1</a>
  </td>
  <td>
    notes, placeholder - TBD during release process
  </td>

</tr>


</table>
</div>

<p align="right">
<font size="-2"></font>
</p>
</div>
<!--+
    |end content
    +-->
<div class="clearboth">&nbsp;</div>
</div>
<div id="footer">
<!--+
    |start bottomstrip
    +-->
<div class="lastmodified">
<script type="text/javascript"><!--
document.write("Last Published: " + document.lastModified);
//  --></script>
</div>
<div class="copyright">
        Copyright &copy;
         2008 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
</div>
<!--+
    |end bottomstrip
    +-->
</div>
</body>
</html>