Package org.elasticsearch.common.io.stream

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, 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 Summary

Constructors

Constructor	Description
StreamOutput()

Method Summary

Modifier and Type	Method	Description
abstract void	close()	Closes this stream to further operations.
abstract void	flush()	Forces any buffered output to be written.
Version	getVersion()	The version of the node on the other side of this stream.
boolean	hasFeature(String feature)	Test if the stream has the specified feature.
long	position()
abstract void	reset()
void	seek(long position)
void	setFeatures(Set<String> features)	Set the features on the stream.
void	setVersion(Version version)	Set the version of the node on the other side of this stream.
void	write(byte[] b, int off, int len)
void	write(int b)
<T> void	writeArray(Writeable.Writer<T> writer, T[] array)	Writes the specified array to the stream using the specified Writeable.Writer for each element in the array.
<T extends Writeable> void	writeArray(T[] array)	Writes the specified array of Writeables.
void	writeBoolean(boolean b)	Writes a boolean.
abstract void	writeByte(byte b)	Writes a single byte.
void	writeByteArray(byte[] b)	Writes an array of bytes.
void	writeBytes(byte[] b)	Writes an array of bytes.
void	writeBytes(byte[] b, int length)	Writes an array of bytes.
abstract void	writeBytes(byte[] b, int offset, int length)	Writes an array of bytes.
void	writeBytesRef(BytesRef bytes)
void	writeBytesReference(BytesReference bytes)	Writes the bytes reference, including a length header.
void	writeCollection(Collection<? extends Writeable> collection)	Writes a collection to this stream.
<T> void	writeCollection(Collection<T> collection, Writeable.Writer<T> writer)	Writes a collection of objects via a Writeable.Writer.
void	writeDouble(double v)
void	writeDoubleArray(double[] values)
<E extends Enum<E>> void	writeEnum(E enumValue)	Writes an enum with type E based on its ordinal value
<E extends Enum<E>> void	writeEnumSet(EnumSet<E> enumSet)	Writes an EnumSet with type E that by serialized it based on it's ordinal value
void	writeException(Throwable throwable)
void	writeFloat(float v)
void	writeFloatArray(float[] values)
void	writeGenericValue(Object value)	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.
void	writeGeoPoint(GeoPoint geoPoint)	Writes the given GeoPoint to the stream
void	writeInstant(Instant instant)	Writes an Instant to the stream with nanosecond resolution
void	writeInt(int i)	Writes an int as four bytes.
void	writeIntArray(int[] values)
void	writeList(List<? extends Writeable> list)	Writes a list of Writeable objects
void	writeLong(long i)	Writes a long as eight bytes.
void	writeLongArray(long[] values)
void	writeMap(Map<String,Object> map)
<K,V> void	writeMap(Map<K,V> map, Writeable.Writer<K> keyWriter, Writeable.Writer<V> valueWriter)	Write a Map of K-type keys to V-type.
<K,V> void	writeMapOfLists(Map<K,List<V>> map, Writeable.Writer<K> keyWriter, Writeable.Writer<V> valueWriter)	Write a Map of K-type keys to V-type Lists.
void	writeMapWithConsistentOrder(Map<String,? extends Object> map)	write map to stream with consistent order to make sure every map generated bytes order are same.
void	writeNamedWriteable(NamedWriteable namedWriteable)	Writes a NamedWriteable to the current stream, by first writing its name and then the object itself
void	writeNamedWriteableList(List<? extends NamedWriteable> list)	Writes a list of NamedWriteable objects.
<T> void	writeOptionalArray(Writeable.Writer<T> writer, T[] array)	Same as writeArray(Writer, Object[]) but the provided array may be null.
<T extends Writeable> void	writeOptionalArray(T[] array)	Same as writeArray(Writeable[]) but the provided array may be null.
void	writeOptionalBoolean(Boolean b)
void	writeOptionalBytesReference(BytesReference bytes)	Writes an optional bytes reference including a length header.
void	writeOptionalDouble(Double v)
void	writeOptionalFloat(Float floatValue)
void	writeOptionalInstant(Instant instant)	Writes an Instant to the stream, which could possibly be null
void	writeOptionalInt(Integer integer)	Writes an optional Integer.
void	writeOptionalLong(Long l)
void	writeOptionalNamedWriteable(NamedWriteable namedWriteable)	Write an optional NamedWriteable to the stream.
void	writeOptionalSecureString(SecureString secureStr)
void	writeOptionalString(String str)
void	writeOptionalStringArray(String[] array)	Writes a string array, for nullable string, writes false.
void	writeOptionalText(Text text)
void	writeOptionalTimeValue(TimeValue timeValue)	Write an optional TimeValue to the stream.
void	writeOptionalTimeZone(org.joda.time.DateTimeZone timeZone)	Write an optional DateTimeZone to the stream.
void	writeOptionalVInt(Integer integer)
void	writeOptionalWriteable(Writeable writeable)
void	writeOptionalZoneId(ZoneId timeZone)	Write an optional ZoneId to the stream.
void	writeSecureString(SecureString secureStr)
void	writeShort(short v)
void	writeString(String str)
void	writeStringArray(String[] array)
void	writeStringArrayNullable(String[] array)	Writes a string array, for nullable string, writes it as 0 (empty string).
void	writeStringCollection(Collection<String> collection)	Writes a collection of a strings.
void	writeText(Text text)
void	writeTimeValue(TimeValue timeValue)	Write a TimeValue to the stream
void	writeTimeZone(org.joda.time.DateTimeZone timeZone)	Write a DateTimeZone to the stream.
void	writeVInt(int i)	Writes an int in a variable-length format.
void	writeVIntArray(int[] values)
void	writeVLong(long i)	Writes a non-negative long in a variable-length format.
void	writeVLongArray(long[] values)
void	writeZLong(long i)	Writes a long in a variable-length format.
void	writeZoneId(ZoneId timeZone)	Write a ZoneId to the stream.

Methods inherited from class java.io.OutputStream

nullOutputStream, write

Methods inherited from class java.lang.Object

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

Constructor Detail

StreamOutput

public StreamOutput()

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.

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

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(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

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

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

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

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

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(TimeValue timeValue)
                    throws IOException

Write a TimeValue to the stream

Throws:

IOException

writeOptionalTimeValue

public void writeOptionalTimeValue(@Nullable
                                   TimeValue timeValue)
                            throws IOException

Write an optional TimeValue to the stream.

Throws:

IOException