org.elasticsearch.common.io.stream

Class StreamInput

java.lang.Object

java.io.InputStream

org.elasticsearch.common.io.stream.StreamInput

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

Direct Known Subclasses:

ByteBufferStreamInput, FilterStreamInput, InputStreamStreamInput

public abstract class StreamInput
extends java.io.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 and Description
StreamInput()

Method Summary

Modifier and Type	Method and 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.
<T> T[]	readArray(Writeable.Reader<T> reader, java.util.function.IntFunction<T[]> arraySupplier)
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, might hold an actual reference to the underlying bytes of the stream.
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 java.lang.Enum<E>> E	readEnum(java.lang.Class<E> enumClass) Reads an enum with type E that was serialized based on the value of it's ordinal
<T extends java.lang.Exception> T	readException()
float	readFloat()
float[]	readFloatArray()
void	readFully(byte[] b)
java.lang.Object	readGenericValue()
GeoPoint	readGeoPoint() Reads a GeoPoint from this stream input
int	readInt() Reads four bytes and returns an int.
int[]	readIntArray()
<T> java.util.List<T>	readList(Writeable.Reader<T> reader) Reads a list of objects
long	readLong() Reads eight bytes and returns a long.
long[]	readLongArray()
java.util.Map<java.lang.String,java.lang.Object>	readMap()
<K,V> java.util.Map<K,V>	readMap(Writeable.Reader<K> keyReader, Writeable.Reader<V> valueReader)
<K,V> java.util.Map<K,java.util.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(java.lang.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(java.lang.Class<C> categoryClass, java.lang.String name) Reads a NamedWriteable from the current stream with the given name.
<T extends NamedWriteable> java.util.List<T>	readNamedWriteableList(java.lang.Class<T> categoryClass) Reads a list of NamedWriteables.
<T> T[]	readOptionalArray(Writeable.Reader<T> reader, java.util.function.IntFunction<T[]> arraySupplier)
java.lang.Boolean	readOptionalBoolean()
BytesReference	readOptionalBytesReference() Reads an optional bytes reference from this stream.
java.lang.Double	readOptionalDouble()
java.lang.Float	readOptionalFloat()
java.lang.Long	readOptionalLong()
<C extends NamedWriteable> C	readOptionalNamedWriteable(java.lang.Class<C> categoryClass) Reads an optional NamedWriteable.
<T extends Streamable> T	readOptionalStreamable(java.util.function.Supplier<T> supplier) Serializes a potential null value.
java.lang.String	readOptionalString()
java.lang.String[]	readOptionalStringArray()
Text	readOptionalText()
org.joda.time.DateTimeZone	readOptionalTimeZone() Read an optional DateTimeZone.
java.lang.Integer	readOptionalVInt()
<T extends Writeable> T	readOptionalWriteable(Writeable.Reader<T> reader)
short	readShort()
<T extends Streamable> java.util.List<T>	readStreamableList(java.util.function.Supplier<T> constructor) Read a List of Streamable objects, using the constructor to instantiate each instance.
java.lang.String	readString()
java.lang.String[]	readStringArray()
Text	readText()
org.joda.time.DateTimeZone	readTimeZone() Read a DateTimeZone.
int	readVInt() Reads an int stored in variable-length format.
int[]	readVIntArray()
long	readVLong() Reads a long stored in variable-length format.
long[]	readVLongArray()
long	readZLong()
void	setVersion(Version version) Set the version of the node on the other side of this stream.
static StreamInput	wrap(byte[] bytes)
static StreamInput	wrap(byte[] bytes, int offset, int length)

Methods inherited from class java.io.InputStream

mark, markSupported, read, read, read, reset, skip

Methods inherited from class java.lang.Object

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

Constructor Detail

StreamInput

public StreamInput()

Method Detail

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 java.io.IOException

Reads and returns a single byte.

Throws:

java.io.IOException

readBytes

public abstract void readBytes(byte[] b,
                               int offset,
                               int len)
                        throws java.io.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:

java.io.IOException

readBytesReference

public BytesReference readBytesReference()
                                  throws java.io.IOException

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

Throws:

java.io.IOException

readOptionalBytesReference

@Nullable
public BytesReference readOptionalBytesReference()
                                                    throws java.io.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:

java.io.IOException

readBytesReference

public BytesReference readBytesReference(int length)
                                  throws java.io.IOException

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

Throws:

java.io.IOException

readBytesRef

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

Throws:

java.io.IOException

readBytesRef

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

Throws:

java.io.IOException

readFully

public void readFully(byte[] b)
               throws java.io.IOException

Throws:

java.io.IOException

readShort

public short readShort()
                throws java.io.IOException

Throws:

java.io.IOException

readInt

public int readInt()
            throws java.io.IOException

Reads four bytes and returns an int.

Throws:

java.io.IOException

readVInt

public int readVInt()
             throws java.io.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:

java.io.IOException

readLong

public long readLong()
              throws java.io.IOException

Reads eight bytes and returns a long.

Throws:

java.io.IOException

readVLong

public long readVLong()
               throws java.io.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:

java.io.IOException

readZLong

public long readZLong()
               throws java.io.IOException

Throws:

java.io.IOException

readOptionalLong

@Nullable
public java.lang.Long readOptionalLong()
                                          throws java.io.IOException

Throws:

java.io.IOException

readOptionalText

@Nullable
public Text readOptionalText()
                                throws java.io.IOException

Throws:

java.io.IOException

readText

public Text readText()
              throws java.io.IOException

Throws:

java.io.IOException

readOptionalString

@Nullable
public java.lang.String readOptionalString()
                                              throws java.io.IOException

Throws:

java.io.IOException

readOptionalFloat

@Nullable
public java.lang.Float readOptionalFloat()
                                            throws java.io.IOException

Throws:

java.io.IOException

readOptionalVInt

@Nullable
public java.lang.Integer readOptionalVInt()
                                             throws java.io.IOException

Throws:

java.io.IOException

readString

public java.lang.String readString()
                            throws java.io.IOException

Throws:

java.io.IOException

readFloat

public final float readFloat()
                      throws java.io.IOException

Throws:

java.io.IOException

readDouble

public final double readDouble()
                        throws java.io.IOException

Throws:

java.io.IOException

readOptionalDouble

@Nullable
public final java.lang.Double readOptionalDouble()
                                                    throws java.io.IOException

Throws:

java.io.IOException

readBoolean

public final boolean readBoolean()
                          throws java.io.IOException

Reads a boolean.

Throws:

java.io.IOException

readOptionalBoolean

@Nullable
public final java.lang.Boolean readOptionalBoolean()
                                                      throws java.io.IOException

Throws:

java.io.IOException

close

public abstract void close()
                    throws java.io.IOException

Closes the stream to further operations.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Overrides:

close in class java.io.InputStream

Throws:

java.io.IOException

available

public abstract int available()
                       throws java.io.IOException

Overrides:

available in class java.io.InputStream

Throws:

java.io.IOException

readStringArray

public java.lang.String[] readStringArray()
                                   throws java.io.IOException

Throws:

java.io.IOException

readOptionalStringArray

@Nullable
public java.lang.String[] readOptionalStringArray()
                                                     throws java.io.IOException

Throws:

java.io.IOException

readMap

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

Throws:

java.io.IOException

readMapOfLists

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

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

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

Parameters:

keyReader - The key reader

valueReader - The value reader

Returns:

Never null.

Throws:

java.io.IOException

readMap

@Nullable
public java.util.Map<java.lang.String,java.lang.Object> readMap()
                                                                   throws java.io.IOException

Throws:

java.io.IOException

readGenericValue

@Nullable
public java.lang.Object readGenericValue()
                                            throws java.io.IOException

Throws:

java.io.IOException

readGeoPoint

public GeoPoint readGeoPoint()
                      throws java.io.IOException

Reads a GeoPoint from this stream input

Throws:

java.io.IOException

readTimeZone

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

Read a DateTimeZone.

Throws:

java.io.IOException

readOptionalTimeZone

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

Read an optional DateTimeZone.

Throws:

java.io.IOException

readIntArray

public int[] readIntArray()
                   throws java.io.IOException

Throws:

java.io.IOException

readVIntArray

public int[] readVIntArray()
                    throws java.io.IOException

Throws:

java.io.IOException

readLongArray

public long[] readLongArray()
                     throws java.io.IOException

Throws:

java.io.IOException

readVLongArray

public long[] readVLongArray()
                      throws java.io.IOException

Throws:

java.io.IOException

readFloatArray

public float[] readFloatArray()
                       throws java.io.IOException

Throws:

java.io.IOException

readDoubleArray

public double[] readDoubleArray()
                         throws java.io.IOException

Throws:

java.io.IOException

readByteArray

public byte[] readByteArray()
                     throws java.io.IOException

Throws:

java.io.IOException

readArray

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

Throws:

java.io.IOException

readOptionalArray

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

Throws:

java.io.IOException

readOptionalStreamable

@Nullable
public <T extends Streamable> T readOptionalStreamable(java.util.function.Supplier<T> supplier)
                                                          throws java.io.IOException

Serializes a potential null value.

Throws:

java.io.IOException

readOptionalWriteable

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

Throws:

java.io.IOException

readException

public <T extends java.lang.Exception> T readException()
                                                throws java.io.IOException

Throws:

java.io.IOException

readNamedWriteable

@Nullable
public <C extends NamedWriteable> C readNamedWriteable(java.lang.Class<C> categoryClass)
                                                          throws java.io.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:

java.io.IOException

readNamedWriteable

@Nullable
public <C extends NamedWriteable> C readNamedWriteable(java.lang.Class<C> categoryClass,
                                                                 java.lang.String name)
                                                          throws java.io.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:

java.io.IOException

readOptionalNamedWriteable

@Nullable
public <C extends NamedWriteable> C readOptionalNamedWriteable(java.lang.Class<C> categoryClass)
                                                                  throws java.io.IOException

Reads an optional NamedWriteable.

Throws:

java.io.IOException

readStreamableList

public <T extends Streamable> java.util.List<T> readStreamableList(java.util.function.Supplier<T> constructor)
                                                            throws java.io.IOException

Read a List of Streamable objects, using the constructor to instantiate each instance.

This is expected to take the form: List<MyStreamableClass> list = in.readStreamList(MyStreamableClass::new);

Parameters:

constructor - Streamable instance creator

Returns:

Never null.

Throws:

java.io.IOException - if any step fails

readList

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

Reads a list of objects

Throws:

java.io.IOException

readNamedWriteableList

public <T extends NamedWriteable> java.util.List<T> readNamedWriteableList(java.lang.Class<T> categoryClass)
                                                                    throws java.io.IOException

Reads a list of NamedWriteables.

Throws:

java.io.IOException

readEnum

public <E extends java.lang.Enum<E>> E readEnum(java.lang.Class<E> enumClass)
                                         throws java.io.IOException

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

Throws:

java.io.IOException

wrap

public static StreamInput wrap(byte[] bytes)

wrap

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

ensureCanReadBytes

protected abstract void ensureCanReadBytes(int length)
                                    throws java.io.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:

java.io.EOFException