<?xml version="1.0" encoding="UTF-8"?>
<!--
  Copyright 2002-2004 The Apache Software Foundation

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->

<!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.0//EN"
"http://www.oasis-open.org/docbook/xml/simple/1.0/sdocbook.dtd">
<article id="bk_GettStartedGuide">
  <title>BookKeeper Getting Started Guide</title>

  <articleinfo>
    <legalnotice>
      <para>Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License. You may
      obtain a copy of the License at <ulink
      url="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</ulink>.</para>

      <para>Unless required by applicable law or agreed to in writing,
      software distributed under the License is distributed on an "AS IS"
      BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied. See the License for the specific language governing permissions
      and limitations under the License.</para>
    </legalnotice>

    <abstract>
      <para>This guide contains detailed information about using BookKeeper
      for logging. It discusses the basic operations BookKeeper supports, 
      and how to create logs and perform basic read and write operations on these
      logs.</para>
    </abstract>
  </articleinfo>
  <section id="bk_GettingStarted">
    <title>Programming with BookKeeper</title>
    
    <itemizedlist>
      <listitem>
        <para><xref linkend="bk_instance" /></para>
      </listitem>

      <listitem>
        <para><xref linkend="bk_createLedger" /></para>
      </listitem>

      <listitem>
        <para><xref linkend="bk_writeLedger" /></para>
      </listitem>

      <listitem>
        <para><xref linkend="bk_closeLedger" /></para>
      </listitem>
      
	  <listitem>
        <para><xref linkend="bk_openLedger" /></para>
      </listitem>
      
      <listitem>
        <para><xref linkend="bk_readLedger" /></para>
      </listitem>
      
      <listitem>
        <para><xref linkend="bk_deleteLedger" /></para>
      </listitem>
      
    </itemizedlist>
    
    <section id="bk_instance">
    <title> Instantiating BookKeeper.</title>
    <para>
    The first step to use BookKeeper is to instantiate a BookKeeper object:
    </para>
    <para>
    <computeroutput>
    org.apache.bookkeeper.BookKeeper
    </computeroutput>
    </para>
    
    <para>
    There are three BookKeeper constructors:
    </para>
    
    <para>
    <computeroutput>
	public BookKeeper(String servers) 
    	throws KeeperException, IOException    
    </computeroutput>
	</para>

    <para>
    where:
    </para>
    <itemizedlist>
    	<listitem>
    	<para> 
        <computeroutput>servers</computeroutput> is a comma-separated list of ZooKeeper servers.
    	</para>
    	</listitem>
    </itemizedlist>

    <para>
    <computeroutput>
	public BookKeeper(ZooKeeper zk) 
    	throws InterruptedException, KeeperException    
    </computeroutput>
	</para>

    <para>
    where:
    </para>
    <itemizedlist>
    	<listitem>
    	<para> 
        <computeroutput>zk</computeroutput> is a ZooKeeper object. This constructor is useful when
        the application also using ZooKeeper and wants to have a single instance of ZooKeeper.  
    	</para>
    	</listitem>
    </itemizedlist>


    <para>
    <computeroutput>
	public BookKeeper(ZooKeeper zk, ClientSocketChannelFactory channelFactory) 
    	throws InterruptedException, KeeperException    
    </computeroutput>
	</para>

    <para>
    where:
    </para>
    <itemizedlist>
    	<listitem>
    	<para> 
        <computeroutput>zk</computeroutput> is a ZooKeeper object. This constructor is useful when
        the application also using ZooKeeper and wants to have a single instance of ZooKeeper.  
    	</para>
    	</listitem>
    	
    	<listitem>
    	<para> 
        <computeroutput>channelFactory</computeroutput> is a netty channel object 
        (<computeroutput>org.jboss.netty.channel.socket</computeroutput>).  
    	</para>
    	</listitem>
    </itemizedlist>


        
    </section>
    
    <section id="bk_createLedger">
    <title> Creating a ledger. </title>
    
    <para> Before writing entries to BookKeeper, it is necessary to create a ledger. 
    With the current BookKeeper API, it is possible to create a ledger both synchronously
    or asynchronously. The following methods belong
    to <computeroutput>org.apache.bookkeeper.client.BookKeeper</computeroutput>.
    </para>
    
    <para>
   	<emphasis role="bold">Synchronous call:</emphasis>
   	</para>
   	
   	<para>
    <computeroutput>
    public LedgerHandle createLedger(int ensSize, int qSize, DigestType type,  byte passwd[])
        throws KeeperException, InterruptedException, 
        IOException, BKException
    </computeroutput>
	</para>

    <para>
    where:
    </para>
    <itemizedlist>
    	<listitem>
    	<para> 
    	<computeroutput>ensSize</computeroutput> is the number of bookies (ensemble size);
    	</para>
    	</listitem>
    
    	<listitem> 
    	<para>
    	<computeroutput>qSize</computeroutput> is the write quorum size;
    	</para>
    	</listitem>
    
    	<listitem> 
    	<para>
    	<computeroutput>type</computeroutput> is the type of digest used with entries: either MAC or CRC32.  
    	</para>
    	</listitem>
    	
    	<listitem>
    	<para>
    	<computeroutput>passwd</computeroutput> is a password that authorizes the client to write to the
    	ledger being created.
    	</para>
    	</listitem>
    </itemizedlist>
    
    <para>
    All further operations on a ledger are invoked through the <computeroutput>LedgerHandle</computeroutput>
    object returned.
    </para>
    
    <para>
    As a convenience, we provide a <computeroutput>createLedger</computeroutput> with default parameters (3,2,VERIFIABLE), 
    and the only two input parameters it requires are a digest type and a password.
    </para>
    
    <para>
   	<emphasis role="bold">Asynchronous call:</emphasis>
   	</para>
    
    <para>
    <computeroutput>
    public void asyncCreateLedger(int ensSize, 
            int qSize, 
            DigestType type,  
            byte passwd[],
            CreateCallback cb,
            Object ctx
            )
    </computeroutput>
	</para>
	
    <para>
	The parameters are the same of the synchronous version, with the
	exception of <computeroutput>cb</computeroutput> and <computeroutput>ctx</computeroutput>. <computeroutput>CreateCallback</computeroutput>
	is an interface in <computeroutput>org.apache.bookkeeper.client.AsyncCallback</computeroutput>, and
	a class implementing it has to implement a method called <computeroutput>createComplete</computeroutput>
	that has the following signature: 
    </para>

	<para>
	<computeroutput>
	void createComplete(int rc, LedgerHandle lh, Object ctx);
	</computeroutput>    
	</para>
	
	<para>
	where:
	</para>
	<itemizedlist>
		<listitem>
		<para>
		<computeroutput>rc</computeroutput> is a return code (please refer to <computeroutput>org.apache.bookeeper.client.BKException</computeroutput> for a list);
		</para>
		</listitem>
	
		<listitem>
		<para>
		<computeroutput>lh</computeroutput> is a <computeroutput>LedgerHandle</computeroutput> object to manipulate a ledger;
		</para>
		</listitem>
		
		<listitem>
		<para>
		<computeroutput>ctx</computeroutput> is a control object for accountability purposes. It can be essentially any object the application is happy with.
		</para>
		</listitem>
	</itemizedlist>	
	
	<para>
	The <computeroutput>ctx</computeroutput> object passed as a parameter to the call to create a ledger
	is the one same returned in the callback.
    </para>
    </section>
    
    <section id="bk_writeLedger">
    <title> Adding entries to a ledger. </title>
    <para>
    Once we have a ledger handle <computeroutput>lh</computeroutput> obtained through a call to create a ledger, we
    can start writing entries. As with creating ledgers, we can write both synchronously and 
    asynchronously. The following methods belong
    to <computeroutput>org.apache.bookkeeper.client.LedgerHandle</computeroutput>.
    </para>
    
    <para>
   	<emphasis role="bold">Synchronous call:</emphasis>
   	</para>
   	
   	<para>
    <computeroutput>
	public long addEntry(byte[] data)
    	throws InterruptedException
    </computeroutput>
	</para>

    <para>
    where:
    </para>
    
    <itemizedlist>
    	<listitem>
    	<para> 
    	<computeroutput>data</computeroutput> is a byte array;
    	</para>
    	</listitem>
    </itemizedlist>
    
    <para>
	A call to <computeroutput>addEntry</computeroutput> returns the status of the operation (please refer to <computeroutput>org.apache.bookeeper.client.BKDefs</computeroutput> for a list);
    </para>
    
    <para>
   	<emphasis role="bold">Asynchronous call:</emphasis>
   	</para>

	<para>
    <computeroutput>
	public void asyncAddEntry(byte[] data, AddCallback cb, Object ctx)
    </computeroutput>
	</para>
	
    <para>
    It also takes a byte array as the sequence of bytes to be stored as an entry. Additionaly, it takes
    a callback object <computeroutput>cb</computeroutput> and a control object <computeroutput>ctx</computeroutput>. The callback object must implement
    the <computeroutput>AddCallback</computeroutput> interface in <computeroutput>org.apache.bookkeeper.client.AsyncCallback</computeroutput>, and
	a class implementing it has to implement a method called <computeroutput>addComplete</computeroutput>
	that has the following signature: 
    </para>

	<para>
	<computeroutput>
	void addComplete(int rc, LedgerHandle lh, long entryId, Object ctx);
	</computeroutput>    
	</para>
	
	<para>
	where:
	</para>
	<itemizedlist>
		<listitem>
		<para>
		<computeroutput>rc</computeroutput> is a return code (please refer to <computeroutput>org.apache.bookeeper.client.BKDefs</computeroutput> for a list);
		</para>
		</listitem>
	
		<listitem>
		<para>
		<computeroutput>lh</computeroutput> is a <computeroutput>LedgerHandle</computeroutput> object to manipulate a ledger;
		</para>
		</listitem>
		
		<listitem>
		<para>
		<computeroutput>entryId</computeroutput> is the identifier of entry associated with this request;
		</para>
		</listitem>
		
		<listitem>
		<para>
		<computeroutput>ctx</computeroutput> is control object used for accountability purposes. It can be any object the application is happy with.
		</para>
		</listitem>
	</itemizedlist>	 
    </section>
    
    <section id="bk_closeLedger">
    <title> Closing a ledger. </title>
    <para>
    Once a client is done writing, it closes the ledger. The following methods belong
    to <computeroutput>org.apache.bookkeeper.client.LedgerHandle</computeroutput>.
    </para>
    <para>
   	<emphasis role="bold">Synchronous close:</emphasis>
   	</para>
    
    <para>
    <computeroutput>
	public void close() 
    throws InterruptedException
    </computeroutput>
	</para>

    <para>
    It takes no input parameters.
    </para>
    
    <para>
   	<emphasis role="bold">Asynchronous close:</emphasis>
   	</para>
    <para>
    <computeroutput>
	public void asyncClose(CloseCallback cb, Object ctx)
    throws InterruptedException
    </computeroutput>
	</para>
	
    <para>
    It takes a callback object <computeroutput>cb</computeroutput> and a control object <computeroutput>ctx</computeroutput>. The callback object must implement
    the <computeroutput>CloseCallback</computeroutput> interface in <computeroutput>org.apache.bookkeeper.client.AsyncCallback</computeroutput>, and
	a class implementing it has to implement a method called <computeroutput>closeComplete</computeroutput>
	that has the following signature: 
    </para>

	<para>
	<computeroutput>
	void closeComplete(int rc, LedgerHandle lh, Object ctx)
	</computeroutput>    
	</para>
	
	<para>
	where:
	</para>
	<itemizedlist>
		<listitem>
		<para>
		<computeroutput>rc</computeroutput> is a return code (please refer to <computeroutput>org.apache.bookeeper.client.BKDefs</computeroutput> for a list);
		</para>
		</listitem>
	
		<listitem>
		<para>
		<computeroutput>lh</computeroutput> is a <computeroutput>LedgerHandle</computeroutput> object to manipulate a ledger;
		</para>
		</listitem>
		
		<listitem>
		<para>
		<computeroutput>ctx</computeroutput> is control object used for accountability purposes. 
		</para>
		</listitem>
	</itemizedlist>	
    
    </section>
    
    <section id="bk_openLedger">
    <title> Opening a ledger. </title>
    <para>
    To read from a ledger, a client must open it first. The following methods belong
    to <computeroutput>org.apache.bookkeeper.client.BookKeeper</computeroutput>.
    </para>
    
    <para>
   	<emphasis role="bold">Synchronous open:</emphasis>
   	</para>
    
    <para>
    <computeroutput>
	public LedgerHandle openLedger(long lId, DigestType type, byte passwd[])
    throws InterruptedException, BKException
    </computeroutput>
	</para>

	<itemizedlist>
	<listitem>
	<para>
	<computeroutput>ledgerId</computeroutput> is the ledger identifier;
	</para>
	</listitem>
	
	<listitem> 
    <para>
    <computeroutput>type</computeroutput> is the type of digest used with entries: either MAC or CRC32.  
    </para>
    </listitem>
	
	<listitem>
	<para>
	<computeroutput>passwd</computeroutput> is a password to access the ledger (used only in the case of <computeroutput>VERIFIABLE</computeroutput> ledgers);
	</para>
	</listitem>
	</itemizedlist>
    
    <para>
   	<emphasis role="bold">Asynchronous open:</emphasis>
   	</para>
    <para>
    <computeroutput>
	public void asyncOpenLedger(long lId, DigestType type, byte passwd[], OpenCallback cb, Object ctx)
    </computeroutput>
	</para>
	
    <para>
    It also takes a a ledger identifier and a password. Additionaly, it takes a callback object 
    <computeroutput>cb</computeroutput> and a control object <computeroutput>ctx</computeroutput>. The callback object must implement
    the <computeroutput>OpenCallback</computeroutput> interface in <computeroutput>org.apache.bookkeeper.client.AsyncCallback</computeroutput>, and
	a class implementing it has to implement a method called <computeroutput>openComplete</computeroutput>
	that has the following signature: 
    </para>

	<para>
	<computeroutput>
	public void openComplete(int rc, LedgerHandle lh, Object ctx)
	</computeroutput>    
	</para>
	
	<para>
	where:
	</para>
	<itemizedlist>
		<listitem>
		<para>
		<computeroutput>rc</computeroutput> is a return code (please refer to <computeroutput>org.apache.bookeeper.client.BKDefs</computeroutput> for a list);
		</para>
		</listitem>
	
		<listitem>
		<para>
		<computeroutput>lh</computeroutput> is a <computeroutput>LedgerHandle</computeroutput> object to manipulate a ledger;
		</para>
		</listitem>
		
		<listitem>
		<para>
		<computeroutput>ctx</computeroutput> is control object used for accountability purposes. 
		</para>
		</listitem>
	</itemizedlist>	
    </section>
    
    <section id="bk_readLedger">
    <title> Reading from ledger </title>
    <para>
    Read calls may request one or more consecutive entries. The following methods belong
    to <computeroutput>org.apache.bookkeeper.client.LedgerHandle</computeroutput>.
    </para>
    
    <para>
   	<emphasis role="bold">Synchronous read:</emphasis>
   	</para>
    
    <para>
    <computeroutput>
	public Enumeration&lt;LedgerEntry&gt; readEntries(long firstEntry, long lastEntry) 
    throws InterruptedException, BKException
    </computeroutput>
	</para>

	<itemizedlist>
	<listitem>
	<para>
	<computeroutput>firstEntry</computeroutput> is the identifier of the first entry in the sequence of entries to read;
	</para>
	</listitem>
	
	<listitem>
	<para>
	<computeroutput>lastEntry</computeroutput> is the identifier of the last entry in the sequence of entries to read.
	</para>
	</listitem>
	</itemizedlist>
    
    <para>
   	<emphasis role="bold">Asynchronous read:</emphasis>
   	</para>
    <para>
    <computeroutput>
	public void asyncReadEntries(long firstEntry, 
            long lastEntry, ReadCallback cb, Object ctx)
    throws BKException, InterruptedException
    </computeroutput>
	</para>
	
    <para>
    It also takes a first and a last entry identifiers. Additionaly, it takes a callback object 
    <computeroutput>cb</computeroutput> and a control object <computeroutput>ctx</computeroutput>. The callback object must implement
    the <computeroutput>ReadCallback</computeroutput> interface in <computeroutput>org.apache.bookkeeper.client.AsyncCallback</computeroutput>, and
	a class implementing it has to implement a method called <computeroutput>readComplete</computeroutput>
	that has the following signature: 
    </para>

	<para>
	<computeroutput>
	void readComplete(int rc, LedgerHandle lh, Enumeration&lt;LedgerEntry&gt; seq, Object ctx)
	</computeroutput>    
	</para>
	
	<para>
	where:
	</para>
	<itemizedlist>
		<listitem>
		<para>
		<computeroutput>rc</computeroutput> is a return code (please refer to <computeroutput>org.apache.bookeeper.client.BKDefs</computeroutput> for a list);
		</para>
		</listitem>
	
		<listitem>
		<para>
		<computeroutput>lh</computeroutput> is a <computeroutput>LedgerHandle</computeroutput> object to manipulate a ledger;
		</para>
		</listitem>
		
		<listitem>
		<para>
		<computeroutput>seq</computeroutput> is a <computeroutput>Enumeration&lt;LedgerEntry&gt; </computeroutput> object to containing the list of entries requested;
		</para>
		</listitem>

		<listitem>
		<para>
		<computeroutput>ctx</computeroutput> is control object used for accountability purposes. 
		</para>
		</listitem>
	</itemizedlist>	
    </section>

    <section id="bk_deleteLedger">
    <title> Deleting a ledger </title>
    <para>
    Once a client is done with a ledger and is sure that nobody will ever need to read from it again, they can delete the ledger.
    The following methods belong to <computeroutput>org.apache.bookkeeper.client.BookKeeper</computeroutput>.
    </para>
    
    <para>
   	<emphasis role="bold">Synchronous delete:</emphasis>
   	</para>
    
    <para>
    <computeroutput>
        public void deleteLedger(long lId) throws InterruptedException, BKException
    </computeroutput>
    </para>

	<itemizedlist>
	<listitem>
	<para>
	<computeroutput>lId</computeroutput> is the ledger identifier;
	</para>
	</listitem>
	</itemizedlist>
    
    <para>
   	<emphasis role="bold">Asynchronous delete:</emphasis>
    </para>
    <para>
      <computeroutput>
	 public void asyncDeleteLedger(long lId, DeleteCallback cb, Object ctx) 
      </computeroutput>
    </para>
	
    <para>
    It takes a ledger identifier. Additionally, it takes a callback object 
    <computeroutput>cb</computeroutput> and a control object <computeroutput>ctx</computeroutput>. The callback object must implement
    the <computeroutput>DeleteCallback</computeroutput> interface in <computeroutput>org.apache.bookkeeper.client.AsyncCallback</computeroutput>, and
	a class implementing it has to implement a method called <computeroutput>deleteComplete</computeroutput>
	that has the following signature: 
    </para>

	<para>
	<computeroutput>
	void deleteComplete(int rc, Object ctx)
	</computeroutput>    
	</para>
	
	<para>
	where:
	</para>
	<itemizedlist>
		<listitem>
		<para>
		<computeroutput>rc</computeroutput> is a return code (please refer to <computeroutput>org.apache.bookeeper.client.BKDefs</computeroutput> for a list);
		</para>
		</listitem>
	
		<listitem>
		<para>
		<computeroutput>ctx</computeroutput> is control object used for accountability purposes. 
		</para>
		</listitem>
	</itemizedlist>	
    </section>
   </section>
</article>