Class 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 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
      • 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
      • 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
      • 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
      • 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
      • 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

        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
      • 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
      • 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
      • 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)
      • 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 TimeValue readTimeValue()
                                throws java.io.IOException
        Read a TimeValue from the stream
        Throws:
        java.io.IOException
      • readOptionalTimeValue

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