com.neeve.pkt
Class PktPacket

java.lang.Object
  com.neeve.util.UtlListElement
      com.neeve.pkt.PktSerializable
          com.neeve.pkt.PktPacket

All Implemented Interfaces:

com.neeve.io.IOElasticBuffer.Sizer, UtlPool.Item<PktPacket>, UtlReferenceTracker.HasReferenceTracker

public final class PktPacket
extends PktSerializable
implements UtlPool.Item<PktPacket>, UtlReferenceTracker.HasReferenceTracker

The packet.

Packets serve as the basic unit of conversation between participants in a distributed system. Each packet flowing through the system is logically part of a conversation between some messaging participants. Each packet is of a specific type and defines the grammar of the packet's contents. Structurally, a packet consists of a header, a body and a set of tag objects. The header portion of a packet contains system information and is used by intermediate and the participants (endpoints) of the conversation of which the packet is a part. On the other hand, the packet body contains information interpreted solely by the conversation participants. Packet tags are opaque objects attached to packets as they travel within process (JVM) boundaries. They serve as a mechanism of decoupled communication between the various processors of a packet in its path through a process. Packet tags are not preserved across process boundaries. Refer to PktHeader for information on the structure of the packet header. The structure of the packet body is defined by the packet type. A separate class exists for each packet type. Structurally, packet tags are opaque to the packet and are interpreted only by the packet processors.

Threading:

Packets are not safe for concurrent access by multiple threads.

Nested Class Summary

Nested classes/interfaces inherited from class com.neeve.pkt.PktSerializable

PktSerializable.DeserializeContext, PktSerializable.SerializeContext

Field Summary

Fields inherited from class com.neeve.util.UtlListElement

count, head, next, prev

Method Summary

PktPacket	acquire() Increase a packet's ownership count.
int	deserialize(ByteBuffer buf, int bufOffset) Deserialize a packet from a byte buffer
int	deserialize(com.neeve.io.IOBuffer iobuf, int iobufOffset, boolean wrap) Deserialize a packet from an IO buffer
void	deserialize(PktSerializable.DeserializeContext context, int packetSerializedLength, Tracer tracer) Implementation of PktSerializable.deserialize(com.neeve.pkt.PktSerializable.DeserializeContext, int, com.neeve.trace.Tracer).
void	dispose() Dispose of a packet.
PktPacket	fork() Fork a packet This method invokes fork(false)
PktPacket	fork(boolean storageOnly) Fork a packet
PktPacket	forkNonPooled() Fork a packet This method is the same as fork(boolean, boolean) except that the forked packet is created from outside of the forking packet's pool, if present.
PktBody	getBody() Get the packet body.
PktHeader	getHeader() Get the packet header.
int	getInitialBufferLength() Implementation of IOElasticBuffer.Sizer.getInitialBufferLength()
long	getInTs() Get a packet's inbound timestamp.
long	getOutTs() Get a packet's outbound (pre-wire) timestamp.
int	getOwnerCount() Get a packet's ownership count.
UtlPool<PktPacket>	getPool() Implementation of UtlPool.Item#getPool.
int	getSerializedLength() Implementation of PktSerializable.getSerializedLength().
Object	getTag(int id) Get a packet tag.
PktPacket	init() Implementation of UtlPool.Item#init.
UtlReferenceTracker	referenceTracker() Get an object's reference tracker.
int	serialize(byte[] array, int arrayOffset) Serialize a packet to a byte array
int	serialize(ByteBuffer buf) Serialize a packet to a byte buffer
int	serialize(ByteBuffer buf, int bufOffset) Serialize a packet to a byte buffer
int	serialize(com.neeve.io.IOBuffer iobuf, int iobufOffset) Serialize a packet to an IO buffer
int	serialize(com.neeve.io.IOElasticBuffer iobuf, int iobufOffset) Serialize a packet to an elastic IO buffer
int	serialize(long address, int addressOffset) Serialize a packet to a native memory region
void	serialize(PktSerializable.SerializeContext context, Tracer tracer) Implementation of PktSerializable.serialize(com.neeve.pkt.PktSerializable.SerializeContext, com.neeve.trace.Tracer).
void	setDeserializationPolicy(int policy) Implementation of PktSerializable.setDeserializationPolicy(int).
void	setInTs(long ts) Set a packet's inbound (post-wire) timestamp.
void	setOutTs(ByteBuffer buffer, int pos, long ts) Set a packet's outbound (pre-wire) timestamp.
PktPacket	setPool(UtlPool<PktPacket> pool) Implementation of UtlPool.Item#setPool.
void	setSerializationPolicy(int policy) Implementation of PktSerializable.setSerializationPolicy(int).
void	setTag(int id, Object tag) Set a packet tag.
String	toString() Return a string representation of the object.

