com.voytechs.jnetstream.codec
Class Decoder

java.lang.Object
  com.voytechs.jnetstream.npl.Visitor
      com.voytechs.jnetstream.codec.Decoder

public class Decoder
extends Visitor

Decoder is the main interpreter for NPL. Not the only one, parsing NPL file is a 3 stage process:

1. Parsing - npl.StatementParser and npl.ExpressionParser
2. Linker - codec.Linker
3. Decoder - codec.Decoder - this file.

Decoder has conveniece Constructor methods where you can supply the name of the NPL file and it will actually call on all 2 steps. And do the 3rd last step itself.

The job of the decoder is to based on the NPL compiled down to a AST (Abstract Syntax Tree) use the Visitor pattern to traverse each node of the the AST and perform neccessary actions. These actions result in the creation of Packet, Header and Field objects which read data from the capture stream and advance it appropriately.

The main method is the nextPacket() method which returns Packet object which is the decoded packet created based on the values of the capture stream.

Field Summary

static int	DEBUG_DEFAULT Internal debugging flag.
static int	DEBUG_STREAM Internal debuggin flag.
static java.lang.String	DO_REASSEMBLY Name of the variable that set the DO_REASSEMBLY property.
static int	DO_REASSEMBLY_DEFAULT
static java.lang.String	PACKET_INDEX The name of the packet index property.

Constructor Summary

Decoder()

Decoder(PacketInputStream captureStream)
Constructor that just requires a capture PacketInputStream.

Decoder(PacketInputStream in, java.io.InputStream protocolNplDef)
Constructor takes a capture file name.

Decoder(PacketInputStream in, java.util.List protocolFiles)
Constructor takes a capture file name.

Decoder(PacketInputStream in, java.util.List protocolFiles, java.lang.String watchVariable)
Constructor takes a capture file name.

Decoder(java.lang.String captureFile)
Constructor that just requires a capture file name.

Decoder(java.lang.String captureFile, java.util.List nplFiles, java.util.List captureFormatFiles)
Constructor takes a capture file name.

Method Summary

