Title:        Streaming with BookKeeper
Notice: 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":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.
        .

h1. Abstract

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.

h1. Summary

p. 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. 

p. The stream API is implemented in the package @Streaming@ , and it contains two main classes: @LedgerOutputStream@ and  @LedgerInputStream@ . The class names are indicative of what they do. 

h1. Writing a stream of bytes

p. Class @LedgerOutputStream@ implements two constructors and five public methods: 

 @public LedgerOutputStream(LedgerHandle lh) @ 

p. where: 

*  @lh@ is a ledger handle for a previously created and open ledger. 


 @public LedgerOutputStream(LedgerHandle lh, int size) @ 

p. where: 

*  @lh@ is a ledger handle for a previously created and open ledger. 
*  @size@ is the size of the byte buffer to store written bytes before flushing. 


 _Closing a stream._ This call closes the stream by flushing the write buffer. 

 @public void close() @ 

p. which has no parameters. 

 _Flushing a stream._ This call essentially flushes the write buffer. 

 @public synchronized void flush() @ 

p. which has no parameters. 

 _Writing bytes._ There are three calls for writing bytes to a stream. 

 @public synchronized void write(byte[] b) @ 

p. where: 

*  @b@ is an array of bytes to write. 


 @public synchronized void write(byte[] b, int off, int len) @ 

p. where: 

*  @b@ is an array of bytes to write. 
*  @off@ is a buffer offset. 
*  @len@ is the length to write. 


 @public synchronized void write(int b) @ 

p. where: 

*  @b@ contains a byte to write. The method writes the least significant byte of the integer four bytes. 


h1. Reading a stream of bytes

p. Class @LedgerOutputStream@ implements two constructors and four public methods: 

 @public LedgerInputStream(LedgerHandle lh) throws BKException, InterruptedException @ 

p. where: 

*  @lh@ is a ledger handle for a previously created and open ledger. 


 @public LedgerInputStream(LedgerHandle lh, int size) throws BKException, InterruptedException @ 

p. where: 

*  @lh@ is a ledger handle for a previously created and open ledger. 
*  @size@ is the size of the byte buffer to store bytes that the application will eventually read. 


 _Closing._ 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. 

 @public void close() @ 

p. which has no parameters. 

 _Reading._ There are three calls to read from the stream. 

 @public synchronized int read() throws IOException @ 

p. which has no parameters. 

 @public synchronized int read(byte[] b) throws IOException @ 

p. where: 

*  @b@ is a byte array to write to. 


 @public synchronized int read(byte[] b, int off, int len) throws IOException @ 

p. where: 

*  @b@ is a byte array to write to. 
*  @off@ is an offset for byte array @b@ . 
*  @len@ is the length in bytes to write to @b@ .