com.neeve.pkt

Class PktPacket

java.lang.Object

com.neeve.util.UtlListElement

com.neeve.pkt.PktPacket

All Implemented Interfaces:

UtlPool.Item<PktPacket>, UtlReferenceTracker.HasReferenceTracker

public final class PktPacket
extends UtlListElement
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.

Field Summary

Fields inherited from class com.neeve.util.UtlListElement

count, head, next, prev

Method Summary

Modifier and Type	Method and Description
PktPacket	acquire() Increase a packet's ownership count.
int	deserialize(ByteBuffer buf, int bufOffset) Deserialize a packet from a byte buffer This method invokes putFrom(buf, bufOffset) followed by desync()
int	deserialize(IOBuffer iobuf, int iobufOffset) Deserialize a packet from an IO buffer This method invokes deserialize(iobuf, iobufOffset, false, false)
int	deserialize(IOBuffer iobuf, int iobufOffset, boolean wrap) Deserialize a packet from an IO buffer This method invokes deserialize(iobuf, iobufOffset, wrap, wrap)
int	deserialize(IOBuffer iobuf, int iobufOffset, boolean wrapHeader, boolean wrapBody) Deserialize a packet from an IO buffer This method invokes putFrom(iobuf, iobufOffset, wrapHeader, wrapBody) followed by desync()
int	deserialize(long addr, int addrOffset) Deserialize a packet from a native memory region This method invokes putFrom(addr, addrOffset) followed by desync()
int	deserialize(PktPacket packet) Deserialize a packet from another packet
void	desync() Desync the early desync contents of a packet body's backing buffer
void	dispose() Dispose of a packet.
PktBody	getBody() Get the packet body.
PktHeader	getHeader() Get the packet header.
int	getOwnerCount() Get a packet's ownership count.
UtlPool<PktPacket>	getPool() Implementation of UtlPool.Item#getPool.
int	getSerializedLength() Get the serialized length of a packet
Object	getTag(int id) Get a packet tag.
int	getTo(byte[] array, int arrayOffset) Copy the contents of a packet's header and body buffers to a byte array This method invokes return getTo(array, arrayOffset, true)
int	getTo(byte[] array, int arrayOffset, boolean withMagic) Copy the contents of a packet's header and body buffers to a byte array
int	getTo(ByteBuffer buf) Copy the contents of a packet's header and body buffers to a byte buffer This method invokes return getTo(buf, true)
int	getTo(ByteBuffer buf, boolean withMagic) Copy the contents of a packet's header and body buffers to a byte buffer This method invokes return getTo(buf, buf.position(), withMagic)
int	getTo(ByteBuffer buf, int bufOffset) Copy the contents of a packet's header and body buffers to a byte buffer This method invokes return getTo(buf, bufOffset, true)
int	getTo(ByteBuffer buf, int bufOffset, boolean withMagic) Copy the contents of a packet's header and body buffers to a byte buffer
int	getTo(IOBuffer iobuf, int iobufOffset) Copy the contents of a packet's header and body buffers to an IOBuffer This method invokes return getTo(iobuf, iobufOffset, true)
int	getTo(IOBuffer iobuf, int iobufOffset, boolean withMagic) Copy the contents of a packet's header and body buffers to an IOBuffer
int	getTo(IOElasticBuffer iobuf, int iobufOffset) Copy the contents of a packet's header and body buffers to an IOElasticBuffer This method invokes return getTo(iobuf, iobufOffset, true)
int	getTo(IOElasticBuffer iobuf, int iobufOffset, boolean withMagic) Copy the contents of a packet's header and body buffers to an IOElasticBuffer
int	getTo(long addr, int addrOffset) Copy the contents of a packet's header and body buffers to a native memory region This method invokes return getTo(addr, addrOffset, true)
int	getTo(long addr, int addrOffset, boolean withMagic) Copy the contents of a packet's header and body buffers to a native memory region
PktPacket	init() Implementation of UtlPool.Item#init.
int	putFrom(ByteBuffer buf, int bufOffset) Copy the contents of a packet's header and body buffers from a byte buffer
int	putFrom(IOBuffer iobuf, int iobufOffset) Copy the contents of a packet's header and body buffers from an IOBuffer This method invokes putFrom(iobuf, iobufOffset, false, false)
int	putFrom(IOBuffer iobuf, int iobufOffset, boolean wrap) Copy the contents of a packet's header and body buffers from an IOBuffer This method invokes putFrom(iobuf, iobufOffset, wrap, wrap)
int	putFrom(IOBuffer iobuf, int iobufOffset, boolean wrapHeader, boolean wrapBody) Copy the contents of a packet's header and body buffers from an IOBuffer
int	putFrom(long addr, int addrOffset) Copy the contents of a packet's header and body buffers from a native memory region
int	putFrom(PktPacket packet) Copy from a packet
UtlReferenceTracker	referenceTracker() Get an object's reference tracker.
PktPacket	reset(boolean initBackingBuffers) Reset a packet
int	serialize(byte[] array, int arrayOffset) Serialize a packet to a byte array This method invokes serialize(array, arrayOffset, true)
int	serialize(byte[] array, int arrayOffset, boolean withMagic) Serialize a packet to a byte array This method invokes syncf().getTo(array, arrayOffset, withMagic)
int	serialize(ByteBuffer buf) Serialize a packet to a byte buffer This method invokes serialize(buf, true)
int	serialize(ByteBuffer buf, boolean withMagic) Serialize a packet to a byte buffer This method invokes serialize(buf, buf.position(), withMagic)
int	serialize(ByteBuffer buf, int bufOffset) Serialize a packet to a byte buffer This method invokes serialize(buf, bufOffset, true)
int	serialize(ByteBuffer buf, int bufOffset, boolean withMagic) Serialize a packet to a byte buffer This method invokes syncf().getTo(buf, bufOffset, withMagic)
int	serialize(IOBuffer iobuf, int iobufOffset) Serialize a packet to an IO buffer This method invokes serialize(iobuf, iobufOffset, true)
int	serialize(IOBuffer iobuf, int iobufOffset, boolean withMagic) Serialize a packet to an IO buffer This method invokes syncf().getTo(iobuf, iobufOffset, withMagic)
int	serialize(IOElasticBuffer iobuf, int iobufOffset) Serialize a packet to an elastic IO buffer This method invokes serialize(iobuf, iobufOffset, true)
int	serialize(IOElasticBuffer iobuf, int iobufOffset, boolean withMagic) Serialize a packet to an elastic IO buffer This method invokes syncf().getTo(iobuf, iobufOffset, withMagic)
int	serialize(long addr, int addrOffset) Serialize a packet to a native memory region This method invokes serialize(addr, addrOffset, true)
int	serialize(long addr, int addrOffset, boolean withMagic) Serialize a packet to a native memory region This method invokes syncf().getTo(addr, addrOffset, withMagic)
PktPacket	setPool(UtlPool<PktPacket> pool) Implementation of UtlPool.Item#setPool.
void	setTag(int id, Object tag) Set a packet tag.
int	sync() Sync a packet's header and body
PktPacket	syncf() Sync method for use with fluent programming
String	toString() Return a string representation of the object.

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

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