void	addListener(DecoderListener listener) Add listeners for events.
void	addListener(DecoderListener listener, java.lang.String eventType) Add listeners for events for specific event.
void	close() Closes the file or input stream.
boolean	enableFlowKeys(boolean state) Sets a flat if flowkeys should be generated for packets.
protected void	exportGlobalProperties(Context global) Utitility method which exports automatic properties.
protected void	exportPacketProperties(Context packet, MutablePacket mpacket) Utitility method which exports automatic properties.
PacketInputStream.BufferedHeader	getFileHeader()
PacketInputStream.BufferedHeader	getRecordHeader()
boolean	isCompressed() Is file or stream in compressed format.
boolean	isEnableFlowKeys() Returns if flow keys are being created or not.
boolean	isIgnoreDefaultCandidate() Should "Data" or another default header be used.
boolean	isUserSubheaders() A flag that indicates wheather sub headers of headers are merged or added to preserve the hierarchy.
protected StatementContainer	lookupTopLevelHeader(java.lang.String name) Utility method that looks up the name of a NPL header definition at the top of the AST (Abstract Syntax Tree).
Packet	nextPacket() Decode the next packet based on previously initialized PacketInputStream and the parsed NPL AST.
Packet	nextPacketWithEOP() Processes the next packet in the packet-byte-stream.
PacketInputStream	openCaptureFile(java.lang.String file) Open capture file using a list of format files.
void	openForDecode(java.lang.String captureFile)
protected Packet	readNextPacket() Processes the next packet in the packet-byte-stream.
void	setDebugHeaders(boolean state)
void	setIgnoreDefaultCandidate(boolean ignore) Should "Data" or another default header be used.
void	setUseSubheaders(boolean keep) Sets a flag in the decoder to tell it what to do with sub headers of headers.
boolean	traverse(AssertStatement stat, java.lang.Object user1, java.lang.Object user2)
boolean	traverse(BreakStatement stat, java.lang.Object user1, java.lang.Object user2)
boolean	traverse(BufferStatement stat, java.lang.Object user1, java.lang.Object user2)
boolean	traverse(ContinueStatement stat, java.lang.Object user1, java.lang.Object user2)
boolean	traverse(FamilyStatement stat, java.lang.Object user1, java.lang.Object user2) Visitor pattern for FamilyStatement.
boolean	traverse(FieldStatement stat, java.lang.Object user1, java.lang.Object user2) FIELD STATEMENT
boolean	traverse(FlowentryStatement stat, java.lang.Object user1, java.lang.Object user2)
boolean	traverse(FlowkeyStatement stat, java.lang.Object user1, java.lang.Object user2)
boolean	traverse(FlowpairStatement stat, java.lang.Object user1, java.lang.Object user2)
boolean	traverse(ForStatement stat, java.lang.Object user1, java.lang.Object user2)
boolean	traverse(HeaderStatement stat, java.lang.Object user1, java.lang.Object user2) Visitor pattern for HeaderStatement.
boolean	traverse(IfStatement stat, java.lang.Object user1, java.lang.Object user2)
boolean	traverse(LinkStatement stat, java.lang.Object user1, java.lang.Object user2)
boolean	traverse(OpNode node, java.lang.Object user1, java.lang.Object user2) Convenience function that dispatches visitor to all nodes in the list.
boolean	traverse(PrintStatement stat, java.lang.Object user1, java.lang.Object user2)
boolean	traverse(ProcessStatement stat, java.lang.Object user1, java.lang.Object user2)
boolean	traverse(PropertyStatement stat, java.lang.Object user1, java.lang.Object user2)
boolean	traverse(VariableStatement stat, java.lang.Object user1, java.lang.Object user2) Visitor pattern.
boolean	traverse(WhileStatement stat, java.lang.Object user1, java.lang.Object user2)
protected void	updateProperty(java.lang.String name, Context context, int value) Utility method which updates the value of an existing property.
protected void	updateProperty(java.lang.String name, Context context, IpAddress value) Utility method which updates the value of an existing property.
protected void	updateProperty(java.lang.String name, Context context, long value) Utility method which updates the value of an existing property.
protected void	updateProperty(java.lang.String name, Context context, java.lang.String value) Utility method which updates the value of an existing property.
protected void	updateProperty(java.lang.String name, Context context, java.sql.Timestamp value) Utility method which updates the value of an existing property.

Methods inherited from class com.voytechs.jnetstream.npl.Visitor

traverse, traverse, traverse, traverse, traverse, traverse, traverse, traverse, visit

Methods inherited from class java.lang.Object

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

Field Detail

DEBUG_DEFAULT

public static final int DEBUG_DEFAULT

Internal debugging flag. Indicated regular dubug messages.

See Also:

Constant Field Values

DEBUG_STREAM

public static final int DEBUG_STREAM

Internal debuggin flag. Indicates stream based messages.

See Also:

Constant Field Values

DO_REASSEMBLY

public static final java.lang.String DO_REASSEMBLY

Name of the variable that set the DO_REASSEMBLY property. Global local property

See Also:

Constant Field Values

DO_REASSEMBLY_DEFAULT

public static final int DO_REASSEMBLY_DEFAULT

See Also:

Constant Field Values

PACKET_INDEX

public static final java.lang.String PACKET_INDEX

The name of the packet index property. This is a LOCAL Integer property. This property is exported and updated for every packet and holds the 0-based index of the current packet being decoded.

See Also:

Constant Field Values

Constructor Detail

Decoder

public Decoder()

Decoder

public Decoder(java.lang.String captureFile)
        throws java.io.FileNotFoundException,
               java.io.IOException,
               SyntaxError

Constructor that just requires a capture file name. It performs a file open on the capture file. It uses the default NPL file normally found in the config directory or as a resource file in the JAR file.

