Class StreamOutput

java.lang.Object
java.io.OutputStream
org.elasticsearch.common.io.stream.StreamOutput
All Implemented Interfaces:
Closeable, Flushable, AutoCloseable
Direct Known Subclasses:
BufferedChecksumStreamOutput, BytesStream, DataOutputStreamOutput, OutputStreamStreamOutput

public abstract class StreamOutput extends OutputStream
A stream from another node to this node. Technically, it can also be streamed from 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 StreamInput. 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

    • StreamOutput

      public StreamOutput()
  • 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.
    • hasFeature

      public boolean hasFeature(String feature)
      Test if the stream has the specified feature. Features are used when serializing ClusterState.Custom or Metadata.Custom; see also ClusterState.FeatureAware.
      Parameters:
      feature - the feature to test
      Returns:
      true if the stream has the specified feature
    • setFeatures

      public void setFeatures(Set<String> features)
      Set the features on the stream. See hasFeature(String).
      Parameters:
      features - the features on the stream
    • getFeatures

      public Set<String> getFeatures()
    • position

      public long position() throws IOException
      Throws:
      IOException
    • seek

      public void seek(long position) throws IOException
      Throws:
      IOException
    • writeByte

      public abstract void writeByte(byte b) throws IOException
      Writes a single byte.
      Throws:
      IOException
    • writeBytes

      public void writeBytes(byte[] b) throws IOException
      Writes an array of bytes.
      Parameters:
      b - the bytes to write
      Throws:
      IOException
    • writeBytes

      public void writeBytes(byte[] b, int length) throws IOException
      Writes an array of bytes.
      Parameters:
      b - the bytes to write
      length - the number of bytes to write
      Throws:
      IOException
    • writeBytes

      public abstract void writeBytes(byte[] b, int offset, int length) throws IOException
      Writes an array of bytes.
      Parameters:
      b - the bytes to write
      offset - the offset in the byte array
      length - the number of bytes to write
      Throws:
      IOException
    • writeByteArray

      public void writeByteArray(byte[] b) throws IOException
      Writes an array of bytes.
      Parameters:
      b - the bytes to write
      Throws:
      IOException
    • writeBytesReference

      public void writeBytesReference(@Nullable BytesReference bytes) throws IOException
      Writes the bytes reference, including a length header.
      Throws:
      IOException
    • writeOptionalBytesReference

      public void writeOptionalBytesReference(@Nullable BytesReference bytes) throws IOException
      Writes an optional bytes reference including a length header. Use this if you need to differentiate between null and empty bytes references. Use writeBytesReference(BytesReference) and StreamInput.readBytesReference() if you do not.
      Throws:
      IOException
    • writeBytesRef

      public void writeBytesRef(org.apache.lucene.util.BytesRef bytes) throws IOException
      Throws:
      IOException
    • writeShort

      public final void writeShort(short v) throws IOException
      Throws:
      IOException
    • writeInt

      public void writeInt(int i) throws IOException
      Writes an int as four bytes.
      Throws:
      IOException
    • writeVInt

      public void writeVInt(int i) throws IOException
      Writes an int in a variable-length format. Writes between one and five bytes. Smaller values take fewer bytes. Negative numbers will always use all 5 bytes and are therefore better serialized using writeInt(int)
      Throws:
      IOException
    • writeLong

      public void writeLong(long i) throws IOException
      Writes a long as eight bytes.
      Throws:
      IOException
    • writeVLong

      public void writeVLong(long i) throws IOException
      Writes a non-negative long in a variable-length format. Writes between one and ten bytes. Smaller values take fewer bytes. Negative numbers use ten bytes and trip assertions (if running in tests) so prefer writeLong(long) or writeZLong(long) for negative numbers.
      Throws:
      IOException
    • writeOptionalVLong

      public void writeOptionalVLong(@Nullable Long l) throws IOException
      Throws:
      IOException
    • writeZLong

      public void writeZLong(long i) throws IOException
      Writes a long in a variable-length format. Writes between one and ten bytes. Values are remapped by sliding the sign bit into the lsb and then encoded as an unsigned number e.g., 0 -;> 0, -1 -;> 1, 1 -;> 2, ..., Long.MIN_VALUE -;> -1, Long.MAX_VALUE -;> -2 Numbers with small absolute value will have a small encoding If the numbers are known to be non-negative, use writeVLong(long)
      Throws:
      IOException
    • writeOptionalLong

      public void writeOptionalLong(@Nullable Long l) throws IOException
      Throws:
      IOException
    • writeOptionalString

      public void writeOptionalString(@Nullable String str) throws IOException
      Throws:
      IOException
    • writeOptionalSecureString

      public void writeOptionalSecureString(@Nullable SecureString secureStr) throws IOException
      Throws:
      IOException
    • writeOptionalInt

      public void writeOptionalInt(@Nullable Integer integer) throws IOException
      Writes an optional Integer.
      Throws:
      IOException
    • writeOptionalVInt

      public void writeOptionalVInt(@Nullable Integer integer) throws IOException
      Throws:
      IOException
    • writeOptionalFloat

      public void writeOptionalFloat(@Nullable Float floatValue) throws IOException
      Throws:
      IOException
    • writeOptionalText

      public void writeOptionalText(@Nullable Text text) throws IOException
      Throws:
      IOException
    • writeText

      public void writeText(Text text) throws IOException
      Throws:
      IOException
    • writeString

      public void writeString(String str) throws IOException
      Throws:
      IOException
    • writeSecureString

      public void writeSecureString(SecureString secureStr) throws IOException
      Throws:
      IOException
    • writeFloat

      public void writeFloat(float v) throws IOException
      Throws:
      IOException
    • writeDouble

      public void writeDouble(double v) throws IOException
      Throws:
      IOException
    • writeOptionalDouble

      public void writeOptionalDouble(@Nullable Double v) throws IOException
      Throws:
      IOException
    • writeBoolean

      public void writeBoolean(boolean b) throws IOException
      Writes a boolean.
      Throws:
      IOException
    • writeOptionalBoolean

      public void writeOptionalBoolean(@Nullable Boolean b) throws IOException
      Throws:
      IOException
    • flush

      public abstract void flush() throws IOException
      Forces any buffered output to be written.
      Specified by:
      flush in interface Flushable
      Overrides:
      flush in class OutputStream
      Throws:
      IOException
    • close

      public abstract void close() throws IOException
      Closes this stream to further operations.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Overrides:
      close in class OutputStream
      Throws:
      IOException
    • reset

      public abstract void reset() throws IOException
      Throws:
      IOException
    • write

      public void write(int b) throws IOException
      Specified by:
      write in class OutputStream
      Throws:
      IOException
    • write

      public void write(byte[] b, int off, int len) throws IOException
      Overrides:
      write in class OutputStream
      Throws:
      IOException
    • writeStringArray

      public void writeStringArray(String[] array) throws IOException
      Throws:
      IOException
    • writeStringArrayNullable

      public void writeStringArrayNullable(@Nullable String[] array) throws IOException
      Writes a string array, for nullable string, writes it as 0 (empty string).
      Throws:
      IOException
    • writeOptionalStringArray

      public void writeOptionalStringArray(@Nullable String[] array) throws IOException
      Writes a string array, for nullable string, writes false.
      Throws:
      IOException
    • writeMap

      public void writeMap(@Nullable Map<String,Object> map) throws IOException
      Throws:
      IOException
    • writeMapWithConsistentOrder

      public void writeMapWithConsistentOrder(@Nullable Map<String,? extends Object> map) throws IOException
      write map to stream with consistent order to make sure every map generated bytes order are same. This method is compatible with StreamInput.readMap and StreamInput.readGenericValue This method only will handle the map keys order, not maps contained within the map
      Throws:
      IOException
    • writeMapOfLists

      public final <K, V> void writeMapOfLists(Map<K,List<V>> map, Writeable.Writer<K> keyWriter, Writeable.Writer<V> valueWriter) throws IOException
      Write a Map of K-type keys to V-type Lists.
      
       Map<String, List<String>> map = ...;
       out.writeMapOfLists(map, StreamOutput::writeString, StreamOutput::writeString);
       
      Parameters:
      keyWriter - The key writer
      valueWriter - The value writer
      Throws:
      IOException
    • writeMap

      public final <K, V> void writeMap(Map<K,V> map, Writeable.Writer<K> keyWriter, Writeable.Writer<V> valueWriter) throws IOException
      Write a Map of K-type keys to V-type.
      
       Map<String, String> map = ...;
       out.writeMap(map, StreamOutput::writeString, StreamOutput::writeString);
       
      Parameters:
      keyWriter - The key writer
      valueWriter - The value writer
      Throws:
      IOException
    • writeMap

      public final <K, V> void writeMap(ImmutableOpenMap<K,V> map, Writeable.Writer<K> keyWriter, Writeable.Writer<V> valueWriter) throws IOException
      Write a ImmutableOpenMap of K-type keys to V-type.
      Parameters:
      keyWriter - The key writer
      valueWriter - The value writer
      Throws:
      IOException
    • writeMap

      public final <K extends Writeable, V extends Writeable> void writeMap(ImmutableOpenMap<K,V> map) throws IOException
      Write a ImmutableOpenMap of K-type keys to V-type.
      Throws:
      IOException
    • writeInstant

      public final void writeInstant(Instant instant) throws IOException
      Writes an Instant to the stream with nanosecond resolution
      Throws:
      IOException
    • writeOptionalInstant

      public final void writeOptionalInstant(@Nullable Instant instant) throws IOException
      Writes an Instant to the stream, which could possibly be null
      Throws:
      IOException
    • writeGenericValue

      public void writeGenericValue(@Nullable Object value) throws IOException
      Notice: when serialization a map, the stream out map with the stream in map maybe have the different key-value orders, they will maybe have different stream order. If want to keep stream out map and stream in map have the same stream order when stream, can use writeMapWithConsistentOrder
      Throws:
      IOException
    • checkWriteable

      public static void checkWriteable(@Nullable Object value) throws IllegalArgumentException
      Throws:
      IllegalArgumentException
    • writeIntArray

      public void writeIntArray(int[] values) throws IOException
      Throws:
      IOException
    • writeVIntArray

      public void writeVIntArray(int[] values) throws IOException
      Throws:
      IOException
    • writeLongArray

      public void writeLongArray(long[] values) throws IOException
      Throws:
      IOException
    • writeVLongArray

      public void writeVLongArray(long[] values) throws IOException
      Throws:
      IOException
    • writeFloatArray

      public void writeFloatArray(float[] values) throws IOException
      Throws:
      IOException
    • writeDoubleArray

      public void writeDoubleArray(double[] values) throws IOException
      Throws:
      IOException
    • writeArray

      public <T> void writeArray(Writeable.Writer<T> writer, T[] array) throws IOException
      Writes the specified array to the stream using the specified Writeable.Writer for each element in the array. This method can be seen as writer version of StreamInput.readArray(Writeable.Reader, IntFunction). The length of array encoded as a variable-length integer is first written to the stream, and then the elements of the array are written to the stream.
      Type Parameters:
      T - the type of the elements of the array
      Parameters:
      writer - the writer used to write individual elements
      array - the array
      Throws:
      IOException - if an I/O exception occurs while writing the array
    • writeOptionalArray

      public <T> void writeOptionalArray(Writeable.Writer<T> writer, @Nullable T[] array) throws IOException
      Same as writeArray(Writer, Object[]) but the provided array may be null. An additional boolean value is serialized to indicate whether the array was null or not.
      Throws:
      IOException
    • writeArray

      public <T extends Writeable> void writeArray(T[] array) throws IOException
      Writes the specified array of Writeables. This method can be seen as writer version of StreamInput.readArray(Writeable.Reader, IntFunction). The length of array encoded as a variable-length integer is first written to the stream, and then the elements of the array are written to the stream.
      Throws:
      IOException
    • writeOptionalArray

      public <T extends Writeable> void writeOptionalArray(@Nullable T[] array) throws IOException
      Same as writeArray(Writeable[]) but the provided array may be null. An additional boolean value is serialized to indicate whether the array was null or not.
      Throws:
      IOException
    • writeOptionalWriteable

      public void writeOptionalWriteable(@Nullable Writeable writeable) throws IOException
      Throws:
      IOException
    • writeException

      public void writeException(Throwable throwable) throws IOException
      Throws:
      IOException
    • writeNamedWriteable

      public void writeNamedWriteable(NamedWriteable namedWriteable) throws IOException
      Writes a NamedWriteable to the current stream, by first writing its name and then the object itself
      Throws:
      IOException
    • writeOptionalNamedWriteable

      public void writeOptionalNamedWriteable(@Nullable NamedWriteable namedWriteable) throws IOException
      Write an optional NamedWriteable to the stream.
      Throws:
      IOException
    • writeGeoPoint

      public void writeGeoPoint(GeoPoint geoPoint) throws IOException
      Writes the given GeoPoint to the stream
      Throws:
      IOException
    • writeTimeZone

      public void writeTimeZone(org.joda.time.DateTimeZone timeZone) throws IOException
      Write a DateTimeZone to the stream.
      Throws:
      IOException
    • writeZoneId

      public void writeZoneId(ZoneId timeZone) throws IOException
      Write a ZoneId to the stream.
      Throws:
      IOException
    • writeOptionalTimeZone

      public void writeOptionalTimeZone(@Nullable org.joda.time.DateTimeZone timeZone) throws IOException
      Write an optional DateTimeZone to the stream.
      Throws:
      IOException
    • writeOptionalZoneId

      public void writeOptionalZoneId(@Nullable ZoneId timeZone) throws IOException
      Write an optional ZoneId to the stream.
      Throws:
      IOException
    • writeCollection

      public void writeCollection(Collection<? extends Writeable> collection) throws IOException
      Writes a collection to this stream. The corresponding collection can be read from a stream input using StreamInput.readList(Writeable.Reader).
      Parameters:
      collection - the collection to write to this stream
      Throws:
      IOException - if an I/O exception occurs writing the collection
    • writeList

      public void writeList(List<? extends Writeable> list) throws IOException
      Writes a list of Writeable objects
      Throws:
      IOException
    • writeCollection

      public <T> void writeCollection(Collection<T> collection, Writeable.Writer<T> writer) throws IOException
      Writes a collection of objects via a Writeable.Writer.
      Parameters:
      collection - the collection of objects
      Throws:
      IOException - if an I/O exception occurs writing the collection
    • writeStringCollection

      public void writeStringCollection(Collection<String> collection) throws IOException
      Writes a collection of a strings. The corresponding collection can be read from a stream input using StreamInput.readList(Writeable.Reader).
      Parameters:
      collection - the collection of strings
      Throws:
      IOException - if an I/O exception occurs writing the collection
    • writeOptionalStringCollection

      public void writeOptionalStringCollection(Collection<String> collection) throws IOException
      Writes an optional collection of a strings. The corresponding collection can be read from a stream input using StreamInput.readList(Writeable.Reader).
      Parameters:
      collection - the collection of strings
      Throws:
      IOException - if an I/O exception occurs writing the collection
    • writeNamedWriteableList

      public void writeNamedWriteableList(List<? extends NamedWriteable> list) throws IOException
      Writes a list of NamedWriteable objects.
      Throws:
      IOException
    • writeEnum

      public <E extends Enum<E>> void writeEnum(E enumValue) throws IOException
      Writes an enum with type E based on its ordinal value
      Throws:
      IOException
    • writeOptionalEnum

      public <E extends Enum<E>> void writeOptionalEnum(@Nullable E enumValue) throws IOException
      Writes an optional enum with type E based on its ordinal value
      Throws:
      IOException
    • writeEnumSet

      public <E extends Enum<E>> void writeEnumSet(EnumSet<E> enumSet) throws IOException
      Writes an EnumSet with type E that by serialized it based on it's ordinal value
      Throws:
      IOException
    • writeTimeValue

      public void writeTimeValue(org.elasticsearch.core.TimeValue timeValue) throws IOException
      Write a TimeValue to the stream
      Throws:
      IOException
    • writeOptionalTimeValue

      public void writeOptionalTimeValue(@Nullable org.elasticsearch.core.TimeValue timeValue) throws IOException
      Write an optional TimeValue to the stream.
      Throws:
      IOException