Introduce protocol documentation

- Also resolve minor bugs found while testing docs
- Binary examples of all primitive values, handshake and chunking
- Examples section with human-readable and binary representations of
  common scenarios

community/kernel/src/main/java/org/neo4j/kernel/impl/store/DumpStore.java

@@ -294,6 +294,7 @@ private boolean dumpRecord( STORE store, int size, StoreChannel fileChannel, Byt
             out.print( record );
             buffer.clear();
             fileChannel.read( buffer, id * size );
+            buffer.flip();
             dumpHex( record, buffer, id, size );
         }
 
@@ -320,7 +321,7 @@ else if ( allZero( buffer ) )
 
     private boolean allZero( ByteBuffer buffer )
     {
-        for ( int i = 0; i < buffer.position(); i++ )
+        for ( int i = 0; i < buffer.limit(); i++ )
         {
             if ( buffer.get( i ) != 0 )
             {

community/kernel/src/main/java/org/neo4j/kernel/impl/util/HexPrinter.java

@@ -214,14 +214,14 @@ public HexPrinter append( ByteBuffer bytes, int offset, int length )
     }
 
     /**
-     * Append the bytes in the byte buffer, starting from position 0, ending at the buffer's current position,
-     * into print stream
+     * Append the bytes in the byte buffer, from its current position to its limit into print stream. This operation
+     * will not move the buffers current position.
      * @param bytes
      * @return
      */
     public HexPrinter append( ByteBuffer bytes )
     {
-        return append( bytes, 0, bytes.position() );
+        return append( bytes, bytes.position(), bytes.remaining() );
     }
 
     /**
@@ -307,7 +307,7 @@ public static String hex( ByteBuffer bytes, int offset, int length )
      */
     public static String hex( ByteBuffer bytes )
     {
-        return hex( bytes, 0, bytes.position() );
+        return hex( bytes, bytes.position(), bytes.limit() );
     }
 
     /**

community/kernel/src/test/java/org/neo4j/kernel/impl/store/DumpStoreTest.java

@@ -19,12 +19,12 @@
  */
 package org.neo4j.kernel.impl.store;
 
+import org.junit.Test;
+
 import java.io.ByteArrayOutputStream;
 import java.io.PrintStream;
 import java.nio.ByteBuffer;
 
-import org.junit.Test;
-
 import org.neo4j.kernel.impl.store.record.AbstractBaseRecord;
 
 import static org.junit.Assert.assertEquals;
@@ -44,6 +44,8 @@ public void dumpStoreShouldPrintBufferWithContent() throws Exception
         {
             buffer.put( i );
         }
+        buffer.flip();
+
         AbstractBaseRecord record = mock( AbstractBaseRecord.class );
 
         // When

community/kernel/src/test/java/org/neo4j/kernel/impl/util/HexPrinterTest.java

@@ -19,14 +19,13 @@
  */
 package org.neo4j.kernel.impl.util;
 
+import org.junit.Test;
+
 import java.io.ByteArrayOutputStream;
 import java.io.PrintStream;
 import java.nio.ByteBuffer;
 
-import org.junit.Test;
-
 import static java.lang.String.format;
-
 import static org.junit.Assert.assertEquals;
 
 public class HexPrinterTest
@@ -165,12 +164,18 @@ public void shouldPrintPartOfByteBuffer() throws Exception
     @Test
     public void shouldOnlyPrintBytesWrittenToBuffer() throws Exception
     {
+        // Given
         ByteBuffer bytes = ByteBuffer.allocate( 1024 );
         for ( byte value = 0; value < 10; value++ )
         {
             bytes.put( value );
         }
+        bytes.flip();
+
+        // When
         String hexString = HexPrinter.hex( bytes );
+
+        // Then
         assertEquals( format( "00 01 02 03 04 05 06 07    08 09" ), hexString );
     }
 }

community/ndp/kernelextension/pom.xml

@@ -29,17 +29,17 @@
       <name>GNU General Public License, Version 3</name>
       <url>http://www.gnu.org/licenses/gpl-3.0-standalone.html</url>
       <comments>The software ("Software") developed and owned by Network Engine for
-Objects in Lund AB (referred to in this notice as "Neo Technology") is
-licensed under the GNU GENERAL PUBLIC LICENSE Version 3 to all third
-parties and that license is included below.
+        Objects in Lund AB (referred to in this notice as "Neo Technology") is
+        licensed under the GNU GENERAL PUBLIC LICENSE Version 3 to all third
+        parties and that license is included below.
 
-However, if you have executed an End User Software License and Services
-Agreement or an OEM Software License and Support Services Agreement, or
-another commercial license agreement with Neo Technology or one of its
-affiliates (each, a "Commercial Agreement"), the terms of the license in
-such Commercial Agreement will supersede the GNU GENERAL PUBLIC LICENSE
-Version 3 and you may use the Software solely pursuant to the terms of
-the relevant Commercial Agreement.
+        However, if you have executed an End User Software License and Services
+        Agreement or an OEM Software License and Support Services Agreement, or
+        another commercial license agreement with Neo Technology or one of its
+        affiliates (each, a "Commercial Agreement"), the terms of the license in
+        such Commercial Agreement will supersede the GNU GENERAL PUBLIC LICENSE
+        Version 3 and you may use the Software solely pursuant to the terms of
+        the relevant Commercial Agreement.
       </comments>
     </license>
   </licenses>
@@ -113,8 +113,8 @@ the relevant Commercial Agreement.
       <!-- Disable the ComponentVersion generation -->
       <plugin>
         <artifactId>maven-antrun-plugin</artifactId>
-          <executions>
-            <execution>
+        <executions>
+          <execution>
             <id>generate-version</id>
             <phase>none</phase>
           </execution>

community/ndp/kernelextension/src/main/java/org/neo4j/ext/NDPKernelExtension.java

@@ -47,19 +47,21 @@ public class NDPKernelExtension extends KernelExtensionFactory<NDPKernelExtensio
 {
     public static class Settings
     {
-        @Description( "Max time that sessions can be idle, after this interval a session will get closed." )
-        public static final Setting<Boolean> ndp_enabled = setting("experimental.ndp.enabled", BOOLEAN,
+        @Description("Max time that sessions can be idle, after this interval a session will get closed.")
+        public static final Setting<Boolean> ndp_enabled = setting( "experimental.ndp.enabled", BOOLEAN,
                 "false" );
 
-        @Description( "Host and port for the Neo4j Data Protocol http transport" )
+        @Description("Host and port for the Neo4j Data Protocol http transport")
         public static final Setting<HostnamePort> ndp_address =
-                setting("dbms.ndp.address", HOSTNAME_PORT, "localhost:7687" );
+                setting( "dbms.ndp.address", HOSTNAME_PORT, "localhost:7687" );
     }
 
     public interface Dependencies
     {
         LogService logService();
+
         Config config();
+
         GraphDatabaseService db();
     }
 
@@ -78,7 +80,7 @@ public Lifecycle newKernelExtension( Dependencies dependencies ) throws Throwabl
         final HostnamePort address = config.get( Settings.ndp_address );
         final LifeSupport life = new LifeSupport();
 
-        if(config.get( Settings.ndp_enabled ))
+        if ( config.get( Settings.ndp_enabled ) )
         {
             final Sessions env = life.add( new StandardSessions( api, log ) );
 

community/ndp/kernelextension/src/test/java/org/neo4j/ext/NDPExtensionIT.java

@@ -51,7 +51,7 @@ public void shouldLaunchNDP() throws Throwable
                 .newGraphDatabase();
 
         // Then
-        assertEventuallyServerResponds("localhost", 7687);
+        assertEventuallyServerResponds( "localhost", 7687 );
     }
 
     @Test
@@ -65,25 +65,25 @@ public void shouldBeAbleToSpecifyHostAndPort() throws Throwable
                 .newGraphDatabase();
 
         // Then
-        assertEventuallyServerResponds("localhost", 8776);
+        assertEventuallyServerResponds( "localhost", 8776 );
     }
 
-    private void assertEventuallyServerResponds(String host, int port) throws IOException, InterruptedException
+    private void assertEventuallyServerResponds( String host, int port ) throws IOException, InterruptedException
     {
         long timeout = System.currentTimeMillis() + 1000 * 30;
-        for(;;)
+        for (; ; )
         {
-            if ( serverResponds(host, port) )
+            if ( serverResponds( host, port ) )
             {
                 return;
             }
             else
             {
-                Thread.sleep(100);
+                Thread.sleep( 100 );
             }
 
             // Make sure process still is alive
-            if(System.currentTimeMillis() > timeout)
+            if ( System.currentTimeMillis() > timeout )
             {
                 throw new RuntimeException( "Waited for 30 seconds for server to respond to HTTP calls, " +
                                             "but no response, timing out to avoid blocking forever." );
@@ -95,23 +95,23 @@ private boolean serverResponds( String host, int port ) throws IOException, Inte
     {
         try
         {
-            try(Socket socket = new Socket())
+            try ( Socket socket = new Socket() )
             {
                 // Ok, we can connect - can we perform the version handshake?
                 socket.connect( new InetSocketAddress( host, port ) );
                 OutputStream out = socket.getOutputStream();
                 InputStream in = socket.getInputStream();
 
                 // Hard-coded handshake, a general "test client" would be useful further on.
-                out.write( new byte[]{ 0,0,0,1, 0,0,0,0, 0,0,0,0, 0,0,0,0 } );
+                out.write( new byte[]{0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0} );
 
                 byte[] accepted = new byte[4];
                 in.read( accepted );
 
-                return Arrays.equals( accepted, new byte[]{0,0,0,1} );
+                return Arrays.equals( accepted, new byte[]{0, 0, 0, 1} );
             }
         }
-        catch(ConnectException e)
+        catch ( ConnectException e )
         {
             return false;
         }
@@ -120,7 +120,7 @@ private boolean serverResponds( String host, int port ) throws IOException, Inte
     @After
     public void cleanup()
     {
-        if(db != null)
+        if ( db != null )
         {
             db.shutdown();
         }

community/ndp/messaging-v1/pom.xml

@@ -49,19 +49,30 @@
     <dependency>
       <groupId>org.hamcrest</groupId>
       <artifactId>hamcrest-all</artifactId>
-      <version>1.3</version>
       <scope>test</scope>
     </dependency>
     <dependency>
       <groupId>junit</groupId>
       <artifactId>junit</artifactId>
-      <version>4.11</version>
       <scope>test</scope>
     </dependency>
     <dependency>
       <groupId>org.mockito</groupId>
       <artifactId>mockito-all</artifactId>
-      <version>1.10.19</version>
+      <scope>test</scope>
+    </dependency>
+
+    <!-- Used to validate docs -->
+    <dependency>
+      <groupId>org.asciidoctor</groupId>
+      <artifactId>asciidoctorj</artifactId>
+      <version>1.5.2</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.jsoup</groupId>
+      <artifactId>jsoup</artifactId>
+      <version>1.8.1</version>
       <scope>test</scope>
     </dependency>
   </dependencies>
@@ -70,7 +81,6 @@
     <plugins>
       <plugin>
         <artifactId>maven-compiler-plugin</artifactId>
-        <version>2.3.2</version>
         <configuration>
           <source>1.7</source>
           <target>1.7</target>
@@ -79,7 +89,6 @@
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-jar-plugin</artifactId>
-        <version>2.2</version>
         <executions>
           <execution>
             <goals>
@@ -98,6 +107,35 @@
           </execution>
         </executions>
       </plugin>
+
+      <!-- Temporary asciidoc generation, pending plugging into manual. -->
+      <plugin>
+        <groupId>org.asciidoctor</groupId>
+        <artifactId>asciidoctor-maven-plugin</artifactId>
+        <version>1.5.2</version>
+        <executions>
+          <execution>
+            <id>generate-compliance-manual</id>
+            <phase>generate-resources</phase>
+            <goals>
+              <goal>process-asciidoc</goal>
+            </goals>
+            <configuration>
+              <backend>html</backend>
+            </configuration>
+          </execution>
+        </executions>
+        <configuration>
+          <sourceDirectory>../v1-docs/src/docs/dev</sourceDirectory>
+          <outputDirectory>${basedir}/target/messaging-manual/html</outputDirectory>
+          <backend>html</backend>
+          <attributes>
+            <toc/>
+            <source-highlighter>coderay</source-highlighter>
+          </attributes>
+        </configuration>
+      </plugin>
+
     </plugins>
   </build>
 

community/ndp/messaging-v1/src/main/java/org/neo4j/ndp/messaging/v1/PackStreamMessageFormatV1.java

@@ -36,6 +36,7 @@
 import org.neo4j.graphdb.PropertyContainer;
 import org.neo4j.graphdb.Relationship;
 import org.neo4j.helpers.collection.Iterables;
+import org.neo4j.kernel.api.exceptions.Status;
 import org.neo4j.ndp.messaging.v1.infrastructure.ValueNode;
 import org.neo4j.ndp.messaging.v1.infrastructure.ValuePath;
 import org.neo4j.ndp.messaging.v1.infrastructure.ValueRelationship;
@@ -114,8 +115,13 @@ public void run()
          */
         public Writer( PackOutput output, Runnable onMessageComplete )
         {
+            this( new PackStream.Packer( output ), onMessageComplete );
+        }
+
+        public Writer( PackStream.Packer packer, Runnable onMessageComplete )
+        {
+            this.packer = packer;
             this.onMessageComplete = onMessageComplete;
-            packer = new PackStream.Packer( output );
         }
 
         @Override
@@ -480,8 +486,13 @@ private <E extends Exception> void unpackFailureMessage( MessageHandler<E> outpu
         {
             Map<String,Object> map = unpackRawMap();
 
-            String codeStr = (String) map.get( "code" );
-            String msg = (String) map.get( "message" );
+            String codeStr = map.containsKey( "code" ) ?
+                             (String) map.get( "code" ) :
+                             Status.General.UnknownFailure.name();
+
+            String msg = map.containsKey( "message" ) ?
+                         (String) map.get( "message" ) :
+                         "<No message supplied>";
 
             output.handleFailureMessage( new Neo4jError( codeFromString( codeStr ), msg ) );
         }