Parameters:

in - Input capture stream with data to be decoded.

Throws:

java.io.FileNotFoundException - If protocols.npl file could not be found.

java.io.IOException - Any I/O errors.

SyntaxError - Any syntax errors in the protocols.npl file are reported.

Decoder

public Decoder(PacketInputStream captureStream)
        throws java.io.IOException,
               SyntaxError

Constructor that just requires a capture PacketInputStream. It uses the default NPL file normally found in the config directory or as a resource file in the JAR file.

Parameters:

captureStream - Input capture stream with data to be decoded.

Throws:

java.io.IOException - Any I/O errors.

SyntaxError - Any syntax errors in the protocols.npl file are reported.

Since:

JNetStream 0.2.2

Decoder

public Decoder(PacketInputStream in,
               java.util.List protocolFiles,
               java.lang.String watchVariable)
        throws java.io.FileNotFoundException,
               java.io.IOException,
               SyntaxError

Constructor takes a capture file name. It performs a file open on the capture file. It uses the user supplied NPL file and parses it to a AST Abstract Syntax Tree.

Parameters:

captureFile - Input capture file name with data to be decoded.

nplFile - protocolFiles A list of protocol NPL files.

watchVariable - A environment variable name which contains additional protocol files to load.

Throws:

java.io.FileNotFoundException - If protocols.npl file could not be found.

java.io.IOException - Any I/O errors.

SyntaxError - Any syntax errors in the protocols.npl file are reported.

Decoder

public Decoder(PacketInputStream in,
               java.io.InputStream protocolNplDef)
        throws java.io.FileNotFoundException,
               java.io.IOException,
               SyntaxError

Constructor takes a capture file name. It performs a file open on the capture file. It uses the user supplied NPL input stream and parses it to a AST Abstract Syntax Tree.

Parameters:

captureFile - Input capture file name with data to be decoded.

protocolNplDef - protocol NPL definition input stream

watchVariable - A environment variable name which contains additional protocol files to load.

Throws:

java.io.FileNotFoundException - If protocols.npl file could not be found.

java.io.IOException - Any I/O errors.

SyntaxError - Any syntax errors in the protocols.npl file are reported.

Decoder

public Decoder(PacketInputStream in,
               java.util.List protocolFiles)
        throws java.io.FileNotFoundException,
               java.io.IOException,
               SyntaxError

Constructor takes a capture file name. It performs a file open on the capture file. It uses the user supplied NPL file and parses it to a AST Abstract Syntax Tree.

Parameters:

captureFile - Input capture file name with data to be decoded.

nplFile - Main NPL file to use for decoding the capture stream.

Throws:

java.io.FileNotFoundException - If protocols.npl file could not be found.

java.io.IOException - Any I/O errors.

SyntaxError - Any syntax errors in the protocols.npl file are reported.

Decoder

public Decoder(java.lang.String captureFile,
               java.util.List nplFiles,
               java.util.List captureFormatFiles)
        throws java.io.FileNotFoundException,
               java.io.IOException,
               SyntaxError

Constructor takes a capture file name. It performs a file open on the capture file. It uses the user supplied list of protocol NPL files and parses them to a AST Abstract Syntax Tree.

Also takes a list of capture fomat files. These are also searched using same algorithm as the protocol NPL file.

Parameters:

captureFile - Input capture file name with data to be decoded.

nplFiles - List of NPL files to use for decoding the capture stream.

captureFormatFiles - List of NPL capture format files to use for decoding the capture files.

Throws:

java.io.FileNotFoundException - If protocols.npl file could not be found.

java.io.IOException - Any I/O errors.

SyntaxError - Any syntax errors in the protocols.npl file are reported.

Method Detail

openForDecode

public void openForDecode(java.lang.String captureFile)
                   throws java.io.FileNotFoundException,
                          java.io.IOException,
                          SyntaxError

Throws:

java.io.FileNotFoundException

java.io.IOException

SyntaxError

