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
Show all versions of ion-java Show documentation
A Java implementation of the Amazon Ion data notation.
/*
* 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;
}