Methods inherited from class com.neeve.pkt.PktSerializable

deserialize, getDeserializationPolicy, getSerializationPolicy, isValidDeserializationPolicy, isValidSerializationPolicy, serialize

Methods inherited from class com.neeve.util.UtlListElement

count, insertAfter, insertBefore, isLinked, next, previous, unlink, wipe

Methods inherited from class java.lang.Object

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

Method Detail

getHeader

public final PktHeader getHeader()

Get the packet header.

Returns:

Returns the packet header

Threading:

This method is not safe for concurrent access by multiple threads

getBody

public final PktBody getBody()

Get the packet body.

Returns:

Returns the packet body

Threading:

This method is not safe for concurrent access by multiple threads

setTag

public final void setTag(int id,
                         Object tag)

Set a packet tag.

Threading:

This method is not safe for concurrent access by multiple threads

getTag

public final Object getTag(int id)

Get a packet tag.

Returns:

Returns a packet tag

Threading:

This method is not safe for concurrent access by multiple threads

setInTs

public final void setInTs(long ts)

Set a packet's inbound (post-wire) timestamp.

This method is used to stamp a packet with its pre-deserialize timestamp (in microseconds)

getInTs

public final long getInTs()

Get a packet's inbound timestamp.

setOutTs

public final void setOutTs(ByteBuffer buffer,
                           int pos,
                           long ts)

Set a packet's outbound (pre-wire) timestamp.

This method is used to stamp a packet with its post-serialize timestamp (in microseconds)

getOutTs

public final long getOutTs()

Get a packet's outbound (pre-wire) timestamp.

acquire

public final PktPacket acquire()

Increase a packet's ownership count.

This method increments a packet's ownership count. Packet ownership is used in conjunction with managing packet pools. If a packet is tagged to an object pool, the packet is released back to the pool by dispose() when the ownership count reduces to 0. If not tagged to a pool, change of ownership count has no side effects.

A packet's ownership count starts at 1.

getOwnerCount

public final int getOwnerCount()

Get a packet's ownership count.

dispose

public final void dispose()

Dispose of a packet.

This method should be invoked by the user when done with a packet. It decrements the packet's ownership count and releases it to its object pool if one is tagged to it and this method cause the ownership count to reduce to zero. If not tagged to a pool, ownership change methods have no side effects aside from just updating the ownership counter.

Upon return from this method, the caller should assume that the packet has been disposed and release uts reference to the packet.

referenceTracker

public final UtlReferenceTracker referenceTracker()

Description copied from interface: UtlReferenceTracker.HasReferenceTracker

Get an object's reference tracker.

This method returns an object's reference tracker intended for use for debugging purposes. An object should instantiate a tracker only if UtlReferenceTracker.ENABLED is true or UtlReferenceTracker.enabled(Class) is true for the object type. The flag can be enabled via the properties nv.reftracking.enabled or by the nv.reftracking.types=fullclassname1[|fullclassnameN].

Specified by:

referenceTracker in interface UtlReferenceTracker.HasReferenceTracker

fork

public final PktPacket fork(boolean storageOnly)

Fork a packet

Parameters:

