BIE::RecordStreamFilter Class Reference

RecordStreamFilter objects can insert new fields into a stream by performing some computation on existing fields. More...

#include <RecordStreamFilter.h>

Inheritance diagram for BIE::RecordStreamFilter:

[legend]

Collaboration diagram for BIE::RecordStreamFilter:

[legend]

List of all members.

Public Member Functions
void	connect (string streamfieldname, string inputname)
	Connects a field from the incoming stream to an input of the filter.
void	connect (int streamfieldindex, string inputname)
	Connects a field from the incoming stream to an input of the filter.
void	connect (string streamfieldname, int inputindex)
	Connects a field from the incoming stream to an input of the filter.
void	connect (int streamfieldindex, int inputindex)
	Connects a field from the incoming stream to an input of the filter.
void	disconnect (string streamfieldname, string inputname)
	Disconnects a stream field from a filter input.
void	disconnect (int streamfieldindex, string inputname)
	Disconnects a stream field from a filter input.
void	disconnect (string streamfieldname, int inputindex)
	Disconnects a stream field from a filter input.
void	disconnect (int streamfieldindex, int inputindex)
	Disconnects a stream field from a filter input.
void	disconnect (string inputname)
	Disconnect all connections made to a specific filter input.
void	disconnect (int inputindex)
	Disconnect all connections made to a specific filter input.
void	disconnect ()
	Disconnect all connections.
void	renameOutputField (int fieldindex, string newname)
	Renames an output field.
void	renameOutputField (string fieldname, string newname)
	Renames an output field.
bool	isConnected ()
	Returns true if all filter inputs have a connection.
bool	isConnected (int inputindex)
	Returns true if the filter input (specified by index) has a connection.
bool	isConnected (string inputname)
	Returns true if the filter input (specified by name) has a connection.
int	getInputCardinality (string inputname)
	Returns the number of connections an input has (this can only be one or zero for scalars, but can be larger for set inputs).
int	getInputCardinality (int inputindex)
	Returns the number of connections an input has (this can only be one or zero for scalars, but can be larger for set inputs).
bool	isAttached ()
	Returns true if the filter is attached to a stream.
bool	nameClash ()
	Returns true if the output field names of the filter clash with names in the stream type.
virtual bool	isUseable ()
	The default definition of a "useable filter" is: the filter is not already being used, all inputs are connected and output names do not clash.
RecordBuffer *	getBuffer ()
	Returns the output buffer of the filter.
RecordType *	getOutputType ()
	Returns the type of the output buffer.
RecordType *	getStreamType ()
	Returns the type of the stream which this filter can be attached to.
int	numInputs ()
	Returns the number of inputs (whether set or scalar).
int	getInputIndex (string inputname)
	Returns the index corresponding to a filter input name.
string	getInputName (int inputindex)
	Returns the name of an input field when given the index.
bool	isValidInputName (string inputname)
	Returns true if the string is the name of an input to this filter.
bool	isValidInputIndex (int inputindex)
	Returns true if this is the index of an input to this filter.
string	toString ()
	Returns a string description of the filter.
virtual void	compute ()=0
	Called when new input is available by the inheriting stream, this fills the filter output buffers.
void	attachToStream (RecordStream *stream)
	This puts a filter to use by attaching it to a stream.
Protected Member Functions
void	initialize (const filterIn *input, const filterOut *output, RecordStream *stream)
	Initialize: Called by subclasses (ie actual filters) to initialize variables in this class.
string	getDefaultOutputName (int outputindex)
	Get the default name of a filter field by specifying an index.
int	getDefaultOutputIndex (string outputname)
	Get the index of a filter field by specifying the default name.
bool	isValidDefaultOutputName (string outputname)
	Returns true if the string is the default name of an output field.
bool	isValidOutputIndex (int outputindex)
	Returns true if the index refers to an output field of the filter.
bool	isArray (int inputindex)
	True if the index value corresponds to an array.
int	getIntInput (string inputname)
	These methods get the value of a scalar filter input.
