Package org.elasticsearch.common.io.stream

Class StreamInput

java.lang.Object

java.io.InputStream

org.elasticsearch.common.io.stream.StreamInput

All Implemented Interfaces:

Closeable, AutoCloseable

Direct Known Subclasses:

ByteBufferStreamInput, FilterStreamInput, InputStreamStreamInput

public abstract class StreamInput
extends InputStream

A stream from this node to another node. Technically, it can also be streamed to a byte array but that is mostly for testing. This class's methods are optimized so you can put the methods that read and write a class next to each other and you can scan them visually for differences. That means that most variables should be read and written in a single line so even large objects fit both reading and writing on the screen. It also means that the methods on this class are named very similarly to StreamOutput. Finally it means that the "barrier to entry" for adding new methods to this class is relatively low even though it is a shared class with code everywhere. That being said, this class deals primarily with Lists rather than Arrays. For the most part calls should adapt to lists, either by storing Lists internally or just converting to and from a List when calling. This comment is repeated on StreamInput.

Constructor Summary

Constructors

Constructor	Description
StreamInput()

Method Summary

Modifier and Type	Method	Description
abstract int	available()
abstract void	close()	Closes the stream to further operations.
protected abstract void	ensureCanReadBytes(int length)	This method throws an EOFException if the given number of bytes can not be read from the this stream.
Version	getVersion()	The version of the node on the other side of this stream.
NamedWriteableRegistry	namedWriteableRegistry()	Get the registry of named writeables if this stream has one, null otherwise.
<T> T[]	readArray(Writeable.Reader<T> reader, IntFunction<T[]> arraySupplier)	Reads an array from the stream using the specified Writeable.Reader to read array elements from the stream.
protected int	readArraySize()	Reads a vint via readVInt() and applies basic checks to ensure the read array size is sane.
BigInteger	readBigInteger()
boolean	readBoolean()	Reads a boolean.
abstract byte	readByte()	Reads and returns a single byte.
byte[]	readByteArray()
abstract void	readBytes(byte[] b, int offset, int len)	Reads a specified number of bytes into an array at the specified offset.
org.apache.lucene.util.BytesRef	readBytesRef()
org.apache.lucene.util.BytesRef	readBytesRef(int length)
BytesReference	readBytesReference()	Reads a bytes reference from this stream, copying any bytes read to a new byte[].
BytesReference	readBytesReference(int length)	Reads a bytes reference from this stream, might hold an actual reference to the underlying bytes of the stream.
double	readDouble()
double[]	readDoubleArray()
<E extends Enum<E>> E	readEnum(Class<E> enumClass)	Reads an enum with type E that was serialized based on the value of its ordinal
<E extends Enum<E>> EnumSet<E>	readEnumSet(Class<E> enumClass)	Reads an enum with type E that was serialized based on the value of it's ordinal
<T extends Exception> T	readException()
float	readFloat()
float[]	readFloatArray()
void	readFully(byte[] b)
Object	readGenericValue()	Reads a value of unspecified type.
GeoPoint	readGeoPoint()	Reads a GeoPoint from this stream input
<K, V> ImmutableOpenMap<K,V>	readImmutableMap(Writeable.Reader<K> keyReader, Writeable.Reader<V> valueReader)	Read ImmutableOpenMap using given key and value readers.
Instant	readInstant()	Read an Instant from the stream with nanosecond resolution
int	readInt()	Reads four bytes and returns an int.
int[]	readIntArray()
<T> List<T>	readList(Writeable.Reader<T> reader)	Reads a list of objects.
long	readLong()	Reads eight bytes and returns a long.
long[]	readLongArray()
Map<String,Object>	readMap()	If the returned map contains any entries it will be mutable.
<K, V> Map<K,V>	readMap(Writeable.Reader<K> keyReader, Writeable.Reader<V> valueReader)	If the returned map contains any entries it will be mutable.
<K, V> Map<K,List<V>>	readMapOfLists(Writeable.Reader<K> keyReader, Writeable.Reader<V> valueReader)	Read a Map of K-type keys to V-type Lists.
<C extends NamedWriteable> C	readNamedWriteable(Class<C> categoryClass)	Reads a NamedWriteable from the current stream, by first reading its name and then looking for the corresponding entry in the registry by name, so that the proper object can be read and returned.
<C extends NamedWriteable> C	readNamedWriteable(Class<C> categoryClass, String name)	Reads a NamedWriteable from the current stream with the given name.
<T extends NamedWriteable> List<T>	readNamedWriteableList(Class<T> categoryClass)	Reads a list of NamedWriteables.
<T> T[]	readOptionalArray(Writeable.Reader<T> reader, IntFunction<T[]> arraySupplier)
Boolean	readOptionalBoolean()
BytesReference	readOptionalBytesReference()	Reads an optional bytes reference from this stream.
Double	readOptionalDouble()
<E extends Enum<E>> E	readOptionalEnum(Class<E> enumClass)	Reads an optional enum with type E that was serialized based on the value of its ordinal
Float	readOptionalFloat()
Instant	readOptionalInstant()	Read an optional Instant from the stream.
Integer	readOptionalInt()	Reads an optional Integer.
Long	readOptionalLong()
<C extends NamedWriteable> C	readOptionalNamedWriteable(Class<C> categoryClass)	Reads an optional NamedWriteable.
SecureString	readOptionalSecureString()
String	readOptionalString()
String[]	readOptionalStringArray()
List<String>	readOptionalStringList()	Reads an optional list of strings.
Text	readOptionalText()
org.elasticsearch.core.TimeValue	readOptionalTimeValue()	Read an optional TimeValue from the stream, returning null if no TimeValue was written.
org.joda.time.DateTimeZone	readOptionalTimeZone()	Read an optional DateTimeZone.
Integer	readOptionalVInt()
Long	readOptionalVLong()
<T extends Writeable> T	readOptionalWriteable(Writeable.Reader<T> reader)
ZoneId	readOptionalZoneId()	Read an optional ZoneId.
<K, V> Map<K,V>	readOrderedMap(Writeable.Reader<K> keyReader, Writeable.Reader<V> valueReader)
ReleasableBytesReference	readReleasableBytesReference()	Reads a releasable bytes reference from this stream.
SecureString	readSecureString()
<T> Set<T>	readSet(Writeable.Reader<T> reader)	Reads a set of objects.
short	readShort()
String	readString()
String[]	readStringArray()
List<String>	readStringList()	Reads a list of strings.
Text	readText()
org.elasticsearch.core.TimeValue	readTimeValue()	Read a TimeValue from the stream
org.joda.time.DateTimeZone	readTimeZone()	Read a DateTimeZone.
int	readVInt()	Reads an int stored in variable-length format.
int[]	readVIntArray()
protected int	readVIntSlow()
long	readVLong()	Reads a long stored in variable-length format.
long[]	readVLongArray()
protected long	readVLongSlow()
long	readZLong()
ZoneId	readZoneId()	Read a DateTimeZone.
void	setVersion(Version version)	Set the version of the node on the other side of this stream.
protected static void	throwOnBrokenVInt(byte b, int accumulated)
protected static void	throwOnBrokenVLong(byte b, long accumulated)
static StreamInput	wrap(byte[] bytes)
static StreamInput	wrap(byte[] bytes, int offset, int length)

