hadoop-hdfs-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From omal...@apache.org
Subject svn commit: r816432 [1/2] - in /hadoop/hdfs/trunk: ./ src/docs/src/documentation/ src/docs/src/documentation/content/xdocs/ src/docs/src/documentation/resources/images/
Date Fri, 18 Sep 2009 01:58:18 GMT
Author: omalley
Date: Fri Sep 18 01:58:17 2009
New Revision: 816432

URL: http://svn.apache.org/viewvc?rev=816432&view=rev
Log:
HDFS-574. Split the documentation between the subprojects.
(Corinne Chandel via omalley)

Added:
    hadoop/hdfs/trunk/src/docs/src/documentation/resources/images/hdfs-logo.jpg   (with props)
Removed:
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/capacity_scheduler.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/cluster_setup.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/commands_manual.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/distcp.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/fair_scheduler.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/hadoop_archives.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/hdfs_shell.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/hod_admin_guide.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/hod_config_guide.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/hod_user_guide.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/mapred_tutorial.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/native_libraries.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/quickstart.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/service_level_auth.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/streaming.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/vaidya.xml
Modified:
    hadoop/hdfs/trunk/CHANGES.txt
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/SLG_user_guide.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/faultinject_framework.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/hdfs_design.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/hdfs_imageviewer.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/hdfs_permissions_guide.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/hdfs_quota_admin_guide.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/hdfs_user_guide.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/index.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/libhdfs.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/site.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/tabs.xml
    hadoop/hdfs/trunk/src/docs/src/documentation/skinconf.xml

Modified: hadoop/hdfs/trunk/CHANGES.txt
URL: http://svn.apache.org/viewvc/hadoop/hdfs/trunk/CHANGES.txt?rev=816432&r1=816431&r2=816432&view=diff
==============================================================================
--- hadoop/hdfs/trunk/CHANGES.txt (original)
+++ hadoop/hdfs/trunk/CHANGES.txt Fri Sep 18 01:58:17 2009
@@ -161,6 +161,9 @@
 
     HDFS-618. Support non-recursive mkdir().  (Kan Zhang via szetszwo)
 
+    HDFS-574. Split the documentation between the subprojects.
+    (Corinne Chandel via omalley)
+
   BUG FIXES
 
     HDFS-76. Better error message to users when commands fail because of 

Modified: hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/SLG_user_guide.xml
URL: http://svn.apache.org/viewvc/hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/SLG_user_guide.xml?rev=816432&r1=816431&r2=816432&view=diff
==============================================================================
--- hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/SLG_user_guide.xml (original)
+++ hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/SLG_user_guide.xml Fri Sep 18 01:58:17 2009
@@ -18,12 +18,12 @@
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
 <document>
 	<header>
-		<title> HDFS Synthetic Load Generator Guide </title>
+		<title>Synthetic Load Generator Guide </title>
 	</header>
 	<body>
-		<section>
-			<title> Description </title>
-			<p>
+	<section>
+	<title>Overview</title>
+		<p>
         The synthetic load generator (SLG) is a tool for testing NameNode behavior
         under different client loads. The user can generate different mixes 
         of read, write, and list requests by specifying the probabilities of
@@ -33,91 +33,121 @@
         monitor the running of the NameNode. When a load generator exits, it
         prints some NameNode statistics like the average execution time of each
         kind of operation and the NameNode throughput.
-                       </p>
-                </section>
-		<section>
-			<title> Synopsis </title>
-			<p>
-        <code>java LoadGenerator [options]</code><br/>
-                        </p>
-                        <p>
-        Options include:<br/>
-        <code>&nbsp;&nbsp;-readProbability &lt;read probability&gt;</code><br/>
-        <code>&nbsp;&nbsp;&nbsp;&nbsp;the probability of the read operation;
-                default is 0.3333. </code><br/>
-        <code>&nbsp;&nbsp;-writeProbability &lt;write probability&gt;</code><br/>
-        <code>&nbsp;&nbsp;&nbsp;&nbsp;the probability of the write 
-                operations; default is 0.3333.</code><br/>
-        <code>&nbsp;&nbsp;-root &lt;test space root&gt;</code><br/>
-        <code>&nbsp;&nbsp;&nbsp;&nbsp;the root of the test space;
-                default is /testLoadSpace.</code><br/>
-        <code>&nbsp;&nbsp;-maxDelayBetweenOps 
-                &lt;maxDelayBetweenOpsInMillis&gt;</code><br/> 
-        <code>&nbsp;&nbsp;&nbsp;&nbsp;the maximum delay between two consecutive
-                operations in a thread; default is 0 indicating no delay.
-                </code><br/>
-        <code>&nbsp;&nbsp;-numOfThreads &lt;numOfThreads&gt;</code><br/> 
-        <code>&nbsp;&nbsp;&nbsp;&nbsp;the number of threads to spawn; 
-                default is 200.</code><br/>
-        <code>&nbsp;&nbsp;-elapsedTime &lt;elapsedTimeInSecs&gt;</code><br/>
-        <code>&nbsp;&nbsp;&nbsp;&nbsp;the number of seconds that the program 
-                will run; A value of zero indicates that the program runs
-                forever. The default value is 0.</code><br/>
-        <code>&nbsp;&nbsp;-startTime &lt;startTimeInMillis&gt;</code><br/> 
-        <code>&nbsp;&nbsp;&nbsp;&nbsp;the time that all worker threads 
+        </p>
+     </section>
+                
+	<section>
+	<title> Synopsis </title>
+	  <p>
+        The synopsis of the command is:
+      </p>
+		<source>java LoadGenerator [options]</source>
+        <p> Options include:</p>
+        
+    <ul>
+    <li>
+        <code>-readProbability &lt;read probability&gt;</code><br/>
+        The probability of the read operation; default is 0.3333.
+    </li>
+ 
+    <li>               
+        <code>-writeProbability &lt;write probability&gt;</code><br/>
+        The probability of the write operations; default is 0.3333.
+    </li>
+
+   <li>            
+        <code>-root &lt;test space root&gt;</code><br/>
+        The root of the test space; default is /testLoadSpace.
+    </li> 
+
+    <li>           
+        <code>-maxDelayBetweenOps &lt;maxDelayBetweenOpsInMillis&gt;</code><br/> 
+        The maximum delay between two consecutive operations in a thread; default is 0 indicating no delay.
+    </li> 
+
+    <li>            
+        <code>-numOfThreads &lt;numOfThreads&gt;</code><br/>
+        The number of threads to spawn; default is 200.
+    </li>
+
+     <li>          
+        <code>-elapsedTime &lt;elapsedTimeInSecs&gt;</code><br/>
+        The number of seconds that the program 
+        will run; A value of zero indicates that the program runs
+        forever. The default value is 0.
+     </li> 
+
+    <li>            
+        <code>-startTime &lt;startTimeInMillis&gt;</code><br/> 
+        The time that all worker threads 
                 start to run. By default it is 10 seconds after the main 
                 program starts running.This creates a barrier if more than
                 one load generator is running.
-        </code><br/>
-        <code>&nbsp;&nbsp;-seed &lt;seed&gt;</code><br/>
-        <code>&nbsp;&nbsp;&nbsp;&nbsp;the random generator seed for repeating 
+      </li>
+    
+    <li>     
+        <code>-seed &lt;seed&gt;</code><br/>
+        The random generator seed for repeating 
                 requests to NameNode when running with a single thread;
-                default is the current time.</code><br/>
-			</p>
-			<p>
+                default is the current time.
+     </li>
+			
+	</ul>
+			
+	<p>
         After command line argument parsing, the load generator traverses 
         the test space and builds a table of all directories and another table
         of all files in the test space. It then waits until the start time to
-        spawn the number of worker threads as specified by the user. Each
-        thread sends a stream of requests to NameNode. At each iteration, 
+        spawn the number of worker threads as specified by the user. 
+        
+        Each thread sends a stream of requests to NameNode. At each iteration, 
         it first decides if it is going to read a file, create a file, or
         list a directory following the read and write probabilities specified
         by the user. The listing probability is equal to 
         <em>1-read probability-write probability</em>. When reading, 
         it randomly picks a file in the test space and reads the entire file. 
         When writing, it randomly picks a directory in the test space and 
-        creates a file there. To avoid two threads with the same load 
-        generator or from two different load generators create the same 
+        creates a file there. 
+    </p>
+    <p>
+        To avoid two threads with the same load 
+        generator or from two different load generators creating the same 
         file, the file name consists of the current machine's host name 
         and the thread id. The length of the file follows Gaussian 
         distribution with an average size of 2 blocks and the standard 
-        deviation of 1. The new file is filled with byte 'a'. To avoid
-        the test space to grow indefinitely, the file is deleted immediately
-        after the file creation completes. While listing, it randomly 
-        picks a directory in the test space and lists its content. 
+        deviation of 1. The new file is filled with byte 'a'. To avoid the test 
+        space growing indefinitely, the file is deleted immediately
+        after the file creation completes. While listing, it randomly picks 
+        a directory in the test space and lists its content. 
+     </p>
+     <p>   
         After an operation completes, the thread pauses for a random 
         amount of time in the range of [0, maxDelayBetweenOps] if the 
         specified maximum delay is not zero. All threads are stopped when 
         the specified elapsed time is passed. Before exiting, the program 
         prints the average execution for each kind of NameNode operations, 
         and the number of requests served by the NameNode per second.
