apacheGH-3080: lots of work on the tests.

* changing how stream capabilities are set up and queried,
  makes it easy to generate streams with different declared
  behaviours.
* pull out common assertions
* lots of javadoc of what each test case is trying to do.

+ all the tests are happy.

parquet-hadoop/src/main/java/org/apache/parquet/hadoop/util/H3ByteBufferInputStream.java

@@ -59,19 +59,23 @@ public void readFully(final ByteBuffer buf) throws EOFException, IOException {
 
   /**
    * Read the buffer fully through use of {@code ByteBufferPositionedReadable.readFully()}
-   * at the current location.
+   * from the current location.
+   * That is it reads from stream[pos] to stream[pos + buf.remaining() -1]
    *
    * @param buf a byte buffer to fill with data from the stream
+   * @return number of bytes read.
+   *
    * @throws EOFException the buffer length is greater than the file length
    * @throws IOException other IO problems.
    */
   // Visible for testing
-  static void performRead(final FSDataInputStream stream, final ByteBuffer buf) throws IOException {
+  static int performRead(final FSDataInputStream stream, final ByteBuffer buf) throws IOException {
     // remember the current position
     final long pos = stream.getPos();
     final int size = buf.remaining();
     stream.readFully(pos, buf);
     // then move read position on afterwards.
     stream.seek(pos + size);
+    return size;
   }
 }