org.hd.d.pg2k.svrCore.datasource
Class ExhibitDataTunnelSource.RawPacket

java.lang.Object
  org.hd.d.pg2k.svrCore.datasource.ExhibitDataTunnelSource.RawPacket

All Implemented Interfaces:

MemoryTools.Internable

Enclosing class:

ExhibitDataTunnelSource

public static final class ExhibitDataTunnelSource.RawPacket
extends java.lang.Object
implements MemoryTools.Internable

Immutable raw packet to send in either direction over a byte stream connection. This consists of an op-code byte, a byte-array payload, and a trailer byte (different to any op-code byte).

We informally attempt to keep a decent Hamming distance between different op-codes (ie more than one bit at a time should have to change to mutate one into another).

The byte array can be sent compressed (using the gzip algorithm), and this compression is adaptive, ie if compression does not save space then it is not used. The assumption if compression is requested is that it is worthwhile burning lots of CPU cycles to compress the data as far as possible, and so we may attempt very CPU-hungry settings. Compressed data is sent on the wire with the length actually -compressedDataLength.

This NOT intended to be directly Serializable.

NOTE: this is only guaranteed immutable if the payload is not tampered with after being passed to the constructor.

OP_NOOP

public static final byte OP_NOOP

Operation code: NO-OP (no operation).

See Also:

Constant Field Values

OP_getGenProps

public static final byte OP_getGenProps

Operation code: getGenProps().

See Also:

Constant Field Values

OP_getAllExhibitImmutableData

public static final byte OP_getAllExhibitImmutableData

Operation code: getAllExhibitImmutableData().

See Also:

Constant Field Values

OP_getStaticAttr

public static final byte OP_getStaticAttr

Operation code: getStaticAttr().

See Also:

Constant Field Values

OP_getRawFile

public static final byte OP_getRawFile

Operation code: getRawFile().

See Also:

Constant Field Values

OP_getGenSecProps

public static final byte OP_getGenSecProps

Operation code: getGenSecProps().

See Also:

Constant Field Values

OP_getAllExhibitProperties

public static final byte OP_getAllExhibitProperties

Operation code: getAllExhibitProperties().

See Also:

Constant Field Values

OP_getAllExhibitPropertiesDiff

public static final byte OP_getAllExhibitPropertiesDiff

Operation code: getAllExhibitPropertiesDiff().

See Also:

Constant Field Values

OP_getThumbnails

public static final byte OP_getThumbnails

Operation code: getThumbnails().

See Also:

Constant Field Values

OP_getVariable

public static final byte OP_getVariable

Operation code: getVariable().

See Also:

Constant Field Values

OP_getVariables

public static final byte OP_getVariables

Operation code: getVariables().

See Also:

Constant Field Values

OP_setVariables

public static final byte OP_setVariables

Operation code: setVariables().

See Also:

Constant Field Values

OP_syncVariables

public static final byte OP_syncVariables

Operation code: syncVariables().

See Also:

Constant Field Values

OP_getEventValues

public static final byte OP_getEventValues

Operation code: getEventValues().

See Also:

Constant Field Values

OP_getStratum

public static final byte OP_getStratum

Operation code: getStratum().

See Also:

Constant Field Values

OP__INTEX

public static final byte OP__INTEX

Reserved op-code for use in response packets to indicate that the operation was interrupted and can be retried (not an error).

See Also:

Constant Field Values

OP__PGMNISEX

public static final byte OP__PGMNISEX

Reserved op-code for use in response packets to indicate a PGMasterNotInServiceException.

See Also:

Constant Field Values

OP__REMEX

public static final byte OP__REMEX

Reserved op-code for use in response packets to indicate a RemoteException.

See Also:

Constant Field Values

OP__RUNTEX

public static final byte OP__RUNTEX

Reserved op-code for use in response packets to indicate a RuntimeException. Receipt of one of these DOES NOT indicate a link failure (and thus need to back off use of the link).

See Also:

Constant Field Values

TRAILER

public static final byte TRAILER

Trailer byte; different to all valid op-code byte values.

See Also:

Constant Field Values

MIN_PLLENGTH_FOR_HEAVY_COMP_ALGS

public static final int MIN_PLLENGTH_FOR_HEAVY_COMP_ALGS

Minimum size of payload for which we will try heaviest compression modes; strictly positive. This is for modes such as BZIP2 or LZMA with heavy memory, CPU and start-up costs (ie much heavier than GZIP).

Below this we assume that the absolute bandwidth savings are not worth the pain.

Probably bigger than a "bulk transfer" block too, so that the heavy guns are wielded only for the biggest frames.

See Also:

Constant Field Values

opCode

public final ExhibitDataTunnelSource.RawPacket.OpCode opCode

Opcode (single byte); never null. Set first in the raw frame on the wire.

Never numerically equal to TRAILER.

FRAME_OVERHEAD_BYTES

