SerializeOutputStream (class)
public SerializeOutputStream {inherits {OutputStream-of any}}
Package: CURL.IO.SERIALIZE

An output stream which serializes into a byte stream.


Constructors
default:Create an output stream for serialization.
constructor public {SerializeOutputStream.default
    raw-byte-stream:ByteOutputStream,
    close-stream-on-close?:bool = true,
    known-values:#FastArray = null,
    protocol:SerializeProtocol = {this-class}.default-protocol
}
Properties
known-values:Set of known values
accessor public inline SerializeOutputStream.known-values:#FastArray
open?:Indicate if this Stream is currently open, should return false once Stream-of.close has been called.
accessor public SerializeOutputStream.open?:bool
origin-url:Returns the Url that this stream was opened from, or null, if no such Url exists.
accessor public SerializeOutputStream.origin-url:#Url
protocol:Serialization protocol used by this stream.
accessor public inline SerializeOutputStream.protocol:SerializeProtocol
raw-byte-stream:Gets a raw byte stream for customized serialization.
accessor public SerializeOutputStream.raw-byte-stream:ByteOutputStream
Properties inherited from Stream-of: non-blocking-supported?
Class Variables and Constants
default-protocol:Default serialization protocol
public SerializeOutputStream.default-protocol:any =SerializeProtocol.version-6-0
Methods
clear-shared-object-table:Clears the table that tracks shared objects.
public {SerializeOutputStream.clear-shared-object-table}:void
close:Close Stream, should make stream un-usable and make sure that Stream-of.open? return false once this has been called.
public {SerializeOutputStream.close}:void
do-not-share-next:Do not share the next object written.
public {SerializeOutputStream.do-not-share-next}:void
flush:Flushes any buffered output that self may have collected.
public {SerializeOutputStream.flush
    non-blocking?:bool = false,
    allow-short-write?:bool = false
}:void
get-package-locator:Gets additional location information for a package.
public {SerializeOutputStream.get-package-locator
    package:Package
}:#String
reopen:Reopen this stream after it has been closed.
public {SerializeOutputStream.reopen
    raw-byte-stream:ByteOutputStream,
    close-stream-on-close?:bool = true,
    known-values:#FastArray = self.known-values,
    protocol:SerializeProtocol = self.protocol
}:void
write-class-version:Writes out a class version.
public {SerializeOutputStream.write-class-version version:int}:void
write-one:Serializes a value into the stream.
public {SerializeOutputStream.write-one val:any}:void
write-one-compact:Write value using compact representation.
public {SerializeOutputStream.write-one-compact
    val:any,
    compile-time-type:Type
}:void
write-protocol:Writes protocol number at head of serialization stream.
public inline {SerializeOutputStream.write-protocol}:void
Methods inherited from OutputStream-of: async-write, write
Methods inherited from Stream-of: verify-open
Methods inherited from Object: object-describe, object-describe-for-debugging, object-serialize

Constructor Details
default (constructor)
public {SerializeOutputStream.default
    raw-byte-stream:ByteOutputStream,
    close-stream-on-close?:bool = true,
    known-values:#FastArray = null,
    protocol:SerializeProtocol = {this-class}.default-protocol
}

Create an output stream for serialization.

raw-byte-stream: The byte stream to which serialized objects will be written.
close-stream-on-close?: If true (the default), then the byte stream raw-byte-stream will be closed when this stream is closed.
known-values: specifies an optional list of known pointer values that will be serialized simply using their index in this array. The SerializeInputStream must be open with the same array.

All values other than procs and class instances will be ignored. The entire array will be ignored under SerializeProtocol version-4-0.
protocol: specifies the serialization protocol to use. This only needs to be specified when writing out data that may be read by code running under the 4.0 or 5.0 API of Curl.

Generally speaking, older protocols will be slower and less compressed than newer ones.

See SerializeProtocol for more details.

Notes

A ByteOutputStream can be created from a ByteArray by using the ByteArrayOutputStream class.

Property Details
known-values (accessor)
accessor public inline SerializeOutputStream.known-values:#FastArray

Set of known values

Description

This is the known-values array that was last given to the default constructor or reopen method.
Introduced in: version 6.0

open? (accessor)
accessor public SerializeOutputStream.open?:bool

Indicate if this Stream is currently open, should return false once Stream-of.close has been called.

Notes

Used by default implementations in InputStream-of and OutputStream-of to error out from many operations if stream is not open.

Overriding

Subclasses must provide this.

origin-url (accessor)
accessor public SerializeOutputStream.origin-url:#Url

Returns the Url that this stream was opened from, or null, if no such Url exists.

Example

{read-open {url "file://c:/foo.txt"}}.origin-url would return the Url file://c:/foo.txt (assuming such a file exists).

On the other hand, {{TextInputStream-from String} "foo"}.origin-url would return null.

protocol (accessor)
accessor public inline SerializeOutputStream.protocol:SerializeProtocol

Serialization protocol used by this stream.

Description

