On this page:
OutputStream in Java
OutputStream class provides a number of overloaded constructors:
The constructors optionally accept the following arguments:
- A communicator instance
- An encoding version
- A flag indicating whether the stream's internal buffer should be allocated as a "direct" buffer.
We recommend supplying a communicator instance. The stream inspects the communicator's settings to configure several of its own default settings, but you can optionally configure these settings manually using methods that we'll describe later.
If you omit an encoding version, the stream uses the default encoding version of the communicator (if provided) or the most recent encoding version.
If a communicator instance is not available at the time you construct the stream, you can optionally supply it later using one of the overloaded
initialize causes the stream to re-initialize its settings based on the configuration of the given communicator.
Use the following method to manually configure the stream:
For instances of Slice classes, the format determines how the slices of an instance are encoded. If the stream is initialized with a communicator, this setting defaults to the value of
com.zeroc.Ice.Default.SlicedFormat, otherwise the setting defaults to the compact format.
Inserting into an
OutputStream in Java
OutputStream provides a number of
write methods that allow you to insert Slice types into the stream.
For example, you can insert a boolean and a sequence of strings into a stream as follows:
Here are the methods for inserting data into a stream:
Member functions are provided for inserting all of the primitive types, as well as sequences of primitive types; these are self-explanatory. The remaining member functions have the following semantics:
void writeType(int tag, type v)
void writeType(int tag, java.util.Optional<Type> v)
void writeTypeSeq(int tag, type v)
void writeTypeSeq(int tag, java.util.Optional<type> v)
Inserts an optional value. Methods that accept
Optionalinstances only insert a value if the argument is non-null and contains a value.
void writeTypeBuffer(java.nio.TypeBuffer v)
Inserts the remaining contents of the given buffer as a sequence. A null value implies an empty sequence.
void rewriteByte(byte v, int dest)
void rewriteBool(boolean v, int dest)
void rewriteInt(int v, int dest)
Overwrites the byte(s) at an existing location in the buffer at the given destination with a value. These methods do not change the current position of the stream.
void writeSize(int sz)
The Ice encoding has a compact representation to indicate size. This function converts the given non-negative integer into the proper encoded representation.
void writeProxy(ObjectPrx v)
Inserts a proxy.
void writeValue(Value v)
Inserts an instance of a Slice class. The Ice encoding for class instances may cause the insertion to be delayed, in which case the stream retains a reference to the given instance and does not insert its state it until
writePendingValuesis invoked on the stream.
void writeEnum(int val, int maxValue)
Writes the integer value of an enumerator. The
maxValueargument represents the highest enumerator value in the enumeration. Consider the following definitions:
The maximum value for
Coloris 2, and the maximum value for
void writeBlob(byte v)
void writeBlob(byte v, int off, int len)
Copies the given blob of bytes directly to the stream's internal buffer without modification.
void writeException(UserException ex)
Inserts a user exception.
void startValue(SlicedData sd)
When marshaling the slices of a class instance, the application must first call
startValue, then marshal the slices, and finally call
endValue. The caller can pass a
SlicedDataobject containing the preserved slices of unknown more-derived types, or null if there are no preserved slices.
void startException(SlicedData sd)
When marshaling the slices of an exception, the application must first call
startException, then marshal the slices, and finally call
endException. The caller can pass a
SlicedDataobject containing the preserved slices of unknown more-derived types, or 0 if there are no preserved slices.
void startSlice(String typeId, int compactId, boolean last)
Starts and ends a slice of class or exception member data. The call to
startSlicemust include the type ID for the current slice, the corresponding compact ID for the type (if any), and a boolean indicating whether this is the last slice of the class instance or exception. The compact ID is only relevant for class instances; pass a negative value to indicate the encoding should use the string type ID.
void startEncapsulation(EncodingVersion encoding, FormatType format
Starts and ends an encapsulation, respectively. The first overloading of
startEncapsulationallows you to specify the encoding version as well as the format to use for any class instances and exceptions marshaled within this encapsulation.
void writeEmptyEncapsulation(EncodingVersion encoding)
Writes an encapsulation having the given encoding version with no encoded data.
void writeEncapsulation(byte v)
Copies the bytes representing an encapsulation from the given array into the stream.
Returns the encoding version currently being used by the stream.
Encodes the state of class instances whose insertion was delayed during
writeValue. With encoding version 1.0, this method must only be called exactly once when non-optional data members or parameters use class types. This method is no-op with encoding version 1.1.
boolean writeOptional(int tag, OptionalFormat fmt)
Prepares the stream to write an optional value with the given tag and format. Returns true if the value should be written, or false otherwise. A return value of false indicates that the encoding version in use by the stream does not support optional values. If this method returns true, the data associated with that optional value must be written next. Optional values must be written in order by tag from least to greatest. The
OptionalFormatenumeration is defined as follows:
Refer to the encoding discussion for more information on the meaning of these values.
void pos(int n)
Returns or changes the stream's current position, respectively.
void endSize(int n)
The encoding for optional values uses a 32-bit integer to hold the size of variable-length types. Calling
startSizewrites a placeholder value for the size and returns the starting position of the size value; after writing the data, call
endSizeto patch the placeholder with the actual size at the given position.
Indicates that marshaling is complete and returns the encoded byte sequence. This member function must only be called once.
void writeSerializable(java.io.Serializable v)
Writes a serializable Java object to the stream.
void resize(int sz)Allocates space for
szmore bytes in the buffer. The stream implementation internally uses this function prior to copying more data into the buffer.