org.jnetstream.protocol
Interface ProtocolInfo<T extends Header>

All Known Subinterfaces:

ProtocolGroup

All Known Implementing Classes:

NullProtocol

public interface ProtocolInfo<T extends Header>

Defines access to a Protocol. Protocols are supplied to help deal with disecting raw packet byte buffers, analyzing protocol specific structure and state. Also verify protocol integrity and check for errors.

Since:

0.2.4

Author:

Mark Bednarczyk, Sly Technologies, Inc

Nested Class Summary

static interface	ProtocolInfo.Binding Binding between protocols.
static interface	ProtocolInfo.ID Defines a unique identification of a protocol.
static interface	ProtocolInfo.Info Informational interface which provides information about the protocol.
static interface	ProtocolInfo.Registry Protocol registry factory methods.
static class	ProtocolInfo.Suite Enum structure which defines all of the jNetStream system defined protocol suites.

Field Summary

static int

NO_BIT_INDEX

Method Summary

void	addBinding(ProtocolInfo.Binding binding)
Codec[]	getAvailableCodecs() Returns all available codecs for this protocol.
ProtocolInfo.Binding[]	getBindings() Gets all of the bindings current attached to this protocol
int	getBitIndex() Returns a special bit index for core protocols.
java.util.Set<Characteristic>	getCharacteristics() Gets a set of special characteristics for this protocol.
int	getCharacteristicsValue() Retrieves various characteristics for this protocol.
HeaderCodec<? extends Header>	getCodec() Returns the current Codec that is responsible for Encoding/Decoding the packet's data buffer to a decomposed state accessible using the Packet public API.
ProtocolInfo.ID	getID() Gets the ID, Identification object which uniquely identifies this protocol.
int	getLength(com.slytechs.utils.memory.BitBuffer bits, int offset)
java.lang.String	getName() Returns the name of this protocol.
java.util.Set<ProtocolInfo<? extends Header>>	getProtocolReferences() Gets a list of all the protocols this protocol references either inside a codec or a binding.
ProtocolInfo.Suite	getSuite() Returns the protocol suite this protocol belongs to.
java.lang.Class<T>	getType()
boolean	isLoaded() Checks if any of the current protocol's codecs have been loaded.
boolean	isProtocolGroup() Method which checks if this protocol is actually a protocol group.
boolean	prioritiseBindings() Forces the protocol to reprioritize its bindings.
void	pushCodec(HeaderCodec<? extends Header> codec) Pushes codec on to a prioritised queue where the highest priority codec is used for actively decoding header content.
int	setBindingWeight(int weight) Changes the prioritisation weight of bindings for this protocol.

Field Detail

NO_BIT_INDEX

static final int NO_BIT_INDEX

See Also:

Constant Field Values

Method Detail

getProtocolReferences

java.util.Set<ProtocolInfo<? extends Header>> getProtocolReferences()

Gets a list of all the protocols this protocol references either inside a codec or a binding.

Returns:

list of all the referenced protocols

getAvailableCodecs

Codec[] getAvailableCodecs()

Returns all available codecs for this protocol. All the available codecs have already been loaded into memory.

Returns:

array of currently available codecs

See Also:

isLoaded()

getCodec

HeaderCodec<? extends Header> getCodec()

Returns the current Codec that is responsible for Encoding/Decoding the packet's data buffer to a decomposed state accessible using the Packet public API. Each codec is assigned a priority which determines which one is actively used, if more than one codec exists for a protocol. You can check codec priority with getPriority and change it using setPriority

Returns:

the currently assigned codec

See Also:

HeaderCodec#getPriority(), HeaderCodec#setPriority(org.jnetstream.protocol.codec.HeaderCodec.Priority)

getName

java.lang.String getName()

Returns the name of this protocol. Protocol names are unique.

Returns:

name of this protocol

See Also:

ProtocolInfo.ID.getIdString()

getID

ProtocolInfo.ID getID()

Gets the ID, Identification object which uniquely identifies this protocol. Each protocol is assigned a unique ID object and a unique integer hash value. The ID structure can be used to uniquely identify a protocol.

