[Gzz-commits] storm/org/nongnu/storm Block.java

[Benja Fallenstein]

CVSROOT:        /cvsroot/storm
Module name:    storm
Changes by:     Benja Fallenstein <address@hidden>      03/04/15 03:22:02

Modified files:
        org/nongnu/storm: Block.java 

Log message:
        doc

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/storm/storm/org/nongnu/storm/Block.java.diff?tr1=1.3&tr2=1.4&r1=text&r2=text

Patches:
Index: storm/org/nongnu/storm/Block.java
diff -u storm/org/nongnu/storm/Block.java:1.3 
storm/org/nongnu/storm/Block.java:1.4
--- storm/org/nongnu/storm/Block.java:1.3       Mon Apr  7 15:35:58 2003
+++ storm/org/nongnu/storm/Block.java   Tue Apr 15 03:22:02 2003
@@ -43,6 +43,31 @@
      */
     StormPool getPool();
 
-    /** Get an input stream for reading the body of this block. */
+    /** Get an input stream for reading the body of this block. 
+     *  The data is <em>not</em> guaranteed to be verified against
+     *  the id of this block before you start reading it, i.e. 
+     *  what you read may be spoofed, incorrect data. This is for 
+     *  efficiency: the data may be checked <em>while you read it</em>.
+     *  If the data is spoofed, a <code>BlockId.WrongIdException</code>
+     *  will be thrown when you call <code>close()</code>
+     *  on the <code>InputStream</code> (that's a subclass of
+     *  <code>IOException</code>). Therefore, <strong>do not forget
+     *  to call <code>close()</code></strong> before you act on
+     *  the data returned by this <code>InputStream</code>!
+     *  <p>
+     *  Generally there will be no network delays when reading
+     *  from the input stream, i.e. if the data is retrieved
+     *  from the network, this method will generally read from
+     *  a local cache. However, there may be network delays
+     *  if explicitly specified by a pool's documentation.
+     *  <p>
+     *  As usual, you have to be prepared for <code>IOException</code>s
+     *  while reading from the stream.
+     *  @return An input stream for reading the body of this block.
+     *          Will not return <code>null</code>.
+     *  @throws IOException if an error occurs while opening the
+     *          input stream; for example, if the block was in
+     *          a cache but has been pruned since.
+     */
     InputStream getInputStream() throws IOException;
 }