Class StreamInput
org.elasticsearch.common.io.stream.StreamInput
- All Implemented Interfaces:
,
- Direct Known Subclasses:
ByteBufferStreamInput
,FilterStreamInput
,InputStreamStreamInput
public abstract class StreamInput
extends
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 List
s rather than Arrays. For the most part calls should adapt to
lists, either by storing List
s internally or just converting to and from a List
when calling. This comment is repeated
on StreamInput
.-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionabstract int
abstract void
close()
Closes the stream to further operations.protected abstract void
ensureCanReadBytes(int length)
This method throws an if the given number of bytes can not be read from the this stream.The version of the node on the other side of this stream.Get the registry of named writeables if this stream has one,null
otherwise.<T> T[]
readArray(Writeable.Reader<T> reader, <T[]> arraySupplier)
Reads an array from the stream using the specifiedWriteable.Reader
to read array elements from the stream.protected int
Reads a vint viareadVInt()
and applies basic checks to ensure the read array size is sane.boolean
Reads a boolean.abstract byte
readByte()
Reads and returns a single byte.byte[]
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
org.apache.lucene.util.BytesRef
readBytesRef(int length)
Reads a bytes reference from this stream, copying any bytes read to a newbyte[]
.readBytesReference(int length)
Reads a bytes reference from this stream, might hold an actual reference to the underlying bytes of the stream.double
double[]
<E extends <E>>
E<E> enumClass)
Reads an enum with type E that was serialized based on the value of its ordinal<E extends <E>>
<E><E> enumClass)
Reads an enum with type E that was serialized based on the value of it's ordinal<T extends >
Tfloat
float[]
void
readFully(byte[] b)
Reads a value of unspecified type.Reads aGeoPoint
from this stream input<K, V> ImmutableOpenMap<K,V>
readImmutableMap(Writeable.Reader<K> keyReader, Writeable.Reader<V> valueReader)
ReadImmutableOpenMap
using given key and value readers.Read an from the stream with nanosecond resolutionint
readInt()
Reads four bytes and returns an int.int[]
<T> <T>
readList(Writeable.Reader<T> reader)
Reads a list of objects.long
readLong()
Reads eight bytes and returns a long.long[]
<,>
readMap()
If the returned map contains any entries it will be mutable.<K, V> <K,V>
readMap(Writeable.Reader<K> keyReader, Writeable.Reader<V> valueReader)
If the returned map contains any entries it will be mutable.<K, V> <K,<V>>
readMapOfLists(Writeable.Reader<K> keyReader, Writeable.Reader<V> valueReader)
Read a ofK
-type keys toV
-type s.<C extends NamedWriteable>
C<C> categoryClass)
Reads aNamedWriteable
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<C> categoryClass, name)
Reads aNamedWriteable
from the current stream with the given name.<T extends <T>
<T> categoryClass)
Reads a list ofNamedWriteable
s.<T> T[]
readOptionalArray(Writeable.Reader<T> reader, <T[]> arraySupplier)
Reads an optional bytes reference from this stream.<E extends <E>>
E<E> enumClass)
Reads an optional enum with type E that was serialized based on the value of its ordinalRead an optional from the stream.Reads an optional .<C extends NamedWriteable>
C<C> categoryClass)
Reads an optionalNamedWriteable
.[]
<>
Reads an optional list of strings.org.elasticsearch.core.TimeValue
Read an optionalTimeValue
from the stream, returning null if no TimeValue was written.org.joda.time.DateTimeZone
Read an optional DateTimeZone.<T extends Writeable>
TreadOptionalWriteable(Writeable.Reader<T> reader)
Read an optional .<K, V> <K,V>
readOrderedMap(Writeable.Reader<K> keyReader, Writeable.Reader<V> valueReader)
Reads a releasable bytes reference from this stream.<T> <T>
readSet(Writeable.Reader<T> reader)
Reads a set of objects.short
[]
<>
Reads a list of strings.readText()
org.elasticsearch.core.TimeValue
Read aTimeValue
from the streamorg.joda.time.DateTimeZone
Read a DateTimeZone.int
readVInt()
Reads an int stored in variable-length format.int[]
protected int
long
Reads a long stored in variable-length format.long[]
protected long
long
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.
, , , , , , , , , , , ,
Methods inherited from class java.lang.
, , , , , , , , , ,
-
Constructor Details
-
StreamInput
public StreamInput()
-
-
Method Details
-
getVersion
The version of the node on the other side of this stream. -
setVersion
Set the version of the node on the other side of this stream. -
readByte
public abstract byte readByte() throwsReads and returns a single byte.- Throws:
-
readBytes
public abstract void readBytes(byte[] b, int offset, int len) throwsReads a specified number of bytes into an array at the specified offset.- Parameters:
b
- the array to read bytes intooffset
- the offset in the array to start storing byteslen
- the number of bytes to read- Throws:
-
readBytesReference
Reads a bytes reference from this stream, copying any bytes read to a newbyte[]
. UsereadReleasableBytesReference()
when reading large bytes references where possible top avoid needless allocations and copying.- Throws:
-
readReleasableBytesReference
Reads a releasable bytes reference from this stream. UnlikereadBytesReference()
the returned bytes reference may reference bytes in a pooled buffer and must be explicitly released viaReleasableBytesReference.close()
once no longer used. Prefer this method overreadBytesReference()
when reading large bytes references to avoid allocations and copying.- Throws:
-
readOptionalBytesReference
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. UsereadBytesReference()
andStreamOutput.writeBytesReference(BytesReference)
if you do not.- Throws:
-
readBytesReference
Reads a bytes reference from this stream, might hold an actual reference to the underlying bytes of the stream.- Throws:
-
readBytesRef
public org.apache.lucene.util.BytesRef readBytesRef() throws- Throws:
-
readBytesRef
public org.apache.lucene.util.BytesRef readBytesRef(int length) throws- Throws:
-
readFully
public void readFully(byte[] b) throws- Throws:
-
readShort
public short readShort() throws- Throws:
-
readInt
public int readInt() throwsReads four bytes and returns an int.- Throws:
-
readOptionalInt
public readOptionalInt() throwsReads an optional .- Throws:
-
readVInt
public int readVInt() throwsReads 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 usingreadInt()
- Throws:
-
readVIntSlow
protected final int readVIntSlow() throws- Throws:
-
throwOnBrokenVInt
protected static void throwOnBrokenVInt(byte b, int accumulated) throws- Throws:
-
readLong
public long readLong() throwsReads eight bytes and returns a long.- Throws:
-
readVLong
public long readVLong() throwsReads 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 preferreadLong()
orreadZLong()
for negative numbers.- Throws:
-
readVLongSlow
protected final long readVLongSlow() throws- Throws:
-
throwOnBrokenVLong
protected static void throwOnBrokenVLong(byte b, long accumulated) throws- Throws:
-
readOptionalVLong
@Nullable public readOptionalVLong() throws- Throws:
-
readZLong
public long readZLong() throws- Throws:
-
readOptionalLong
@Nullable public readOptionalLong() throws- Throws:
-
readBigInteger
public readBigInteger() throws- Throws:
-
readOptionalText
- Throws:
-
readText
- Throws:
-
readOptionalString
@Nullable public readOptionalString() throws- Throws:
-
readOptionalSecureString
- Throws:
-
readOptionalFloat
@Nullable public readOptionalFloat() throws- Throws:
-
readOptionalVInt
@Nullable public readOptionalVInt() throws- Throws:
-
readString
public readString() throws- Throws:
-
readSecureString
- Throws:
-
readFloat
public final float readFloat() throws- Throws:
-
readDouble
public final double readDouble() throws- Throws:
-
readOptionalDouble
@Nullable public final readOptionalDouble() throws- Throws:
-
readBoolean
public final boolean readBoolean() throwsReads a boolean.- Throws:
-
readOptionalBoolean
@Nullable public final readOptionalBoolean() throws- Throws:
-
close
public abstract void close() throwsCloses the stream to further operations.- Specified by:
in interface
- Specified by:
in interface
- Overrides:
in class
- Throws:
-
available
public abstract int available() throws- Overrides:
in class
- Throws:
-
readStringArray
public [] readStringArray() throws- Throws:
-
readOptionalStringArray
@Nullable public [] readOptionalStringArray() throws- Throws:
-
readMap
public <K, V> <K,V> readMap(Writeable.Reader<K> keyReader, Writeable.Reader<V> valueReader) throwsIf the returned map contains any entries it will be mutable. If it is empty it might be immutable.- Throws:
-
readOrderedMap
public <K, V> <K,V> readOrderedMap(Writeable.Reader<K> keyReader, Writeable.Reader<V> valueReader) throws- Throws:
-
readMapOfLists
public <K, V> <K,<V>> readMapOfLists(Writeable.Reader<K> keyReader, Writeable.Reader<V> valueReader) throwsRead a ofK
-type keys toV
-type s.
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.Map<String, List<String>> map = in.readMapOfLists(StreamInput::readString, StreamInput::readString);
- Parameters:
keyReader
- The key readervalueReader
- The value reader- Returns:
- Never
null
. - Throws:
-
readMap
@Nullable public <,> readMap() throwsIf the returned map contains any entries it will be mutable. If it is empty it might be immutable.- Throws:
-
readImmutableMap
public <K, V> ImmutableOpenMap<K,V> readImmutableMap(Writeable.Reader<K> keyReader, Writeable.Reader<V> valueReader) throwsReadImmutableOpenMap
using given key and value readers.- Parameters:
keyReader
- key readervalueReader
- value reader- Throws:
-
readGenericValue
@Nullable public readGenericValue() throwsReads 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:
-
readInstant
public final readInstant() throwsRead an from the stream with nanosecond resolution- Throws:
-
readOptionalInstant
@Nullable public final readOptionalInstant() throwsRead an optional from the stream. Returnsnull
when no instant is present.- Throws:
-
readGeoPoint
Reads aGeoPoint
from this stream input- Throws:
-
readTimeZone
public org.joda.time.DateTimeZone readTimeZone() throwsRead a DateTimeZone.- Throws:
-
readOptionalTimeZone
public org.joda.time.DateTimeZone readOptionalTimeZone() throwsRead an optional DateTimeZone.- Throws:
-
readZoneId
public readZoneId() throwsRead a DateTimeZone.- Throws:
-
readOptionalZoneId
public readOptionalZoneId() throwsRead an optional .- Throws:
-
readIntArray
public int[] readIntArray() throws- Throws:
-
readVIntArray
public int[] readVIntArray() throws- Throws:
-
readLongArray
public long[] readLongArray() throws- Throws:
-
readVLongArray
public long[] readVLongArray() throws- Throws:
-
readFloatArray
public float[] readFloatArray() throws- Throws:
-
readDoubleArray
public double[] readDoubleArray() throws- Throws:
-
readByteArray
public byte[] readByteArray() throws- Throws:
-
readArray
Reads an array from the stream using the specifiedWriteable.Reader
to read array elements from the stream. This method can be seen as the reader version ofStreamOutput.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 elementsarraySupplier
- a supplier used to construct a new array- Returns:
- an array read from the stream
- Throws:
- if an I/O exception occurs while reading the array
-
readOptionalArray
- Throws:
-
readOptionalWriteable
- Throws:
-
readException
@Nullable public <T extends > T readException() throws- Throws:
-
namedWriteableRegistry
Get the registry of named writeables if this stream has one,null
otherwise. -
readNamedWriteable
@Nullable public <C extends <C> categoryClass) throwsReads aNamedWriteable
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 as StreamInput doesn't hold a registry. Use instead which wraps a stream and supports aNamedWriteableRegistry
too.- Throws:
-
readNamedWriteable
@Nullable public <C extends <C> categoryClass, name) throwsReads aNamedWriteable
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 as StreamInput doesn't hold a registry. Use instead which wraps a stream and supports aNamedWriteableRegistry
too. PreferreadNamedWriteable(Class)
andStreamOutput.writeNamedWriteable(NamedWriteable)
unless you have a compelling reason to use this method instead.- Throws:
-
readOptionalNamedWriteable
@Nullable public <C extends <C> categoryClass) throwsReads an optionalNamedWriteable
.- Throws:
-
readList
Reads a list of objects. The list is expected to have been written usingStreamOutput.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:
- if an I/O exception occurs reading the list
-
readStringList
public <> readStringList() throwsReads a list of strings. The list is expected to have been written usingStreamOutput.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:
- if an I/O exception occurs reading the list
-
readOptionalStringList
public <> readOptionalStringList() throwsReads an optional list of strings. The list is expected to have been written usingStreamOutput.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:
- if an I/O exception occurs reading the list
-
readSet
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:
-
readNamedWriteableList
public <T extends <T> readNamedWriteableList(<T> categoryClass) throwsReads a list ofNamedWriteable
s. If the returned list contains any entries it will be mutable. If it is empty it might be immutable.- Throws:
-
readEnum
public <E extends <E>> E readEnum(<E> enumClass) throwsReads an enum with type E that was serialized based on the value of its ordinal- Throws:
-
readOptionalEnum
@Nullable public <E extends <E>> E readOptionalEnum(<E> enumClass) throwsReads an optional enum with type E that was serialized based on the value of its ordinal- Throws:
-
readEnumSet
public <E extends <E>> <E> readEnumSet(<E> enumClass) throwsReads an enum with type E that was serialized based on the value of it's ordinal- Throws:
-
wrap
-
wrap
-
readArraySize
protected int readArraySize() throwsReads a vint viareadVInt()
and applies basic checks to ensure the read array size is sane. This method usesensureCanReadBytes(int)
to ensure this stream has enough bytes to read for the read array size.- Throws:
-
ensureCanReadBytes
protected abstract void ensureCanReadBytes(int length) throwsThis method throws an 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:
-
readTimeValue
public org.elasticsearch.core.TimeValue readTimeValue() throwsRead aTimeValue
from the stream- Throws:
-
readOptionalTimeValue
@Nullable public org.elasticsearch.core.TimeValue readOptionalTimeValue() throwsRead an optionalTimeValue
from the stream, returning null if no TimeValue was written.- Throws:
-