nl.basjes.parse.core

Class Dissector

java.lang.Object

nl.basjes.parse.core.Dissector

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

SimpleDissector

public abstract class Dissector
extends Object
implements Serializable

A Dissector is a class capable of chopping a String into multiple values of specific types.

The lifecycle:

Parser setup

1. First instance is constructed
2. First instance is added to the Parser using Parser.addDissector(Dissector)
3. The Parser calls getInputType() and getPossibleOutput() to know what this dissector can deliver.

The parser now constructs a tree based on the available Dissectors and what was requested.

Dissectors setup

For each node in the tree a new instance of the required dissector is created by calling getNewInstance() which calls initializeNewInstance(Dissector). Note that only Dissectors that are actually needed will be in the parse tree.

For each of those instances in the tree:

1. For each of the actually needed input+output combinations prepareForDissect(String, String) is called. This can be used to avoid needless CPU cycles during the actual run.
2. As a final step a call to prepareForRun() is done as an indication that all preparation input has been provided. A Dissector can use this to finalize the runtime data structures so doing the actual dissecting faster.

Dissecting

• During a run the instance will be called with dissect(nl.basjes.parse.core.Parsable<?>, java.lang.String) many times.
• In the dissect(Parsable, String) the actual value to be worked on must be retrieved using Parsable.getParsableField(String, String)
• The result(s) of the dissection must be put back using Parsable.addDissection(String, String, String, String)

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
Dissector()

Method Summary

Modifier and Type	Method and Description
<RECORD> void	createAdditionalDissectors(Parser<RECORD> parser) If a dissector really needs to add an additional dissector to the set this method is the place to do so.
abstract void	dissect(Parsable<?> parsable, String inputname) This method must dissect the provided field from the parsable into 'smaller' pieces.
String	extractFieldName(String inputname, String outputname)
abstract String	getInputType()
Dissector	getNewInstance() Create an additional instance of this dissector.
abstract List<String>	getPossibleOutput() What are all possible outputs that can be provided.
boolean	initializeFromSettingsParameter(String settings) If a Dissector is loaded through an external language then this is the method that is called to set all the parameters.
protected void	initializeNewInstance(Dissector newInstance) This is called after instantiating the class that is actually in the parsetree.
abstract EnumSet<Casts>	prepareForDissect(String inputname, String outputname) This tells the dissector that it should prepare that we will call it soon with 'inputname' and expect to get 'inputname.outputname' because inputname is of the type returned by getInputType and outputname was part of the answer from getPossibleOutput.
void	prepareForRun() The framework will tell the dissector that it should get ready to run.
void	setInputType(String s)
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

Dissector

public Dissector()

Method Detail

initializeFromSettingsParameter

public boolean initializeFromSettingsParameter(String settings)

If a Dissector is loaded through an external language then this is the method that is called to set all the parameters. There is exactly one String as input so it is up to the specific Dissector implementation to parse and handle this input.

Returns:

true if everything went right. false otherwise.

dissect

public abstract void dissect(Parsable<?> parsable,
                             String inputname)
                      throws DissectionFailure

This method must dissect the provided field from the parsable into 'smaller' pieces.

Throws:

DissectionFailure

getInputType

public abstract String getInputType()

Returns:

The required typename of the input

getPossibleOutput

public abstract List<String> getPossibleOutput()

What are all possible outputs that can be provided.

Returns:

array of "type:name" values that indicates all the possible outputs. Never a null!

prepareForDissect

public abstract EnumSet<Casts> prepareForDissect(String inputname,
                                                 String outputname)

This tells the dissector that it should prepare that we will call it soon with 'inputname' and expect to get 'inputname.outputname' because inputname is of the type returned by getInputType and outputname was part of the answer from getPossibleOutput. This can be used by the dissector implementation to optimize the internal parsing algorithms and lookup tables and such. The dissector must return the types to which this value can be mapped later on during the run.

Returns:

The EnumSet of all allowed casts. Returns an empty EnumSet if nothing is allowed. Never a null !

prepareForRun

public void prepareForRun()
                   throws InvalidDissectorException

The framework will tell the dissector that it should get ready to run. I.e. finalize the bootstrapping.

Throws:

InvalidDissectorException

getNewInstance

public Dissector getNewInstance()

Create an additional instance of this dissector. This is needed because in the parse tree we may need the same dissector multiple times. In order to optimize per node we need separate instances.

Returns:

New instance of this Dissector

extractFieldName

public String extractFieldName(String inputname,
                               String outputname)

initializeNewInstance

protected void initializeNewInstance(Dissector newInstance)
                              throws InvalidDissectorException

This is called after instantiating the class that is actually in the parsetree.

Parameters:

newInstance - The new instances of this class that must be initialized

Throws:

InvalidDissectorException

createAdditionalDissectors

public <RECORD> void createAdditionalDissectors(Parser<RECORD> parser)

If a dissector really needs to add an additional dissector to the set this method is the place to do so.

Type Parameters:

RECORD - The type of the record.

Parameters:

parser - The instance of the parser where the extra dissector is to be added to.

setInputType

public void setInputType(String s)
                  throws InvalidDissectorException

Throws:

InvalidDissectorException

toString

public String toString()

Overrides:

toString in class Object