Simplify the Page interface by removing methods it shouldn't have

Also add javadocs to the equivalent methods on the PageCursor interface.

community/io/src/main/java/org/neo4j/io/pagecache/Page.java

@@ -30,82 +30,6 @@
  */
 public interface Page
 {
-    /**
-     * Get the signed byte at the given offset into the page.
-     *
-     * May throw an AssertionError or a RuntimeException if the read is out of bounds.
-     */
-    byte getByte( int offset );
-
-    /**
-     * Set the signed byte at the given offset into the page.
-     *
-     * May throw an AssertionError or a RuntimeException if the write is out of bounds.
-     */
-    void putByte( byte value, int offset );
-
-    /**
-     * Fill the given array with bytes by reading from the page, beginning at the given
-     * offset in the page.
-     *
-     * May throw an AssertionError or a RuntimeException if the read is out of bounds.
-     * If an exception is thrown, then the array may have been partially filled with
-     * the requested bytes, if the offset starts within the page.
-     */
-    void getBytes( byte[] data, int offset );
-
-    /**
-     * Write out all the bytes of the given array into the page, beginning at the given
-     * offset in the page.
-     *
-     * May throw an AssertionError or a RuntimeException if the write is out of bounds.
-     * If an exception is thrown, then some of the bytes from the given array may have
-     * been written to the page, if the offset starts within the page.
-     */
-    void putBytes( byte[] data, int offset );
-
-    /**
-     * Get the signed short at the given offset into the page.
-     *
-     * May throw an AssertionError or a RuntimeException if the read is out of bounds.
-     */
-    short getShort( int offset );
-
-    /**
-     * Set the signed short at the given offset into the page.
-     *
-     * May throw an AssertionError or a RuntimeException if the write is out of bounds.
-     */
-    void putShort( short value, int offset );
-
-    /**
-     * Get the signed int at the given offset into the page.
-     *
-     * May throw an AssertionError or a RuntimeException if the read is out of bounds.
-     */
-    int getInt( int offset );
-
-    /**
-     * Set the signed int at the given offset into the page.
-     *
-     * May throw an AssertionError or a RuntimeException if the write is out of bounds.
-     */
-    void putInt( int value, int offset );
-
-    /**
-     * Get the signed long at the given offset into the page.
-     *
-     * May throw an AssertionError or a RuntimeException if the read is out of bounds.
-     */
-    long getLong( int offset );
-
-    /**
-     * Set the signed long at the given offset into the page.
-     *
-     * May throw an AssertionError or a RuntimeException if the write is out of bounds.
-     */
-    void putLong( long value, int offset );
-
     /**
      * Swap a file-page into memory.
      *
@@ -151,9 +75,4 @@ public interface Page
      *                     reopened and the swapIn operation must be retried.
      */
     void swapOut( StoreChannel channel, long offset, int length ) throws IOException;
-
-    /**
-     * Get the internal id of this cache page object.
-     */
-    int getCachePageId();
 }

community/io/src/main/java/org/neo4j/io/pagecache/PageCursor.java

