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 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 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, copying any bytes read to a new byte[]. Use readReleasableBytesReference() when reading large bytes references where possible top avoid needless allocations and copying.
      Throws:
      java.io.IOException
    • readReleasableBytesReference

      public ReleasableBytesReference readReleasableBytesReference() throws java.io.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:
      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
    • readOptionalInt

      public java.lang.Integer readOptionalInt() throws java.io.IOException
      Reads an optional Integer.
      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
    • readOptionalVLong

      @Nullable public java.lang.Long readOptionalVLong() throws java.io.IOException
      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
    • readBigInteger

      public java.math.BigInteger readBigInteger() 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
    • readOptionalSecureString

      @Nullable public SecureString readOptionalSecureString() 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
    • readSecureString

      public SecureString readSecureString() 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.lang.AutoCloseable
      Specified by:
      close in interface java.io.Closeable
      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
      If the returned map contains any entries it will be mutable. If it is empty it might be immutable.
      Throws:
      java.io.IOException
    • readOrderedMap

      public <K,​ V> java.util.Map<K,​V> readOrderedMap​(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);
       
      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:
      java.io.IOException
    • readMap

      @Nullable public java.util.Map<java.lang.String,​java.lang.Object> readMap() throws java.io.IOException
      If the returned map contains any entries it will be mutable. If it is empty it might be immutable.
      Throws:
      java.io.IOException
    • readImmutableMap

      public <K,​ V> ImmutableOpenMap<K,​V> readImmutableMap​(Writeable.Reader<K> keyReader, Writeable.Reader<V> valueReader) throws java.io.IOException
      Read ImmutableOpenMap using given key and value readers.
      Parameters:
      keyReader - key reader
      valueReader - value reader
      Throws:
      java.io.IOException
    • readGenericValue

      @Nullable public java.lang.Object readGenericValue() throws java.io.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:
      java.io.IOException
    • readInstant

      public final java.time.Instant readInstant() throws java.io.IOException
      Read an Instant from the stream with nanosecond resolution
      Throws:
      java.io.IOException
    • readOptionalInstant

      @Nullable public final java.time.Instant readOptionalInstant() throws java.io.IOException
      Read an optional Instant from the stream. Returns null when no instant is present.
      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
    • readZoneId

      public java.time.ZoneId readZoneId() throws java.io.IOException
      Read a DateTimeZone.
      Throws:
      java.io.IOException
    • readOptionalZoneId

      public java.time.ZoneId readOptionalZoneId() throws java.io.IOException
      Read an optional ZoneId.
      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
      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:
      java.io.IOException - if an I/O exception occurs while reading the array
    • readOptionalArray

      public <T> T[] readOptionalArray​(Writeable.Reader<T> reader, java.util.function.IntFunction<T[]> arraySupplier) throws java.io.IOException
      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

      @Nullable public <T extends java.lang.Exception> T readException() throws java.io.IOException
      Throws:
      java.io.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​(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
    • readList

      public <T> java.util.List<T> readList​(Writeable.Reader<T> reader) throws java.io.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:
      java.io.IOException - if an I/O exception occurs reading the list
    • readStringList

      public java.util.List<java.lang.String> readStringList() throws java.io.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:
      java.io.IOException - if an I/O exception occurs reading the list
    • readOptionalStringList

      public java.util.List<java.lang.String> readOptionalStringList() throws java.io.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:
      java.io.IOException - if an I/O exception occurs reading the list
    • readSet

      public <T> java.util.Set<T> readSet​(Writeable.Reader<T> reader) throws java.io.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:
      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. If the returned list contains any entries it will be mutable. If it is empty it might be immutable.
      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 its ordinal
      Throws:
      java.io.IOException
    • readOptionalEnum

      @Nullable public <E extends java.lang.Enum<E>> E readOptionalEnum​(java.lang.Class<E> enumClass) throws java.io.IOException
      Reads an optional enum with type E that was serialized based on the value of its ordinal
      Throws:
      java.io.IOException
    • readEnumSet

      public <E extends java.lang.Enum<E>> java.util.EnumSet<E> readEnumSet​(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)
    • readArraySize

      protected int readArraySize() throws java.io.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:
      java.io.IOException
    • 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
    • readTimeValue

      public org.elasticsearch.common.unit.TimeValue readTimeValue() throws java.io.IOException
      Read a TimeValue from the stream
      Throws:
      java.io.IOException
    • readOptionalTimeValue

      @Nullable public org.elasticsearch.common.unit.TimeValue readOptionalTimeValue() throws java.io.IOException
      Read an optional TimeValue from the stream, returning null if no TimeValue was written.
      Throws:
      java.io.IOException