nl.basjes.parse.core

Class Dissector

java.lang.Object

nl.basjes.parse.core.Dissector

public abstract class Dissector
extends Object

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)

Constructor Summary

Constructors

Constructor and Description
Dissector()

Method Summary

Methods

Modifier and Type	Method and Description
abstract void	dissect(Parsable<?> parsable, String inputname) This method must dissect the provided field from the parsable into 'smaller' pieces.
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.
abstract 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 abstract 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.
abstract void	prepareForRun() The framework will tell the dissector that it should get ready to run.

Methods inherited from class java.lang.Object

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

Constructor Detail

Dissector

public Dissector()

Method Detail

initializeFromSettingsParameter

public abstract 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

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.

prepareForRun

public abstract 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

initializeNewInstance

protected abstract void initializeNewInstance(Dissector newInstance)

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