Java tutorial
/* * Copyright (c) 2011-2019 Contributors to the Eclipse Foundation * * This program and the accompanying materials are made available under the * terms of the Eclipse Public License 2.0 which is available at * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0 * which is available at https://www.apache.org/licenses/LICENSE-2.0. * * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 */ package io.vertx.core.parsetools; import io.vertx.codegen.annotations.Fluent; import io.vertx.codegen.annotations.VertxGen; import io.vertx.core.Handler; import io.vertx.core.buffer.Buffer; import io.vertx.core.parsetools.impl.RecordParserImpl; import io.vertx.core.streams.ReadStream; /** * A helper class which allows you to easily parse protocols which are delimited by a sequence of bytes, or fixed * size records. * <p> * Instances of this class take as input {@link io.vertx.core.buffer.Buffer} instances containing raw bytes, * and output records. * <p> * For example, if I had a simple ASCII text protocol delimited by '\n' and the input was the following: * <p> * <pre> * buffer1:HELLO\nHOW ARE Y * buffer2:OU?\nI AM * buffer3: DOING OK * buffer4:\n * </pre> * Then the output would be:<p> * <pre> * buffer1:HELLO * buffer2:HOW ARE YOU? * buffer3:I AM DOING OK * </pre> * Instances of this class can be changed between delimited mode and fixed size record mode on the fly as * individual records are read, this allows you to parse protocols where, for example, the first 5 records might * all be fixed size (of potentially different sizes), followed by some delimited records, followed by more fixed * size records. * <p> * Instances of this class can't currently be used for protocols where the text is encoded with something other than * a 1-1 byte-char mapping. * <p> * Please see the documentation for more information. * * @author <a href="http://tfox.org">Tim Fox</a> * @author <a href="mailto:larsdtimm@gmail.com">Lars Timm</a> */ @VertxGen public interface RecordParser extends Handler<Buffer>, ReadStream<Buffer> { void setOutput(Handler<Buffer> output); /** * Like {@link #newDelimited(String)} but set the {@code output} that will receive whole records * which have been parsed. * * @param delim the initial delimiter string * @param output handler that will receive the output */ static RecordParser newDelimited(String delim, Handler<Buffer> output) { return RecordParserImpl.newDelimited(delim, null, output); } /** * Like {@link #newDelimited(String)} but wraps the {@code stream}. The {@code stream} handlers will be set/unset * when the {@link #handler(Handler)} is set. * <p/> * The {@code pause()}/{@code resume()} operations are propagated to the {@code stream}. * * @param delim the initial delimiter string * @param stream the wrapped stream */ static RecordParser newDelimited(String delim, ReadStream<Buffer> stream) { return RecordParserImpl.newDelimited(delim, stream, null); } /** * Create a new {@code RecordParser} instance, initially in delimited mode, and where the delimiter can be represented * by the String {@code} delim endcoded in latin-1 . Don't use this if your String contains other than latin-1 characters. * <p> * {@code output} Will receive whole records which have been parsed. * * @param delim the initial delimiter string */ static RecordParser newDelimited(String delim) { return RecordParserImpl.newDelimited(delim, null, null); } /** * Create a new {@code RecordParser} instance, initially in delimited mode, and where the delimiter can be represented * by the {@code Buffer} delim. * <p> * * @param delim the initial delimiter buffer */ static RecordParser newDelimited(Buffer delim) { return RecordParserImpl.newDelimited(delim, null, null); } /** * Like {@link #newDelimited(Buffer)} but set the {@code output} that will receive whole records * which have been parsed. * * @param delim the initial delimiter buffer * @param output handler that will receive the output */ static RecordParser newDelimited(Buffer delim, Handler<Buffer> output) { return RecordParserImpl.newDelimited(delim, null, output); } /** * Like {@link #newDelimited(Buffer)} but wraps the {@code stream}. The {@code stream} handlers will be set/unset * when the {@link #handler(Handler)} is set. * <p/> * The {@code pause()}/{@code resume()} operations are propagated to the {@code stream}. * * @param delim the initial delimiter buffer * @param stream the wrapped stream */ static RecordParser newDelimited(Buffer delim, ReadStream<Buffer> stream) { return RecordParserImpl.newDelimited(delim, stream, null); } /** * Create a new {@code RecordParser} instance, initially in fixed size mode, and where the record size is specified * by the {@code size} parameter. * <p> * {@code output} Will receive whole records which have been parsed. * * @param size the initial record size */ static RecordParser newFixed(int size) { return RecordParserImpl.newFixed(size, null, null); } /** * Like {@link #newFixed(int)} but set the {@code output} that will receive whole records * which have been parsed. * * @param size the initial record size * @param output handler that will receive the output */ static RecordParser newFixed(int size, Handler<Buffer> output) { return RecordParserImpl.newFixed(size, null, output); } /** * Like {@link #newFixed(int)} but wraps the {@code stream}. The {@code stream} handlers will be set/unset * when the {@link #handler(Handler)} is set. * <p/> * The {@code pause()}/{@code resume()} operations are propagated to the {@code stream}. * * @param size the initial record size * @param stream the wrapped stream */ static RecordParser newFixed(int size, ReadStream<Buffer> stream) { return RecordParserImpl.newFixed(size, stream, null); } /** * Flip the parser into delimited mode, and where the delimiter can be represented * by the String {@code delim} encoded in latin-1 . Don't use this if your String contains other than latin-1 characters. * <p> * This method can be called multiple times with different values of delim while data is being parsed. * * @param delim the new delimeter */ void delimitedMode(String delim); /** * Flip the parser into delimited mode, and where the delimiter can be represented * by the delimiter {@code delim}. * <p> * This method can be called multiple times with different values of delim while data is being parsed. * * @param delim the new delimiter */ void delimitedMode(Buffer delim); /** * Flip the parser into fixed size mode, where the record size is specified by {@code size} in bytes. * <p> * This method can be called multiple times with different values of size while data is being parsed. * * @param size the new record size */ void fixedSizeMode(int size); /** * Set the maximum allowed size for a record when using the delimited mode. * The delimiter itself does not count for the record size. * <p> * If a record is longer than specified, an {@link IllegalStateException} will be thrown. * * @param size the maximum record size * @return a reference to this, so the API can be used fluently */ @Fluent RecordParser maxRecordSize(int size); /** * This method is called to provide the parser with data. * * @param buffer a chunk of data */ void handle(Buffer buffer); @Override RecordParser exceptionHandler(Handler<Throwable> handler); @Override RecordParser handler(Handler<Buffer> handler); @Override RecordParser pause(); @Override RecordParser fetch(long amount); @Override RecordParser resume(); @Override RecordParser endHandler(Handler<Void> endHandler); }