This is set on construction or on reopen.
Introduced in: version 6.0

raw-byte-stream (accessor)
accessor public SerializeOutputStream.raw-byte-stream:ByteOutputStream

Gets a raw byte stream for customized serialization.


Class Variable and Constant Details
default-protocol (class variable)
public SerializeOutputStream.default-protocol:any =SerializeProtocol.version-6-0

Default serialization protocol

Description

Identifies the default serialization protocol for output streams. This may be overridden when constructing or reopening the stream.

See SerializeProtocol.
Introduced in: version 6.0

Method Details
clear-shared-object-table (method)
public {SerializeOutputStream.clear-shared-object-table}:void

Clears the table that tracks shared objects.

Description

Clears the table of temporary interned procs and class instances. A call to this method will insert a code into the serialization stream indicating that the table should be cleared during deserialization as well.

You can use this to save space when a large number of objects have been serialized and most of them will not be serialized again.

See SerializeCode.clear-temporary and SerializeCode.interned-temporary for details on the underlying implementation.

close (method)
public {SerializeOutputStream.close}:void

Close Stream, should make stream un-usable and make sure that Stream-of.open? return false once this has been called.

Notes

This calls OutputStream-of.flush before closing the stream.

Overriding

Implementors of this should call OutputStream-of.flush in a try block, with the code to close the stream in the finally part of the try block.

do-not-share-next (method)
public {SerializeOutputStream.do-not-share-next}:void

Do not share the next object written.

Description

This prevents the next value to be written from being shared in the temporary interning table.

There are two occasions to use this:

  1. When the object to be serialized is a container, such as an array, which you want to serialize multiple times with different contents. Without using this method only the original contents would ever be serialized.
    For example:
    def out = {SerializeOutputStream byte-stream}
def array = {Array 1,2,3}
{out.do-not-share-next}
{out.write-one array}

{array.clear}
{array.append 4}
{array.append 5}
{array.append 6}

{out.do-not-share-next}
{out.write-one array}
  2. When a very large number of unique objects need to be serialized. In this case, the overhead of sharing the objects can hamper performance.
    For example:
    def out = {SerializeOutputStream byte-stream}
{for obj in many-unique-objs do
    {out.do-not-share-next}
    {out.write-one obj}
}


This has no effect when protocol is set to version-4-0.
Introduced in: version 6.0

flush (method)
public {SerializeOutputStream.flush
    non-blocking?:bool = false,
    allow-short-write?:bool = false
}:void

Flushes any buffered output that self may have collected.

Overriding

Must be provided by non-abstract subclasses. Implementers should probably include code like: 
{if not self.open? then
    {throw {new IOException, {format "%s not open", self}}}
}
at the top of their implementations of this method.

Throws

IOException — If the data can not be written due to such problems as a full disk.

get-package-locator (method)
public {SerializeOutputStream.get-package-locator
    package:Package
}:#String

Gets additional location information for a package.

Description

When a package is serialized, this method will be called to provide an optional locator that can be used during deserialization to help locate a package. The locator value will be processed by SerializeInputStream.import-package to help resolve the package location.

The default implementation always returns null.

reopen (method)
public {SerializeOutputStream.reopen
    raw-byte-stream:ByteOutputStream,
    close-stream-on-close?:bool = true,
    known-values:#FastArray = self.known-values,
    protocol:SerializeProtocol = self.protocol
}:void

Reopen this stream after it has been closed.

Description

Allows the stream to be reused after it has been closed.

The arguments are the same as used for the default constructor and this is semantically equivalent to constructing a new stream with the given arguments.

Both protocol and known-values will default to their existing values.

write-class-version (method)
public {SerializeOutputStream.write-class-version version:int}:void

Writes out a class version.

version: The version to be written.

Description

This is used in object-serialize methods to write out a version number that can be used by the matching object-deserialize constructor to recognize and support older serialization formats for the class.

write-one (method)
public {SerializeOutputStream.write-one val:any}:void

Serializes a value into the stream.

Description

Serializes the provided value to the underlying raw-byte-stream. This will involve writing one or more SerializeCode values followed by the serialized value. See SerializeCode for details.

Values written by this method should be read using SerializeInputStream.read-one.

Also see write-one.

write-one-compact (method)
public {SerializeOutputStream.write-one-compact
    val:any,
    compile-time-type:Type
}:void

Write value using compact representation.

compile-time-type: is a supertype of the type of val, which is typically the declared type of the variable or field passed to the function. This same type must be given to SerializeInputStream.read-one-compact to read the value.

When SerializeOutputStream.protocol is set to version-4-0 then this produces the same output as write-one.
Introduced in: version 6.0

write-protocol (method)
public inline {SerializeOutputStream.write-protocol}:void

Writes protocol number at head of serialization stream.

Description

This writes the value of the SerializeProtocol specified when opening the stream, if it has not already been written.

This is written automatically by write-one and write-one-compact and only needs to be invoked when using other methods to write to the underlying stream when the above methods may not yet have been called.
Introduced in: version 6.0