storageOnly - If set to true, then the forking process will only fork the packet's underlying storage. This means that packet header contents can be accessed via the PktHeader API on the forked packet but the packet subheader and concrete packet body implementation that is layered on top of the packet body storage will not be made aware of the fact that the body storage has legitimate contents in it. This parameter should be set to true for situations where only the storage of the forked packet is going to be accessed e.g. for persistence

The act of forking a packet creates a new (forked) packet of the same type as the original packet but with both packets sharing the same set of underlying IO buffers but marked as copy on write. The subheader and body elements of the original packets are sync'd to the backing buffer before the fork is performed. All other state elements of the forked packet - tags, reference count, etc - are the same as if the packet was created fresh.

fork

public final PktPacket fork()

Fork a packet

This method invokes fork(false)

forkNonPooled

public final PktPacket forkNonPooled()

Fork a packet

This method is the same as fork(boolean, boolean) except that the forked packet is created from outside of the forking packet's pool, if present.
NOTE: THIS METHOD IS INTENDED FOR X PLATFORM INTERNAL USE AND SHOULD NOT BE USED. PLEASE CONSULT NEEVE TECHNICAL SUPPORT BEFORE YOU USE THIS METHOD. THIS METHOD CAN BE DEPRECATED/REMOVED/CHANGED AT ANY TIME WIHOUT NOTICE

setSerializationPolicy

public final void setSerializationPolicy(int policy)

Implementation of PktSerializable.setSerializationPolicy(int).

Overrides:

setSerializationPolicy in class PktSerializable

Parameters:

policy - The serialization policy to use for this entity. The following are the permissible serialization policies:
PktConstants.SERIALIZE_POLICY_HEADER_COPY_BODY_COPY
PktConstants.SERIALIZE_POLICY_HEADER_COPY_BODY_ATTACH
PktConstants.SERIALIZE_POLICY_HEADER_ATTACH_BODY_ATTACH

serialize

public final void serialize(PktSerializable.SerializeContext context,
                            Tracer tracer)
                     throws EPktSerializeException

Implementation of PktSerializable.serialize(com.neeve.pkt.PktSerializable.SerializeContext, com.neeve.trace.Tracer).

This method serializes the packet into the buffers list specified in the provided serialization context. The method serializes the packet by invoking PktHeader.serialize(com.neeve.pkt.PktSerializable.SerializeContext, com.neeve.trace.Tracer) and PktBody.serialize(com.neeve.pkt.PktSerializable.SerializeContext, com.neeve.trace.Tracer). Refer to those methods for more detailed information on the serialization process including how the serialization policy to use is resolved.

Specified by:

serialize in class PktSerializable

Parameters:

context - The context to be used by the serialization process. See PktSerializable.SerializeContext for more information.

tracer - Tracer used to output serialization related trace. Can be null in which case no trace is output.

Throws:

EPktSerializeException - Thrown in case an error is encountered during the serialization process.

This method serializes a serialiable entity into a byte array presented as a set of byte buffers. As input, this method accepts a serialization context that, among other fields, contains a list of buffers of type {link java.nio.ByteBuffer} into which the entity is to serialize itself. The serialization operation is policy driven and the policy determines whether the header is copied into space remaining in the provided buffers or whether the internal entity buffers are just appended to the provided buffer list. In case the decision is made to copy the serialized data into the provided buffers, the data is always copied into the last buffer in the list. In case the last buffer does not contain enough remaining space to accomodate all the serialized data, this method will allocate and append a new buffer that will be of the same type and capacity as the last buffer in the provided list. Read the documentation of the policy constants to understand which policies cause the header to be copied as opposed to appended (the policy constant names are also self descriptive)

serialize

public final int serialize(ByteBuffer buf)

Serialize a packet to a byte buffer

Parameters:

buf - The byte buffer to serialize to

Returns:

length The number of bytes serialized (copied)

This method serialized the contents of a packet by copying the contents of the packet's header and body buffers to a byte buffer. This method copies the contents to the target buffer starting at the target buffer's position. This method does not change any of the markers of the target buffer.