Methods inherited from class java.io.InputStream

mark, markSupported, nullInputStream, read, read, read, readAllBytes, readNBytes, readNBytes, reset, skip, skipNBytes, transferTo

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

StreamInput

public StreamInput()

Method Details

getVersion

public Version getVersion()

The version of the node on the other side of this stream.

setVersion

public void setVersion(Version version)

Set the version of the node on the other side of this stream.

readByte

public abstract byte readByte()
                       throws IOException

Reads and returns a single byte.

Throws:

IOException

readBytes

public abstract void readBytes(byte[] b,
 int offset,
 int len)
                        throws IOException

Reads a specified number of bytes into an array at the specified offset.

Parameters:

b - the array to read bytes into

offset - the offset in the array to start storing bytes

len - the number of bytes to read

Throws:

IOException

readBytesReference

public BytesReference readBytesReference()
                                  throws IOException

Reads a bytes reference from this stream, copying any bytes read to a new byte[]. Use readReleasableBytesReference() when reading large bytes references where possible top avoid needless allocations and copying.

Throws:

IOException

readReleasableBytesReference

public ReleasableBytesReference readReleasableBytesReference()
                                                      throws IOException

Reads a releasable bytes reference from this stream. Unlike readBytesReference() the returned bytes reference may reference bytes in a pooled buffer and must be explicitly released via ReleasableBytesReference.close() once no longer used. Prefer this method over readBytesReference() when reading large bytes references to avoid allocations and copying.

Throws:

IOException

readOptionalBytesReference

@Nullable
public BytesReference readOptionalBytesReference()
                                          throws IOException

Reads an optional bytes reference from this stream. It might hold an actual reference to the underlying bytes of the stream. Use this only if you must differentiate null from empty. Use readBytesReference() and StreamOutput.writeBytesReference(BytesReference) if you do not.