public static final int FRAME_OVERHEAD_BYTES

Frame overhead (header and trailer) in bytes; strictly positive.

See Also:

Constant Field Values

MAX_FRAME_SIZE

public static final int MAX_FRAME_SIZE

Maximum permitted total frame length including header/trailer; strictly positive power of two minus the frame overhead. Set much larger than the user-level transfer-size limit to allow for some control data overhead on top of the given data, and for much larger non-user-controlled items such as the AEP.

This limit mainly exists to prevent DoS-style out-of-memory problems arising from corrupt (huge) length values.

See Also:

Constant Field Values

MAX_PAYLOAD_SIZE

public static final int MAX_PAYLOAD_SIZE

Maximum permitted payload length; strictly positive power of two minus the frame overhead. Set much larger than the user-level transfer-size limit to allow for some control data overhead on top of the given data, and for much larger non-user-controlled items such as the AEP.

This mainly exists to prevent DoS-style out-of-memory problems arising from corrupt (huge) length values.

See Also:

Constant Field Values

payload

private final byte[] payload

Payload data, non-null unless the data is stored compressed. Private in order to keep the whole packet immutable.

payloadCompressed

private final byte[] payloadCompressed

Compressed payload data, null unless the data is stored compressed. Private in order to keep the whole packet immutable.

trailer

public static final byte trailer

Trailer byte; not a valid op-code.

See Also:

Constant Field Values

ExhibitDataTunnelSource.RawPacket

public ExhibitDataTunnelSource.RawPacket(ExhibitDataTunnelSource.RawPacket.OpCode opCode)

Construct a new raw packet with an empty payload.

Parameters:

op - the op-code of the RPC; never null

ExhibitDataTunnelSource.RawPacket

public ExhibitDataTunnelSource.RawPacket(ExhibitDataTunnelSource.RawPacket.OpCode op,
                                         byte[] data)

Construct a new raw packet with the whole data array as the payload. Note that the data is not copied (nor modified); the array should not subsequently be modified.

This assumes that it is worth trying to compress the payload, if other conditions support it.

Parameters:

op - the op-code of the RPC; never null

data - the payload bytes; never null

ExhibitDataTunnelSource.RawPacket

public ExhibitDataTunnelSource.RawPacket(ExhibitDataTunnelSource.RawPacket.OpCode op,
                                         byte[] data,
                                         boolean attemptCompression)

Construct a new raw packet with the whole data array as the payload. Note that the data is not copied (nor modified); the array should not subsequently be modified.

Parameters:

op - the op-code of the RPC; never null

data - the payload bytes; never null

attemptCompression - if true, it is probably worth attempting to compress the payload data unless very short

ExhibitDataTunnelSource.RawPacket

public ExhibitDataTunnelSource.RawPacket(ExhibitDataTunnelSource.RawPacket.OpCode op,
                                         byte[] data,
                                         int initialPortion,
                                         boolean attemptCompression)

Construct a new raw packet with the initial portion of the data array as the payload. Note that the data is not copied (nor modified), unless it is compressed or the data does not occupy the whole array; the array should not subsequently be modified.

If compression is requested and is possible then the compression may be performed at construction time and the compressed form of the data held to save space.

Parameters:

op - the op-code of the RPC; never null

data - the (uncompressed) payload bytes; never null

initialPortion - the initial portion of data[] containing payload data; never negative or larger than data.length or MAX_PAYLOAD_SIZE

attemptCompression - if true, it is probably worth attempting to compress the payload data unless very short

ExhibitDataTunnelSource.RawPacket

private ExhibitDataTunnelSource.RawPacket(ExhibitDataTunnelSource.RawPacket.OpCode opCode,
                                          byte[] payload,
                                          byte[] payloadCompressed)

Construct a new raw packet with data provided. This accepts whatever it is passed (we check for some errors with run-time assertions in debug code), and is intended only to be called from other constructors or factory methods.

Parameters:

op - the op-code of the RPC; never null

ExhibitDataTunnelSource.RawPacket

public ExhibitDataTunnelSource.RawPacket(ExhibitDataTunnelSource.RawPacket.OpCode op,
                                         java.io.Serializable obj,
                                         boolean attemptCompression)
                                  throws java.io.IOException

Construct a new raw packet with a serialised object as the payload. This will use an uncompressed form if more efficient on the wire.

This will have the entire uncompressed form in memory at peak, so may be unsuitable for very large (and highly-compressible) objects.

Parameters:

op - the op-code of the RPC; never null

obj - the Serializable object to send, or null to send empty payload

attemptCompression - if true, it is probably worth attempting to compress the payload data if not very short

Throws:

java.io.IOException

equals

public boolean equals(java.lang.Object obj)

Depends on the whole packet being identical. This depends on the header and data being identical, including being compressed in the same way if at all.

Overrides:

equals in class java.lang.Object

