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.util.UtlPool.Item<PktPacket>, com.neeve.util.UtlReferenceTracker.HasReferenceTracker

public final class PktPacket
extends PktSerializable
implements com.neeve.util.UtlPool.Item<PktPacket>, com.neeve.util.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.
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 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.
PktBody	getBody() Get the packet body.
PktHeader	getHeader() Get the packet header.
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.
com.neeve.util.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.
com.neeve.util.UtlReferenceTracker	referenceTracker()
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(com.neeve.util.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 com.neeve.util.UtlReferenceTracker referenceTracker()

Specified by:

referenceTracker in interface com.neeve.util.UtlReferenceTracker.HasReferenceTracker

fork

public final PktPacket fork()

Fork a packet

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.

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)

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

getSerializedLength

public final int getSerializedLength()

Implementation of PktSerializable.getSerializedLength().

Specified by:

getSerializedLength in class PktSerializable

init

public final PktPacket init()

Implementation of UtlPool.Item#init.

Specified by:

init in interface com.neeve.util.UtlPool.Item<PktPacket>

setPool

public final PktPacket setPool(com.neeve.util.UtlPool<PktPacket> pool)

Implementation of UtlPool.Item#setPool.

Specified by:

setPool in interface com.neeve.util.UtlPool.Item<PktPacket>

getPool

public final com.neeve.util.UtlPool<PktPacket> getPool()

Implementation of UtlPool.Item#getPool.

Specified by:

getPool in interface com.neeve.util.UtlPool.Item<PktPacket>

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