Note:Since this method does not change any markers of the target buffer, the caller needs to ensure the buffer limit is set correctly to accommodate the 's contents. The caller can invoke getSerializedLength() to get the length of the's contents and use that to set the target buffer's limit before invoking this method.

serialize

public final int serialize(ByteBuffer buf,
                           int bufOffset)

Serialize a packet to a byte buffer

Parameters:

buf - The byte buffer to serialize to

bufOffset - The offset into the buffer where the serialized contents of the packet needs to be serialized (copied)

Returns:

length The number of bytes serialized (copied)

This method serialized the contents of a packet by copying the contents of the packet's header and body buffers to a byte buffer. This method copies the contents to the target buffer starting at the supplied buffer offset. This method does not change any of the markers of the target byte buffer.

Note:Since this method does not change any markers of the target buffer, the caller needs to ensure the buffer limit is set correctly to accommodate the contents. The caller can invoke getSerializedLength() to get the length of the's contents and use that to set the target buffer's limit before invoking this method.

serialize

public final int serialize(byte[] array,
                           int arrayOffset)

Serialize a packet to a byte array

Parameters:

array - The byte array to serialize to

arrayOffset - The offset into the array where the serialized contents of the packet needs to be serialized (copied)

Returns:

length The number of bytes serialized (copied)

This method serialized the contents of a packet by copying the contents of the packet's header and body buffers to a byte array.

serialize

public final int serialize(com.neeve.io.IOBuffer iobuf,
                           int iobufOffset)

Serialize a packet to an IO buffer

Parameters:

iobuf - The IO buffer to serialize to

iobufOffset - The offset into the IO buffer where the serialized contents of the packet needs to be serialized (copied)

Returns:

length The number of bytes serialized (copied)

This method serialized the contents of a packet by copying the contents of the packet's header and body buffers to an IO buffer.

serialize

public final int serialize(com.neeve.io.IOElasticBuffer iobuf,
                           int iobufOffset)

Serialize a packet to an elastic IO buffer

Parameters:

iobuf - The IO buffer to serialize to

iobufOffset - The offset into the IO buffer where the serialized contents of the packet needs to be serialized (copied)

Returns:

length The number of bytes serialized (copied)

This method serialized the contents of a packet by copying the contents of the packet's header and body buffers to an elastic IO buffer.

serialize

public final int serialize(long address,
                           int addressOffset)

Serialize a packet to a native memory region

Parameters:

address - The address of the native memory region to serialize to

addressOffset - The offset into the memory region where the serialized contents of the packet should be serialized to.

Returns:

length The number of bytes serialized (copied)

This method serialized the contents of a packet by copying the contents of the packet's header and body buffers to a native memory region.

setDeserializationPolicy

public final void setDeserializationPolicy(int policy)

Implementation of PktSerializable.setDeserializationPolicy(int).

Overrides:

setDeserializationPolicy in class PktSerializable

Parameters:

policy - The deserialization policy to use for this entity. The following are the permissible serialization policies:
PktConstants.DESERIALIZE_POLICY_HEADER_COPY_BODY_COPY
PktConstants.DESERIALIZE_POLICY_HEADER_COPY_BODY_SLICE
PktConstants.DESERIALIZE_POLICY_HEADER_SLICE_BODY_SLICE

deserialize

public final void deserialize(PktSerializable.DeserializeContext context,
                              int packetSerializedLength,
                              Tracer tracer)
                       throws EPktDeserializeException

Implementation of PktSerializable.deserialize(com.neeve.pkt.PktSerializable.DeserializeContext, int, com.neeve.trace.Tracer).

This method deserializes the packet from the buffer specified in the provided deserialization context. The method deserializes the packet by invoking PktHeader.deserialize(com.neeve.pkt.PktSerializable.DeserializeContext, int, com.neeve.trace.Tracer) and PktBody.deserialize(com.neeve.pkt.PktSerializable.DeserializeContext, int, com.neeve.trace.Tracer). Refer to those methods for information more detailed information on the deserialization process including how the deserialization policy to use is resolved.

