src/docs/src/documentation/content/xdocs/bookkeeperProgrammer.xml - zookeeper - Git at Google

 <?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>
	<?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<LedgerEntry> 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<LedgerEntry> 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<LedgerEntry> </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>