Package org.bluezoo.gumdrop.telemetry.protobuf

Class ProtobufParser

java.lang.Object
org.bluezoo.gumdrop.telemetry.protobuf.ProtobufParser
public class ProtobufParser extends Object
Push-based protobuf parser.

This parser processes protobuf wire format data incrementally, calling handler methods as fields are parsed. It uses an all-or-nothing approach for each field: if there isn't enough data to parse a complete field, the buffer position is left unchanged (at the start of the incomplete field) and the parser enters an underflow state.

Usage

 ProtobufHandler handler = new MyHandler();
 ProtobufParser parser = new ProtobufParser(handler);

 while (channel.read(buffer) > 0) {
     buffer.flip();
     parser.receive(buffer);
     buffer.compact();
 }

 parser.close();

Buffer Management

The caller is responsible for managing the input buffer. After receive() returns, any unconsumed data (incomplete field) remains in the buffer between position and limit. The caller should call compact() before reading more data into the buffer.

Underflow Handling

When the parser cannot complete a field due to insufficient data, it enters an underflow state. The next receive() call will attempt to parse from the same position. If close() is called while in underflow state, an exception is thrown.

Author:
Chris Burdess
See Also:

  • Constructor Details

    • ProtobufParser

      public ProtobufParser(ProtobufHandler handler)
      Creates a new parser with the given handler.
      Parameters:
      handler - the handler to receive parse events

  • Method Details

    • isUnderflow

      public boolean isUnderflow()
      Returns true if the parser is in underflow state.

      Underflow means the last receive() call ended with an incomplete field. More data is needed before parsing can continue.

      Returns:
      true if in underflow state

    • receive

      public void receive(ByteBuffer data) throws ProtobufParseException
      Processes protobuf data from the buffer.

      Parses as many complete fields as possible, calling handler methods for each. If the buffer contains an incomplete field, the parser leaves the position at the start of that field and enters underflow state.

      Parameters:
      data - the buffer to read from (must be in read mode)
      Throws:
      ProtobufParseException - if the data is malformed

    • close

      public void close() throws ProtobufParseException
      Completes parsing and validates state.
      Throws:
      ProtobufParseException - if in underflow state or unclosed messages

    • reset

      public void reset()
      Resets the parser to initial state.

      Call this to reuse the parser for a new independent message.