com.netflix.msl.msg
Class MessageOutputStream

java.lang.Object
  java.io.OutputStream
      com.netflix.msl.msg.MessageOutputStream

All Implemented Interfaces:

Closeable, Flushable

public class MessageOutputStream
extends OutputStream

A MSL message consists of a single MSL header followed by one or more payload chunks carrying application data. Each payload chunk is individually packaged but sequentially ordered. The end of the message is indicated by a payload with no data.

No payload chunks may be included in an error message.

Data is buffered until flush() or close() is called. At that point a new payload chunk is created and written out. Closing a MessageOutputStream does not close the destination output stream in case additional MSL messages will be written.

A copy of the payload chunks is kept in-memory and can be retrieved by a a call to getPayloads() until stopCaching() is called. This is used to facilitate automatic re-sending of messages.

Field Summary

private boolean	caching True if caching data.
private MessageCapabilities	capabilities Message output stream capabilities.
private Charset	charset Output stream character set encoding.
private boolean	closed Stream is closed.
private boolean	closeDestination True if the destination output stream should be closed.
private MslConstants.CompressionAlgorithm	compressionAlgo Paload chunk compression algorithm.
private ICryptoContext	cryptoContext Payload crypto context.
private ByteArrayOutputStream	currentPayload Current payload chunk data.
private OutputStream	destination Destination output stream.
private Header	header Header.
private List<PayloadChunk>	payloads Ordered list of sent payloads.
private long	payloadSequenceNumber Current payload sequence number.

Constructor Summary

MessageOutputStream(MslContext ctx, OutputStream destination, Charset charset, ErrorHeader header)
Construct a new error message output stream.

MessageOutputStream(MslContext ctx, OutputStream destination, Charset charset, MessageHeader header, ICryptoContext cryptoContext)
Construct a new message output stream.

Method Summary

void	close()
void	closeDestination(boolean close) By default the destination output stream is not closed when this message output stream is closed.
protected void	finalize()
void	flush() Flush any buffered data out to the destination.
ErrorHeader	getErrorHeader()
MessageHeader	getMessageHeader()
(package private) List<PayloadChunk>	getPayloads() Returns the payloads sent so far.
boolean	setCompressionAlgorithm(MslConstants.CompressionAlgorithm compressionAlgo) Set the payload chunk compression algorithm that will be used for all future payload chunks.
(package private) void	stopCaching() Turns off caching of any message data (e.g.
void	write(byte[] b)
void	write(byte[] b, int off, int len)
void	write(int b)

Methods inherited from class java.lang.Object

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

Field Detail

destination

private final OutputStream destination

Destination output stream.

charset

private final Charset charset

Output stream character set encoding.

capabilities

private final MessageCapabilities capabilities

Message output stream capabilities.

header

private final Header header

Header.

cryptoContext

private final ICryptoContext cryptoContext

Payload crypto context.

compressionAlgo

private MslConstants.CompressionAlgorithm compressionAlgo

Paload chunk compression algorithm.

payloadSequenceNumber

private long payloadSequenceNumber

Current payload sequence number.

currentPayload

private ByteArrayOutputStream currentPayload

Current payload chunk data.

closed

private boolean closed

Stream is closed.

closeDestination

private boolean closeDestination

True if the destination output stream should be closed.

caching

private boolean caching

True if caching data.

payloads

private final List<PayloadChunk> payloads

Ordered list of sent payloads.

Constructor Detail

MessageOutputStream

public MessageOutputStream(MslContext ctx,
                           OutputStream destination,
                           Charset charset,
                           ErrorHeader header)
                    throws IOException

Construct a new error message output stream. The header is output immediately by calling #flush() on the destination output stream.

Parameters:

ctx - the MSL context.

destination - MSL output stream.

charset - output stream character set encoding.

header - error header.

Throws:

IOException - if there is an error writing the header.

MessageOutputStream

public MessageOutputStream(MslContext ctx,
                           OutputStream destination,
                           Charset charset,
                           MessageHeader header,
                           ICryptoContext cryptoContext)
                    throws IOException

Construct a new message output stream. The header is output immediately by calling #flush() on the destination output stream. The most preferred compression algorithm supported by the local entity and message header will be used.

Parameters:

ctx - the MSL context.

destination - MSL output stream.

charset - output stream character set encoding.

header - message header.

cryptoContext - payload data crypto context.

Throws:

IOException - if there is an error writing the header.

Method Detail

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable

setCompressionAlgorithm

public boolean setCompressionAlgorithm(MslConstants.CompressionAlgorithm compressionAlgo)
                                throws IOException

Set the payload chunk compression algorithm that will be used for all future payload chunks. This function will flush any buffered data iff the compression algorithm is being changed.

Parameters:

compressionAlgo - payload chunk compression algorithm. Null for no compression.

Returns:

true if the compression algorithm is supported by the message, false if it is not.

Throws:

IOException - if buffered data could not be flushed. The compression algorithm will be unchanged.

MslInternalException - if writing an error message.

See Also:

flush()

getMessageHeader

public MessageHeader getMessageHeader()

Returns:

the message header. Will be null for error messages.

getErrorHeader

public ErrorHeader getErrorHeader()

Returns:

the error header. Will be null except for error messages.

getPayloads

List<PayloadChunk> getPayloads()

Returns the payloads sent so far. Once payload caching is turned off this list will always be empty.

Returns:

an immutable ordered list of the payloads sent so far.

stopCaching

void stopCaching()

Turns off caching of any message data (e.g. payloads).

closeDestination

public void closeDestination(boolean close)

By default the destination output stream is not closed when this message output stream is closed. If it should be closed then this method can be used to dictate the desired behavior.

Parameters:

close - true if the destination output stream should be closed, false if it should not.

close

public void close()
           throws IOException

Specified by:

close in interface Closeable

Overrides:

close in class OutputStream

Throws:

IOException

flush

public void flush()
           throws IOException

Flush any buffered data out to the destination. This creates a payload chunk. If there is no buffered data or this is an error message this function does nothing.

Specified by:

flush in interface Flushable

Overrides:

flush in class OutputStream

Throws:

IOException - if buffered data could not be flushed.

MslInternalException - if writing an error message.

See Also:

OutputStream.flush()

write

public void write(byte[] b,
                  int off,
                  int len)
           throws IOException

Overrides:

write in class OutputStream

Throws:

IOException

write

public void write(byte[] b)
           throws IOException

Overrides:

write in class OutputStream

Throws:

IOException

write

public void write(int b)
           throws IOException

Specified by:

write in class OutputStream

Throws:

IOException