org.openuat.apps
Class BinaryBlockStreamer

java.lang.Object
  org.openuat.apps.BinaryBlockStreamer

public class BinaryBlockStreamer
extends java.lang.Object

This is a helper class for streaming binary blocks over some (byte-safe) connection. It can e.g. be used to stream a file over a TCP connection that has been opened previously. The sender side can prefix the binary block with a name so that the receiver side can distinguish different types of binary blocks in a protocol. This name prefix as well as the length of the following binary block in bytes is prefixing the block itself as a complete line terminated with "\n".

Version:

1.0

Author:

Rene Mayrhofer

Constructor Summary

BinaryBlockStreamer(java.io.InputStream input, java.io.OutputStream output)
Initializes the object with input and/or output.

Method Summary

int	receiveBinaryBlock(java.lang.StringBuffer blockName, java.io.OutputStream block) Receive a binary block from the input that has been passed to the constructor.
void	sendBinaryBlock(java.lang.String blockName, java.io.InputStream block, int size) Send a binary block over the output that has been passed to the constructor.

Methods inherited from class java.lang.Object

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

Constructor Detail

BinaryBlockStreamer

public BinaryBlockStreamer(java.io.InputStream input,
                           java.io.OutputStream output)

Initializes the object with input and/or output. At least one of them must be set.

Parameters:

input - The input from which to read, if this object is to be used for receiving binary blocks from a channel. It can be null, but then output must be set.

output - The output to write to, if this object is to be used for sending binary blocks to a channel. It can be null, but then input must be set.

Method Detail

sendBinaryBlock

public void sendBinaryBlock(java.lang.String blockName,
                            java.io.InputStream block,
                            int size)
                     throws java.io.IOException

Send a binary block over the output that has been passed to the constructor.

Parameters:

blockName - The name that should be prefixed before sending the block.

block - The block itself, represented as InputStream. This stream is read from the beginning.

size - The size of the block to send, i.e. how many bytes of block should be read and sent to output.

Throws:

java.io.IOException - When something does not work as expected, i.e. when the bytes can not be sent, an IOException is thrown (or passed through from the underlying streams).

receiveBinaryBlock

public int receiveBinaryBlock(java.lang.StringBuffer blockName,
                              java.io.OutputStream block)
                       throws java.io.IOException

Receive a binary block from the input that has been passed to the constructor.

Parameters:

blockName - The name of the block that has been received in the prefix. This parameter should point to an empty StringBuffer object, to which the name will be appended (also known as poor/Java man's output parameter).

block - The block itself, represented as OutputStream. This stream is written to.

Returns:

size The number of bytes that have actually been received, if it was possible to receive the number of bytes that the sender of the block specified in its prefix line, If less then this intended number was received, the number of bytes that have been received is returned as a negative number. E.g. when the sender stated that 20 bytes would be sent, but only 15 could be received before an end of file or other read error occured, this method will return -15. In short, any return value >0 indicates an successful receive of the whole block and specifies the number of bytes that have been written to block. Any number <=0 indicates an error.

Throws:

java.io.IOException - When something does not work as expected, i.e. when the bytes can not be received, an IOException is thrown (or passed through from the underlying streams).