-                        </p>
-                </section>
-                <section>
-                        <title> Test Space Population </title>
-                        <p>
-        The user needs to populate a test space before she runs a 
+    </p>
+    
+     </section>
+                
+     <section>
+     <title> Test Space Population </title>
+     <p>
+        The user needs to populate a test space before running a 
         load generator. The structure generator generates a random 
         test space structure and the data generator creates the files 
         and directories of the test space in Hadoop distributed file system.
-                        </p>
-                        <section>
-                                <title> Structure Generator </title>
-                                <p>
+     </p>
+     
+     <section>
+     <title> Structure Generator </title>
+    <p>
         This tool generates a random namespace structure with the 
         following constraints:
-                                </p>
-                                        <ol>
+     </p>
+     
+     <ol>
         <li>The number of subdirectories that a directory can have is 
             a random number in [minWidth, maxWidth].</li>
         <li>The maximum depth of each subdirectory is a random number 
@@ -125,69 +155,83 @@
         <li>Files are randomly placed in leaf directories. The size of 
             each file follows Gaussian distribution with an average size 
             of 1 block and a standard deviation of 1.</li>
-                                        </ol>
-                                <p>
+     </ol>
+      <p>
         The generated namespace structure is described by two files in 
         the output directory. Each line of the first file contains the 
         full name of a leaf directory. Each line of the second file 
         contains the full name of a file and its size, separated by a blank.
-                                </p>
-                                <p>
-        The synopsis of the command is
-                                </p>
-                                <p>
-        <code>java StructureGenerator [options]</code>
-                                </p>
-                                <p>
-        Options include:<br/>
-        <code>&nbsp;&nbsp;-maxDepth &lt;maxDepth&gt;</code><br/>
-        <code>&nbsp;&nbsp;&nbsp;&nbsp;maximum depth of the directory tree; 
-                default is 5.</code><br/>
-        <code>&nbsp;&nbsp;-minWidth &lt;minWidth&gt;</code><br/> 
-        <code>&nbsp;&nbsp;&nbsp;&nbsp;minimum number of subdirectories per 
-                directories; default is 1.</code><br/>
-        <code>&nbsp;&nbsp;-maxWidth &lt;maxWidth&gt;</code><br/> 
-        <code>&nbsp;&nbsp;&nbsp;&nbsp;maximum number of subdirectories per 
-                directories; default is 5.</code><br/>
-        <code>&nbsp;&nbsp;-numOfFiles &lt;#OfFiles&gt;</code><br/> 
-        <code>&nbsp;&nbsp;&nbsp;&nbsp;the total number of files in the test 
-                space; default is 10.</code><br/>
-        <code>&nbsp;&nbsp;-avgFileSize &lt;avgFileSizeInBlocks&gt;</code><br/>
-        <code>&nbsp;&nbsp;&nbsp;&nbsp;average size of blocks; default is 1.
-                </code><br/>
-        <code>&nbsp;&nbsp;-outDir &lt;outDir&gt;</code><br/>
-        <code>&nbsp;&nbsp;&nbsp;&nbsp;output directory; default is the 
-                current directory. </code><br/>
-        <code>&nbsp;&nbsp;-seed &lt;seed&gt;</code><br/>
-        <code>&nbsp;&nbsp;&nbsp;&nbsp;random number generator seed; 
-                default is the current time.</code><br/>
-                                </p>
-                        </section>
-                        <section>
-                                <title> Test Space Generator </title>
-                                <p>
+      </p>
+      <p>
+        The synopsis of the command is:
+      </p>
+      <source>java StructureGenerator [options]</source>
+
+     <p>Options include:</p>
+     <ul>
+     <li>
+        <code>-maxDepth &lt;maxDepth&gt;</code><br/>
+        Maximum depth of the directory tree; default is 5.
+     </li>
+
+     <li>    
+        <code>-minWidth &lt;minWidth&gt;</code><br/> 
+        Minimum number of subdirectories per directories; default is 1.
+     </li> 
+
+     <li>  
+        <code>-maxWidth &lt;maxWidth&gt;</code><br/> 
+        Maximum number of subdirectories per directories; default is 5.
+      </li>
+
+     <li>           
+        <code>-numOfFiles &lt;#OfFiles&gt;</code><br/> 
+        The total number of files in the test space; default is 10.
+      </li>
+
+     <li>          
+        <code>-avgFileSize &lt;avgFileSizeInBlocks&gt;</code><br/>
+        Average size of blocks; default is 1.
+      </li> 
+
+     <li>           
+        <code>-outDir &lt;outDir&gt;</code><br/>
+        Output directory; default is the current directory.
+     </li>
+
+     <li>           
+        <code>-seed &lt;seed&gt;</code><br/>
+        Random number generator seed; default is the current time.
+    </li>            
+     </ul>
+     </section>
+
+    <section>
+    <title>Data Generator </title>
+         <p>
         This tool reads the directory structure and file structure from 
         the input directory and creates the namespace in Hadoop distributed
         file system. All files are filled with byte 'a'.
-                                </p>
-                                <p>
-        The synopsis of the command is
-                                </p>
-                                <p>
-        <code>java DataGenerator [options]</code>
-                                </p>
-                                <p>
-        Options include:<br/>
-        <code>&nbsp;&nbsp;-inDir &lt;inDir&gt;</code><br/>
-        <code>&nbsp;&nbsp;&nbsp;&nbsp;input directory name where directory/file
-                structures are stored; default is the current directory.
-        </code><br/>
-        <code>&nbsp;&nbsp;-root &lt;test space root&gt;</code><br/>
-        <code>&nbsp;&nbsp;&nbsp;&nbsp;the name of the root directory which the 
-                new namespace is going to be placed under; 
-                default is "/testLoadSpace".</code><br/>
-                                </p>
-		        </section>
-                </section>
+        </p>
+         <p>
+        The synopsis of the command is:
+         </p>
+         <source>java DataGenerator [options]</source>
+         <p>Options include:</p>
+         <ul>
+    <li>
+        <code>-inDir &lt;inDir&gt;</code><br/>
+        Input directory name where directory/file
+        structures are stored; default is the current directory.
+    </li>
+    <li>
+        <code>-root &lt;test space root&gt;</code><br/>
+        The name of the root directory which the 
+        new namespace is going to be placed under; 
+        default is "/testLoadSpace".
+    </li>
+     </ul>
+	</section>
+    </section>
 	</body>
 </document>

Modified: hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/faultinject_framework.xml
URL: http://svn.apache.org/viewvc/hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/faultinject_framework.xml?rev=816432&r1=816431&r2=816432&view=diff
==============================================================================
--- hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/faultinject_framework.xml (original)
+++ hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/faultinject_framework.xml Fri Sep 18 01:58:17 2009
@@ -21,41 +21,40 @@
 
 <document>
   <header>
-    <title>Fault injection Framework and Development Guide</title>
+    <title>Fault Injection Framework and Development Guide</title>
   </header>
 
   <body>
     <section>
       <title>Introduction</title>
-      <p>The following is a brief help for Hadoops' Fault Injection (FI)
-        Framework and Developer's Guide for those who will be developing
-        their own faults (aspects).
+      <p>This guide provides an overview of the Hadoop Fault Injection (FI) framework for those
+      who will be developing their own faults (aspects).
       </p>
-      <p>An idea of Fault Injection (FI) is fairly simple: it is an
+      <p>The idea of fault injection is fairly simple: it is an
         infusion of errors and exceptions into an application's logic to
         achieve a higher coverage and fault tolerance of the system.
-        Different implementations of this idea are available at this day.
+        Different implementations of this idea are available today.
         Hadoop's FI framework is built on top of Aspect Oriented Paradigm
         (AOP) implemented by AspectJ toolkit.
       </p>
     </section>
     <section>
       <title>Assumptions</title>
-      <p>The current implementation of the framework assumes that the faults it
-        will be emulating are of non-deterministic nature. i.e. the moment
-        of a fault's happening isn't known in advance and is a coin-flip
-        based.
+      <p>The current implementation of the FI framework assumes that the faults it
+        will be emulating are of non-deterministic nature. That is,  the moment
+        of a fault's happening isn't known in advance and is a coin-flip based.
       </p>
     </section>
+    
     <section>
       <title>Architecture of the Fault Injection Framework</title>
       <figure src="images/FI-framework.gif" alt="Components layout" />
+      
       <section>
-        <title>Configuration management</title>
-        <p>This piece of the framework allow to
-          set expectations for faults to happen. The settings could be applied
-          either statically (in advance) or in a runtime. There's two ways to
-          configure desired level of faults in the framework:
+        <title>Configuration Management</title>
+        <p>This piece of the FI framework allows you to set expectations for faults to happen. 
+        The settings can be applied either statically (in advance) or in runtime. 
+        The desired level of faults in the framework can be configured two ways:
         </p>
         <ul>
           <li>