getSerializedLength

public final int getSerializedLength()

Get the serialized length of a packet

sync

public final int sync()

Sync a packet's header and body

Returns:

Returns the length of the serialized contents

Invoking this method ensures that a packet is fully serialized to it backing buffers and can be copied out

desync

public final void desync()

Desync the early desync contents of a packet body's backing buffer

syncf

public final PktPacket syncf()

Sync method for use with fluent programming

Returns:

Return this instance for fluent invocation chaining

This method is the same as sync() except it return this object instead of length for fluent invocation chaining

getTo

public final int getTo(ByteBuffer buf,
                       int bufOffset,
                       boolean withMagic)

Copy the contents of a packet's header and body buffers to a byte buffer

Parameters:

buf - The byte buffer to copy to

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

withMagic - Whether to copy the magic number or not

Returns:

length The number of bytes copied

This method copies the contents of a packet' header and body buffers to a byte buffer. It 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 buffer.

Note:Since this method does not change any markers of the target buffer, the caller needs to ensure the buffer has enough capacity to accommodate the packet's contents. The caller can invoke getSerializedLength() to get the length of the header's contents and use that to set the target buffer's capacity before invoking this method. Note:This method does not invoke sync() before doing the copy. The caller needs to ensure that sync() is invoked prior to invoking this method.

getTo

public final int getTo(ByteBuffer buf,
                       int bufOffset)

Copy the contents of a packet's header and body buffers to a byte buffer

This method invokes return getTo(buf, bufOffset, true)

getTo

public final int getTo(ByteBuffer buf,
                       boolean withMagic)

Copy the contents of a packet's header and body buffers to a byte buffer

This method invokes return getTo(buf, buf.position(), withMagic)

getTo

public final int getTo(ByteBuffer buf)

Copy the contents of a packet's header and body buffers to a byte buffer

This method invokes return getTo(buf, true)

getTo

