com.amazon.ion.impl.ByteReader Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ion-java Show documentation
A Java implementation of the Amazon Ion data notation.
The newest version!
/*
 * Copyright 2007-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License").
 * You may not use this file except in compliance with the License.
 * A copy of the License is located at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * or in the "license" file accompanying this file. This file 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 com.amazon.ion.impl;

import com.amazon.ion.Decimal;
import com.amazon.ion.Timestamp;
import java.io.IOException;
/**
 * Interface to read bytes over a variety of sources.
 * Avoiding the Java standard overhead in so far as possible.
 * This requires the ability to access any part of the underlying
 * data source randomly.  However forward access is expected to be
 * the standard direction.
 */
interface ByteReader
{
    /**
     * yet another definition of eof of file as -1
     */
    public static final int EOF = -1;

    /**
     * returns the current position of the reader in the underlying
     * byte buffer
     * @return offset of the next byte to read
     */
    public int  position();
    /**
     * sets the position of the reader so that it will read the
     * byte at the passed in offset (newPosition) on the next call
     * to read()
     * @param newPosition offset to position the reader to
     */
    public void position(int newPosition);
    /**
     * moves the reader forward length bytes.  This is typically
     * faster than read as it has no need to actually move any
     * bytes of data.  It may error if the skip would take the
     * current position off the end of the buffer.
     * @param length number of bytes to skip
     */
    public void skip(int length);

    /**
     * reads a single byte and returns it as an unsigned value,
     * that is from 0 to 255.  This returns a ByteReader.EOF (-1)
     * if there is not data to read.
     * @return next byte of data
     * @throws IOException
     */
    public int  read() throws IOException;
    /**
     * reads a number of bytes into the callers supplied buffer (dst).
     * This will return the number of bytes read, if any.
     * @param dst callers destination byte array
     * @param start offset of the first destination array element to write into
     * @param len maximum number of bytes to copy
     * @return number of bytes actually copied
     * @throws IOException
     */
    public int  read(byte[] dst, int start, int len) throws IOException;

    /**
     * reads the next byte as a typedesc bytes
     * @return typedesc byte
     * @throws IOException
     */
    public int  readTypeDesc() throws IOException;

    /**
     * reads the upcoming bytes as a signed long.  This uses
     * 7 bits per byte, expects the bytes in bigendian order, and
     * looks for the high order bit (0x80) to be set to mark the
     * end of the value. It expects the 2nd bit (0x40 of the first
     * byte) to be the sign of the value.  The remaining bits are
     * the absolute value of the orginal value. It
     * returns the aggregated bytes as a Java long (signed 64 bit
     * value) correctly signed.
     * @return long value read
     * @throws IOException
     */
    public long readVarLong() throws IOException;
    /**
     * reads the upcoming bytes as a unsigned long.  This uses
     * 7 bits per byte, expects the bytes in bigendian order, and
     * looks for the high order bit (0x80) to be set to mark the
     * end of the value. It does not include a sign bit so all 7 bits
     * in the first byte are treated as positive. It
     * returns the aggregated bytes as a Java long (signed 64 bit
     * value).
     * @return long value read
     * @throws IOException
     */
    public long readVarULong() throws IOException;
    /**
     * reads the next len bytes as a signed long.  This uses
     * 8 bits per byte and expects the bytes in bigendian order. It
     * returns the aggregated bytes as a Java long (signed 64 bit
     * value).
     * @param len number of bytes to read into the long
     * @return long value read
     * @throws IOException
     */
    public long readULong(int len) throws IOException;

    /**
     * reads the upcoming bytes as a signed int.  This uses
     * 7 bits per byte, expects the bytes in bigendian order, and
     * looks for the high order bit (0x80) to be set to mark the
     * end of the value. It expects the 2nd bit (0x40 of the first
     * byte) to be the sign of the value.  The remaining bits are
     * the absolute value of the orginal value. It
     * returns the aggregated bytes as a Java long (signed 32 bit
     * value) correctly signed.
     * @return int value read
     * @throws IOException
     */
    public int  readVarInt() throws IOException;
    /**
     * reads the upcoming bytes as a unsigned int.  This uses
     * 7 bits per byte, expects the bytes in bigendian order, and
     * looks for the high order bit (0x80) to be set to mark the
     * end of the value. It does not include a sign bit so all 7 bits
     * in the first byte are treated as positive. It
     * returns the aggregated bytes as a Java long (signed 32 bit
     * value).
     * @return int value read
     * @throws IOException
     */
    public int  readVarUInt() throws IOException;

    /**
     * reads len bytes and treats them as an IEEE 64 binary
     * floating point value.  Currently the only valid values for
     * len are 0 (which returns 0.0e1) or 8 which is treated
     * as a 64 bit binary float and returned.
     * @param len 0 or 8
     * @return 0.0 or the double represented by the next 8 bytes
     * @throws IOException
     */
    public double readFloat(int len) throws IOException;
    /**
     * reads the next len bytes and converts them to a {@link Decimal} value.
     * @param len number of bytes over which the value extends
     * @return Decimal object initialized to the represented value; not null.
     * @throws IOException
     */
    public Decimal readDecimal(int len) throws IOException;

    /**
     * Reads the next len bytes and returns them as a {@link Timestamp}
     * object.  This contains an UTC date and time value and a
     * timezone offset of the original value.
     *
     * @param len
     * @return a new {@link Timestamp} instance,
     * or {@code null} if the encoded value is {@code null.timestamp}.
     * @throws IOException
     */
    public Timestamp readTimestamp(int len) throws IOException;

    /** reads the next len bytes and converts them from UTF-8 into Java
     * characters and returns those characters as a String.  This may throw
     * an exception in the event it encounters byte sequences that are not
     * value UTF-8.  This converts some Unicode values into character pairs
     * when the value requires the use of surrogate pairs in Unicode 16.
     * @param len number of bytes to read
     * @return resultant Java string
     * @throws IOException
     */
    public String readString(int len) throws IOException;
}