Iceberg (Randolf's Java library)

Object
- ca.randolf.net.cs.Iceberg

public class Iceberg
extends Object

The Iceberg class is the encapsulation of a portion of data, similar to a frame (or packet) of data (which is normally stored in compressed form).

The format is as follows:

       3                   2
     1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6
    +---------------+-+-+-+-+-+-+-+-+
    |                               |
    |  River ID; -31,768 to 32,767  |          1
    |                               |5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
    +-+-+---------------------------+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    | | |                                                           |
    |C|F|   Length of data section, in bytes; 0 to 1,073,741,823    |
    | | |                                                           |
    +-+-+-----------------------------------------------------------+
    |                                                               |
    ///   Data (number of 8-bit bytes defined by Length field)    ///
    |                                                               |
    +---------------------------------------------------------------+

    River ID:  The River that this data is assigned to

    C:  Compression flag (indicates whether the Data is compressed)

    F:  Functional flag, in which case the Data section contains not Data,
        but some "Functional" information that must not be regarded as Data,
        and which begins with a bytecode followed by any necessary data (see
        the static final bytes in the Iceberg.Constants class for details).

    Length:  Size of Data (number of 8-bit bytes in Data section; if the data
             is compressed, then this field indicates the compressed size)

    Data:  The binary data (if the "C" flag is set, the data is compressed)

See Also:: ca.randolf.net.Iceberg.Constants

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`Iceberg.Constants` Iceberg.Constants class provides sets of various constants used in the implementation of the protocol.

Constructor Summary

Constructors
Constructor and Description
`Iceberg(byte... rawData)` Instantiation of newly-received data (inbound). The River ID, flags, and data are extracted on-the-fly, and an Exception is thrown only if a problem with the data is encountered.
`Iceberg(java.io.InputStream is)` Instantiation of newly-received data (inbound). The River ID, flags, and data are extracted on-the-fly, and an Exception is thrown only if a problem with the data is encountered.
`Iceberg(short id, boolean functional, byte... data)` Instantiation of data to be sent, with the option of flagging it as Functional so that it will be received out-of-band from regular Data.
`Iceberg(short id, boolean functional, byte[]... data)` Instantiation of data to be sent, with the option of flagging it as Functional so that it will be received out-of-band from regular Data.
`Iceberg(short id, byte... data)` Instantiation of data to be sent. The data will be compressed if compression results in reducing the total size of the data.
`Iceberg(short id, byte[]... data)` Instantiation of data to be sent. The data will be compressed if compression results in reducing the total size of the data.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`equals(Object obj)` Compares this object to the specified object. The result is TRUE if and only if the argument is not NULL and is another Iceberg object that contains the same River ID and Data as this object. If the Data section is compressed in only one of the Icebergs being compared, the decompressed forms of the data will be compared.
`byte[]`	`getData()` Returns only the Data section; you need to use the isCompressed() method to determine whether the data is compressed.
`byte`	`getFn()` Returns the first byte of the Data section. This is primarily useful for obtaining the bytecode for Functional data.
`byte[]`	`getFnData()` Returns all except the first byte of the Data section. This is needed obtain the Functional data without its leading Bytecode.
`short`	`getRiverID()` Returns the River ID number that this Iceberg belongs to.
`boolean`	`hasData()` Indicates whether this Iceberg contains at least one byte of data.
`boolean`	`isCompressed()` Indicates whether the data stored internally is compressed.
`boolean`	`isData()` Indicates whether this Iceberg is data.
`boolean`	`isFunctional()` Indicates whether this Iceberg is functional.
`static Iceberg`	`NULL()` Instantiation of zero-byte packet to be sent.
`Iceberg`	`setData(byte... data)` Creates a new Iceberg based on the current one, but with a new Data section stored internally in compressed form if it can be compressed.
`int`	`size()` Returns the total number of 8-bit bytes of data, in its compressed form (if it is compressed).
`int`	`sizeOriginal()` Returns the total number of 8-bit bytes of data, according to the header (a.k.a., in its compressed form if it arrived in compressed form).
`byte[]`	`toBytes()` Returns all headers (which includes the River ID, flags, and Length field), followed immediately by the Data section, ready for sending to a remote host.
`String`	`toString()` Provide debug-readable output version of this object.
`boolean`	`wasCompressed()` Indicates whether the data stored internally was ever compressed.
`int`	`writeToStream(java.io.OutputStream out)` Outputs all headers (which includes the River ID, flags, and Length field), followed immediately by the Data section, to the specifed OutputStream object (which can optionally be a RiverOutputStream object).

Methods inherited from class Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - Iceberg
```
public Iceberg(byte... rawData)
        throws IcebergException
```
    Instantiation of newly-received data (inbound). The River ID, flags, and data are extracted on-the-fly, and an Exception is thrown only if a problem with the data is encountered.
    
    Parameters:
    
    rawData - Full data, which includes River ID, flags, and length
    
    Throws:
    
    IcebergException - If the Iceberg is damaged (e.g., if a problem is detected in the header fields or with the data's integrity)
  - Iceberg
```
public Iceberg(java.io.InputStream is)
        throws java.io.IOException,
               IcebergException
```
    Instantiation of newly-received data (inbound). The River ID, flags, and data are extracted on-the-fly, and an Exception is thrown only if a problem with the data is encountered.
    
    Parameters:
    
    is - The InputStream to read the next Iceberg from
    
    Throws:
    
    java.io.IOException - If an error occurs reading the Stream
    
    IcebergException - If the Iceberg is damaged (e.g., if a problem is detected in the header fields or with the data's integrity)
  - Iceberg
```
public Iceberg(short id,
               boolean functional,
               byte... data)
```
    Instantiation of data to be sent, with the option of flagging it as Functional so that it will be received out-of-band from regular Data.
    
    Parameters:
    
    id - River ID number
    
    functional - TRUE=Functional, FALSE=Data
    
    data - Any number of bytes of data that is not compressed
  - Iceberg
```
public Iceberg(short id,
               boolean functional,
               byte[]... data)
```
    Instantiation of data to be sent, with the option of flagging it as Functional so that it will be received out-of-band from regular Data.
    
    Parameters:
    
    id - River ID number
    
    functional - TRUE=Functional, FALSE=Data
    
    data - Any number of byte arrays of data that is not compressed
  - Iceberg
```
public Iceberg(short id,
               byte... data)
```
    Instantiation of data to be sent. The data will be compressed if compression results in reducing the total size of the data.
    
    Parameters:
    
    id - River ID number
    
    data - Any number of bytes of data that is not already compressed
  - Iceberg
```
public Iceberg(short id,
               byte[]... data)
```
    Instantiation of data to be sent. The data will be compressed if compression results in reducing the total size of the data.
    
    Parameters:
    
    id - River ID number
    
    data - Any number of byte arrays of data that is not already compressed
- Method Detail
  - equals
```
public boolean equals(Object obj)
```
    Compares this object to the specified object. The result is TRUE if and only if the argument is not NULL and is another Iceberg object that contains the same River ID and Data as this object. If the Data section is compressed in only one of the Icebergs being compared, the decompressed forms of the data will be compared.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    obj - - the object to compare with.
    
    Returns:
    
    boolean TRUE if the objects are the same; FALSE otherwise
  - getData
```
public byte[] getData()
```
    Returns only the Data section; you need to use the isCompressed() method to determine whether the data is compressed.
    Note: The Iceberg(byte...) constructor always stores data internally in its decompressed form. The other constructors, and the setData() methods, always attempt to compress data in preparation of sending it.
    
    Returns:
    
    byte[] Data in the form of a byte[] array
  - getFn
```
public byte getFn()
```
    Returns the first byte of the Data section. This is primarily useful for obtaining the bytecode for Functional data.
    Note: If the Data section is in compressed form, then there will be overhead when obtaining this data.
    
    Returns:
    
    byte Bytecode for functional data
    
    Throws:
    
    ArrayIndexOutOfBoundsException - If Data section is empty or if this Iceberg is not Functional
  - getFnData
```
public byte[] getFnData()
```
    Returns all except the first byte of the Data section. This is needed obtain the Functional data without its leading Bytecode.
    Note: If the Data section is in compressed form, then there will be overhead when obtaining this data.
    
    Returns:
    
    byte[] Functional data in the form of a byte[] array
    
    Throws:
    
    ArrayIndexOutOfBoundsException - If Data section is empty or if this Iceberg is not Functional
  - getRiverID
```
public short getRiverID()
```
    Returns the River ID number that this Iceberg belongs to.
    
    Returns:
    
    int River ID
  - hasData
```
public boolean hasData()
```
    Indicates whether this Iceberg contains at least one byte of data.
    Note: Do not presume that the Iceberg is not "functional" based on whatever else the name of this method might seem to imply, rather use the isData() or isFunctional() method to make that determination.
    
    Returns:
    
    boolean TRUE=At least one byte of data, FALSE=No data
  - isCompressed
```
public boolean isCompressed()
```
    Indicates whether the data stored internally is compressed.
    
    Returns:
    
    boolean TRUE=Compressed, FALSE=Raw
  - isData
```
public boolean isData()
```
    Indicates whether this Iceberg is data.
    
    Returns:
    
    boolean TRUE=Data, FALSE=Functional (not Data)
  - isFunctional
```
public boolean isFunctional()
```
    Indicates whether this Iceberg is functional.
    
    Returns:
    
    boolean TRUE=Functional, FALSE=Data (not Functional)
  - NULL
```
public static Iceberg NULL()
```
    Instantiation of zero-byte packet to be sent.
    
    Parameters:
    
    id - River ID number
  - setData
```
public Iceberg setData(byte... data)
```
    Creates a new Iceberg based on the current one, but with a new Data section stored internally in compressed form if it can be compressed.
    
    Returns:
    
    byte[] Data in the form of a byte[] array
  - size
```
public int size()
```
    Returns the total number of 8-bit bytes of data, in its compressed form (if it is compressed).
    
    Returns:
    
    int Total number of 8-bit bytes of data
  - sizeOriginal
```
public int sizeOriginal()
```
    Returns the total number of 8-bit bytes of data, according to the header (a.k.a., in its compressed form if it arrived in compressed form).
    
    Returns:
    
    int Total number of 8-bit bytes of data
  - toBytes
```
public byte[] toBytes()
```
    Returns all headers (which includes the River ID, flags, and Length field), followed immediately by the Data section, ready for sending to a remote host.
    Note: The toStream(RvierOutputStream) method is a convenience method that calls this method and sends it to the specified stream.
    
    Returns:
    
    byte[] Headers and Data in the form of a byte[] array
  - toString
```
public String toString()
```
    Provide debug-readable output version of this object.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    String Output that will be helpful for debugging
  - wasCompressed
```
public boolean wasCompressed()
```
    Indicates whether the data stored internally was ever compressed.
    
    Returns:
    
    boolean TRUE=Compressed, FALSE=Raw
  - writeToStream
```
public int writeToStream(java.io.OutputStream out)
                  throws java.io.IOException
```
    Outputs all headers (which includes the River ID, flags, and Length field), followed immediately by the Data section, to the specifed OutputStream object (which can optionally be a RiverOutputStream object).
    Note: This method uses the java.io.OutputStream.write(byte[]) method to write the entire Iceberg (headers and data) in a single operation.
    
    Returns:
    
    int Number of bytes written (normally a minimum of 6 + total length of the Data section)
    
    Throws:
    
    java.io.IOException - If an I/O error occurs

Class Iceberg

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class Object

Constructor Detail

Iceberg

Iceberg

Iceberg

Iceberg

Iceberg

Iceberg

Method Detail

equals

getData

getFn

getFnData

getRiverID

hasData

isCompressed

isData

isFunctional

NULL

setData

size

sizeOriginal

toBytes

toString

wasCompressed

writeToStream