[Java]: Added javadoc and tidy up of OTF decoder.

Author: mjpt777

build.xml

@@ -257,6 +257,9 @@
  <java classname="uk.co.real_logic.sbe.examples.ExampleUsingGeneratedStubExtension">
  <classpath refid="examples.classpath"/>
  </java>
+ <java classname="uk.co.real_logic.sbe.examples.OtfExample">
+ <classpath refid="examples.classpath"/>
+ </java>
  </target>
 
  <target name="cpp:examples:gen" depends="dist" description="Generate and run C++ generated code example">

examples/java/uk/co/real_logic/sbe/examples/ExampleUsingGeneratedStub.java

@@ -51,6 +51,8 @@ public class ExampleUsingGeneratedStub
 
  public static void main(final String[] args)throws Exception
  {
+ System.out.println("\n*** Basic Stub Example ***");
+
  final ByteBuffer byteBuffer = ByteBuffer.allocateDirect(4096);
  final DirectBuffer directBuffer = new DirectBuffer(byteBuffer);
  final short messageTemplateVersion = 0;

examples/java/uk/co/real_logic/sbe/examples/ExampleUsingGeneratedStubExtension.java

@@ -52,6 +52,8 @@ public class ExampleUsingGeneratedStubExtension
 
  public static void main(final String[] args)throws Exception
  {
+ System.out.println("\n*** Extension Stub Example ***");
+
  final ByteBuffer byteBuffer = ByteBuffer.allocateDirect(4096);
  final DirectBuffer directBuffer = new DirectBuffer(byteBuffer);
  final short messageTemplateVersion = 0;

examples/java/uk/co/real_logic/sbe/examples/OtfExample.java

@@ -42,6 +42,8 @@ public class OtfExample
 
  public static void main(final String[] args) throws Exception
  {
+ System.out.println("\n*** OTF Example ***\n");
+
  // Encode up message and schema as if we just got them off the wire.
  final ByteBuffer encodedSchemaBuffer = ByteBuffer.allocateDirect(SCHEMA_BUFFER_CAPACITY);
  encodeSchema(encodedSchemaBuffer);
@@ -65,6 +67,7 @@ public static void main(final String[] args) throws Exception
  bufferOffset += headerDecoder.size();
 
  // Given the header information we can select the appropriate message template to do the decode.
+ // The OTF Java classes are thread safe so the same instances can be reused across multiple threads.
  final OtfGroupSizeDecoder groupSizeDecoder = new OtfGroupSizeDecoder(ir.getType(OtfGroupSizeDecoder.GROUP_SIZE_ENCODING_NAME));
  final OtfVarDataDecoder varDataDecoder = new OtfVarDataDecoder(ir.getType(OtfVarDataDecoder.VAR_DATA_ENCODING_NAME));
  final List<Token> msgTokens = ir.getMessage(templateId);

main/java/uk/co/real_logic/sbe/otf/AbstractTokenListener.java

@@ -0,0 +1,81 @@
+/*
+ * Copyright 2013 Real Logic Ltd.
+ *
+ * Licensed 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.
+ */
+package uk.co.real_logic.sbe.otf;
+
+import uk.co.real_logic.sbe.codec.java.DirectBuffer;
+import uk.co.real_logic.sbe.ir.Token;
+
+import java.util.List;
+
+/**
+ * Abstract {@link TokenListener} that can be extended when not all callback methods are required.
+ * <p/>
+ * By extending this class their is a possibility for the optimizer to elide unused methods otherwise requiring polymorphic dispatch.
+ */
+public abstract class AbstractTokenListener implements TokenListener
+{
+ public void onBeginMessage(final Token token)
+ {
+ // no op
+ }
+
+ public void onEndMessage(final Token token)
+ {
+ // no op
+ }
+
+ public void onEncoding(final Token fieldToken, final DirectBuffer buffer, final int bufferIndex, final Token typeToken, final int actingVersion)
+ {
+ // no op
+ }
+
+ public void onEnum(final Token fieldToken, final DirectBuffer buffer, final int bufferIndex,
+ final List<Token> tokens, final int fromIndex, final int toIndex, final int actingVersion)
+ {
+ // no op
+ }
+
+ public void onBitSet(final Token fieldToken, final DirectBuffer buffer,
+ final int bufferIndex, final List<Token> tokens, final int fromIndex, final int toIndex, final int actingVersion)
+ {
+ // no op
+ }
+
+ public void onBeginComposite(final Token fieldToken, final List<Token> tokens, final int fromIndex, final int toIndex)
+ {
+ // no op
+ }
+
+ public void onEndComposite(final Token fieldToken, final List<Token> tokens, final int fromIndex, final int toIndex)
+ {
+ // no op
+ }
+
+ public void onBeginGroup(final Token token, final int groupIndex, final int numInGroup)
+ {
+ // no op
+ }
+
+ public void onEndGroup(final Token token, final int groupIndex, final int numInGroup)
+ {
+ // no op
+ }
+
+ public void onVarData(final Token fieldToken, final DirectBuffer buffer, final int bufferIndex, final int length, final Token typeToken)
+ {
+ // no op
+ }
+}

main/java/uk/co/real_logic/sbe/otf/OtfGroupSizeDecoder.java

@@ -24,7 +24,9 @@
 import java.util.List;
 
 /**
- * Used to decode the group size header.
+ * Used to decode group size headers.
+ * <p/>
+ * This class is thread safe.
  */
 public class OtfGroupSizeDecoder
 {

main/java/uk/co/real_logic/sbe/otf/OtfHeaderDecoder.java

@@ -26,6 +26,8 @@
  * Used to decode a message header while doing on-the-fly decoding of a message stream.
  * <p/>
  * Meta data is cached to improve the performance of decoding headers.
+ * <p/>
+ * This class is thread safe.
  */
 public class OtfHeaderDecoder
 {

main/java/uk/co/real_logic/sbe/otf/OtfMessageDecoder.java

@@ -22,11 +22,26 @@
 
 import java.util.List;
 
+/**
+ * On-the-fly decoder that dynamically decodes messages based on the IR for a schema.
+ * <p/>
+ * The contents of the messages are structurally decomposed and passed to a {@link TokenListener} for decoding the primitive values.
+ * <p/>
+ * The design keeps all state on the stack to maximise performance and avoid object allocation. The message decoder can be used reused by
+ * repeatably calling {@link OtfMessageDecoder#decode(DirectBuffer, int, int, int, java.util.List, TokenListener)}
+ * and is thread safe to be used across multiple threads.
+ */
 public class OtfMessageDecoder
 {
  private final OtfGroupSizeDecoder groupSizeDecoder;
  private final OtfVarDataDecoder varDataDecoder;
 
+ /**
+ * Construct a message decoder with provided decoders for the group and var data headers. The provided decoders are expected to be thread safe.
+ *
+ * @param groupSizeDecoder for decoding the repeating group header.
+ * @param varDataDecoder for decoding the var data field header.
+ */
  public OtfMessageDecoder(final OtfGroupSizeDecoder groupSizeDecoder, final OtfVarDataDecoder varDataDecoder)
  {
  Verify.notNull(groupSizeDecoder, "groupSizeDecoder");
@@ -36,6 +51,17 @@ public OtfMessageDecoder(final OtfGroupSizeDecoder groupSizeDecoder, final OtfVa
  this.varDataDecoder = varDataDecoder;
  }
 
+ /**
+ * Decode a message from the provided buffer based on the message schema described with IR {@link uk.co.real_logic.sbe.ir.Token}s.
+ *
+ * @param buffer containing the encoded message.
+ * @param bufferIndex at which the message encoding starts in the buffer.
+ * @param actingVersion of the encoded message for dealing with extension fields.
+ * @param blockLength of the root message fields.
+ * @param msgTokens in IR format describing the message structure.
+ * @param listener to callback for decoding the primitive values as discovered in the structure.
+ * @return the index in the underlying buffer after decoding.
+ */
  public int decode(final DirectBuffer buffer,
  int bufferIndex,
  final int actingVersion,
@@ -71,7 +97,7 @@ private static void decodeFields(final DirectBuffer buffer,
  {
  for (int i = fromIndex; i < toIndex; i++)
  {
- if (tokens.get(i).signal() == Signal.BEGIN_FIELD)
+ if (Signal.BEGIN_FIELD == tokens.get(i).signal())
  {
  i = decodeField(buffer, bufferIndex, tokens, i, actingVersion, listener);
  }
@@ -164,8 +190,8 @@ private static int decodeField(final DirectBuffer buffer,
 
  switch (typeToken.signal())
  {
- case ENCODING:
- listener.onEncoding(fieldToken, buffer, bufferIndex + typeToken.offset(), typeToken, actingVersion);
+ case BEGIN_COMPOSITE:
+ decodeComposite(fieldToken, buffer, bufferIndex + typeToken.offset(), tokens, fromIndex + 1, toIndex - 1, actingVersion, listener);
  break;
 
  case BEGIN_ENUM:
@@ -176,8 +202,8 @@ private static int decodeField(final DirectBuffer buffer,
  listener.onBitSet(fieldToken, buffer, bufferIndex + typeToken.offset(), tokens, fromIndex + 1, toIndex - 1, actingVersion);
  break;
 
- case BEGIN_COMPOSITE:
- decodeComposite(fieldToken, buffer, bufferIndex + typeToken.offset(), tokens, fromIndex + 1, toIndex - 1, actingVersion, listener);
+ case ENCODING:
+ listener.onEncoding(fieldToken, buffer, bufferIndex + typeToken.offset(), typeToken, actingVersion);
  break;
  }
 

main/java/uk/co/real_logic/sbe/otf/OtfVarDataDecoder.java

@@ -24,7 +24,9 @@
 import java.util.List;
 
 /**
- * Used to decode the var data field.
+ * Used to decode var data fields.
+ * <p/>
+ * This class is thread safe.
  */
 public class OtfVarDataDecoder
 {

main/java/uk/co/real_logic/sbe/otf/Util.java

@@ -27,7 +27,7 @@
 public class Util
 {
  /**
- * Get an integer value from a buffer.
+ * Get an integer value from a buffer at a given index.
  *
  * @param buffer from which to read.
  * @param bufferIndex at which he integer should be read.