MessageParser implementation notes

1. Supporting multiple JSONObject returns from a single byte[] The original MessageParser interface supported parsing a message and returning a List<JSONObject>. Therefore explicitly supporting multiple messages from one input. While this is fine, it only allows for the complete failure of a message for any reason. There can only be one exception thrown. This means that if there are multiple messages in the buffer, any one failure will necessarily fail all of them. To improve on this situation, a new method was added to the MessageParser interface (with a default implementation), that introduces a return type to provide not only the JSONObjects produced, but also a Map of messages -> throwable.

To support this in your parser, you should:

• Implement the new method

 @Override
  public Optional<MessageParserResult<JSONObject>> parseOptionalResult(byte[] rawMessage)

• Implement the original List<JSONObject> parse(byte[] message) to delegate to that method such as below:

 @Override
  public List<JSONObject> parse(byte[] rawMessage) {
    Optional<MessageParserResult<JSONObject>> resultOptional = parseOptionalResult(rawMessage);
    if (!resultOptional.isPresent()) {
      return Collections.EMPTY_LIST;
    }
    Map<Object,Throwable> errors = resultOptional.get().getMessageThrowables();
    if (!errors.isEmpty()) {
      throw new RuntimeException(errors.entrySet().iterator().next().getValue());
    }

    return resultOptional.get().getMessages();
  }

• You may want to govern treating the incoming buffer as multiline or not by adding a configuration option for your parser, such as "multiline":"true"|"false"

• See the org.apache.metron.parsers.GrokParser for an example of this implementation.

The Metron system itself will call the new parseOptionalResult method during processing. The default implementation in the interface handles backwards compatability with previous implementations.