setDebugHeaders

public void setDebugHeaders(boolean state)

getFileHeader

public PacketInputStream.BufferedHeader getFileHeader()

Returns:

getRecordHeader

public PacketInputStream.BufferedHeader getRecordHeader()

Returns:

enableFlowKeys

public boolean enableFlowKeys(boolean state)

Sets a flat if flowkeys should be generated for packets.

Parameters:

state - true means flowkeys will be created, otherwise no.

Returns:

previous state of flow keys.

isEnableFlowKeys

public boolean isEnableFlowKeys()

Returns if flow keys are being created or not.

Returns:

true if flow keys are being created, otherwise false.

openCaptureFile

public PacketInputStream openCaptureFile(java.lang.String file)
                                  throws java.io.FileNotFoundException,
                                         java.io.IOException

Open capture file using a list of format files. The each format of the files is checked and appropriate File reader is used.

First the file is checked if its in GZIP format. If not then normal plain version is checked. File formats are assumed to be the default captureformats.npl file found in the config directory.

Parameters:

file - Filename to locate and open.

captureFormatFiles - A list of capture format file names.

Returns:

packet stream object.

Throws:

java.io.FileNotFoundException - if capture formats file is not found.

java.io.IOException - Any I/O errors.

addListener

public void addListener(DecoderListener listener)

Add listeners for events.

Parameters:

listener - Listener for all events.

addListener

public void addListener(DecoderListener listener,
                        java.lang.String eventType)

Add listeners for events for specific event.

Parameters:

listener - Listener for specific event.

eventType - Type of event to be dispatched on.

nextPacket

public Packet nextPacket()
                  throws StreamFormatException,
                         java.io.IOException,
                         SyntaxError

Decode the next packet based on previously initialized PacketInputStream and the parsed NPL AST.

Returns:

next packet from the stream or null if end of stream.

Throws:

SyntaxError - Any NPL syntax errors.

java.io.IOException - Any I/O errors.

StreamFormatException - Any problems with the capture stream.

nextPacketWithEOP

public Packet nextPacketWithEOP()
                         throws NodeException,
                                EOPacketStream,
                                StreamFormatException,
                                java.io.IOException

Processes the next packet in the packet-byte-stream. A number of exceptions can be thrown by this method. A Packet object is returned containing all of the headers that could be parsed.

Returns:

Packet full of headers if there were no errors. All errors are always throw as an exception. This method never returns null.

Throws:

NodeException - Any AST errors that occured. A usefull check to see if AssertionFailure exception occured.

EOPacketStream - Indicates no more packets in the current stream.

StreamFormatException - Stream is not formated properly.

java.io.IOException - any read/write errors that occured on thes tream.

readNextPacket

protected Packet readNextPacket()
                         throws NodeException,
                                EOPacketStream,
                                StreamFormatException,
                                java.io.IOException

Processes the next packet in the packet-byte-stream. A number of exceptions can be thrown by this method. A Packet object is returned containing all of the headers that could be parsed.

Returns:

Packet full of headers if there were no errors. All errors are always throw as an exception. This method never returns null.

Throws:

NodeException - Any AST errors that occured. A usefull check to see if AssertionFailure exception occured.

EOPacketStream - Indicates no more packets in the current stream.

StreamFormatException - Stream is not formated properly.

java.io.IOException - any read/write errors that occured on thes tream.

exportPacketProperties

protected void exportPacketProperties(Context packet,
                                      MutablePacket mpacket)

Utitility method which exports automatic properties. Properties are exported in to Packet context.

Parameters:

packet - Context to export this to.

exportGlobalProperties

protected void exportGlobalProperties(Context global)

Utitility method which exports automatic properties. Properties are exported in to global context.

Parameters:

packet - Context to export this to.

updateProperty

protected void updateProperty(java.lang.String name,
                              Context context,
                              IpAddress value)

Utility method which updates the value of an existing property.

Parameters:

name - Name of the property