equivalentTo

public boolean equivalentTo(ExhibitDataTunnelSource.RawPacket other)

Checks for equivalent raw packets, ignoring internal representation details. Mainly this means ignoring whether the data is held compressed or not, as long as the values that the user can see are identical.

May be very slow and memory intensive.

hashCode

public int hashCode()

Hash is based on just packet type and (actual) packet length.

Overrides:

hashCode in class java.lang.Object

streamSerialiseObject

public static ExhibitDataTunnelSource.RawPacket streamSerialiseObject(ExhibitDataTunnelSource.RawPacket.OpCode op,
                                                                      java.io.Serializable obj)
                                                               throws java.io.IOException

Construct a new raw packet with a stream-serialised object as the payload. This will always compress the supplied object (unless null, in which case an empty payload is used) to try to avoid ever having the full unserialised form in memory.

This will veto with an IOException any attempt to write more than MAX_PAYLOAD_SIZE pre-compression or pre-compression bytes.

Parameters:

op - the op-code of the RPC; one of the OP_XXX values

obj - the Serializable object to send, or null to send empty payload

attemptCompression - if true, it is probably worth attempting to compress the payload data if not very short

Throws:

java.io.IOException

_serObjForPayload

private static byte[] _serObjForPayload(java.io.Serializable obj)
                                 throws java.io.IOException

Serialise object for payload. Returns a zero-length array if the object is null.

Throws:

java.io.IOException

getSerializedObjectPayload

public java.lang.Object getSerializedObjectPayload()
                                            throws java.io.IOException

Retrieves a single serialised Object from the payload. If the payload is empty (zero-length), we return null.

For robustness, treats a class mismatch problem like a data problem, ie this will re-throw any ClassNotFoundException as an IOException.

Throws:

java.io.IOException

getFrameLength

public int getFrameLength()

Computes the total number of bytes that would be written by writePacket(); strictly positive.

writePacket

public void writePacket(java.io.OutputStream os)
                 throws java.io.IOException

Send the packet down the given OutputStream with header and trailer. This flushes the data after writing it.

This does not close() the stream.

Throws:

java.io.IOException

writePacket

public void writePacket(java.io.OutputStream os,
                        boolean reduceWrites)
                 throws java.io.IOException

Send the packet down the given OutputStream with header and trailer. This flushes the data after writing it.

If the payload is not too large, then the entire packet will be buffered and sent in one write(), else it will be sent in LAN-packet-size chunks.

This does not close() the stream.

Parameters:

reduceWrites - if true then make an effort to reduce the number of writes done (ie try to write fewer larger blocks) since the output may be to a raw network stream or similar which may require more copying of data first

Throws:

java.io.IOException

readPacket

public static ExhibitDataTunnelSource.RawPacket readPacket(java.io.InputStream is)
                                                    throws java.io.IOException

Reads a packet from the input stream, blocking until done. Preserves its compressed/uncompressed form, possibly helping reduce memory footprint at the receiver.

Compressed data is signalled by a negative length on the wire, where this is the negation of the compressed data size.

The ZLIB deflater with maximum compression and no checksum is used for any (de)compression.

To prevent unpleasantness such a OutOfMemoryError from a corrupt length value, we veto lengths greater than the maximum specified for this frame type.

Throws:

java.io.IOException

toString

public java.lang.String toString()

Create a human-readable summary (not including the payload data).

Overrides:

toString in class java.lang.Object

getPayloadAsInputStream

public java.io.InputStream getPayloadAsInputStream()

Get the payload data as an InputStream; never null. If the internal data is stored compressed however, then this will return the uncompressed version.

Each stream returned is independent.

This stream should be explicitly closed when finished with to release underlying memory and other resources ASAP.

Returns:

the uncompressed payload data as a stream of length plLength

getPayloadCopy

public byte[] getPayloadCopy()

Get a copy of the payload data; never null. We return a copy to keep this object immutable.

If the internal data is stored compressed then this will return the original uncompressed version.

Returns:

a copy of the payload data, of length plLength

getPayload

byte[] getPayload()

Get direct access to the uncompressed payload; never null. We avoid making a copy, for speed. The caller must not alter the byte array returned.

If the internal data is stored compressed then this will return an uncompressed copy.

This is package-visible and is only for trusted callers that will not alter the content.

Returns:

a the payload data, of length plLength; never null,

getPayloadCopy

void getPayloadCopy(java.nio.ByteBuffer buf)

Copy the payload data into the supplied (trusted) buffer. We only make this package-visible to keep this object immutable.

If the internal data is stored compressed then this will return the original uncompressed version.

getActualPayloadLength

public int getActualPayloadLength()

Return the actual payload length; non-negative. The payload may be compressed so this may be less than the uncompressed full payload size.

If the original payload is empty (zero length) and getUncompressedPayloadLength() returns 0 then this returns 0 also.