org.finos.legend.pure.m4.serialization.Reader Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of legend-pure-m4 Show documentation
There is a newer version: 5.23.0
// Copyright 2020 Goldman Sachs
//
// 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 org.finos.legend.pure.m4.serialization;

import java.io.Closeable;
import java.util.Objects;

/**
 * Reader for reading data from a binary source.
 *
 * If there are not enough bytes in the underlying source to perform the
 * requested read operation, an {@link org.finos.legend.pure.m4.serialization.binary.UnexpectedEndException UnexpectedEndException}
 * is thrown. In this case, the state of the Reader is uncertain, as some bytes may or may not have been read from the
 * underlying source during the operation. So it is not advisable to continue use of the Reader after such an exception.
 *
 * Any {@link java.io.IOException IOException} thrown by an underlying data source should be wrapped in
 * {@link java.io.UncheckedIOException UncheckedIOException} by implementing classes.
 */
public interface Reader extends Closeable
{
    /**
     * Read a single byte of data.
     *
     * @return the byte read
     */
    byte readByte();

    /**
     * Read n bytes.
     *
     * @param n number of bytes to read
     * @return array of the n bytes read
     */
    default byte[] readBytes(int n)
    {
        return readBytes(new byte[n], 0, n);
    }

    /**
     * Read bytes into the given byte array to fill the array, and return the array. If there are not enough bytes to
     * fill the array, an {@link org.finos.legend.pure.m4.serialization.binary.UnexpectedEndException UnexpectedEndException}
     * will be thrown. In this case, some bytes may or may not be written to the given array.
     *
     * @param bytes byte array to write bytes into
     * @return given byte array
     */
    default byte[] readBytes(byte[] bytes)
    {
        return readBytes(Objects.requireNonNull(bytes, "byte array may not be null"), 0, bytes.length);
    }

    /**
     * Read n bytes into the given byte array at the given offset. Returns the given byte array. Throws an
     * {@link org.finos.legend.pure.m4.serialization.binary.UnexpectedEndException UnexpectedEndException} if there are
     * fewer than n bytes left to read. In this case, some bytes may or may not be written to the given array.
     *
     * @param bytes  byte array to write bytes into
     * @param offset offset at which to start writing bytes
     * @param n      number of bytes to read
     * @return given byte array
     */
    byte[] readBytes(byte[] bytes, int offset, int n);

    /**
     * Skip n bytes.
     *
     * @param n number of bytes to skip
     */
    void skipBytes(long n);

    /**
     * Read an array of bytes.
     *
     * @return array of bytes
     */
    byte[] readByteArray();

    /**
     * Skip an array of bytes.
     */
    void skipByteArray();

    /**
     * Read a boolean value.
     *
     * @return boolean value
     */
    boolean readBoolean();

    /**
     * Skip a boolean value
     */
    void skipBoolean();

    /**
     * Read a short value.
     *
     * @return short value
     */
    short readShort();

    /**
     * Skip a short value.
     */
    void skipShort();

    /**
     * Read an array of short values.
     *
     * @return array of short values
     */
    short[] readShortArray();

    /**
     * Skip an array of short values.
     */
    void skipShortArray();

    /**
     * Read an int value.
     *
     * @return int value
     */
    int readInt();

    /**
     * Skip an int value.
     */
    void skipInt();

    /**
     * Read an array of int values.
     *
     * @return array of int values
     */
    int[] readIntArray();

    /**
     * Skip an array of int values.
     */
    void skipIntArray();

    /**
     * Read a long value.
     *
     * @return long value
     */
    long readLong();

    /**
     * Skip a long value
     */
    void skipLong();

    /**
     * Read an array of long values.
     *
     * @return array of long values
     */
    long[] readLongArray();

    /**
     * Skip an array of long values.
     */
    void skipLongArray();

    /**
     * Read a float value.
     *
     * @return float value
     */
    float readFloat();

    /**
     * Skip a float value.
     */
    void skipFloat();

    /**
     * Read an array of float values.
     *
     * @return array of float values
     */
    float[] readFloatArray();

    /**
     * Skip an array of float values.
     */
    void skipFloatArray();

    /**
     * Read a double value.
     *
     * @return double value
     */
    double readDouble();

    /**
     * Skip a double value.
     */
    void skipDouble();

    /**
     * Read an array of double values.
     *
     * @return array of double values
     */
    double[] readDoubleArray();

    /**
     * Skip an array of double values.
     */
    void skipDoubleArray();

    /**
     * Read a string.
     *
     * @return string
     */
    String readString();

    /**
     * Skip a string.
     */
    void skipString();

    /**
     * Read an array of strings.
     *
     * @return array of strings
     */
    String[] readStringArray();

    /**
     * Skip an array of strings.
     */
    void skipStringArray();

    /**
     * Close the reader. This will also close any underlying source the reader is reading from.
     */
    @Override
    void close();
}