public final int getTo(byte[] array,
                       int arrayOffset,
                       boolean withMagic)

Copy the contents of a packet's header and body buffers to a byte array

Parameters:

array - The byte array to copy to

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

withMagic - Whether to copy the magic number or not

Returns:

length The number of bytes copied

This method copies the contents of a packet' header and body buffers to a byte array.

Note:The caller needs to ensure the target array has enough capacity to accommodate the packet's serialized contents. The caller can invoke the getSerializedLength() method to get the length of the header's contents to ensure the target array is sized correctly Note:This method does not invoke sync() before doing the copy. The caller needs to ensure that sync() is invoked prior to invoking this method.

getTo

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

Copy the contents of a packet's header and body buffers to a byte array

This method invokes return getTo(array, arrayOffset, true)

getTo

public final int getTo(IOBuffer iobuf,
                       int iobufOffset,
                       boolean withMagic)

Copy the contents of a packet's header and body buffers to an IOBuffer

Parameters:

iobuf - The IO buffer to copy to

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

withMagic - Whether to copy the magic number or not

Returns:

length The number of bytes copied

This method copies the contents of a packet' header and body buffers to an IOBuffer.

Note:The caller needs to ensure the target buffer has enough capacity to accommodate the packet's serialized contents. The caller can invoke the getSerializedLength() method to get the length of the header's contents to ensure the target buffer is sized correctly Note:This method does not invoke sync() before doing the copy. The caller needs to ensure that sync() is invoked prior to invoking this method.

getTo

public final int getTo(IOBuffer iobuf,
                       int iobufOffset)

Copy the contents of a packet's header and body buffers to an IOBuffer

This method invokes return getTo(iobuf, iobufOffset, true)

getTo

public final int getTo(IOElasticBuffer iobuf,
                       int iobufOffset,
                       boolean withMagic)

Copy the contents of a packet's header and body buffers to an IOElasticBuffer

Parameters:

iobuf - The IO buffer to copy to

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

withMagic - Whether to copy the magic number or not

Returns:

length The number of bytes copied

This method copies the contents of a packet' header and body buffers to an IOElasticBuffer.

Note:This method does not invoke sync() before doing the copy. The caller needs to ensure that sync() is invoked prior to invoking this method.

getTo

public final int getTo(IOElasticBuffer iobuf,
                       int iobufOffset)

Copy the contents of a packet's header and body buffers to an IOElasticBuffer

This method invokes return getTo(iobuf, iobufOffset, true)

getTo

public final int getTo(long addr,
                       int addrOffset,
                       boolean withMagic)

Copy the contents of a packet's header and body buffers to a native memory region

Parameters:

addr - The address of the native memory region to copy to

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

withMagic - Whether to copy the magic number or not

Returns:

length The number of bytes copied

This method copies the contents of a packet' header and body buffers to a native memory region

Note:The caller needs to ensure the target buffer has enough capacity to accommodate the packet's serialized contents. The caller can invoke the getSerializedLength() method to get the length of the header's contents to ensure the target buffer is sized correctly Note:This method does not invoke sync() before doing the copy. The caller needs to ensure that sync() is invoked prior to invoking this method.

getTo

public final int getTo(long addr,
                       int addrOffset)

Copy the contents of a packet's header and body buffers to a native memory region

This method invokes return getTo(addr, addrOffset, true)

putFrom

public final int putFrom(ByteBuffer buf,
                         int bufOffset)

Copy the contents of a packet's header and body buffers from a byte buffer

Parameters:

buf - The byte buffer to copy from

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

Returns:

returns the serialized length of the packet

This method copies the serialized form of a packet from a byte buffer. The method first copies data from the supplied buffer to the packet header's buffer followed by to the packet body's buffer.

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.getSerializedPacketLength(java.nio.ByteBuffer, int, int)

putFrom

public final int putFrom(IOBuffer iobuf,
                         int iobufOffset,
                         boolean wrapHeader,
                         boolean wrapBody)

Copy the contents of a packet's header and body buffers from an IOBuffer

Parameters:

iobuf - The IO buffer to copy from

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

wrapHeader - If true, then the deserialization process will wrap the packet header around the supplied IO buffer

wrapBody - If true, then the deserialization process will wrap the packet body's buffer around the supplied IO buffer

Returns:

returns the serialized length of the packet

This method copies the serialized form of a packet from an IOBuffer. The method first copies data from the supplied buffer to the packet header's buffer followed by to the packet body's buffer.

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.getSerializedPacketLength(java.nio.ByteBuffer, int, int)

putFrom

public final int putFrom(IOBuffer iobuf,
                         int iobufOffset,
                         boolean wrap)

