svn commit: r873543 - in /websites/staging/directory/trunk/content: ./ mavibot/five-minutes-tutorial.html

[bu...@apache.org]

Author: buildbot
Date: Thu Aug  8 17:10:22 2013
New Revision: 873543

Log:
Staging update by buildbot for directory

Modified:
    websites/staging/directory/trunk/content/   (props changed)
    websites/staging/directory/trunk/content/mavibot/five-minutes-tutorial.html

Propchange: websites/staging/directory/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Aug  8 17:10:22 2013
@@ -1 +1 @@
-1511790
+1511880

Modified: websites/staging/directory/trunk/content/mavibot/five-minutes-tutorial.html
==============================================================================
--- websites/staging/directory/trunk/content/mavibot/five-minutes-tutorial.html (original)
+++ websites/staging/directory/trunk/content/mavibot/five-minutes-tutorial.html Thu Aug  8 17:10:22 2013
@@ -123,7 +123,82 @@
 
 
 <h1 id="five-minutes-tutorial">Five Minutes Tutorial</h1>
-<p>TO BE COMPLETED...</p>
+<p>Let's drop a quick sample first :</p>
+<div class="codehilite"><pre><span class="c1">// Create a BTree that stores String indexed by a Long</span>
+<span class="n">BTree</span><span class="o">&lt;</span><span class="n">Long</span><span class="o">,</span> <span class="n">String</span><span class="o">&gt;</span> <span class="n">btree</span> <span class="o">=</span> <span class="k">new</span> <span class="n">BTree</span><span class="o">&lt;</span><span class="n">Long</span><span class="o">,</span> <span class="n">String</span><span class="o">&gt;(</span> <span class="s">&quot;test&quot;</span><span class="o">,</span> <span class="k">new</span> <span class="n">LongSerializer</span><span class="o">(),</span> <span class="k">new</span> <span class="n">StringSerializer</span><span class="o">()</span> <span class="o">);</span>
+
+<span class="c1">// Inject some random data in it</span>
+<span class="k">for</span> <span class="o">(</span> <span class="kt">long</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0L</span><span class="o">;</span> <span class="n">i</span> <span class="o">&lt;</span> <span class="mi">10000L</span><span class="o">;</span> <span class="n">i</span><span class="o">++</span> <span class="o">)</span>
+<span class="o">{</span>
+    <span class="n">Long</span> <span class="n">key</span> <span class="o">=</span> <span class="o">(</span> <span class="kt">long</span> <span class="o">)</span> <span class="n">random</span><span class="o">.</span><span class="na">nextLong</span><span class="o">();</span>
+    <span class="n">String</span> <span class="n">value</span> <span class="o">=</span> <span class="n">Long</span><span class="o">.</span><span class="na">toString</span><span class="o">(</span> <span class="n">key</span> <span class="o">);</span>
+
+    <span class="n">btree</span><span class="o">.</span><span class="na">insert</span><span class="o">(</span> <span class="n">key</span><span class="o">,</span> <span class="n">value</span> <span class="o">);</span>
+<span class="o">}</span>
+
+<span class="c1">// Check that the tree contains all the values</span>
+<span class="k">try</span>
+<span class="o">{</span>
+    <span class="k">for</span> <span class="o">(</span> <span class="kt">long</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0L</span><span class="o">;</span> <span class="n">i</span> <span class="o">&lt;</span> <span class="mi">100000L</span><span class="o">;</span> <span class="n">i</span><span class="o">++</span> <span class="o">)</span>
+    <span class="o">{</span>
+        <span class="n">assertEquals</span><span class="o">(</span> <span class="n">Long</span><span class="o">.</span><span class="na">toString</span><span class="o">(</span> <span class="n">i</span> <span class="o">),</span> <span class="n">btree</span><span class="o">.</span><span class="na">get</span><span class="o">(</span> <span class="n">i</span> <span class="o">)</span> <span class="o">);</span>
+    <span class="o">}</span>
+<span class="o">}</span>
+<span class="k">catch</span> <span class="o">(</span> <span class="n">KeyNotFoundException</span> <span class="n">knfe</span> <span class="o">)</span>
+<span class="o">{</span>
+    <span class="n">fail</span><span class="o">();</span>
+<span class="o">}</span>
+
+<span class="c1">// Let&#39;s close the BTree now</span>
+<span class="n">btree</span><span class="o">.</span><span class="na">close</span><span class="o">();</span>
+</pre></div>
+
+
+<p>So what do we have here ? </p>
+<ul>
+<li>we have created a BTree</li>
+<li>we have fed it with 10 000 keys and values</li>
+<li>we have read all of them</li>
+</ul>
+<p>That's pretty simple ! All you have to do is to carefully create your BTree, and to provide the Key and Value serializers.</p>
+<p>We will now look a little more in detail what you can do.</p>
+<h2 id="btrees-and-storage">BTrees and storage</h2>
+<p>A BTree knows pretty much nothing about the way the data it contains are stored. The default is to store data in memory, with a backup being done on disk regularly, so that you don't lose anything in case of a crash. This is what we have done in the previous example.</p>
+<p>But you can also associate a <em>BTree</em> to a <em>RecordManager</em>, which will manage the storage on disk on any modification. In this case, the RecordManager will encapsulate the <em>BTree</em> (in fact, a <em>RecordManager</em> can handle more than one <em>BTree</em>). Here is how you use this feature :</p>
+<div class="codehilite"><pre><span class="c1">// Create the RecordManager</span>
+<span class="n">RecordManager</span> <span class="n">recordManager</span> <span class="o">=</span> <span class="k">new</span> <span class="n">RecordManager</span><span class="o">(</span> <span class="s">&quot;MyData.db&quot;</span> <span class="o">);</span>
+
+<span class="c1">// Delegate the creation of the BTree to the recordManager</span>
+<span class="n">BTree</span><span class="o">&lt;</span><span class="n">Long</span><span class="o">,</span> <span class="n">String</span><span class="o">&gt;</span> <span class="n">btree</span> <span class="o">=</span> <span class="n">recordManager1</span><span class="o">.</span><span class="na">addBTree</span><span class="o">(</span> <span class="s">&quot;test&quot;</span><span class="o">,</span> <span class="k">new</span> <span class="n">LongSerializer</span><span class="o">(),</span> <span class="k">new</span> <span class="n">StringSerializer</span><span class="o">(),</span> <span class="kc">false</span> <span class="o">);</span>
+
+<span class="c1">// Do whatever you want with the BTree now...</span>
+
+<span class="c1">// Close the RecordManager. It will close all the associated BTrees</span>
+<span class="n">recordManager</span><span class="o">.</span><span class="na">close</span><span class="o">();</span>
+</pre></div>
+
+
+<p>Here, all the modifications wil be stored on disk, and in an efficient way.</p>
+<h2 id="operations-on-a-btree">Operations on a BTree</h2>
+<p>The type of operations you can conduct on a <em>Btree</em> are listed below (for the most useful ones )</p>
+<ul>
+<li>browse : allow a user to browse the full <em>BTree</em> up and down</li>
+<li>contains : tells if a <em>BTree</em> contains a specific key and value</li>
+<li>delete : delete from a <em>BTree</em></li>
+<li>get : return a value from a key </li>
+<li>hasKey : tells if the <em>BTree</em> contains a specific key</li>
+<li>insert : inject a new key and values in a <em>BTree</em></li>
+</ul>
+<p>You will find a detailed description of all the associated methods in the Mavibot javadoc.</p>
+<h2 id="values">Values</h2>
+<p>A <em>BTree</em> can stor single value or mmultiple values, associated to a key. The <em>AllowDuplicates</em> flags is set to true if you want to store multiple values associated with one key.</p>
+<p>The default <em>BTree</em> wll only accept single value.</p>
+<h2 id="revisions">Revisions</h2>
+<p>Your <em>BTree</em> can store a new revision for each new modification done on it. Those revisions are kept until no operation are holding them. The <em>BTree</em> operations can all be done using a specific revision number.</p>
+<p>Once the revision is not anymore in use, the associated pages are likely to be reclaimed.</p>
+<h2 id="cache">Cache</h2>
+<p>We don't implement a cache : we depends on Java for that. The <em>BTree</em> is stored in memory, using class instances, and are eventually loaded from disk if they are not present in memory. We use <em>WeakReference</em> to hold all the pages.</p>
+<p>As the <em>Java</em> garbage collector already keep in memory the most frequently used data, it's likely that the important pages - ie, the top of each <em>BTree</em> - will be kept in memory.</p>