@@ -71,31 +70,31 @@
           </li>
         </ul>
       </section>
+      
       <section>
-        <title>Probability model</title>
-        <p>This fundamentally is a coin flipper. The methods of this class are
+        <title>Probability Model</title>
+        <p>This is fundamentally a coin flipper. The methods of this class are
           getting a random number between 0.0
-          and 1.0 and then checking if new number has happened to be in the
-          range of
-          0.0 and a configured level for the fault in question. If that
-          condition
-          is true then the fault will occur.
+          and 1.0 and then checking if a new number has happened in the
+          range of 0.0 and a configured level for the fault in question. If that
+          condition is true then the fault will occur.
         </p>
-        <p>Thus, to guarantee a happening of a fault one needs to set an
+        <p>Thus, to guarantee the happening of a fault one needs to set an
           appropriate level to 1.0.
           To completely prevent a fault from happening its probability level
-          has to be set to 0.0
+          has to be set to 0.0.
         </p>
-        <p><strong>Nota bene</strong>: default probability level is set to 0
+        <p><strong>Note</strong>: The default probability level is set to 0
           (zero) unless the level is changed explicitly through the
           configuration file or in the runtime. The name of the default
           level's configuration parameter is
           <code>fi.*</code>
         </p>
       </section>
+      
       <section>
-        <title>Fault injection mechanism: AOP and AspectJ</title>
-        <p>In the foundation of Hadoop's fault injection framework lays
+        <title>Fault Injection Mechanism: AOP and AspectJ</title>
+        <p>The foundation of Hadoop's FI framework includes a
           cross-cutting concept implemented by AspectJ. The following basic
           terms are important to remember:
         </p>
@@ -122,8 +121,9 @@
           </li>
         </ul>
       </section>
+      
       <section>
-        <title>Existing join points</title>
+        <title>Existing Join Points</title>
         <p>
           The following readily available join points are provided by AspectJ:
         </p>
@@ -154,7 +154,7 @@
       </section>
     </section>
     <section>
-      <title>Aspects examples</title>
+      <title>Aspect Example</title>
       <source>
 package org.apache.hadoop.hdfs.server.datanode;
 
@@ -191,17 +191,22 @@
     }
   }
 }
-      </source>
-      <p>
-        The aspect has two main parts: the join point
+</source>
+
+      <p>The aspect has two main parts: </p>
+       <ul>
+        <li>The join point
         <code>pointcut callReceivepacket()</code>
         which servers as an identification mark of a specific point (in control
-        and/or data flow) in the life of an application. A call to the advice -
+        and/or data flow) in the life of an application. </li>
+        
+       <li> A call to the advice -
         <code>before () throws IOException : callReceivepacket()</code>
-        - will be
-        <a href="#Putting+it+all+together">injected</a>
-        before that specific spot of the application's code.
-      </p>
+        - will be injected (see
+        <a href="#Putting+it+all+together">Putting It All Together</a>)
+        before that specific spot of the application's code.</li>
+        </ul>
+      
 
       <p>The pointcut identifies an invocation of class'
         <code>java.io.OutputStream write()</code>
@@ -210,8 +215,8 @@
         take place within the body of method
         <code>receivepacket()</code>
         from class<code>BlockReceiver</code>.
-        The method can have any parameters and any return type. possible
-        invocations of
+        The method can have any parameters and any return type. 
+        Possible invocations of
         <code>write()</code>
         method happening anywhere within the aspect
         <code>BlockReceiverAspects</code>
@@ -222,24 +227,22 @@
         class. In such a case the names of the faults have to be different
         if a developer wants to trigger them separately.
       </p>
-      <p><strong>Note 2</strong>: After
-        <a href="#Putting+it+all+together">injection step</a>
+      <p><strong>Note 2</strong>: After the injection step (see
+        <a href="#Putting+it+all+together">Putting It All Together</a>)
         you can verify that the faults were properly injected by
-        searching for
-        <code>ajc</code>
-        keywords in a disassembled class file.
+        searching for <code>ajc</code> keywords in a disassembled class file.
       </p>
 
     </section>
     
     <section>
-      <title>Fault naming convention &amp; namespaces</title>
-      <p>For the sake of unified naming
+      <title>Fault Naming Convention and Namespaces</title>
+      <p>For the sake of a unified naming
       convention the following two types of names are recommended for a
       new aspects development:</p>
       <ul>
-        <li>Activity specific notation (as
-          when we don't care about a particular location of a fault's
+        <li>Activity specific notation 
+          (when we don't care about a particular location of a fault's
           happening). In this case the name of the fault is rather abstract:
           <code>fi.hdfs.DiskError</code>
         </li>
@@ -251,14 +254,11 @@
     </section>
 
     <section>
-      <title>Development tools</title>
+      <title>Development Tools</title>
       <ul>
-        <li>Eclipse
-          <a href="http://www.eclipse.org/ajdt/">AspectJ
-            Development Toolkit
-          </a>
-          might help you in the aspects' development
-          process.
+        <li>The Eclipse
+          <a href="http://www.eclipse.org/ajdt/">AspectJ Development Toolkit</a> 
+          may help you when developing aspects
         </li>
         <li>IntelliJ IDEA provides AspectJ weaver and Spring-AOP plugins
         </li>
@@ -266,60 +266,67 @@
     </section>
 
     <section>
-      <title>Putting it all together</title>
-      <p>Faults (or aspects) have to injected (or woven) together before
-        they can be used. Here's a step-by-step instruction how this can be
-        done.</p>
-      <p>Weaving aspects in place:</p>
-      <source>
+      <title>Putting It All Together</title>
+      <p>Faults (aspects) have to injected (or woven) together before
+        they can be used. Follow these instructions:</p>
+        
+    <ul>
+      <li>To weave aspects in place use:
+<source>
 % ant injectfaults
-      </source>
-      <p>If you
-        misidentified the join point of your aspect then you'll see a
-        warning similar to this one below when 'injectfaults' target is
-        completed:</p>
-        <source>
+</source>
+      </li>
+      
+      <li>If you
+        misidentified the join point of your aspect you will see a
+        warning (similar to the one shown here) when 'injectfaults' target is
+        completed:
+<source>
 [iajc] warning at
 src/test/aop/org/apache/hadoop/hdfs/server/datanode/ \
           BlockReceiverAspects.aj:44::0
 advice defined in org.apache.hadoop.hdfs.server.datanode.BlockReceiverAspects
 has not been applied [Xlint:adviceDidNotMatch]
-        </source>
-      <p>It isn't an error, so the build will report the successful result.
-
-        To prepare dev.jar file with all your faults weaved in
-      place run (HDFS-475 pending)</p>
-        <source>
+</source>
+        </li>
+        
+      <li>It isn't an error, so the build will report the successful result. <br />
+     To prepare dev.jar file with all your faults weaved in place (HDFS-475 pending) use:
+<source>
 % ant jar-fault-inject
-        </source>
+</source>
+        </li>
 
-      <p>Test jars can be created by</p>
-        <source>
+     <li>To create test jars use:
+<source>
 % ant jar-test-fault-inject
-        </source>
+</source>
+      </li>
 
-      <p>To run HDFS tests with faults injected:</p>
-        <source>
+     <li>To run HDFS tests with faults injected use:
+<source>
 % ant run-test-hdfs-fault-inject
-        </source>
+</source>
+      </li>
+    </ul>
+        
       <section>
-        <title>How to use fault injection framework</title>
-        <p>Faults could be triggered by the following two meanings:
+        <title>How to Use the Fault Injection Framework</title>
+        <p>Faults can be triggered as follows:
         </p>
         <ul>
-          <li>In the runtime as:
-            <source>
+          <li>During runtime:
+<source>
 % ant run-test-hdfs -Dfi.hdfs.datanode.BlockReceiver=0.12
-            </source>
-            To set a certain level, e.g. 25%, of all injected faults one can run
+</source>
+            To set a certain level, for example 25%, of all injected faults use:
             <br/>
-            <source>
+<source>
 % ant run-test-hdfs-fault-inject -Dfi.*=0.25
-            </source>
+</source>
           </li>
-          <li>or from a program as follows:
-          </li>
-        </ul>
+          <li>From a program:
+  
         <source>
 package org.apache.hadoop.fs;
 
@@ -354,23 +361,23 @@
     //Cleaning up test test environment
   }
 }
-        </source>
+</source>
+        </li>
+        </ul>
+        
         <p>
-          as you can see above these two methods do the same thing. They are
-          setting the probability level of
-          <code>hdfs.datanode.BlockReceiver</code>
-          at 12%.
-          The difference, however, is that the program provides more
-          flexibility and allows to turn a fault off when a test doesn't need
-          it anymore.
+          As you can see above these two methods do the same thing. They are
+          setting the probability level of <code>hdfs.datanode.BlockReceiver</code>
+          at 12%. The difference, however, is that the program provides more
+          flexibility and allows you to turn a fault off when a test no longer needs it.
         </p>
       </section>
     </section>
 
     <section>
-      <title>Additional information and contacts</title>
-      <p>This two sources of information seem to be particularly
-        interesting and worth further reading:
+      <title>Additional Information and Contacts</title>
+      <p>These two sources of information are particularly
+        interesting and worth reading:
       </p>
       <ul>
         <li>
@@ -381,9 +388,8 @@
         <li>AspectJ Cookbook (ISBN-13: 978-0-596-00654-9)
         </li>
       </ul>
-      <p>Should you have any farther comments or questions to the author
-        check
-        <a href="http://issues.apache.org/jira/browse/HDFS-435">HDFS-435</a>
+      <p>If you have additional comments or questions for the author check
+        <a href="http://issues.apache.org/jira/browse/HDFS-435">HDFS-435</a>.
       </p>
     </section>
   </body>

Modified: hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/hdfs_design.xml
URL: http://svn.apache.org/viewvc/hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/hdfs_design.xml?rev=816432&r1=816431&r2=816432&view=diff
==============================================================================
--- hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/hdfs_design.xml (original)
+++ hadoop/hdfs/trunk/src/docs/src/documentation/content/xdocs/hdfs_design.xml Fri Sep 18 01:58:17 2009
@@ -24,7 +24,7 @@
 
   <header>
     <title> 
-      HDFS Architecture
+      HDFS Architecture Guide
     </title>
     <authors>
       <person name="Dhruba Borthakur" email="dhruba@yahoo-inc.com"/>
@@ -35,7 +35,13 @@
     <section>
       <title> Introduction </title>
       <p>
-      The Hadoop Distributed File System (<acronym title="Hadoop Distributed File System">HDFS</acronym>) is a distributed file system designed to run on commodity hardware. It has many similarities with existing distributed file systems. However, the differences from other distributed file systems are significant. HDFS is highly fault-tolerant and is designed to be deployed on low-cost hardware. HDFS provides high throughput access to application data and is suitable for applications that have large data sets. HDFS relaxes a few POSIX requirements to enable streaming access to file system data.  HDFS was originally built as infrastructure for the Apache Nutch web search engine project. HDFS is part of the Apache Hadoop Core project. The project URL is <a href="http://hadoop.apache.org/core/">http://hadoop.apache.org/core/</a>.
+      The Hadoop Distributed File System (<acronym title="Hadoop Distributed File System">HDFS</acronym>) is a distributed file system 
+      designed to run on commodity hardware. It has many similarities with existing distributed file systems. However, the differences from 
+      other distributed file systems are significant. HDFS is highly fault-tolerant and is designed to be deployed on low-cost hardware. 
+      HDFS provides high throughput access to application data and is suitable for applications that have large data sets. HDFS relaxes 
+      a few POSIX requirements to enable streaming access to file system data.  HDFS was originally built as infrastructure for the 
+      Apache Nutch web search engine project. HDFS is now an Apache Hadoop subproject.
+      The project URL is <a href="http://hadoop.apache.org/hdfs/">http://hadoop.apache.org/hdfs/</a>.
       </p>
     </section>
 
@@ -45,7 +51,10 @@
       <section> 
         <title> Hardware Failure </title>
         <p>
-        Hardware failure is the norm rather than the exception. An HDFS instance may consist of hundreds or thousands of server machines, each storing part of the file system&#x2019;s data. The fact that there are a huge number of components and that each component has a non-trivial probability of failure means that some component of HDFS is always non-functional. Therefore, detection of faults and quick, automatic recovery from them is a core architectural goal of HDFS.
+        Hardware failure is the norm rather than the exception. An HDFS instance may consist of hundreds or thousands of server machines, 
+        each storing part of the file system&#x2019;s data. The fact that there are a huge number of components and that each component has 
+        a non-trivial probability of failure means that some component of HDFS is always non-functional. Therefore, detection of faults and quick, 
+        automatic recovery from them is a core architectural goal of HDFS.
        </p>
      </section>
 
@@ -53,14 +62,19 @@
       <section> 
         <title> Streaming Data Access </title>
         <p>
-        Applications that run on HDFS need streaming access to their data sets. They are not general purpose applications that typically run on general purpose file systems. HDFS is designed more for batch processing rather than interactive use by users. The emphasis is on high throughput of data access rather than low latency of data access. POSIX imposes many hard requirements that are not needed for applications that are targeted for HDFS. POSIX semantics in a few key areas has been traded to increase data throughput rates. 
+        Applications that run on HDFS need streaming access to their data sets. They are not general purpose applications that typically run 
+        on general purpose file systems. HDFS is designed more for batch processing rather than interactive use by users. The emphasis is on 
+        high throughput of data access rather than low latency of data access. POSIX imposes many hard requirements that are not needed for 
+        applications that are targeted for HDFS. POSIX semantics in a few key areas has been traded to increase data throughput rates. 
         </p>
       </section>
 
       <section> 
         <title> Large Data Sets </title>
         <p>
-        Applications that run on HDFS have large data sets. A typical file in HDFS is gigabytes to terabytes in size. Thus, HDFS is tuned to support large files. It should provide high aggregate data bandwidth and scale to hundreds of nodes in a single cluster. It should support tens of millions of files in a single instance.
+        Applications that run on HDFS have large data sets. A typical file in HDFS is gigabytes to terabytes in size. Thus, HDFS is tuned to 
+        support large files. It should provide high aggregate data bandwidth and scale to hundreds of nodes in a single cluster. It should support 
+        tens of millions of files in a single instance.
         </p>
       </section>
 
@@ -68,7 +82,9 @@
       <section> 
         <title> Simple Coherency Model </title>
         <p>
-        HDFS applications need a write-once-read-many access model for files. A file once created, written, and closed need not be changed. This assumption simplifies data coherency issues and enables high throughput data access. A Map/Reduce application or a web crawler application fits perfectly with this model. There is a plan to support appending-writes to files in the future. 
+        HDFS applications need a write-once-read-many access model for files. A file once created, written, and closed need not be changed. 
+        This assumption simplifies data coherency issues and enables high throughput data access. A MapReduce application or a web crawler 
+        application fits perfectly with this model. There is a plan to support appending-writes to files in the future. 
         </p>
       </section>
 
@@ -76,7 +92,10 @@
       <section> 
         <title> &#x201c;Moving Computation is Cheaper than Moving Data&#x201d; </title>
         <p>
-        A computation requested by an application is much more efficient if it is executed near the data it operates on. This is especially true when the size of the data set is huge. This minimizes network congestion and increases the overall throughput of the system. The assumption is that it is often better to migrate the computation closer to where the data is located rather than moving the data to where the application is running. HDFS provides interfaces for applications to move themselves closer to where the data is located. 
+        A computation requested by an application is much more efficient if it is executed near the data it operates on. This is especially true 
+        when the size of the data set is huge. This minimizes network congestion and increases the overall throughput of the system. The 
+        assumption is that it is often better to migrate the computation closer to where the data is located rather than moving the data to where 
+        the application is running. HDFS provides interfaces for applications to move themselves closer to where the data is located. 
         </p>
       </section>
 
@@ -84,7 +103,8 @@
       <section> 
         <title> Portability Across Heterogeneous Hardware and Software Platforms </title>
         <p>
-        HDFS has been designed to be easily portable from one platform to another. This facilitates widespread adoption of HDFS as a platform of choice for a large set of applications. 
+        HDFS has been designed to be easily portable from one platform to another. This facilitates widespread adoption of HDFS as a 
+        platform of choice for a large set of applications. 
         </p>
       </section>
     </section>
@@ -93,14 +113,28 @@
     <section>
       <title> NameNode and DataNodes </title>
       <p>
-      HDFS has a master/slave architecture. An HDFS cluster consists of a single NameNode, a master server that manages the file system namespace and regulates access to files by clients. In addition, there are a number of DataNodes, usually one per node in the cluster, which manage storage attached to the nodes that they run on. HDFS exposes a file system namespace and allows user data to be stored in files. Internally, a file is split into one or more blocks and these blocks are stored in a set of DataNodes. The NameNode executes file system namespace operations like opening, closing, and renaming files and directories. It also determines the mapping of blocks to DataNodes. The DataNodes are responsible for serving read and write requests from the file system&#x2019;s clients. The DataNodes also perform block creation, deletion, and replication upon instruction from the NameNode.
+      HDFS has a master/slave architecture. An HDFS cluster consists of a single NameNode, a master server that manages the file 
+      system namespace and regulates access to files by clients. In addition, there are a number of DataNodes, usually one per node 
+      in the cluster, which manage storage attached to the nodes that they run on. HDFS exposes a file system namespace and allows 
+      user data to be stored in files. Internally, a file is split into one or more blocks and these blocks are stored in a set of DataNodes. 
+      The NameNode executes file system namespace operations like opening, closing, and renaming files and directories. It also 
+      determines the mapping of blocks to DataNodes. The DataNodes are responsible for serving read and write requests from the file 
+      system&#x2019;s clients. The DataNodes also perform block creation, deletion, and replication upon instruction from the NameNode.
+      </p>
+      
+           <figure alt="HDFS Architecture" src="images/hdfsarchitecture.gif"/>
+
+      <p>
+      The NameNode and DataNode are pieces of software designed to run on commodity machines. These machines typically run a 
+      GNU/Linux operating system (<acronym title="operating system">OS</acronym>). HDFS is built using the Java language; any 
+      machine that supports Java can run the NameNode or the DataNode software. Usage of the highly portable Java language means 
+      that HDFS can be deployed on a wide range of machines. A typical deployment has a dedicated machine that runs only the 
+      NameNode software. Each of the other machines in the cluster runs one instance of the DataNode software. The architecture 
+      does not preclude running multiple DataNodes on the same machine but in a real deployment that is rarely the case.
       </p>
