com.voytechs.jnetstream.codec
Class FlowDecoder

java.lang.Object
  com.voytechs.jnetstream.codec.event.DecoderSupport
      com.voytechs.jnetstream.codec.FlowDecoder

All Implemented Interfaces:

DecoderListener

public class FlowDecoder
extends DecoderSupport
implements DecoderListener

Flow decoder is used to group packets into flows. A flow is a stream of packets flowing between 2 end points.

A flow has a abstract concept of a direction. The direction is completely arbitrary and determined by the first packet within the flow. From then on packets from the same source->destination pair are termed as going in the Flow.RIGHT direction and when packet is seen with reverse addresses its labeled as going in the Flow.LEFT direction. Again this is determinted by the first packet.

There are two way for accessing flows. First is using the nextFlow() method. The second method is by implementing the event.DecoderListener interface and using the DecoderSupport.addListener(DecoderListener) method to register. The listener will be notified of a number of events in real time. Such as DecoderFlowEvent.NEW_FLOW, DecoderFlowEvent.RIGHT_PACKET, DecoderFlowEvent.LEFT_PACKET, DecoderFlowEvent.EXPIRED_FLOW

Here is an example:

        public static void main(String[] args) {
                try {
                        Decoder packet = new Decoder(args[0]);
                        FlowDecoder decoder = new FlowDecoder(packet);
                        Flow flow = null;
                        
                        while ( (flow = decoder.nextFlow()) != null) {
                                System.out.println(flow.toString());
                        }

                } catch (Exception e) {
                        e.printStackTrace();
                }

                System.out.println("DONE");
        }
 

There are other concepts introduced with FlowDecoder such as unidirectional flows setBiDirectionalFlows(boolean) and methods how packets are pumped from packet decoder setPumpPackets(boolean) into the flow decoder. In the first case when flow decoder has been told to create uni-directional flows TCP streams would have 2 flows created corresponding to a flow in each of the 2 directions of a TCP stream.

Since:

0.2.3

Author:

Mark Bednarczyk

Field Summary

static long

EXPIRE_FLOWS_TIMEOUT

Fields inherited from class com.voytechs.jnetstream.codec.event.DecoderSupport

EVENT_ALL

Constructor Summary

FlowDecoder()

FlowDecoder(Decoder decoder)

FlowDecoder(DecoderSupport decoder)
Initializes the flow decoder.

Method Summary

protected void	acceptPacket(Packet packet, FlowKey key) Main method that accepts a just decoded packet and assigns it to a specific flow.
void	expireAllActiveFlows() Expire all active flows and put them on the expired list.
void	expireFlow(Flow flow, Packet cause) Remove a flow from the list of active flows and onto the list of expired flows.
FlowList	getFlows() Returns the list of current flows.
static void	main(java.lang.String[] args) Test method.
Flow	nextFlow() Returns the next flow that has been expired or completed and is ready to be returned to the user.
void	processDecoderEvent(DecoderEvent event) Callback method for dispatcher events.
void	setBiDirectionalFlows(boolean enable) Method which tells the decoder if it should create bidirectional or unidirectional flows.
void	setPumpPackets(boolean state) Sets a flag that tells the decoder to internally pump packats from from packet decoder or to allow packets to be pumped externally.

Methods inherited from class com.voytechs.jnetstream.codec.event.DecoderSupport

addListener, addListener, fireDecoderEvent, getListeners, getListenersForAll, hasListeners, hasListeners

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EXPIRE_FLOWS_TIMEOUT

public static final long EXPIRE_FLOWS_TIMEOUT

See Also:

Constant Field Values

Constructor Detail

FlowDecoder

public FlowDecoder()

FlowDecoder

public FlowDecoder(DecoderSupport decoder)

Initializes the flow decoder. This flow decoder will use the supplied decoder as the source of packets. The packets will retrieved and appropriate flows created.

Parameters:

decoder - The decoder to be used for generating flows.

Throws:

java.lang.IllegalArgumentException - This constructor checks for decoder object being null. If it is a IllegalArgumentException is thrown. This is a critical parameter that must be specified.

FlowDecoder

public FlowDecoder(Decoder decoder)

Method Detail

processDecoderEvent

public void processDecoderEvent(DecoderEvent event)
                         throws AssertFailure

Callback method for dispatcher events.

Specified by:

processDecoderEvent in interface DecoderListener

Parameters:

event - Dispatcher event that caused this callback.

Throws:

AssertFailure - Whatever object was being created by the Decoder when the event was dispatched, will be aborted. (VETO power)

See Also:

DecoderEvent

acceptPacket

protected void acceptPacket(Packet packet,
                            FlowKey key)
                     throws AssertFailure

Main method that accepts a just decoded packet and assigns it to a specific flow.

Parameters:

packet - packet to assign to a flow

flowkey - the flow key associated with the packet. You can retrieve the flow key by using "(FlowKey) packet.getValue(Packet.FLOWKEY)" property.

Throws:

AssertFailure

expireFlow

public void expireFlow(Flow flow,
                       Packet cause)
                throws AssertFailure

Remove a flow from the list of active flows and onto the list of expired flows. The decoder can further return the flows to the users that are completed and expired.

Parameters:

flow - flow to the expired.

cause - the packet that cuased the flow to expire

Throws:

AssertFailure

expireAllActiveFlows

public void expireAllActiveFlows()
                          throws AssertFailure

Expire all active flows and put them on the expired list.

Throws:

AssertFailure

setPumpPackets

public void setPumpPackets(boolean state)

Sets a flag that tells the decoder to internally pump packats from from packet decoder or to allow packets to be pumped externally. If set to false then the user has to pump packets in the packet decoder. That is call the Decoder.nextPacket() method before calling nextFlow() method. Also if packet decoder is finished make sure to expire all active flows and continue to call nextFlow() to extract the remainder of the flows until nextFlow() returns null as well indicating that all flows are complete and have been returned.

Parameters:

state - true if you want FlowDecoder to pump the packets, false if the user is going to do it externally.

nextFlow

public Flow nextFlow()
              throws StreamFormatException,
                     java.io.IOException

Returns the next flow that has been expired or completed and is ready to be returned to the user. Flow could have been expired for several reasons including reaching the Flow.MAX_PACKET count and timeout has been reached or appropriate protocol analyzer has determined that the flow has completed such as TCP FIN handshaking has taken place.

Returns:

flow that is complete and is ready to be returned.

Throws:

StreamFormatException

java.io.IOException

getFlows

public FlowList getFlows()

Returns the list of current flows.

Returns:

list of flows.

setBiDirectionalFlows

public void setBiDirectionalFlows(boolean enable)

Method which tells the decoder if it should create bidirectional or unidirectional flows. In a unidirectional flow a TCP Stream will will have 2 flows associated with it and packets in both flows will always will be marked as being in the RIGHT direction.

Parameters:

enable - true (Default) means enable bi-directional flows. false means create uni-directional flows.

main

public static void main(java.lang.String[] args)

Test method.

Parameters:

args - args[0] must contain a filename of a capture file to use.