Returns:

ID structure that uniquely identifies this protocol

getSuite

ProtocolInfo.Suite getSuite()

Returns the protocol suite this protocol belongs to. Many protocol suites have been predefined for all standard and common protocols.

Returns:

protocol suite of this protocol

See Also:

ProtocolInfo.Suite

isLoaded

boolean isLoaded()

Checks if any of the current protocol's codecs have been loaded. Each protocol can have a number of codecs assigned to it. The codecs are first assigned by a reference ID, but not neccessarily loaded into memory. When the codec is needed for decoding of a packet, and its not currently loaded, the protocol will request that the codec be loaded into memory. This may take a slight amount of time to do, but only needs to be done once. After the codec has been loaded it remains in memory and is available for immediate utilization.

Returns:

true if any of the protocol's codecs has been loaded, otherwise false.

See Also:

pushCodec(HeaderCodec)

pushCodec

void pushCodec(HeaderCodec<? extends Header> codec)

Pushes codec on to a prioritised queue where the highest priority codec is used for actively decoding header content. Each codec is assigned a priority which determines which one of the codecs is currently active.

Parameters:

codec - codec to push on to the priority queue list

See Also:

HeaderCodec#getPriority(), HeaderCodec#setPriority(org.jnetstream.protocol.codec.HeaderCodec.Priority)

getCharacteristics

java.util.Set<Characteristic> getCharacteristics()

Gets a set of special characteristics for this protocol. The set contains various types of characteristics such as Frame and Physical. Each class of characteristics is defined in its own enum structure which can be used to check against the set.

 Protocol ethernet = // from some source
 Set<Characteristics> ch = ethernet.getCharacteristics();
 if (ch.contains(Frame.HasCRC)) {
   // Do something
 } else if (ch.contains(Physical.Serial)) {
   // Do something with a serial line based protocol
 }
 

Returns:

a set containing any special characteristics that this protocol has

getCharacteristicsValue

int getCharacteristicsValue()

Retrieves various characteristics for this protocol.

Returns:

a 32-bit unsigned integer value whos bits are encoded with various characteristics for this protocol

See Also:

method for description of how decode characteristic enum constants out of the integer representation

prioritiseBindings

boolean prioritiseBindings()

Forces the protocol to reprioritize its bindings. Each binding keeps a hit counter which is incremented when a binding succeeds and decremented when it fails. The hit counter is used to place bindings that are successful more often at the front of the list. This allows a more popular binding to be at the top of the list which is more efficient in most cases. The protocol automatically reprioritises the binding list according to binding prioritisation weight setBindingWeight.

Returns:

true means that changes did occur as a result of the prioritization, otherwise false

See Also:

setBindingWeight(int)

setBindingWeight

int setBindingWeight(int weight)

Changes the prioritisation weight of bindings for this protocol. The lower the value, the more often the protocol will reprioritize the bindings according to their usage.

Parameters:

weight - A non negative value specifying the priority weight. The lower the value the more often reprioritization algorithm is run. A value of zero turns off prioritization completely.

Returns:

the previous weight value

See Also:

prioritiseBindings()

addBinding

void addBinding(ProtocolInfo.Binding binding)

getBindings

ProtocolInfo.Binding[] getBindings()

Gets all of the bindings current attached to this protocol

Returns:

array of bindinds

getType

java.lang.Class<T> getType()

Returns:

getBitIndex

int getBitIndex()

Returns a special bit index for core protocols. Bit indexes are used to significantly speedup the process of caching certain protocol information within a packet. Only the core protocols can provide a bit index. All other non-core protocols must return value of 0.

Returns:

bit index if this is a core protocol, otherwise 0

isProtocolGroup

boolean isProtocolGroup()

Method which checks if this protocol is actually a protocol group. Protocol groups do not have any codecs, only pure bindings. All CODEC related methods are disabled, therefore it is required to check first if this protocol is a normal or a group protocol.

Returns:

true means that this is a protocol group, otherwise false

getLength

int getLength(com.slytechs.utils.memory.BitBuffer bits,
              int offset)

Parameters:

bits -

offset - TODO

Returns: