com.neeve.pkt
Class PktSerializable.DeserializeContext

java.lang.Object
  com.neeve.pkt.PktSerializable.DeserializeContext

Enclosing class:

PktSerializable

public static final class PktSerializable.DeserializeContext
extends Object

Contains context used in the deserialization of an entity.

An instance of this class is passed to the PktSerializable.deserialize(com.neeve.pkt.PktSerializable.DeserializeContext, int, com.neeve.trace.Tracer) method and contains information related to the deserialization process. Basically, the class stores the following pieces of information. The numBytes field is an OUT field and serves a dual purpose. In the event that the deserialization was successful, this field contains the number of bytes that were used up in the provided buffer to perform the deserialization. In the event that the deserialization was not successful i.e. the remaining bytes in the buffer did not contain a complete serialized entity, this field contains the number of additional bytes needed to complete the deserialization. The bufferRetained field is also an OUT field and contains information as to whether the deserialization was performed by copying from or retaining a reference to the provided buffer. This field is only valid in case the deserialization was successful. The buffer field contains the buffer from where the entity is to be initialized. This is an IN-OUT field i.e. on input, the entity uses this buffer to initialize itself and is free to replace the buffer with a new incarnation before returning to the caller. The policy field contains the deserialization policy to be used by the entity. This is an IN-OUT field allowing an entity to modify the deserialization policy to be used by subsequent entities deserialized using the same context.

It should be noted that this context does not convey the status of the deserialization. See PktSerializable.deserialize(com.neeve.pkt.PktSerializable.DeserializeContext, int, com.neeve.trace.Tracer) on how the status is communicated back to the user.

Threading:

This class is not safe for concurrent access by multiple threads.

Method Summary

static PktSerializable.DeserializeContext	create() Create a deserialize context
static void	dumpCorruptedPacketBuffer(String message, ByteBuffer buffer, int packetBufferPos, int packetBufferLimit, Throwable e, Tracer tracer) Utility method to dump deserialize context on packet corruption.
ByteBuffer	getBuffer() Get the deserialization buffer.
boolean	getBufferRetained() Get whether a reference to the buffer is retained by the packet post deserialization.
int	getNumBytes() Get the number of bytes consumed or fell short by the deserialization process.
int	getPolicy() Get the deserialization policy to be used.
boolean	isPacketBodyDesyncDisabled() Gets whether packet body desync has been disabled.
PktSerializable.DeserializeContext	reset() Reset the contents of the context.
PktSerializable.DeserializeContext	setBuffer(ByteBuffer buffer) Set the deserialization buffer.
void	setPacketBodyDesyncDisabled(boolean val) Sets whether or not packet bodies will be desync'd as they are read from the the log.
PktSerializable.DeserializeContext	setPolicy(int policy) Set the deserialization policy to be used.
void	trace(Tracer tracer, String prefix) Trace contents for debugging purposes

Methods inherited from class java.lang.Object

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

Method Detail

create

public static PktSerializable.DeserializeContext create()

Create a deserialize context

setBuffer

public final PktSerializable.DeserializeContext setBuffer(ByteBuffer buffer)

Set the deserialization buffer.

Parameters:

buffer - The deserialization buffer

Returns:

Returns this object for invocation chaining.

This method sets the buffer to be used to initialize the entity.

See Also:

getBuffer()

Threading:

This method is not safe for concurrent access by multiple threads

getBuffer

public final ByteBuffer getBuffer()

Get the deserialization buffer.

This method returns the buffer from where the entity is to be initialized. This field is an IN-OUT field and therefore the user should not retain any reference to the buffer outside of this context. The entity is free to change this field upon return from the deserialization process. Typically, the entity would replace it with the sliced buffer in case the deserialization was performed by slicing the buffer. However, there may be other cases too.

Threading:

This method is not safe for concurrent access by multiple threads

setPolicy

public final PktSerializable.DeserializeContext setPolicy(int policy)

Set the deserialization policy to be used.

Returns:

Returns this object for invocation chaining.

Throws:

IllegalArgumentException - Thrown in case the specified policy is invalid.

The following are the permissible deserialization policies:
PktConstants.DESERIALIZE_POLICY_DEFAULT
PktConstants.DESERIALIZE_POLICY_HEADER_COPY_BODY_COPY
PktConstants.DESERIALIZE_POLICY_HEADER_COPY_BODY_SLICE
PktConstants.DESERIALIZE_POLICY_HEADER_SLICE_BODY_SLICE

See Also:

getPolicy()

Threading:

This method is not safe for concurrent access by multiple threads

getPolicy

public final int getPolicy()

Get the deserialization policy to be used.

This method returns the deserialization policy to be used by the deserialization process. This field is an IN-OUT field and therefore the user should not retain any reference to the policy outside of this context. The entity is free to change this field before returning from the deserialization process.

Threading:

This method is not safe for concurrent access by multiple threads

setPacketBodyDesyncDisabled

public final void setPacketBodyDesyncDisabled(boolean val)

Sets whether or not packet bodies will be desync'd as they are read from the the log.

Parameters:

val - false to disable packet body desync

isPacketBodyDesyncDisabled

public final boolean isPacketBodyDesyncDisabled()

Gets whether packet body desync has been disabled.

Returns:

true if packet body desync has been disabled.

getNumBytes

public final int getNumBytes()

Get the number of bytes consumed or fell short by the deserialization process.

This method returns a value that is to be interpreted according to whether the entity was successfully resconstructed from the byte buffer or not. In case a packet was successfully reconstructed, this method returns the number of bytes used up from the byte buffer to recontruct the entity (the position markers in the buffer would also have been moved to reflect this). In case the entity could not be successfully created, this method returns the number of additional bytes needed to reconstruct the entity.

Threading:

This method is not safe for concurrent access by multiple threads

getBufferRetained

public final boolean getBufferRetained()

Get whether a reference to the buffer is retained by the packet post deserialization.

This method returns a value that is only valid in case an entity was successfully reconstructed from the set of byte buffers. In that case, the return value indicates that a reference to the deserialization buffer was retained by the deserialization process and, therefore, the buffer cannot be reused until the packet has been garbage collected.

Threading:

This method is not safe for concurrent access by multiple threads

reset

public final PktSerializable.DeserializeContext reset()

Reset the contents of the context. All fields except for the buffer field are reset.

trace

public final void trace(Tracer tracer,
                        String prefix)

Trace contents for debugging purposes

dumpCorruptedPacketBuffer

public static final void dumpCorruptedPacketBuffer(String message,
                                                   ByteBuffer buffer,
                                                   int packetBufferPos,
                                                   int packetBufferLimit,
                                                   Throwable e,
                                                   Tracer tracer)

Utility method to dump deserialize context on packet corruption.

This method dumps the packet contents in hex to an diagnostic file and also trace an error to the provided tracer.

Parameters:

message - The error message to trace.

buffer - The packet buffer.

packetBufferPos - The starting position in the buffer from which the packet was to be read.

packetBufferLimit - The limit in the packet buffer to which to read.

e - The deserialization exception.

tracer - The tracer to use to trace the location at which the dump file was written.