-      <figure alt="HDFS Architecture" src="images/hdfsarchitecture.gif"/>
       <p>
-      The NameNode and DataNode are pieces of software designed to run on commodity machines. These machines typically run a GNU/Linux operating system (<acronym title="operating system">OS</acronym>). HDFS is built using the Java language; any machine that supports Java can run the NameNode or the DataNode software. Usage of the highly portable Java language means that HDFS can be deployed on a wide range of machines. A typical deployment has a dedicated machine that runs only the NameNode software. Each of the other machines in the cluster runs one instance of the DataNode software. The architecture does not preclude running multiple DataNodes on the same machine but in a real deployment that is rarely the case.
-      </p>
-      <p>
-      The existence of a single NameNode in a cluster greatly simplifies the architecture of the system. The NameNode is the arbitrator and repository for all HDFS metadata. The system is designed in such a way that user data never flows through the NameNode.
+      The existence of a single NameNode in a cluster greatly simplifies the architecture of the system. The NameNode is the arbitrator 
+      and repository for all HDFS metadata. The system is designed in such a way that user data never flows through the NameNode.
       </p>
     </section>
 
@@ -109,10 +143,15 @@
     <section>
       <title> The File System Namespace </title>
       <p>
-      HDFS supports a traditional hierarchical file organization. A user or an application can create directories and store files inside these directories. The file system namespace hierarchy is similar to most other existing file systems; one can create and remove files, move a file from one directory to another, or rename a file. HDFS does not yet implement user quotas. HDFS does not support hard links or soft links. However, the HDFS architecture does not preclude implementing these features.
+      HDFS supports a traditional hierarchical file organization. A user or an application can create directories and store files inside 
+      these directories. The file system namespace hierarchy is similar to most other existing file systems; one can create and 
+      remove files, move a file from one directory to another, or rename a file. HDFS does not yet implement user quotas. HDFS 
+      does not support hard links or soft links. However, the HDFS architecture does not preclude implementing these features.
       </p>
       <p>
-      The NameNode maintains the file system namespace. Any change to the file system namespace or its properties is recorded by the NameNode. An application can specify the number of replicas of a file that should be maintained by HDFS. The number of copies of a file is called the replication factor of that file. This information is stored by the NameNode.
+      The NameNode maintains the file system namespace. Any change to the file system namespace or its properties is 
+      recorded by the NameNode. An application can specify the number of replicas of a file that should be maintained by 
+      HDFS. The number of copies of a file is called the replication factor of that file. This information is stored by the NameNode.
       </p>
     </section>
 
@@ -121,26 +160,52 @@
     <section> 
       <title> Data Replication </title>
       <p>
-      HDFS is designed to reliably store very large files across machines in a large cluster. It stores each file as a sequence of blocks; all blocks in a file except the last block are the same size. The blocks of a file are replicated for fault tolerance. The block size and replication factor are configurable per file. An application can specify the number of replicas of a file. The replication factor can be specified at file creation time and can be changed later. Files in HDFS are write-once and have strictly one writer at any time. 
+      HDFS is designed to reliably store very large files across machines in a large cluster. It stores each file as a sequence 
+      of blocks; all blocks in a file except the last block are the same size. The blocks of a file are replicated for fault tolerance. 
+      The block size and replication factor are configurable per file. An application can specify the number of replicas of a file. 
+      The replication factor can be specified at file creation time and can be changed later. Files in HDFS are write-once and 
+      have strictly one writer at any time. 
       </p>
       <p>
-      The NameNode makes all decisions regarding replication of blocks. It periodically receives a Heartbeat and a Blockreport from each of the DataNodes in the cluster. Receipt of a Heartbeat implies that the DataNode is functioning properly. A Blockreport contains a list of all blocks on a DataNode. 
+      The NameNode makes all decisions regarding replication of blocks. It periodically receives a Heartbeat and a Blockreport 
+      from each of the DataNodes in the cluster. Receipt of a Heartbeat implies that the DataNode is functioning properly. A 
+      Blockreport contains a list of all blocks on a DataNode. 
     </p>
     <figure alt="HDFS DataNodes" src="images/hdfsdatanodes.gif"/>
 
       <section>
         <title> Replica Placement: The First Baby Steps </title>
         <p>
-        The placement of replicas is critical to HDFS reliability and performance. Optimizing replica placement distinguishes HDFS from most other distributed file systems. This is a feature that needs lots of tuning and experience. The purpose of a rack-aware replica placement policy is to improve data reliability, availability, and network bandwidth utilization. The current implementation for the replica placement policy is a first effort in this direction. The short-term goals of implementing this policy are to validate it on production systems, learn more about its behavior, and build a foundation to test and research more sophisticated policies. 
-        </p>
-        <p>
-        Large HDFS instances run on a cluster of computers that commonly spread across many racks. Communication between two nodes in different racks has to go through switches. In most cases, network bandwidth between machines in the same rack is greater than network bandwidth between machines in different racks.  
-        </p>
-        <p>
-        The NameNode determines the rack id each DataNode belongs to via the process outlined in <a href="cluster_setup.html#Hadoop+Rack+Awareness">Rack Awareness</a>. A simple but non-optimal policy is to place replicas on unique racks. This prevents losing data when an entire rack fails and allows use of bandwidth from multiple racks when reading data. This policy evenly distributes replicas in the cluster which makes it easy to balance load on component failure. However, this policy increases the cost of writes because a write needs to transfer blocks to multiple racks. 
-        </p>
-        <p>
-        For the common case, when the replication factor is three, HDFS&#x2019;s placement policy is to put one replica on one node in the local rack, another on a node in a different (remote) rack, and the last on a different node in the same remote rack. This policy cuts the inter-rack write traffic which generally improves write performance. The chance of rack failure is far less than that of node failure; this policy does not impact data reliability and availability guarantees. However, it does reduce the aggregate network bandwidth used when reading data since a block is placed in only two unique racks rather than three. With this policy, the replicas of a file do not evenly distribute across the racks. One third of replicas are on one node, two thirds of replicas are on one rack, and the other third are evenly distributed across the remaining racks. This policy improves write performance without compromising data reliability or read performance.
+        The placement of replicas is critical to HDFS reliability and performance. Optimizing replica placement distinguishes 
+        HDFS from most other distributed file systems. This is a feature that needs lots of tuning and experience. The purpose 
+        of a rack-aware replica placement policy is to improve data reliability, availability, and network bandwidth utilization. 
+        The current implementation for the replica placement policy is a first effort in this direction. The short-term goals of 
+        implementing this policy are to validate it on production systems, learn more about its behavior, and build a foundation 
+        to test and research more sophisticated policies. 
+        </p>
+        <p>
+        Large HDFS instances run on a cluster of computers that commonly spread across many racks. Communication 
+        between two nodes in different racks has to go through switches. In most cases, network bandwidth between machines 
+        in the same rack is greater than network bandwidth between machines in different racks.  
+        </p>
+        <p>
+        The NameNode determines the rack id each DataNode belongs to via the process outlined in 
+        <a href="http://hadoop.apache.org/common/docs/current/cluster_setup.html#Hadoop+Rack+Awareness">Hadoop Rack Awareness</a>. 
+        A simple but non-optimal policy is to place replicas on unique racks. This prevents losing data when an entire rack 
+        fails and allows use of bandwidth from multiple racks when reading data. This policy evenly distributes replicas in 
+        the cluster which makes it easy to balance load on component failure. However, this policy increases the cost of 
+        writes because a write needs to transfer blocks to multiple racks. 
+        </p>
+        <p>
+        For the common case, when the replication factor is three, HDFS&#x2019;s placement policy is to put one replica 
+        on one node in the local rack, another on a node in a different (remote) rack, and the last on a different node in the 
+        same remote rack. This policy cuts the inter-rack write traffic which generally improves write performance. The 
+        chance of rack failure is far less than that of node failure; this policy does not impact data reliability and availability 
+        guarantees. However, it does reduce the aggregate network bandwidth used when reading data since a block is 
+        placed in only two unique racks rather than three. With this policy, the replicas of a file do not evenly distribute 
+        across the racks. One third of replicas are on one node, two thirds of replicas are on one rack, and the other third 
+        are evenly distributed across the remaining racks. This policy improves write performance without compromising 
+        data reliability or read performance.
         </p>
         <p>
         The current, default replica placement policy described here is a work in progress.
