An OutputStream
is created using the following function:
{zcode:java} package Ice; public class Util { public static OutputStream createOutputStream(Communicator communicator); public static OutputStream createOutputStream(Communicator communicator, EncodingVersion version); } {zcode} |
You can optionally specify an encoding version for the stream, otherwise the stream uses the communicator's default encoding version.
The OutputStream
class is shown below.
{zcode:java} package Ice; public interface OutputStream { Communicator communicator(); void writeBool(boolean v); void writeBoolSeq(boolean[] v); void writeByte(byte v); void writeByteSeq(byte[] v); void writeShort(short v); void writeShortSeq(short[] v); void writeInt(int v); void writeIntSeq(int[] v); void writeLong(long v); void writeLongSeq(long[] v); void writeFloat(float v); void writeFloatSeq(float[] v); void writeDouble(double v); void writeDoubleSeq(double[] v); void writeString(String v); void writeStringSeq(String[] v); void writeSize(int sz); void writeProxy(ObjectPrx v); void writeObject(Ice.Object v); void writeEnum(int v, int maxValue); void writeException(UserException ex); void startObject(SlicedData sd); void endObject(); void startException(SlicedData sd); void endException(); void startSlice(String typeId, boolean last); void endSlice(); void startEncapsulation(EncodingVersion encoding, FormatType format); void startEncapsulation(); void endEncapsulation(); EncodingVersion getEncoding(); void writePendingObjects(); boolean writeOptional(int tag, OptionalFormat format); int pos(); void rewrite(int sz, int pos); void startSize(); void endSize(); byte[] finished(); void reset(boolean clearBuffer); void writeSerializable(java.io.Serializable o); void destroy(); } {zcode} |
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 writeSize(int sz)
void writeProxy(Ice.ObjectPrx v)
void writeObject(Ice.Object v)
writePendingObjects
is invoked on the stream.void writeEnum(int val, int maxValue)
Writes the integer value of an enumerator. The maxValue
argument represents the highest enumerator value in the enumeration. Consider the following definitions:
{zcode:slice} enum Color { red, green, blue }; enum Fruit { Apple, Pear=3, Orange }; {zcode} |
The maximum value for Color
is 2, and the maximum value for Fruit
is 4.
void writeException(UserException ex)
UserExceptionWriter
, which allows you to implement your own exception marshaling logic.void startObject(SlicedData sd)
void endObject()
When marshaling the slices of an object, the application must first call startObject
, then marshal the slices, and finally call endObject
. The caller can pass a SlicedData
object containing the preserved slices of unknown more-derived types, or 0 if there are no preserved slices.
void startException(SlicedData sd)
void endException()
startException
, then marshal the slices, and finally call endException
. The caller can pass a SlicedData
object containing the preserved slices of unknown more-derived types, or 0 if there are no preserved slices.void startSlice(String typeId, boolean last)
void endSlice()
startSlice
must include the type ID for the current slice, and a boolean indicating whether this is the last slice of the object or exception.void startEncapsulation(EncodingVersion encoding, FormatType format
)
void startEncapsulation()
void endEncapsulation()
startEncapsulation
allows you to specify the encoding version as well as the format to use for any objects and exceptions marshaled within this encapsulation.EncodingVersion getEncoding()
void writePendingObjects()
writeObject
. This member function must only be called once. For backward compatibility with encoding version 1.0, this function must only be called when non-optional data members or parameters use class types.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 OptionalFormat
enumeration is defined as follows:
{zcode:java} package Ice; enum OptionalFormat { OptionalFormatF1, OptionalFormatF2, OptionalFormatF4, OptionalFormatF8, OptionalFormatSize, OptionalFormatVSize, OptionalFormatFSize, OptionalFormatEndMarker } {zcode} |
Refer to the encoding discussion for more information on the meaning of these values.
int pos()
void rewrite(int sz, int pos)
pos
method returns the stream's current position, and rewrite
allows you to overwrite a 32-bit integer value at the given position in the stream. Calling rewrite
does not change the stream's current position.void startSize()
void endSize()
startSize
writes a placeholder value for the size; after writing the data, call endSize
to patch the placeholder with the actual size.byte[] finished()
void reset(boolean clearBuffer)
clearBuffer
determines whether the stream releases the internal buffer it allocated to hold the encoded data. If clearBuffer
is true, the stream releases the buffer in order to make it eligible for garbage collection. If clearBuffer
is false, the stream retains the buffer to avoid generating unnecessary garbage.void writeSerializable(java.io.Serializable v)
void destroy()
Here is a simple example that demonstrates how to insert a boolean and a sequence of strings into a stream:
{zcode:java} final String[] seq = { "Ice", "rocks!" }; Ice.OutputStream out = Ice.Util.createOutputStream(communicator); try { out.writeBool(true); out.writeStringSeq(seq); byte[] data = out.finished(); } finally { out.destroy(); } {zcode} |