com.neeve.pkt
Class PktSerializable

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

All Implemented Interfaces:

com.neeve.io.IOElasticBuffer.Sizer

Direct Known Subclasses:

PktBody, PktHeader, PktPacket

public abstract class PktSerializable
extends UtlListElement
implements com.neeve.io.IOElasticBuffer.Sizer

Represents a serialiable packet entity.

This abstract class represents a serializable packet entity. Any packet entity that supports being serializable to and from a byte array extends this class.

Threading:

Serialiable entities are not safe for concurrent access by multiple threads.

Nested Class Summary

static class	PktSerializable.DeserializeContext Contains context used in the deserialization of an entity.
static class	PktSerializable.SerializeContext Contains context used in the serialization of an entity.

Field Summary

Fields inherited from class com.neeve.util.UtlListElement

count, head, next, prev

Constructor Summary

PktSerializable()

Method Summary

void	deserialize(PktSerializable.DeserializeContext context) Deserialize an entity from a byte buffer (array).
abstract void	deserialize(PktSerializable.DeserializeContext context, int entitySerializedLength, Tracer tracer) Deserialize an entity from a byte buffer (array).
int	getDeserializationPolicy() Get the deserialization policy for this entity.
int	getSerializationPolicy() Get the serialization policy for this entity.
abstract int	getSerializedLength() Get the serialized length of this entity.
static boolean	isValidDeserializationPolicy(int policy) Validates a deserialization policy
static boolean	isValidSerializationPolicy(int policy) Validates a serialization policy
void	serialize(PktSerializable.SerializeContext context) Serialize this entity into a byte array.
abstract void	serialize(PktSerializable.SerializeContext context, Tracer tracer) Serialize this entity into a byte array.
void	setDeserializationPolicy(int policy) Set the deserialization policy for this entity.
void	setSerializationPolicy(int policy) Set the serialization policy for this entity.

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, toString, wait, wait, wait

Methods inherited from interface com.neeve.io.IOElasticBuffer.Sizer

getInitialBufferLength

Constructor Detail

PktSerializable

public PktSerializable()

Method Detail

isValidSerializationPolicy

public static final boolean isValidSerializationPolicy(int policy)

Validates a serialization policy

Returns:

Returns true in case the specified policy is valid and false otherwise.

Threading:

This method is safe for concurrent access by multiple threads

isValidDeserializationPolicy

public static final boolean isValidDeserializationPolicy(int policy)

Validates a deserialization policy

Returns:

Returns true in case the specified policy is valid and false otherwise.

Threading:

This method is safe for concurrent access by multiple threads

setSerializationPolicy

public void setSerializationPolicy(int policy)

Set the serialization policy for this entity.

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

Throws:

IllegalArgumentException - Thrown in case the specified policy is invalid

This method sets the serialization policy to use for this entity. Refer to the documentation of each policy for further information about the policy. The serialization policy set here is overriden by the policy specified when the entity is serialized (serialize(com.neeve.pkt.PktSerializable.SerializeContext, com.neeve.trace.Tracer).

Threading:

This method is not safe for concurrent access by multiple threads

getSerializationPolicy

public int getSerializationPolicy()

Get the serialization policy for this entity.

Threading:

This method is not safe for concurrent access by multiple threads

serialize

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

Serialize this entity into a byte array.

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)

Threading:

This method is not safe for concurrent access by multiple threads

serialize

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

Serialize this entity into a byte array.

This method invoked serialize(context, null)

Throws:

EPktSerializeException

setDeserializationPolicy

public void setDeserializationPolicy(int policy)

Set the deserialization policy for this entity.

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

Throws:

IllegalArgumentException - Thrown in case the specified policy is invalid

This method sets the deserialization policy to use for this entity. Refer to the documentation of each policy for further information about the policy. The deserialization policy set here is overriden by the policy specified when this entity is serialized (deserialize(com.neeve.pkt.PktSerializable.DeserializeContext, int, com.neeve.trace.Tracer).

Threading:

This method is not safe for concurrent access by multiple threads

getDeserializationPolicy

public int getDeserializationPolicy()

Get the deserialization policy for this entity.

Threading:

This method is not safe for concurrent access by multiple threads

deserialize

public abstract void deserialize(PktSerializable.DeserializeContext context,
                                 int entitySerializedLength,
                                 Tracer tracer)
                          throws EPktDeserializeException

Deserialize an entity from a byte buffer (array).

Parameters:

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

entitySerializedLength - 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.

Threading:

This method is not safe for concurrent access by multiple threads

deserialize

public final void deserialize(PktSerializable.DeserializeContext context)
                       throws EPktDeserializeException

Deserialize an entity from a byte buffer (array).

This method invokes deserialize(context, null)

Throws:

EPktDeserializeException

getSerializedLength

public abstract int getSerializedLength()

Get the serialized length of this entity.

Threading:

This method is not safe for concurrent access by multiple threads