Specified by:

deserialize in class PktSerializable

Parameters:

context - The context to be used by the deserialization process. See PktSerializable.DeserializeContext for more information.

packetSerializedLength - This parameter is present for entities whose serialized form does not contain the serialized length of the entity. For such entities, the caller needs to pass in the serialized length to the entity during deserialize time. For other entities, this value will be ignored and should be set to -1 (some entities that pull the length from the serialized form may indeed validate that the passed in value is -1)

tracer - Tracer used to output deserialization related trace. Can be null in which case no trace is output.

Throws:

EPktDeserializeException - Thrown in case an error is encountered during the deserialization process.

This method initializes a serializable entity from a byte buffer. As input, this method accepts a deserialization context that contains, in addition to other fields, a ByteBuffer from where the entity is to be initialized. It is assumed that the caller has validated (using some other means) that the buffer contains enough data to initialize the entity. Upon successful return, the context is updated with information relating to the deserialization e.g. how many bytes were consumed from the buffer to initialize the entity and whether a reference to the buffer is being retained by the entity subsequent to returning from this method. Refer to the context documentation for detailed information on how and when the fields are updated.

Before returning from this method, the implementation must replace the buffer in the context with a sliced version of the provided buffer so that the next entity in the deserialization chain can operate out of the buffer provided to it using absolute indices i.e. relative to the beginning of the buffer rather than relative to the current buffer position.

deserialize

public final int deserialize(ByteBuffer buf,
                             int bufOffset)

Deserialize a packet from a byte buffer

Parameters:

buf - The byte buffer to deserialize from

bufOffset - The offset into the buffer where the serialized packet starts

Returns:

returns the serialized length of the packet

This method deserializes the packet from a byte buffer. The method deserializes the packet by first deserializing the header followed by the body.

Note: This method assumes that the supplied length is greater than or equal to the length of the serialized packet. To ensure that the buffer does indeed contain the full serialized packet, use PktHeader.preDeserialize(ByteBuffer, int, int)

deserialize

public final int deserialize(com.neeve.io.IOBuffer iobuf,
                             int iobufOffset,
                             boolean wrap)

Deserialize a packet from an IO buffer

Parameters:

iobuf - The IO buffer to deserialize from

iobufOffset - The offset into the IO buffer where the serialized packet starts

wrap - Indicates whether the deserialization process should copy the contents of the IO buffer to the packet body or wrap the packet body's buffer around the supplied IO buffer

Returns:

returns the serialized length of the packet

This method deserializes the packet from an IO buffer. The method deserializes the packet by first deserializing the header followed by the body.

getSerializedLength

public final int getSerializedLength()

Implementation of PktSerializable.getSerializedLength().

Specified by:

getSerializedLength in class PktSerializable

getInitialBufferLength

public final int getInitialBufferLength()

Implementation of IOElasticBuffer.Sizer.getInitialBufferLength()

Specified by:

getInitialBufferLength in interface com.neeve.io.IOElasticBuffer.Sizer

init

public final PktPacket init()

Implementation of UtlPool.Item#init.

Specified by:

init in interface UtlPool.Item<PktPacket>

Returns:

Return 'this' object for method invocation chaining.

setPool

public final PktPacket setPool(UtlPool<PktPacket> pool)

Implementation of UtlPool.Item#setPool.

Specified by:

setPool in interface UtlPool.Item<PktPacket>

Returns:

Return 'this' object for method invocation chaining.

getPool

public final UtlPool<PktPacket> getPool()

Implementation of UtlPool.Item#getPool.

Specified by:

getPool in interface UtlPool.Item<PktPacket>

Returns:

the pool set using UtlPool.Item.setPool(com.neeve.util.UtlPool)

toString

public final String toString()

Return a string representation of the object.

Overrides:

toString in class Object

Threading:

This method is safe for concurrent access by multiple threads