@@ -150,14 +215,24 @@
       <section> 
         <title> Replica Selection </title>
         <p>
-        To minimize global bandwidth consumption and read latency, HDFS tries to satisfy a read request from a replica that is closest to the reader. If there exists a replica on the same rack as the reader node, then that replica is preferred to satisfy the read request. If angg/ HDFS cluster spans multiple data centers, then a replica that is resident in the local data center is preferred over any remote replica.
+        To minimize global bandwidth consumption and read latency, HDFS tries to satisfy a read request from a replica 
+        that is closest to the reader. If there exists a replica on the same rack as the reader node, then that replica is 
+        preferred to satisfy the read request. If angg/ HDFS cluster spans multiple data centers, then a replica that is 
+        resident in the local data center is preferred over any remote replica.
         </p>
       </section>
 
       <section> 
         <title> Safemode </title>
         <p>
-        On startup, the NameNode enters a special state called Safemode. Replication of data blocks does not occur when the NameNode is in the Safemode state. The NameNode receives Heartbeat and Blockreport messages from the DataNodes. A Blockreport contains the list of data blocks that a DataNode is hosting. Each block has a specified minimum number of replicas. A block is considered safely replicated when the minimum number of replicas of that data block has checked in with the NameNode. After a configurable percentage of safely replicated data blocks checks in with the NameNode (plus an additional 30 seconds), the NameNode exits the Safemode state. It then determines the list of data blocks (if any) that still have fewer than the specified number of replicas. The NameNode then replicates these blocks to other DataNodes.
+        On startup, the NameNode enters a special state called Safemode. Replication of data blocks does not occur 
+        when the NameNode is in the Safemode state. The NameNode receives Heartbeat and Blockreport messages 
+        from the DataNodes. A Blockreport contains the list of data blocks that a DataNode is hosting. Each block 
+        has a specified minimum number of replicas. A block is considered safely replicated when the minimum number 
+        of replicas of that data block has checked in with the NameNode. After a configurable percentage of safely 
+        replicated data blocks checks in with the NameNode (plus an additional 30 seconds), the NameNode exits 
+        the Safemode state. It then determines the list of data blocks (if any) that still have fewer than the specified 
+        number of replicas. The NameNode then replicates these blocks to other DataNodes.
         </p>
       </section>
 
@@ -166,13 +241,32 @@
     <section>
       <title> The Persistence of File System Metadata </title>
         <p>
-        The HDFS namespace is stored by the NameNode. The NameNode uses a transaction log called the EditLog to persistently record every change that occurs to file system metadata. For example, creating a new file in HDFS causes the NameNode to insert a record into the EditLog indicating this. Similarly, changing the replication factor of a file causes a new record to be inserted into the EditLog. The NameNode uses a file in its local host OS file system to store the EditLog. The entire file system namespace, including the mapping of blocks to files and file system properties, is stored in a file called the FsImage. The FsImage is stored as a file in the NameNode&#x2019;s local file system too.
-        </p>
-        <p>
-        The NameNode keeps an image of the entire file system namespace and file Blockmap in memory. This key metadata item is designed to be compact, such that a NameNode with 4 GB of RAM is plenty to support a huge number of files and directories. When the NameNode starts up, it reads the FsImage and EditLog from disk, applies all the transactions from the EditLog to the in-memory representation of the FsImage, and flushes out this new version into a new FsImage on disk. It can then truncate the old EditLog because its transactions have been applied to the persistent FsImage. This process is called a checkpoint. In the current implementation, a checkpoint only occurs when the NameNode starts up. Work is in progress to support periodic checkpointing in the near future.
-        </p>
-        <p>
-        The DataNode stores HDFS data in files in its local file system. The DataNode has no knowledge about HDFS files. It stores each block of HDFS data in a separate file in its local file system. The DataNode does not create all files in the same directory. Instead, it uses a heuristic to determine the optimal number of files per directory and creates subdirectories appropriately. It is not optimal to create all local files in the same directory because the local file system might not be able to efficiently support a huge number of files in a single directory. When a DataNode starts up, it scans through its local file system, generates a list of all HDFS data blocks that correspond to each of these local files and sends this report to the NameNode: this is the Blockreport. 
+        The HDFS namespace is stored by the NameNode. The NameNode uses a transaction log called the EditLog 
+        to persistently record every change that occurs to file system metadata. For example, creating a new file in 
+        HDFS causes the NameNode to insert a record into the EditLog indicating this. Similarly, changing the 
+        replication factor of a file causes a new record to be inserted into the EditLog. The NameNode uses a file 
+        in its local host OS file system to store the EditLog. The entire file system namespace, including the mapping 
+        of blocks to files and file system properties, is stored in a file called the FsImage. The FsImage is stored as 
+        a file in the NameNode&#x2019;s local file system too.
+        </p>
+        <p>
+        The NameNode keeps an image of the entire file system namespace and file Blockmap in memory. This key 
+        metadata item is designed to be compact, such that a NameNode with 4 GB of RAM is plenty to support a 
+        huge number of files and directories. When the NameNode starts up, it reads the FsImage and EditLog from 
+        disk, applies all the transactions from the EditLog to the in-memory representation of the FsImage, and flushes 
+        out this new version into a new FsImage on disk. It can then truncate the old EditLog because its transactions 
+        have been applied to the persistent FsImage. This process is called a checkpoint. In the current implementation, 
+        a checkpoint only occurs when the NameNode starts up. Work is in progress to support periodic checkpointing 
+        in the near future.
+        </p>
+        <p>
+        The DataNode stores HDFS data in files in its local file system. The DataNode has no knowledge about HDFS files. 
+        It stores each block of HDFS data in a separate file in its local file system. The DataNode does not create all files 
+        in the same directory. Instead, it uses a heuristic to determine the optimal number of files per directory and creates 
+        subdirectories appropriately. It is not optimal to create all local files in the same directory because the local file 
+        system might not be able to efficiently support a huge number of files in a single directory. When a DataNode starts 
+        up, it scans through its local file system, generates a list of all HDFS data blocks that correspond to each of these 
+        local files and sends this report to the NameNode: this is the Blockreport. 
         </p>
     </section>
 
@@ -180,7 +274,12 @@
     <section> 
       <title> The Communication Protocols </title>
       <p>
-      All HDFS communication protocols are layered on top of the TCP/IP protocol. A client establishes a connection to a configurable <acronym title="Transmission Control Protocol">TCP</acronym> port on the NameNode machine. It talks the ClientProtocol with the NameNode. The DataNodes talk to the NameNode using the DataNode Protocol. A Remote Procedure Call (<acronym title="Remote Procedure Call">RPC</acronym>) abstraction wraps both the Client Protocol and the DataNode Protocol. By design, the NameNode never initiates any RPCs. Instead, it only responds to RPC requests issued by DataNodes or clients. 
+      All HDFS communication protocols are layered on top of the TCP/IP protocol. A client establishes a connection to 
+      a configurable <acronym title="Transmission Control Protocol">TCP</acronym> port on the NameNode machine. 
+      It talks the ClientProtocol with the NameNode. The DataNodes talk to the NameNode using the DataNode Protocol. 
+      A Remote Procedure Call (<acronym title="Remote Procedure Call">RPC</acronym>) abstraction wraps both the 
+      Client Protocol and the DataNode Protocol. By design, the NameNode never initiates any RPCs. Instead, it only 
+      responds to RPC requests issued by DataNodes or clients. 
       </p>
     </section>
  
@@ -188,20 +287,32 @@
     <section> 
       <title> Robustness </title>
       <p>
-      The primary objective of HDFS is to store data reliably even in the presence of failures. The three common types of failures are NameNode failures, DataNode failures and network partitions.
+      The primary objective of HDFS is to store data reliably even in the presence of failures. The three common types 
+      of failures are NameNode failures, DataNode failures and network partitions.
       </p>
  
       <section>
         <title> Data Disk Failure, Heartbeats and Re-Replication </title>
         <p>
-        Each DataNode sends a Heartbeat message to the NameNode periodically. A network partition can cause a subset of DataNodes to lose connectivity with the NameNode. The NameNode detects this condition by the absence of a Heartbeat message. The NameNode marks DataNodes without recent Heartbeats as dead and does not forward any new <acronym title="Input/Output">IO</acronym> requests to them. Any data that was registered to a dead DataNode is not available to HDFS any more. DataNode death may cause the replication factor of some blocks to fall below their specified value. The NameNode constantly tracks which blocks need to be replicated and initiates replication whenever necessary. The necessity for re-replication may arise due to many reasons: a DataNode may become unavailable, a replica may become corrupted, a hard disk on a DataNode may fail, or the replication factor of a file may be increased. 
+        Each DataNode sends a Heartbeat message to the NameNode periodically. A network partition can cause a 
+        subset of DataNodes to lose connectivity with the NameNode. The NameNode detects this condition by the 
+        absence of a Heartbeat message. The NameNode marks DataNodes without recent Heartbeats as dead and 
+        does not forward any new <acronym title="Input/Output">IO</acronym> requests to them. Any data that was 
+        registered to a dead DataNode is not available to HDFS any more. DataNode death may cause the replication 
+        factor of some blocks to fall below their specified value. The NameNode constantly tracks which blocks need 
+        to be replicated and initiates replication whenever necessary. The necessity for re-replication may arise due 
+        to many reasons: a DataNode may become unavailable, a replica may become corrupted, a hard disk on a 
+        DataNode may fail, or the replication factor of a file may be increased. 
         </p>
       </section>
 
       <section>
         <title> Cluster Rebalancing </title>
         <p>