Copy the contents of a packet's header and body buffers from an IOBuffer

This method invokes putFrom(iobuf, iobufOffset, wrap, wrap)

putFrom

public final int putFrom(IOBuffer iobuf,
                         int iobufOffset)

Copy the contents of a packet's header and body buffers from an IOBuffer

This method invokes putFrom(iobuf, iobufOffset, false, false)

putFrom

public final int putFrom(long addr,
                         int addrOffset)

Copy the contents of a packet's header and body buffers from a native memory region

Parameters:

addr - The address of the memory region containing the serialized packet

addrOffset - The offset into the region where the serialized packet starts

Returns:

returns the serialized length of the packet

This method copies the serialized form of a packet from a native memory region. The method first copies data from the supplied region to the packet header's buffer followed by to the packet body's buffer.

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.getSerializedPacketLength(java.nio.ByteBuffer, int, int)

putFrom

public final int putFrom(PktPacket packet)

Copy from a packet

Returns:

This object for invocation chaining

This method assumes that the source packet has already been sync'd

serialize

public final int serialize(ByteBuffer buf,
                           int bufOffset,
                           boolean withMagic)

Serialize a packet to a byte buffer

This method invokes syncf().getTo(buf, bufOffset, withMagic)

serialize

public final int serialize(ByteBuffer buf,
                           int bufOffset)

Serialize a packet to a byte buffer

This method invokes serialize(buf, bufOffset, true)

serialize

public final int serialize(ByteBuffer buf,
                           boolean withMagic)

Serialize a packet to a byte buffer

This method invokes serialize(buf, buf.position(), withMagic)

serialize

public final int serialize(ByteBuffer buf)

Serialize a packet to a byte buffer

This method invokes serialize(buf, true)

serialize

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

Serialize a packet to a byte array

This method invokes syncf().getTo(array, arrayOffset, withMagic)

serialize

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

Serialize a packet to a byte array

This method invokes serialize(array, arrayOffset, true)

serialize

public final int serialize(IOBuffer iobuf,
                           int iobufOffset,
                           boolean withMagic)

Serialize a packet to an IO buffer

This method invokes syncf().getTo(iobuf, iobufOffset, withMagic)

serialize

public final int serialize(IOBuffer iobuf,
                           int iobufOffset)

Serialize a packet to an IO buffer

This method invokes serialize(iobuf, iobufOffset, true)

serialize

public final int serialize(IOElasticBuffer iobuf,
                           int iobufOffset,
                           boolean withMagic)

Serialize a packet to an elastic IO buffer

This method invokes syncf().getTo(iobuf, iobufOffset, withMagic)

serialize

public final int serialize(IOElasticBuffer iobuf,
                           int iobufOffset)

Serialize a packet to an elastic IO buffer

This method invokes serialize(iobuf, iobufOffset, true)

serialize

public final int serialize(long addr,
                           int addrOffset,
                           boolean withMagic)

Serialize a packet to a native memory region

This method invokes syncf().getTo(addr, addrOffset, withMagic)

serialize

public final int serialize(long addr,
                           int addrOffset)

Serialize a packet to a native memory region

This method invokes serialize(addr, addrOffset, true)

deserialize

public final int deserialize(ByteBuffer buf,
                             int bufOffset)

Deserialize a packet from a byte buffer

This method invokes putFrom(buf, bufOffset) followed by desync()

deserialize

public final int deserialize(IOBuffer iobuf,
                             int iobufOffset,
                             boolean wrapHeader,
                             boolean wrapBody)

Deserialize a packet from an IO buffer

This method invokes putFrom(iobuf, iobufOffset, wrapHeader, wrapBody) followed by desync()

deserialize

public final int deserialize(PktPacket packet)

Deserialize a packet from another packet

deserialize

public final int deserialize(IOBuffer iobuf,
                             int iobufOffset,
                             boolean wrap)

Deserialize a packet from an IO buffer

This method invokes deserialize(iobuf, iobufOffset, wrap, wrap)

deserialize

public final int deserialize(IOBuffer iobuf,
                             int iobufOffset)

Deserialize a packet from an IO buffer

This method invokes deserialize(iobuf, iobufOffset, false, false)

deserialize

public final int deserialize(long addr,
                             int addrOffset)

Deserialize a packet from a native memory region

This method invokes putFrom(addr, addrOffset) followed by desync()

reset

public final PktPacket reset(boolean initBackingBuffers)

Reset a packet

Parameters:

initializeBuffer - Whether to wipe and initialize the backing buffer

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<T>)

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