<?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_Stream">
  <title>Streaming with BookKeeper</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 how to stream bytes
      on top of BookKeeper. It essentially motivates and discusses the basic stream 
      operations currently supported.</para>
    </abstract>
  </articleinfo>
	<section id="bk_StreamSummary">
    <title>Summary</title>
    
    <para>
    When using the BookKeeper API, an application has to split the data to write into entries, each
    entry being a byte array. This is natural for many applications. For example, when using BookKeeper
    for write-ahead logging, an application typically wants to write the modifications corresponding
    to a command or a transaction. Some other applications, however, might not have a natural boundary
    for entries, and may prefer to write and read streams of bytes. This is exactly the purpose of the
    stream API we have implemented on top of BookKeeper.
    </para>
    
    <para>
    The stream API is implemented in the package <computeroutput>Streaming</computeroutput>, and it contains two main classes: <computeroutput>LedgerOutputStream</computeroutput> and 
    <computeroutput>LedgerInputStream</computeroutput>. The class names are indicative of what they do.
    </para>
    </section>
    
    <section id="bk_LedgerOutputStream">
    <title>Writing a stream of bytes</title>
    <para>
    Class <computeroutput>LedgerOutputStream</computeroutput> implements two constructors and five public methods:
    </para>
    
    <para>
    <computeroutput>
	public LedgerOutputStream(LedgerHandle lh) 
    </computeroutput>
	</para>

    <para>
    where:
    </para>
    <itemizedlist>
    	<listitem>
    	<para> 
        <computeroutput>lh</computeroutput> is a ledger handle for a previously created and open ledger.  
    	</para>
    	</listitem>
    </itemizedlist>
    
    <para>
    <computeroutput>
	public LedgerOutputStream(LedgerHandle lh, int size) 
    </computeroutput>
	</para>

    <para>
    where:
    </para>
    <itemizedlist>
    	<listitem>
    	<para> 
        <computeroutput>lh</computeroutput> is a ledger handle for a previously created and open ledger.  
    	</para>
    	</listitem>

    	<listitem>
    	<para> 
        <computeroutput>size</computeroutput> is the size of the byte buffer to store written bytes before flushing.  
    	</para>
    	</listitem>
    </itemizedlist>
    
    
    <para>
   	<emphasis role="bold">Closing a stream.</emphasis> This call closes the stream by flushing the write buffer.
   	</para>
    <para>
    <computeroutput>
	public void close() 
    </computeroutput>
	</para>

    <para>
    which has no parameters.
    </para>
    
    <para>
   	<emphasis role="bold">Flushing a stream.</emphasis> This call essentially flushes the write buffer.
   	</para>
    <para>
    <computeroutput>
	public synchronized void flush() 
    </computeroutput>
	</para>
    
    <para>
    which has no parameters.
    </para>
    
    <para>
   	<emphasis role="bold">Writing bytes.</emphasis> There are three calls for writing bytes to a stream.
   	</para>
   	
    <para>
    <computeroutput>
	public synchronized void write(byte[] b) 
    </computeroutput>
	</para>
    
    <para>
    where:
    </para>
    <itemizedlist>
    	<listitem>
    	<para> 
        <computeroutput>b</computeroutput> is an array of bytes to write.  
    	</para>
    	</listitem>
    </itemizedlist>
    
    <para>
    <computeroutput>
	public synchronized void write(byte[] b, int off, int len) 
    </computeroutput>
	</para>
    
    <para>
    where:
    </para>
    <itemizedlist>
    	<listitem>
    	<para> 
        <computeroutput>b</computeroutput> is an array of bytes to write.  
    	</para>
    	</listitem>
    	
    	<listitem>
    	<para> 
        <computeroutput>off</computeroutput> is a buffer offset.  
    	</para>
    	</listitem>
    	
    	<listitem>
    	<para> 
        <computeroutput>len</computeroutput> is the length to write.  
    	</para>
    	</listitem>
    </itemizedlist>
    
        <para>
    <computeroutput>
	public synchronized void write(int b) 
    </computeroutput>
	</para>
    
    <para>
    where:
    </para>
    <itemizedlist>
    	<listitem>
    	<para> 
        <computeroutput>b</computeroutput> contains a byte to write. The method writes the least significant byte of the integer four bytes.    
    	</para>
    	</listitem>
    </itemizedlist>
    </section>
    
    <section id="bk_LedgerInputStream">
    <title>Reading a stream of bytes</title>
    
    <para>
    Class <computeroutput>LedgerOutputStream</computeroutput> implements two constructors and four public methods:
    </para>
    
    <para>
    <computeroutput>
	public LedgerInputStream(LedgerHandle lh)
	throws BKException, InterruptedException 
    </computeroutput>
	</para>

    <para>
    where:
    </para>
    <itemizedlist>
    	<listitem>
    	<para> 
        <computeroutput>lh</computeroutput> is a ledger handle for a previously created and open ledger.  
    	</para>
    	</listitem>
    </itemizedlist>    
    
    <para>
    <computeroutput>
	public LedgerInputStream(LedgerHandle lh, int size) 
    throws BKException, InterruptedException
    </computeroutput>
	</para>

    <para>
    where:
    </para>
    <itemizedlist>
    	<listitem>
    	<para> 
        <computeroutput>lh</computeroutput> is a ledger handle for a previously created and open ledger.  
    	</para>
    	</listitem>

    	<listitem>
    	<para> 
        <computeroutput>size</computeroutput> is the size of the byte buffer to store bytes that the application
        will eventually read.  
    	</para>
    	</listitem>
    </itemizedlist>

    <para>
   	<emphasis role="bold">Closing.</emphasis> There is one call to close an input stream, but the call
   	is currently empty and the application is responsible for closing the ledger handle. 
   	</para>
    <para>
    <computeroutput>
	public void close()
    </computeroutput>
	</para>

    <para>
    which has no parameters.
    </para>
   
    <para>
   	<emphasis role="bold">Reading.</emphasis> There are three calls to read from the stream.
   	</para>
    <para>
    <computeroutput>
	public synchronized int read()
	throws IOException 
    </computeroutput>
	</para>

    <para>
    which has no parameters.
    </para>

    <para>
    <computeroutput>
	public synchronized int read(byte[] b)
	throws IOException 
    </computeroutput>
	</para>

    <para>
    where:
    </para>
        <itemizedlist>
    	<listitem>
    	<para> 
        <computeroutput>b</computeroutput> is a byte array to write to.  
    	</para>
    	</listitem>
    </itemizedlist>
    

    <para>
    <computeroutput>
	public synchronized int read(byte[] b, int off, int len)
	throws IOException 
    </computeroutput>
	</para>

    <para>
    where:
    </para>
    <itemizedlist>
    	<listitem>
    	<para> 
        <computeroutput>b</computeroutput> is a byte array to write to.  
    	</para>
    	</listitem>
    	
    	<listitem>
    	<para> 
        <computeroutput>off</computeroutput> is an offset for byte array <computeroutput>b</computeroutput>.  
    	</para>
    	</listitem>
    	
    	<listitem>
    	<para> 
        <computeroutput>len</computeroutput> is the length in bytes to write to <computeroutput>b</computeroutput>.  
    	</para>
    	</listitem>
    </itemizedlist>

    
    </section>
  </article>