context - The context in which the property exists

value - IP address to set for the property as new value.

updateProperty

protected void updateProperty(java.lang.String name,
                              Context context,
                              java.lang.String value)

Utility method which updates the value of an existing property.

Parameters:

name - Name of the property

context - The context in which the property exists

value - String value set for the property as new value.

updateProperty

protected void updateProperty(java.lang.String name,
                              Context context,
                              int value)

Utility method which updates the value of an existing property.

Parameters:

name - Name of the property

context - The context in which the property exists

value - Integer value set for the property as new value.

updateProperty

protected void updateProperty(java.lang.String name,
                              Context context,
                              long value)

Utility method which updates the value of an existing property.

Parameters:

name - Name of the property

context - The context in which the property exists

value - Long integer value set for the property as new value.

updateProperty

protected void updateProperty(java.lang.String name,
                              Context context,
                              java.sql.Timestamp value)

Utility method which updates the value of an existing property.

Parameters:

name - Name of the property

context - The context in which the property exists

value - Timestamp value set for the property as new value.

lookupTopLevelHeader

protected StatementContainer lookupTopLevelHeader(java.lang.String name)
                                           throws NodeException

Utility method that looks up the name of a NPL header definition at the top of the AST (Abstract Syntax Tree). The top of the tree is a NodeList object that contains all the top-level headers.

Parameters:

name - Name of the top level header to lookup starting at the root of the AST.

NodeException - If header is not found.

Throws:

NodeException

traverse

public boolean traverse(FamilyStatement stat,
                        java.lang.Object user1,
                        java.lang.Object user2)
                 throws NodeException

Visitor pattern for FamilyStatement. Family statement is empty method because its only a grouping object for header linking.

Overrides:

traverse in class Visitor

Throws:

NodeException

traverse

public boolean traverse(HeaderStatement stat,
                        java.lang.Object user1,
                        java.lang.Object user2)
                 throws NodeException

Visitor pattern for HeaderStatement. This is a major instruction in NPL. It defines the Header object that is added to a Packet object.

Overrides:

traverse in class Visitor

Parameters:

stat - Header statement from the AST. It contains initialization values and code for the body of the header statement.

user1 - The parent object. It can be either a Packet or Header object. Do a instanceof comparison method to find out which.

user2 - Context in which we set our fields and variables.

Throws:

NodeException - Any runtime errors.

traverse

public boolean traverse(VariableStatement stat,
                        java.lang.Object user1,
                        java.lang.Object user2)
                 throws NodeException

Visitor pattern. VariableStatement declares a variable to be of specific datat type. This data type is initialized and set in the current context.

Overrides:

traverse in class Visitor

Parameters:

stat - The variable statement with its initialization parameters and expression.

user1 - Object to which we belong to. Should be a Header.

user2 - Context this variable exists in.

Throws:

NodeException

traverse

public boolean traverse(FieldStatement stat,
                        java.lang.Object user1,
                        java.lang.Object user2)
                 throws NodeException

FIELD STATEMENT

Overrides:

traverse in class Visitor

Throws:

NodeException

traverse

public boolean traverse(AssertStatement stat,
                        java.lang.Object user1,
                        java.lang.Object user2)
                 throws NodeException

Overrides:

traverse in class Visitor

Throws:

NodeException

traverse

public boolean traverse(BufferStatement stat,
                        java.lang.Object user1,
                        java.lang.Object user2)
                 throws NodeException

Overrides:

traverse in class Visitor

Throws:

NodeException

traverse

public boolean traverse(ProcessStatement stat,
                        java.lang.Object user1,
                        java.lang.Object user2)
                 throws NodeException

Overrides:

traverse in class Visitor

Throws:

NodeException

traverse

public boolean traverse(FlowkeyStatement stat,
                        java.lang.Object user1,
                        java.lang.Object user2)
                 throws NodeException

Overrides:

traverse in class Visitor

Throws:

NodeException

traverse

