| <!DOCTYPE html> |
| <!-- |
| |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You 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. |
| --> |
| <html> |
| <head> |
| <title>Apache BookKeeper - Streaming with BookKeeper</title> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <!-- Bootstrap --> |
| <link href="/archives/css/bootstrap.min.css" rel="stylesheet"> |
| <link href="/archives/css/bootstrap-responsive.min.css" rel="stylesheet"> |
| <link href="/archives/css/styles.css" rel="stylesheet"> |
| </head> |
| <body> |
| <header class="navbar navbar-inverse navbar-static-top" role="banner"> |
| <div class="container"> |
| <div class="navbar-header hidden-xs hidden-sm"> |
| <a class="navbar-brand navbar-logo" href="/archives/"><img class="img-responsive" src="/archives/img/bookkeeper_blk40.png" alt="Bookkeeper Logo" /></a> |
| </div> |
| <div class="navbar-header"> |
| <button class="navbar-toggle collapsed" type="button" data-toggle="collapse" data-target=".bs-navbar-collapse"> |
| <span class="sr-only">Toggle navigation</span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </button> |
| <a class="navbar-brand" href="/archives/">Apache BookKeeper</a> |
| </div> |
| <nav class="collapse navbar-collapse bs-navbar-collapse" role="navigation"> |
| <ul class="nav navbar-nav"> |
| <li><a href="/archives/releases.html">Download</a></li> |
| |
| <li class="dropdown"> |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">Documentation<span class="caret"></span></a> |
| <ul class="dropdown-menu" role="menu"> |
| <li><a href="/archives/docs/master">Latest (master)</a></li> |
| <li><ul> |
| <li><a href="/archives/docs/master/apidocs">Java API docs</a></li> |
| <li><a href="/archives/docs/master/bookkeeperTutorial.html">Tutorial</a></li> |
| <li><a href="/archives/docs/master/bookkeeperConfig.html">Admin guide</a></li> |
| </ul><li> |
| <li><a href="/archives/docs/r4.4.0">Release 4.4.0</a></li> |
| <li class="divider"></li> |
| <li>Older releases</li> |
| <li><a href="/archives/docs/r4.3.2">Release 4.3.2</a></li> |
| <li><a href="/archives/docs/r4.3.1">Release 4.3.1</a></li> |
| <li><a href="/archives/docs/r4.3.0">Release 4.3.0</a></li> |
| <li><a href="/archives/docs/r4.2.4">Release 4.2.4</a></li> |
| <li><a href="/archives/docs/r4.2.3">Release 4.2.3</a></li> |
| <li><a href="/archives/docs/r4.2.2">Release 4.2.2</a></li> |
| <li><a href="/archives/docs/r4.2.1">Release 4.2.1</a></li> |
| <li><a href="/archives/docs/r4.2.0">Release 4.2.0</a></li> |
| <li><a href="/archives/docs/r4.1.0">Release 4.1.0</a></li> |
| <li><a href="/archives/docs/r4.0.0">Release 4.0.0</a></li> |
| </ul> |
| </li> |
| |
| <li class="dropdown"> |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">Get Involved<span class="caret"></span></a> |
| <ul class="dropdown-menu" role="menu"> |
| <li><a href="/archives/lists.html">Mailing Lists</a></li> |
| <li><a href="/archives/irc.html">IRC</a></li> |
| <li><a href="/archives/svn.html">Version Control</a></li> |
| <li><a href="https://issues.apache.org/jira/browse/BOOKKEEPER">Issue Tracker</a></li> |
| </ul> |
| </li> |
| |
| <li><a href="https://cwiki.apache.org/confluence/display/BOOKKEEPER/Index">Wiki</a></li> |
| <!--<li><a href="#">Hedwig</a></li>//--> |
| <li class="dropdown"> |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">Project Info<span class="caret"></span></a> |
| <ul class="dropdown-menu" role="menu"> |
| <li><a href="/archives/credits.html">Who are we?</a></li> |
| <li><a href="/archives/bylaws.html">Bylaws</a></li> |
| <li><a href="http://www.apache.org/licenses/">License</a></li> |
| <li class="divider"></li> |
| <li><a href="/archives/privacy.html">Privacy Policy</a></li> |
| <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsership</a></li> |
| <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li> |
| </ul> |
| </li> |
| </ul> |
| <script> |
| (function() { |
| var cx = '017580107654524087317:iqnsyimpydg'; |
| var gcse = document.createElement('script'); |
| gcse.type = 'text/javascript'; |
| gcse.async = true; |
| gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') + |
| '//www.google.com/cse/cse.js?cx=' + cx; |
| var s = document.getElementsByTagName('script')[0]; |
| s.parentNode.insertBefore(gcse, s); |
| })(); |
| </script> |
| |
| <div class="navbar-form navbar-right visible-lg" id="googlebox"> |
| <gcse:searchbox-only></gcse:searchbox-only> |
| </div> |
| </nav> |
| </div> |
| </header> |
| <div class="container"> |
| |
| <h1>Abstract</h1> |
| |
| <p>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.</p> |
| |
| <h1>Summary</h1> |
| |
| <p>When using the BookKeeper <span class="caps">API, </span>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 <span class="caps">API </span>we have implemented on top of BookKeeper. </p> |
| |
| <p>The stream <span class="caps">API </span>is implemented in the package <code>Streaming</code> , and it contains two main classes: <code>LedgerOutputStream</code> and <code>LedgerInputStream</code> . The class names are indicative of what they do. </p> |
| |
| <h1>Writing a stream of bytes</h1> |
| |
| <p>Class <code>LedgerOutputStream</code> implements two constructors and five public methods: </p> |
| |
| <p> <code>public LedgerOutputStream(LedgerHandle lh) </code> </p> |
| |
| <p>where: </p> |
| |
| <ul> |
| <li> <code>lh</code> is a ledger handle for a previously created and open ledger. </li> |
| </ul> |
| |
| |
| <p> <code>public LedgerOutputStream(LedgerHandle lh, int size) </code> </p> |
| |
| <p>where: </p> |
| |
| <ul> |
| <li> <code>lh</code> is a ledger handle for a previously created and open ledger. </li> |
| <li> <code>size</code> is the size of the byte buffer to store written bytes before flushing. </li> |
| </ul> |
| |
| |
| <p> <em>Closing a stream.</em> This call closes the stream by flushing the write buffer. </p> |
| |
| <p> <code>public void close() </code> </p> |
| |
| <p>which has no parameters. </p> |
| |
| <p> <em>Flushing a stream.</em> This call essentially flushes the write buffer. </p> |
| |
| <p> <code>public synchronized void flush() </code> </p> |
| |
| <p>which has no parameters. </p> |
| |
| <p> <em>Writing bytes.</em> There are three calls for writing bytes to a stream. </p> |
| |
| <p> <code>public synchronized void write(byte[] b) </code> </p> |
| |
| <p>where: </p> |
| |
| <ul> |
| <li> <code>b</code> is an array of bytes to write. </li> |
| </ul> |
| |
| |
| <p> <code>public synchronized void write(byte[] b, int off, int len) </code> </p> |
| |
| <p>where: </p> |
| |
| <ul> |
| <li> <code>b</code> is an array of bytes to write. </li> |
| <li> <code>off</code> is a buffer offset. </li> |
| <li> <code>len</code> is the length to write. </li> |
| </ul> |
| |
| |
| <p> <code>public synchronized void write(int b) </code> </p> |
| |
| <p>where: </p> |
| |
| <ul> |
| <li> <code>b</code> contains a byte to write. The method writes the least significant byte of the integer four bytes. </li> |
| </ul> |
| |
| |
| <h1>Reading a stream of bytes</h1> |
| |
| <p>Class <code>LedgerOutputStream</code> implements two constructors and four public methods: </p> |
| |
| <p> <code>public LedgerInputStream(LedgerHandle lh) throws BKException, InterruptedException </code> </p> |
| |
| <p>where: </p> |
| |
| <ul> |
| <li> <code>lh</code> is a ledger handle for a previously created and open ledger. </li> |
| </ul> |
| |
| |
| <p> <code>public LedgerInputStream(LedgerHandle lh, int size) throws BKException, InterruptedException </code> </p> |
| |
| <p>where: </p> |
| |
| <ul> |
| <li> <code>lh</code> is a ledger handle for a previously created and open ledger. </li> |
| <li> <code>size</code> is the size of the byte buffer to store bytes that the application will eventually read. </li> |
| </ul> |
| |
| |
| <p> <em>Closing.</em> 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. </p> |
| |
| <p> <code>public void close() </code> </p> |
| |
| <p>which has no parameters. </p> |
| |
| <p> <em>Reading.</em> There are three calls to read from the stream. </p> |
| |
| <p> <code>public synchronized int read() throws IOException </code> </p> |
| |
| <p>which has no parameters. </p> |
| |
| <p> <code>public synchronized int read(byte[] b) throws IOException </code> </p> |
| |
| <p>where: </p> |
| |
| <ul> |
| <li> <code>b</code> is a byte array to write to. </li> |
| </ul> |
| |
| |
| <p> <code>public synchronized int read(byte[] b, int off, int len) throws IOException </code> </p> |
| |
| <p>where: </p> |
| |
| <ul> |
| <li> <code>b</code> is a byte array to write to. </li> |
| <li> <code>off</code> is an offset for byte array <code>b</code> . </li> |
| <li> <code>len</code> is the length in bytes to write to <code>b</code> . </li> |
| </ul> |
| |
| </div> |
| <footer class="footer"> |
| <div class="container"> |
| <p class="text-muted">Copyright © 2014 The Apache Software Foundation, Licensed under the Apache License, Version 2.0.<br/> |
| Apache BookKeeper, BookKeeper, Apache, Apache ZooKeeper, ZooKeeper, the Apache feather logo, and the Apache BookKeeper project logo are trademarks of The Apache Software Foundation.</p> |
| </div> |
| </footer> |
| |
| <script src="//code.jquery.com/jquery.js"></script> |
| <script src="/archives/js/bootstrap.min.js"></script> |
| </body> |
| </html> |