Throws:

IOException

readBytesReference

public BytesReference readBytesReference(int length)
                                  throws IOException

Reads a bytes reference from this stream, might hold an actual reference to the underlying bytes of the stream.

Throws:

IOException

readBytesRef

public org.apache.lucene.util.BytesRef readBytesRef()
                                             throws IOException

Throws:

IOException

readBytesRef

public org.apache.lucene.util.BytesRef readBytesRef(int length)
                                             throws IOException

Throws:

IOException

readFully

public void readFully(byte[] b)
               throws IOException

Throws:

IOException

readShort

public short readShort()
                throws IOException

Throws:

IOException

readInt

public int readInt()
            throws IOException

Reads four bytes and returns an int.

Throws:

IOException

readOptionalInt

public Integer readOptionalInt()
                        throws IOException

Reads an optional Integer.

Throws:

IOException

readVInt

public int readVInt()
             throws IOException

Reads an int stored in variable-length format. Reads between one and five bytes. Smaller values take fewer bytes. Negative numbers will always use all 5 bytes and are therefore better serialized using readInt()

Throws:

IOException

readVIntSlow

protected final int readVIntSlow()
                          throws IOException

Throws:

IOException

throwOnBrokenVInt

protected static void throwOnBrokenVInt(byte b,
 int accumulated)
                                 throws IOException

Throws:

IOException

readLong

public long readLong()
              throws IOException

Reads eight bytes and returns a long.

Throws:

IOException

readVLong

public long readVLong()
               throws IOException

Reads a long stored in variable-length format. Reads between one and ten bytes. Smaller values take fewer bytes. Negative numbers are encoded in ten bytes so prefer readLong() or readZLong() for negative numbers.

Throws:

IOException

readVLongSlow

protected final long readVLongSlow()
                            throws IOException

Throws:

IOException

throwOnBrokenVLong

protected static void throwOnBrokenVLong(byte b,
 long accumulated)
                                  throws IOException

Throws:

IOException

readOptionalVLong

@Nullable
public Long readOptionalVLong()
                       throws IOException

Throws:

IOException

readZLong

public long readZLong()
               throws IOException

Throws:

IOException

readOptionalLong

@Nullable
public Long readOptionalLong()
                      throws IOException

Throws:

IOException

readBigInteger

public BigInteger readBigInteger()
                          throws IOException

Throws:

IOException

readOptionalText

@Nullable
public Text readOptionalText()
                      throws IOException

Throws:

IOException

readText

public Text readText()
              throws IOException

Throws:

IOException

readOptionalString

@Nullable
public String readOptionalString()
                          throws IOException

Throws:

IOException

readOptionalSecureString

@Nullable
public SecureString readOptionalSecureString()
                                      throws IOException

Throws:

IOException

readOptionalFloat

@Nullable
public Float readOptionalFloat()
                        throws IOException

Throws:

IOException

readOptionalVInt

@Nullable
public Integer readOptionalVInt()
                         throws IOException

Throws:

IOException

readString

public String readString()
                  throws IOException

Throws:

IOException

readSecureString

public SecureString readSecureString()
                              throws IOException

Throws:

IOException

readFloat

public final float readFloat()
                      throws IOException

Throws:

IOException

readDouble

public final double readDouble()
                        throws IOException

Throws:

IOException

readOptionalDouble

@Nullable
public final Double readOptionalDouble()
                                throws IOException

Throws:

IOException

readBoolean

public final boolean readBoolean()
                          throws IOException

Reads a boolean.

Throws:

IOException

readOptionalBoolean

@Nullable
public final Boolean readOptionalBoolean()
                                  throws IOException

Throws:

IOException

close

public abstract void close()
                    throws IOException

Closes the stream to further operations.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Overrides:

close in class InputStream

Throws:

IOException

available

public abstract int available()
                       throws IOException

Overrides:

available in class InputStream

Throws:

IOException

readStringArray

public String[] readStringArray()
                         throws IOException

Throws:

IOException

readOptionalStringArray

@Nullable
public String[] readOptionalStringArray()
                                 throws IOException

Throws:

IOException

readMap

public <K,
V> Map<K,V> readMap(Writeable.Reader<K> keyReader,
 Writeable.Reader<V> valueReader)
                       throws IOException

If the returned map contains any entries it will be mutable. If it is empty it might be immutable.

Throws:

IOException

readOrderedMap