int	getIntInput (int inputindex)
double	getRealInput (string inputname)
double	getRealInput (int inputindex)
bool	getBoolInput (string inputname)
bool	getBoolInput (int inputindex)
string	getStringInput (string inputname)
string	getStringInput (int inputindex)
vector< int >	getIntArrayInput (int inputindex)
vector< double >	getRealArrayInput (int inputindex)
vector< bool >	getBoolArrayInput (int inputindex)
int	getIntInput (string inputname, int setindex)
	These methods get the value of a member of a set input.
int	getIntInput (int inputindex, int setindex)
double	getRealInput (string inputname, int setindex)
double	getRealInput (int inputindex, int setindex)
bool	getBoolInput (string inputname, int setindex)
bool	getBoolInput (int inputindex, int setindex)
string	getStringInput (string inputname, int setindex)
string	getStringInput (int inputindex, int setindex)
Filter output field value setting methods.
These methods set the value of a filter output. The field can be referred to by the original (default) name of the output, or by index. Indices start at 1.
void	setIntOutput (string inputname, int value)
void	setIntOutput (int inputindex, int value)
void	setRealOutput (string inputname, double value)
void	setRealOutput (int inputindex, double value)
void	setBoolOutput (string inputname, bool value)
void	setBoolOutput (int inputindex, bool value)
void	setStringOutput (string inputname, string value)
void	setStringOutput (int inputindex, string value)
void	setIntArrayOutput (int outputindex, vector< int > vint)
void	setRealArrayOutput (int outputindex, vector< double > vdbl)
void	setBoolArrayOutput (int outputindex, vector< bool > vbln)
Friends
class	boost::serialization::access

---

Detailed Description

RecordStreamFilter objects can insert new fields into a stream by performing some computation on existing fields.

This class defines the interface to all filters (and implements much of the functionality).

Using filters:

Once a filter has been created, the filter must be hooked up to a stream. This involves the following steps:

-- Connection

The inputs to the filter are connected to fields in the stream the filter is going to be attached to using the connect() methods. Inputs can be either a scalar or a set - meaning that one stream field, or one or more stream fields can be connected respectively. If the filter input is a single field and is already connected the existing connection is overwritten. If the filter input field is a set field then the stream field is added to the set (unless already in it). Filter inputs are typed and the type must match with the stream field being connected. Connections can be deleted using the disconnect() methods. Stream fields can be specified by name or index, and filter inputs also by name or index (starting at 1).

-- Output field renaming

Filters give default names to their output fields, but these might clash with field names in the stream being filtered (for instance, if the same filter was used more than once on the same stream). Output fields are renamed using the renameOutputField() methods.

-- Attaching to the stream The final stage attaches the stream to the filter - this is done using the filterWith() methods in the stream classes.

-- Writing a filter class

Subclasses need only implement code which defines the input and output, implements a constructor, and performs the computation.

-- Defining input and output

Filter input and output is defined using arrays of structures that are terminated with a NULL structure (all fields set to zero). For each input, the filter class must specify the name, the BasicType, and the format (set or scalar, where true corresponds to set). For each output, the filter class should specify the default name of the output, and the BasicType. The arrays defining the input and output must exist for the lifetime of the filter, since they are used (not copied) by this class. If the inputs and outputs do not vary, then these arrays should be both const and static*

-- Writing a constructor:

All subclass constructors must call the initialize() method in the constructor. Three variables are passed to this method - the array describing the input to the filter, the array describing the output from the filter, and the stream which is to be filtered.

-- Performing the computation.

The computation should set the values of the filter output fields. The methods set<Type>Output will set the value of output fields. To read input field values, use the get<Type>Input methods. When an input is a set input, then the index of the item in the set must must also be specified.

---

Member Function Documentation

void BIE::RecordStreamFilter::connect	(	string	streamfieldname,
		string	inputname
	)

Connects a field from the incoming stream to an input of the filter.

The first argument is the name of the field in the incoming stream, and the second is the name of the field in the filter.

void BIE::RecordStreamFilter::connect	(	int	streamfieldindex,
		string	inputname
	)

Connects a field from the incoming stream to an input of the filter.

The first argument is the index of the field in the incoming stream, and the second is the name of the field in the filter.

void BIE::RecordStreamFilter::connect	(	string	streamfieldname,
		int	inputindex
	)

Connects a field from the incoming stream to an input of the filter.

The first argument is the name of the field in the incoming stream, and the second is the index of the field in the filter.