@@ -67,33 +67,187 @@ public interface PageCursor extends AutoCloseable
 {
     long UNBOUND_PAGE_ID = -1;
 
+    /**
+     * Get the signed byte at the current page offset, and then increment the offset by one.
+     *
+     * @throws IndexOutOfBoundsException
+     * if the current offset is not within the page bounds.
+     */
     byte getByte();
+
+    /**
+     * Get the signed byte at the given offset into the page.
+     * Leaves the current page offset unchanged.
+     *
+     * @throws IndexOutOfBoundsException
+     * if the given offset is not within the page bounds.
+     */
     byte getByte( int offset );
+
+    /**
+     * Set the signed byte at the current offset into the page, and then increment the offset by one.
+     *
+     * @throws IndexOutOfBoundsException
+     * if the current offset is not within the page bounds.
+     */
     void putByte( byte value );
+
+    /**
+     * Set the signed byte at the given offset into the page.
+     * Leaves the current page offset unchanged.
+     *
+     * @throws IndexOutOfBoundsException
+     * if the given offset is not within the page bounds.
+     */
     void putByte( int offset, byte value );
 
+    /**
+     * Get the signed long at the current page offset, and then increment the offset by one.
+     *
+     * @throws IndexOutOfBoundsException
+     * if the current offset is not within the page bounds.
+     */
     long getLong();
+
+    /**
+     * Get the signed long at the given offset into the page.
+     * Leaves the current page offset unchanged.
+     *
+     * @throws IndexOutOfBoundsException
+     * if the given offset is not within the page bounds.
+     */
     long getLong( int offset );
+
+    /**
+     * Set the signed long at the current offset into the page, and then increment the offset by one.
+     *
+     * @throws IndexOutOfBoundsException
+     * if the current offset is not within the page bounds.
+     */
     void putLong( long value );
+
+    /**
+     * Set the signed long at the given offset into the page.
+     * Leaves the current page offset unchanged.
+     *
+     * @throws IndexOutOfBoundsException
+     * if the given offset is not within the page bounds.
+     */
     void putLong( int offset, long value );
 
+    /**
+     * Get the signed int at the current page offset, and then increment the offset by one.
+     *
+     * @throws IndexOutOfBoundsException
+     * if the current offset is not within the page bounds.
+     */
     int getInt();
+
+    /**
+     * Get the signed int at the given offset into the page.
+     * Leaves the current page offset unchanged.
+     *
+     * @throws IndexOutOfBoundsException
+     * if the given offset is not within the page bounds.
+     */
     int getInt( int offset );
+
+    /**
+     * Set the signed int at the current offset into the page, and then increment the offset by one.
+     *
+     * @throws IndexOutOfBoundsException
+     * if the current offset is not within the page bounds.
+     */
     void putInt( int value );
+
+    /**
+     * Set the signed int at the given offset into the page.
+     * Leaves the current page offset unchanged.
+     *
+     * @throws IndexOutOfBoundsException
+     * if the given offset is not within the page bounds.
+     */
     void putInt( int offset, int value );
 
+    /**
+     * Get the unsigned int at the current page offset, and then increment the offset by one.
+     *
+     * @throws IndexOutOfBoundsException
+     * if the current offset is not within the page bounds.
+     */
     long getUnsignedInt();
+
+    /**
+     * Get the unsigned int at the given offset into the page.
+     * Leaves the current page offset unchanged.
+     *
+     * @throws IndexOutOfBoundsException
+     * if the given offset is not within the page bounds.
+     */
     long getUnsignedInt( int offset );
 
+    /**
+     * Fill the given array with bytes from the page, beginning at the current offset into the page,
+     * and then increment the current offset by the length of the array.
+     *
+     * @throws IndexOutOfBoundsException
+     * if the current offset plus the length of the array reaches beyond the end of the page.
+     */
     void getBytes( byte[] data );
+
+    /**
+     * Write out all the bytes of the given array into the page, beginning at the current offset into the page,
+     * and then increment the current offset by the length of the array.
+     *
+     * @throws IndexOutOfBoundsException
+     * if the current offset plus the length of the array reaches beyond the end of the page.
+     */
     void putBytes( byte[] data );
 
+    /**
+     * Get the signed short at the current page offset, and then increment the offset by one.
+     *
+     * @throws IndexOutOfBoundsException
+     * if the current offset is not within the page bounds.
+     */
     short getShort();
+
+    /**
+     * Get the signed short at the given offset into the page.
+     * Leaves the current page offset unchanged.
+     *
+     * @throws IndexOutOfBoundsException
+     * if the given offset is not within the page bounds.
+     */
     short getShort( int offset );
+
+    /**
+     * Set the signed short at the current offset into the page, and then increment the offset by one.
+     *
+     * @throws IndexOutOfBoundsException
+     * if the current offset is not within the page bounds.
+     */
     void putShort( short value );
+
+    /**
+     * Set the signed short at the given offset into the page.
+     * Leaves the current page offset unchanged.
+     *
+     * @throws IndexOutOfBoundsException
+     * if the given offset is not within the page bounds.
+     */
     void putShort( int offset, short value );
 
+    /**
+     * Set the current offset into the page, for interacting with the page through the read and write methods that do
+     * not take a specific offset as an argument.
+     */
     void setOffset( int offset );
+
+    /**
+     * Get the current offset into the page, which is the location on the page where the next interaction would take
+     * place through the read and write methods that do not take a specific offset as an argument.
+     */
     int getOffset();
 
     /**

community/io/src/main/java/org/neo4j/io/pagecache/impl/muninn/MuninnPage.java

@@ -79,7 +79,6 @@ private void checkBounds( int position )
         }
     }
 
-    @Override
     public int getCachePageId()
     {
         return System.identityHashCode( this );
@@ -277,7 +276,6 @@ private void putShortBigEndian( short value, int offset )
         UnsafeUtil.putByte( p + 1, (byte)( value      ) );
     }
 
-    @Override
     public void getBytes( byte[] data, int offset )
     {
         checkBounds( offset + data.length );
@@ -290,7 +288,6 @@ public void getBytes( byte[] data, int offset )
         }
     }
 
-    @Override
     public void putBytes( byte[] data, int offset )
     {
         checkBounds( offset + data.length );

community/io/src/main/java/org/neo4j/io/pagecache/tracing/DefaultPageCacheTracer.java

@@ -202,7 +202,7 @@ public void setParked( boolean parked )
         }
     };
 
-    private final PinEvent pinEvent = new PinEvent()
+    private final PinEvent pinTracingEvent = new PinEvent()
     {
         @Override
         public void setCachePageId( int cachePageId )
@@ -222,6 +222,25 @@ public void done()
         }
     };
 
+    private final PinEvent nullPinEvent = new PinEvent()
+    {
+        @Override
+        public void setCachePageId( int cachePageId )
+        {
+        }
+
+        @Override
+        public PageFaultEvent beginPageFault()
+        {
+            return pageFaultEvent;
+        }
+
+        @Override
+        public void done()
+        {
+        }
+    };
+
     private final MajorFlushEvent majorFlushEvent = new MajorFlushEvent()
     {
         @Override
@@ -273,7 +292,7 @@ public PinEvent beginPin( boolean exclusiveLock, long filePageId, PageSwapper sw
     @SuppressWarnings( "UnusedDeclaration" )
     private PinEvent beginNullPin()
     {
-        return PinEvent.NULL;
+        return nullPinEvent;
     }
 
     /**
@@ -283,7 +302,7 @@ private PinEvent beginNullPin()
     private PinEvent beginTracingPin()
     {
         pins.getAndIncrement();
-        return pinEvent;
+        return pinTracingEvent;
     }
 
     @Override

community/io/src/test/java/org/neo4j/io/pagecache/PageSwappingTest.java

@@ -101,6 +101,14 @@ public PageSwappingTest( Factory<PageSwapperFactory> fixture )
 
     protected abstract void unlockWrite( Page page, long stamp );
 
+    protected abstract long getLong( Page page, int offset );
+
+    protected abstract int getInt( Page page, int offset );
+
+    protected abstract void putLong( Page page, long value, int offset );
+
+    protected abstract void putInt( Page page, int value, int offset );
+
     @Before
     @After
     public void clearStrayInterrupts()
@@ -179,9 +187,9 @@ public void mustReopenChannelWhenReadFailsWithAsynchronousCloseException() throw
         // Clear the interrupted flag and assert that it was still raised
         assertTrue( Thread.interrupted() );
 
-        assertThat( page.getLong( 0 ), is( x ) );
-        assertThat( page.getLong( 8 ), is( y ) );
-        assertThat( page.getInt( 16 ), is( z ) );
+        assertThat( getLong( page, 0 ), is( x ) );
+        assertThat( getLong( page, 8 ), is( y ) );
+        assertThat( getInt( page, 16 ), is( z ) );
 
         // This must not throw because we should still have a usable channel
         swapper.force();
@@ -195,9 +203,9 @@ public void mustReopenChannelWhenWriteFailsWithAsynchronousCloseException() thro
         int z = ThreadLocalRandom.current().nextInt();
 
         Page page = createPage( cachePageSize );
-        page.putLong( x, 0 );
-        page.putLong( y, 8 );
-        page.putInt( z, 16 );
+        putLong( page, x, 0 );
+        putLong( page, y, 8 );
+        putInt( page, z, 16 );
         File file = new File( "a" );
         fs.create( file ).close();