public <K,
V> Map<K,V> readOrderedMap(Writeable.Reader<K> keyReader,
 Writeable.Reader<V> valueReader)
                              throws IOException

Throws:

IOException

readMapOfLists

public <K,
V> Map<K,List<V>> readMapOfLists(Writeable.Reader<K> keyReader,
 Writeable.Reader<V> valueReader)
                                    throws IOException

Read a Map of K-type keys to V-type Lists.

 Map<String, List<String>> map = in.readMapOfLists(StreamInput::readString, StreamInput::readString);
 

If the map or a list in it contains any elements it will be mutable, otherwise either the empty map or empty lists it contains might be immutable.

Parameters:

keyReader - The key reader

valueReader - The value reader

Returns:

Never null.

Throws:

IOException

readMap

@Nullable
public Map<String,Object> readMap()
                           throws IOException

If the returned map contains any entries it will be mutable. If it is empty it might be immutable.

Throws:

IOException

readImmutableMap

public <K,
V> ImmutableOpenMap<K,V> readImmutableMap(Writeable.Reader<K> keyReader,
 Writeable.Reader<V> valueReader)
                                             throws IOException

Read ImmutableOpenMap using given key and value readers.

Parameters:

keyReader - key reader

valueReader - value reader

Throws:

IOException

readGenericValue

@Nullable
public Object readGenericValue()
                        throws IOException

Reads a value of unspecified type. If a collection is read then the collection will be mutable if it contains any entry but might be immutable if it is empty.

Throws:

IOException

readInstant

public final Instant readInstant()
                          throws IOException

Read an Instant from the stream with nanosecond resolution

Throws:

IOException

readOptionalInstant

@Nullable
public final Instant readOptionalInstant()
                                  throws IOException

Read an optional Instant from the stream. Returns null when no instant is present.

Throws:

IOException

readGeoPoint

public GeoPoint readGeoPoint()
                      throws IOException

Reads a GeoPoint from this stream input

Throws:

IOException

readTimeZone

public org.joda.time.DateTimeZone readTimeZone()
                                        throws IOException

Read a DateTimeZone.

Throws:

IOException

readOptionalTimeZone

public org.joda.time.DateTimeZone readOptionalTimeZone()
                                                throws IOException

Read an optional DateTimeZone.

Throws:

IOException

readZoneId

public ZoneId readZoneId()
                  throws IOException

Read a DateTimeZone.

Throws:

IOException

readOptionalZoneId

public ZoneId readOptionalZoneId()
                          throws IOException

Read an optional ZoneId.

Throws:

IOException

readIntArray

public int[] readIntArray()
                   throws IOException

Throws:

IOException

readVIntArray

public int[] readVIntArray()
                    throws IOException

Throws:

IOException

readLongArray

public long[] readLongArray()
                     throws IOException

Throws:

IOException

readVLongArray

public long[] readVLongArray()
                      throws IOException

Throws:

IOException

readFloatArray

public float[] readFloatArray()
                       throws IOException

Throws:

IOException

readDoubleArray

public double[] readDoubleArray()
                         throws IOException

Throws:

IOException

readByteArray

public byte[] readByteArray()
                     throws IOException

Throws:

IOException

readArray

public <T> T[] readArray(Writeable.Reader<T> reader,
 IntFunction<T[]> arraySupplier)
                  throws IOException

Reads an array from the stream using the specified Writeable.Reader to read array elements from the stream. This method can be seen as the reader version of StreamOutput.writeArray(Writeable.Writer, Object[]). It is assumed that the stream first contains a variable-length integer representing the size of the array, and then contains that many elements that can be read from the stream.

Type Parameters:

T - the type of the elements of the array

Parameters:

reader - the reader used to read individual elements

arraySupplier - a supplier used to construct a new array

Returns:

an array read from the stream

Throws:

IOException - if an I/O exception occurs while reading the array

readOptionalArray

public <T> T[] readOptionalArray(Writeable.Reader<T> reader,
 IntFunction<T[]> arraySupplier)
                          throws IOException

Throws:

IOException

readOptionalWriteable

@Nullable
public <T extends Writeable> T readOptionalWriteable(Writeable.Reader<T> reader)
                                              throws IOException

Throws:

IOException

readException

@Nullable
public <T extends Exception> T readException()
                                      throws IOException

Throws:

IOException

namedWriteableRegistry

public NamedWriteableRegistry namedWriteableRegistry()

Get the registry of named writeables if this stream has one, null otherwise.

readNamedWriteable

@Nullable
public <C extends NamedWriteable> C readNamedWriteable(Class<C> categoryClass)
                                                throws IOException