-        The HDFS architecture is compatible with data rebalancing schemes. A scheme might automatically move data from one DataNode to another if the free space on a DataNode falls below a certain threshold. In the event of a sudden high demand for a particular file, a scheme might dynamically create additional replicas and rebalance other data in the cluster. These types of data rebalancing schemes are not yet implemented. 
+        The HDFS architecture is compatible with data rebalancing schemes. A scheme might automatically move 
+        data from one DataNode to another if the free space on a DataNode falls below a certain threshold. In the 
+        event of a sudden high demand for a particular file, a scheme might dynamically create additional replicas 
+        and rebalance other data in the cluster. These types of data rebalancing schemes are not yet implemented. 
         </p>
       </section>
 
@@ -209,7 +320,13 @@
         <title> Data Integrity </title>
         <p>
         <!-- XXX "checksum checking" sounds funny -->
-        It is possible that a block of data fetched from a DataNode arrives corrupted. This corruption can occur because of faults in a storage device, network faults, or buggy software. The HDFS client software implements checksum checking on the contents of HDFS files. When a client creates an HDFS file, it computes a checksum of each block of the file and stores these checksums in a separate hidden file in the same HDFS namespace. When a client retrieves file contents it verifies that the data it received from each DataNode matches the checksum stored in the associated checksum file. If not, then the client can opt to retrieve that block from another DataNode that has a replica of that block.
+        It is possible that a block of data fetched from a DataNode arrives corrupted. This corruption can occur 
+        because of faults in a storage device, network faults, or buggy software. The HDFS client software 
+        implements checksum checking on the contents of HDFS files. When a client creates an HDFS file, 
+        it computes a checksum of each block of the file and stores these checksums in a separate hidden 
+        file in the same HDFS namespace. When a client retrieves file contents it verifies that the data it 
+        received from each DataNode matches the checksum stored in the associated checksum file. If not, 
+        then the client can opt to retrieve that block from another DataNode that has a replica of that block.
         </p>
       </section>
  
@@ -217,17 +334,28 @@
       <section>
         <title> Metadata Disk Failure </title>
         <p>
-        The FsImage and the EditLog are central data structures of HDFS. A corruption of these files can cause the HDFS instance to be non-functional. For this reason, the NameNode can be configured to support maintaining multiple copies of the FsImage and EditLog. Any update to either the FsImage or EditLog causes each of the FsImages and EditLogs to get updated synchronously. This synchronous updating of multiple copies of the FsImage and EditLog may degrade the rate of namespace transactions per second that a NameNode can support. However, this degradation is acceptable because even though HDFS applications are very data intensive in nature, they are not metadata intensive. When a NameNode restarts, it selects the latest consistent FsImage and EditLog to use.
+        The FsImage and the EditLog are central data structures of HDFS. A corruption of these files can 
+        cause the HDFS instance to be non-functional. For this reason, the NameNode can be configured 
+        to support maintaining multiple copies of the FsImage and EditLog. Any update to either the FsImage 
+        or EditLog causes each of the FsImages and EditLogs to get updated synchronously. This 
+        synchronous updating of multiple copies of the FsImage and EditLog may degrade the rate of 
+        namespace transactions per second that a NameNode can support. However, this degradation is 
+        acceptable because even though HDFS applications are very data intensive in nature, they are not 
+        metadata intensive. When a NameNode restarts, it selects the latest consistent FsImage and EditLog to use.
         </p>
         <p> 
-        The NameNode machine is a single point of failure for an HDFS cluster. If the NameNode machine fails, manual intervention is necessary. Currently, automatic restart and failover of the NameNode software to another machine is not supported.
+        The NameNode machine is a single point of failure for an HDFS cluster. If the NameNode machine fails, 
+        manual intervention is necessary. Currently, automatic restart and failover of the NameNode software to 
+        another machine is not supported.
         </p>
       </section>
 
       <section>
         <title> Snapshots </title>
         <p>
-        Snapshots support storing a copy of data at a particular instant of time. One usage of the snapshot feature may be to roll back a corrupted HDFS instance to a previously known good point in time. HDFS does not currently support snapshots but will in a future release.
+        Snapshots support storing a copy of data at a particular instant of time. One usage of the snapshot 
+        feature may be to roll back a corrupted HDFS instance to a previously known good point in time. 
+        HDFS does not currently support snapshots but will in a future release.
         </p>
       </section>
 
@@ -241,7 +369,11 @@
       <section>
         <title> Data Blocks </title>
         <p>
-        HDFS is designed to support very large files. Applications that are compatible with HDFS are those that deal with large data sets. These applications write their data only once but they read it one or more times and require these reads to be satisfied at streaming speeds. HDFS supports write-once-read-many semantics on files. A typical block size used by HDFS is 64 MB. Thus, an HDFS file is chopped up into 64 MB chunks, and if possible, each chunk will reside on a different DataNode.
+        HDFS is designed to support very large files. Applications that are compatible with HDFS are those 
+        that deal with large data sets. These applications write their data only once but they read it one or 
+        more times and require these reads to be satisfied at streaming speeds. HDFS supports 
+        write-once-read-many semantics on files. A typical block size used by HDFS is 64 MB. Thus, 
+        an HDFS file is chopped up into 64 MB chunks, and if possible, each chunk will reside on a different DataNode.
         </p>
       </section>
 
@@ -250,17 +382,42 @@
         <!-- XXX staging never described / referenced in its section -->
         <title> Staging </title>
         <p>
-        A client request to create a file does not reach the NameNode immediately. In fact, initially the HDFS client caches the file data into a temporary local file. Application writes are transparently redirected to this temporary local file. When the local file accumulates data worth over one HDFS block size, the client contacts the NameNode. The NameNode inserts the file name into the file system hierarchy and allocates a data block for it. The NameNode responds to the client request with the identity of the DataNode and the destination data block. Then the client flushes the block of data from the local temporary file to the specified DataNode. When a file is closed, the remaining un-flushed data in the temporary local file is transferred to the DataNode. The client then tells the NameNode that the file is closed. At this point, the NameNode commits the file creation operation into a persistent store. If the NameNode dies before the file is closed, the file is lost. 
-        </p>
-        <p>
-        The above approach has been adopted after careful consideration of target applications that run on HDFS. These applications need streaming writes to files. If a client writes to a remote file directly without any client side buffering, the network speed and the congestion in the network impacts throughput considerably. This approach is not without precedent. Earlier distributed file systems, e.g. <acronym title="Andrew File System">AFS</acronym>, have used client side caching to improve performance. A POSIX requirement has been relaxed to achieve higher performance of data uploads. 
+        A client request to create a file does not reach the NameNode immediately. In fact, initially the HDFS 
+        client caches the file data into a temporary local file. Application writes are transparently redirected to 
+        this temporary local file. When the local file accumulates data worth over one HDFS block size, the 
+        client contacts the NameNode. The NameNode inserts the file name into the file system hierarchy 
+        and allocates a data block for it. The NameNode responds to the client request with the identity 
+        of the DataNode and the destination data block. Then the client flushes the block of data from the 
+        local temporary file to the specified DataNode. When a file is closed, the remaining un-flushed data 
+        in the temporary local file is transferred to the DataNode. The client then tells the NameNode that 
+        the file is closed. At this point, the NameNode commits the file creation operation into a persistent 
+        store. If the NameNode dies before the file is closed, the file is lost. 
+        </p>
+        <p>
+        The above approach has been adopted after careful consideration of target applications that run on 
+        HDFS. These applications need streaming writes to files. If a client writes to a remote file directly 
+        without any client side buffering, the network speed and the congestion in the network impacts 
+        throughput considerably. This approach is not without precedent. Earlier distributed file systems, 
+        e.g. <acronym title="Andrew File System">AFS</acronym>, have used client side caching to 
+        improve performance. A POSIX requirement has been relaxed to achieve higher performance of 
+        data uploads. 
         </p>
       </section>
 
       <section>
         <title> Replication Pipelining </title>
         <p>
-        When a client is writing data to an HDFS file, its data is first written to a local file as explained in the previous section. Suppose the HDFS file has a replication factor of three. When the local file accumulates a full block of user data, the client retrieves a list of DataNodes from the NameNode. This list contains the DataNodes that will host a replica of that block. The client then flushes the data block to the first DataNode. The first DataNode starts receiving the data in small portions (4 KB), writes each portion to its local repository and transfers that portion to the second DataNode in the list. The second DataNode, in turn starts receiving each portion of the data block, writes that portion to its repository and then flushes that portion to the third DataNode. Finally, the third DataNode writes the data to its local repository. Thus, a DataNode can be receiving data from the previous one in the pipeline and at the same time forwarding data to the next o
 ne in the pipeline. Thus, the data is pipelined from one DataNode to the next.