void BIE::RecordStreamFilter::connect	(	int	streamfieldindex,
		int	inputindex
	)

Connects a field from the incoming stream to an input of the filter.

The first argument is the index of the field in the incoming stream, and the second is the index of the field in the filter.

void BIE::RecordStreamFilter::disconnect	(	string	streamfieldname,
		string	inputname
	)

Disconnects a stream field from a filter input.

1st argument: stream field name, 2nd argument: filter input name.

void BIE::RecordStreamFilter::disconnect	(	int	streamfieldindex,
		string	inputname
	)

Disconnects a stream field from a filter input.

1st argument: stream field index, 2nd argument: filter input name.

void BIE::RecordStreamFilter::disconnect	(	string	streamfieldname,
		int	inputindex
	)

Disconnects a stream field from a filter input.

1st argument: stream field name, 2nd argument: filter input index.

void BIE::RecordStreamFilter::disconnect	(	int	streamfieldindex,
		int	inputindex
	)

Disconnects a stream field from a filter input.

1st argument: stream field index, 2nd argument: filter input index.

void BIE::RecordStreamFilter::renameOutputField	(	int	fieldindex,
		string	newname
	)

Renames an output field.

Output fields are assigned default names which may have to be changed to aboid clashes with the stream input. 1st argument: index of output field, 2nd argument: the new name.

void BIE::RecordStreamFilter::renameOutputField	(	string	fieldname,
		string	newname
	)

Renames an output field.

Output fields are assigned default names which may have to be changed to aboid clashes with the stream input. 1st argument: the old name, 2nd argument: the new name.

int BIE::RecordStreamFilter::getInputCardinality

(

string

inputname

)

Returns the number of connections an input has (this can only be one or zero for scalars, but can be larger for set inputs).

int BIE::RecordStreamFilter::getInputCardinality

(

int

inputindex

)

Returns the number of connections an input has (this can only be one or zero for scalars, but can be larger for set inputs).

bool BIE::RecordStreamFilter::nameClash

(

)

Returns true if the output field names of the filter clash with names in the stream type.

virtual bool BIE::RecordStreamFilter::isUseable

(

)

[virtual]

The default definition of a "useable filter" is: the filter is not already being used, all inputs are connected and output names do not clash.

Certain filters might have more specific requirements, and they can override this method.

virtual void BIE::RecordStreamFilter::compute

(

)

[pure virtual]

Called when new input is available by the inheriting stream, this fills the filter output buffers.

Implemented in BIE::AdditionFilter, BIE::SubtractionFilter, BIE::ProductFilter, BIE::DivisionFilter, BIE::PowerFilter, BIE::MPIStreamFilter, BIE::SumFilter, BIE::AverageFilter, BIE::StatisticsFilter, BIE::QuantileFilter, BIE::MaxFilter, BIE::MinFilter, BIE::PSanityFilter, BIE::RPhiFilter, BIE::AbsFilter, BIE::LogFilter, BIE::LogBaseNFilter, BIE::ScaleFilter, BIE::CosineFilter, BIE::SineFilter, BIE::MuFilter, and BIE::InverseMuFilter.

void BIE::RecordStreamFilter::attachToStream

(

RecordStream *

stream

)

This puts a filter to use by attaching it to a stream.

The filter must be in a useable state, with inputs connected, no name clashes etc.

void BIE::RecordStreamFilter::initialize	(	const filterIn *	input,
		const filterOut *	output,
		RecordStream *	stream
	)			[protected]

Initialize: Called by subclasses (ie actual filters) to initialize variables in this class.

The input and output specifications are arrays of structures terminated with a null record (all zero).

int BIE::RecordStreamFilter::getIntInput

(

string

inputname

)

[protected]

These methods get the value of a scalar filter input.

Either the input name or input index can be used to specify the input field. An attempt to access a set input with these methods will result in a TypeException.

int BIE::RecordStreamFilter::getIntInput	(	string	inputname,
		int	setindex
	)			[protected]

These methods get the value of a member of a set input.

Either the input name or input index can be used to specify the input field. An attempt to access a scalar variable with these methods will result in a TypeException.

---

The documentation for this class was generated from the following file:

• /home/weinberg/src/BIE/include/RecordStreamFilter.h