Reads a NamedWriteable from the current stream, by first reading its name and then looking for the corresponding entry in the registry by name, so that the proper object can be read and returned. Default implementation throws UnsupportedOperationException as StreamInput doesn't hold a registry. Use FilterInputStream instead which wraps a stream and supports a NamedWriteableRegistry too.

Throws:

IOException

readNamedWriteable

@Nullable
public <C extends NamedWriteable> C readNamedWriteable(Class<C> categoryClass,
 String name)
                                                throws IOException

Reads a NamedWriteable from the current stream with the given name. It is assumed that the caller obtained the name from other source, so it's not read from the stream. The name is used for looking for the corresponding entry in the registry by name, so that the proper object can be read and returned. Default implementation throws UnsupportedOperationException as StreamInput doesn't hold a registry. Use FilterInputStream instead which wraps a stream and supports a NamedWriteableRegistry too. Prefer readNamedWriteable(Class) and StreamOutput.writeNamedWriteable(NamedWriteable) unless you have a compelling reason to use this method instead.

Throws:

IOException

readOptionalNamedWriteable

@Nullable
public <C extends NamedWriteable> C readOptionalNamedWriteable(Class<C> categoryClass)
                                                        throws IOException

Reads an optional NamedWriteable.

Throws:

IOException

readList

public <T> List<T> readList(Writeable.Reader<T> reader)
                     throws IOException

Reads a list of objects. The list is expected to have been written using StreamOutput.writeList(List). If the returned list contains any entries it will be mutable. If it is empty it might be immutable.

Returns:

the list of objects

Throws:

IOException - if an I/O exception occurs reading the list

readStringList

public List<String> readStringList()
                            throws IOException

Reads a list of strings. The list is expected to have been written using StreamOutput.writeStringCollection(Collection). If the returned list contains any entries it will be mutable. If it is empty it might be immutable.

Returns:

the list of strings

Throws:

IOException - if an I/O exception occurs reading the list

readOptionalStringList

public List<String> readOptionalStringList()
                                    throws IOException

Reads an optional list of strings. The list is expected to have been written using StreamOutput.writeOptionalStringCollection(Collection). If the returned list contains any entries it will be mutable. If it is empty it might be immutable.

Returns:

the list of strings

Throws:

IOException - if an I/O exception occurs reading the list

readSet

public <T> Set<T> readSet(Writeable.Reader<T> reader)
                   throws IOException

Reads a set of objects. If the returned set contains any entries it will be mutable. If it is empty it might be immutable.

Throws:

IOException

readNamedWriteableList

public <T extends NamedWriteable> List<T> readNamedWriteableList(Class<T> categoryClass)
                                                          throws IOException

Reads a list of NamedWriteables. If the returned list contains any entries it will be mutable. If it is empty it might be immutable.

Throws:

IOException

readEnum

public <E extends Enum<E>> E readEnum(Class<E> enumClass)
                               throws IOException

Reads an enum with type E that was serialized based on the value of its ordinal

Throws:

IOException

readOptionalEnum

@Nullable
public <E extends Enum<E>> E readOptionalEnum(Class<E> enumClass)
                                       throws IOException

Reads an optional enum with type E that was serialized based on the value of its ordinal

Throws:

IOException

readEnumSet

public <E extends Enum<E>> EnumSet<E> readEnumSet(Class<E> enumClass)
                                           throws IOException

Reads an enum with type E that was serialized based on the value of it's ordinal

Throws:

IOException

wrap

public static StreamInput wrap(byte[] bytes)

wrap

public static StreamInput wrap(byte[] bytes,
 int offset,
 int length)

readArraySize

protected int readArraySize()
                     throws IOException

Reads a vint via readVInt() and applies basic checks to ensure the read array size is sane. This method uses ensureCanReadBytes(int) to ensure this stream has enough bytes to read for the read array size.

Throws:

IOException

ensureCanReadBytes

protected abstract void ensureCanReadBytes(int length)
                                    throws EOFException

This method throws an EOFException if the given number of bytes can not be read from the this stream. This method might be a no-op depending on the underlying implementation if the information of the remaining bytes is not present.

Throws:

EOFException

readTimeValue

public org.elasticsearch.core.TimeValue readTimeValue()
                                               throws IOException

Read a TimeValue from the stream

Throws:

IOException

readOptionalTimeValue

@Nullable
public org.elasticsearch.core.TimeValue readOptionalTimeValue()
                                                       throws IOException

Read an optional TimeValue from the stream, returning null if no TimeValue was written.

Throws:

IOException