+        When a client is writing data to an HDFS file, its data is first written to a local file as explained 
+        in the previous section. Suppose the HDFS file has a replication factor of three. When the local 
+        file accumulates a full block of user data, the client retrieves a list of DataNodes from the NameNode. 
+        This list contains the DataNodes that will host a replica of that block. The client then flushes the 
+        data block to the first DataNode. The first DataNode starts receiving the data in small portions (4 KB), 
+        writes each portion to its local repository and transfers that portion to the second DataNode in the list. 
+        The second DataNode, in turn starts receiving each portion of the data block, writes that portion to its 
+        repository and then flushes that portion to the third DataNode. Finally, the third DataNode writes the 
+        data to its local repository. Thus, a DataNode can be receiving data from the previous one in the pipeline 
+        and at the same time forwarding data to the next one in the pipeline. Thus, the data is pipelined from 
+        one DataNode to the next.
         </p>
       </section>
 
@@ -271,26 +428,36 @@
       <title> Accessibility </title>
       <!-- XXX Make an API section ? (HTTP is "web service" API?) -->
       <p>
-      HDFS can be accessed from applications in many different ways. Natively, HDFS provides a <a href="http://hadoop.apache.org/core/docs/current/api/">Java API</a> for applications to use. A C language wrapper for this Java API is also available. In addition, an HTTP browser can also be used to browse the files of an HDFS instance. Work is in progress to expose HDFS through the <acronym title="Web-based Distributed Authoring and Versioning">WebDAV</acronym> protocol. 
+      HDFS can be accessed from applications in many different ways. Natively, HDFS provides a 
+      <a href="http://hadoop.apache.org/core/docs/current/api/">Java API</a> for applications to 
+      use. A C language wrapper for this Java API is also available. In addition, an HTTP browser 
+      can also be used to browse the files of an HDFS instance. Work is in progress to expose 
+      HDFS through the <acronym title="Web-based Distributed Authoring and Versioning">WebDAV</acronym> protocol. 
       </p>
 
       <section>
         <title> FS Shell </title>
         <p>
-        HDFS allows user data to be organized in the form of files and directories. It provides a commandline interface called  FS shell that lets a user interact with the data in HDFS. The syntax of this command set is similar to other shells (e.g. bash, csh) that users are already familiar with. Here are some sample action/command pairs:
+        HDFS allows user data to be organized in the form of files and directories. It provides a commandline 
+        interface called  FS shell that lets a user interact with the data in HDFS. The syntax of this command 
+        set is similar to other shells (e.g. bash, csh) that users are already familiar with. Here are some sample 
+        action/command pairs:
         </p>
         <table>
           <tr>
             <th> Action </th><th> Command </th>
           </tr>
           <tr>
-            <td> Create a directory named <code>/foodir</code> </td> <td> <code>bin/hadoop dfs -mkdir /foodir</code> </td>
+            <td> Create a directory named <code>/foodir</code> </td> 
+            <td> <code>bin/hadoop dfs -mkdir /foodir</code> </td>
           </tr>
           <tr>
-            <td> Remove a directory named <code>/foodir</code> </td> <td> <code>bin/hadoop dfs -rmr /foodir</code> </td>
+            <td> Remove a directory named <code>/foodir</code> </td> 
+            <td> <code>bin/hadoop dfs -rmr /foodir</code> </td>
           </tr>
           <tr>
-            <td> View the contents of a file named <code>/foodir/myfile.txt</code> </td> <td> <code>bin/hadoop dfs -cat /foodir/myfile.txt</code> </td>
+            <td> View the contents of a file named <code>/foodir/myfile.txt</code> </td> 
+            <td> <code>bin/hadoop dfs -cat /foodir/myfile.txt</code> </td>
           </tr>
         </table>
         <p>
@@ -301,7 +468,8 @@
       <section> 
         <title> DFSAdmin </title>
         <p>
-        The DFSAdmin command set is used for administering an HDFS cluster. These are commands that are used only by an HDFS administrator. Here are some sample action/command pairs:
+        The DFSAdmin command set is used for administering an HDFS cluster. These are commands that are 
+        used only by an HDFS administrator. Here are some sample action/command pairs:
         </p>
         <table>
           <tr>
@@ -314,7 +482,8 @@
             <td> Generate a list of DataNodes </td> <td> <code>bin/hadoop dfsadmin -report</code> </td>
           </tr>
           <tr>
-            <td> Recommission or decommission DataNode(s) </td><td> <code>bin/hadoop dfsadmin -refreshNodes</code> </td>
+            <td> Recommission or decommission DataNode(s) </td>
+            <td> <code>bin/hadoop dfsadmin -refreshNodes</code> </td>
           </tr>
         </table>
       </section>
@@ -322,7 +491,9 @@
       <section> 
         <title> Browser Interface </title>
         <p>
-        A typical HDFS install configures a web server to expose the HDFS namespace through a configurable TCP port. This allows a user to navigate the HDFS namespace and view the contents of its files using a web browser.
+        A typical HDFS install configures a web server to expose the HDFS namespace through 
+        a configurable TCP port. This allows a user to navigate the HDFS namespace and view 
+        the contents of its files using a web browser.
        </p>
       </section>
 
@@ -334,17 +505,32 @@
       <section>
         <title> File Deletes and Undeletes </title>
         <p>
-        When a file is deleted by a user or an application, it is not immediately removed from HDFS.  Instead, HDFS first renames it to a file in the <code>/trash</code> directory. The file can be restored quickly as long as it remains in <code>/trash</code>. A file remains in <code>/trash</code> for a configurable amount of time. After the expiry of its life in <code>/trash</code>, the NameNode deletes the file from the HDFS namespace. The deletion of a file causes the blocks associated with the file to be freed. Note that there could be an appreciable time delay between the time a file is deleted by a user and the time of the corresponding increase in free space in HDFS.
-        </p>
-        <p>
-        A user can Undelete a file after deleting it as long as it remains in the <code>/trash</code> directory. If a user wants to undelete a file that he/she has deleted, he/she can navigate the <code>/trash</code> directory and retrieve the file. The <code>/trash</code> directory contains only the latest copy of the file that was deleted. The <code>/trash</code> directory is just like any other directory with one special feature: HDFS applies specified policies to automatically delete files from this directory. The current default policy is to delete files from <code>/trash</code> that are more than 6 hours old. In the future, this policy will be configurable through a well defined interface.
+        When a file is deleted by a user or an application, it is not immediately removed from HDFS.  Instead, 
+        HDFS first renames it to a file in the <code>/trash</code> directory. The file can be restored quickly 
+        as long as it remains in <code>/trash</code>. A file remains in <code>/trash</code> for a configurable 
+        amount of time. After the expiry of its life in <code>/trash</code>, the NameNode deletes the file from 
+        the HDFS namespace. The deletion of a file causes the blocks associated with the file to be freed. 
+        Note that there could be an appreciable time delay between the time a file is deleted by a user and 
+        the time of the corresponding increase in free space in HDFS.
+        </p>
+        <p>
+        A user can Undelete a file after deleting it as long as it remains in the <code>/trash</code> directory. 
+        If a user wants to undelete a file that he/she has deleted, he/she can navigate the <code>/trash</code> 
+        directory and retrieve the file. The <code>/trash</code> directory contains only the latest copy of the file 
+        that was deleted. The <code>/trash</code> directory is just like any other directory with one special 
+        feature: HDFS applies specified policies to automatically delete files from this directory. The current 
+        default policy is to delete files from <code>/trash</code> that are more than 6 hours old. In the future, 
+        this policy will be configurable through a well defined interface.
         </p>
       </section>
 
       <section>
         <title> Decrease Replication Factor </title>
         <p>
-        When the replication factor of a file is reduced, the NameNode selects excess replicas that can be deleted. The next Heartbeat transfers this information to the DataNode. The DataNode then removes the corresponding blocks and the corresponding free space appears in the cluster. Once again, there might be a time delay between the completion of the <code>setReplication</code> API call and the appearance of free space in the cluster.
+        When the replication factor of a file is reduced, the NameNode selects excess replicas that can be deleted. 
+        The next Heartbeat transfers this information to the DataNode. The DataNode then removes the corresponding 
+        blocks and the corresponding free space appears in the cluster. Once again, there might be a time delay 
+        between the completion of the <code>setReplication</code> API call and the appearance of free space in the cluster.
         </p>
       </section>
     </section>
@@ -360,8 +546,8 @@
       </p>
       <p>
       HDFS source code: 
-      <a href= "http://hadoop.apache.org/core/version_control.html"> 
-        http://hadoop.apache.org/core/version_control.html
+      <a href= "http://hadoop.apache.org/hdfs/version_control.html"> 
+        http://hadoop.apache.org/hdfs/version_control.html
       </a>
       </p>
     </section> 



Mime
View raw message