public boolean traverse(FlowentryStatement stat,
                        java.lang.Object user1,
                        java.lang.Object user2)
                 throws NodeException

Overrides:

traverse in class Visitor

Throws:

NodeException

traverse

public boolean traverse(FlowpairStatement stat,
                        java.lang.Object user1,
                        java.lang.Object user2)
                 throws NodeException

Overrides:

traverse in class Visitor

Throws:

NodeException

traverse

public boolean traverse(LinkStatement stat,
                        java.lang.Object user1,
                        java.lang.Object user2)
                 throws NodeException

Overrides:

traverse in class Visitor

Throws:

NodeException

traverse

public boolean traverse(OpNode node,
                        java.lang.Object user1,
                        java.lang.Object user2)
                 throws NodeException

Description copied from class: Visitor

Convenience function that dispatches visitor to all nodes in the list.

Overrides:

traverse in class Visitor

Throws:

NodeException

traverse

public boolean traverse(IfStatement stat,
                        java.lang.Object user1,
                        java.lang.Object user2)
                 throws NodeException

Overrides:

traverse in class Visitor

Throws:

NodeException

traverse

public boolean traverse(ForStatement stat,
                        java.lang.Object user1,
                        java.lang.Object user2)
                 throws NodeException

Overrides:

traverse in class Visitor

Throws:

NodeException

traverse

public boolean traverse(WhileStatement stat,
                        java.lang.Object user1,
                        java.lang.Object user2)
                 throws NodeException

Overrides:

traverse in class Visitor

Throws:

NodeException

traverse

public boolean traverse(ContinueStatement stat,
                        java.lang.Object user1,
                        java.lang.Object user2)
                 throws NodeException

Overrides:

traverse in class Visitor

Throws:

NodeException

traverse

public boolean traverse(BreakStatement stat,
                        java.lang.Object user1,
                        java.lang.Object user2)
                 throws NodeException

Overrides:

traverse in class Visitor

Throws:

NodeException

traverse

public boolean traverse(PrintStatement stat,
                        java.lang.Object user1,
                        java.lang.Object user2)
                 throws NodeException

Overrides:

traverse in class Visitor

Throws:

NodeException

traverse

public boolean traverse(PropertyStatement stat,
                        java.lang.Object user1,
                        java.lang.Object user2)
                 throws NodeException

Overrides:

traverse in class Visitor

Throws:

NodeException

isIgnoreDefaultCandidate

public boolean isIgnoreDefaultCandidate()

Should "Data" or another default header be used.

Returns:

true ignores the default candidate, false the default candidate usually the "Data" header is appended to all parent header's candidate list.

setIgnoreDefaultCandidate

public void setIgnoreDefaultCandidate(boolean ignore)

Should "Data" or another default header be used.

Parameters:

ignore - true ignores the default candidate, false the default candidate usually the "Data" header is appended to all parent header's candidate list.

isUserSubheaders

public boolean isUserSubheaders()

A flag that indicates wheather sub headers of headers are merged or added to preserve the hierarchy.

Returns:

true indicates that sub headers are merged with the parent header and a single header remains. false indicates that sub headers are added to parent sub header and complete hierarchy as defined by the NPL definition remains.

setUseSubheaders

public void setUseSubheaders(boolean keep)

Sets a flag in the decoder to tell it what to do with sub headers of headers. Decoder can either merge the subheader into the parent header or preserve the hierarchy and add the sub header as a child to the parent header. The default is to merge (true).

Parameters:

keep - The mergeHeaders to set. true indicates that sub headers are merged with the parent header and a single header remains. false indicates that sub headers are added to parent sub header and complete hierarchy as defined by the NPL definition remains.

close

public void close()
           throws java.io.IOException

Closes the file or input stream.

Throws:

java.io.IOException

See Also:

InputStream.close()

isCompressed

public boolean isCompressed()

Is file or stream in compressed format.

See Also:

PacketInputStream.isCompressed()