stella.util
Class TriggerBoard

java.lang.Object
  stella.util.TriggerBoard

All Implemented Interfaces:

Toggling

Direct Known Subclasses:

QuadraticBoard

public class TriggerBoard
extends Object
implements Toggling

A trigger board. The functionality of a trigger board is reminiscent of a schmidt trigger but has some memory function, i.e. it triggers not on an actual value but takes also history into account.
Equal as a smith trigger it knows two states, in the following refered to as 'positive' and 'negative'. Its action can be illustrated as given below for a trigger board in the 'positive' state.

• Values that indicate negative add negatively to the trigger board.
• Readings that indicate positive add positively to the trigger board, but may not shift the trigger board to positive values.
• If the trigger board reaches a certein toggle value its state sweeps over to 'negative'. The trigger board is cleared and the process is reversed.
• Now, 'positive' values add positively to the trigger board while 'negative' values reduce the trigger boad (but not below zero). Note that the trigger switches for positive/negative do not need to be of equal absoulte value.

One application is the use of a trigger board in WeatherSensors.

Field Summary

private double	meanTrigger The trigger mean value.
private double	negativeTrigger The trigger switch to turn this state to 'negative'.
private double	positiveTrigger The trigger switch to turn this state to 'positive'.
private boolean	triggerState The actual trigger state.
private double	triggerValue The actual trigger value.

Constructor Summary

protected	TriggerBoard() Empty constructor.
	TriggerBoard(double mean, double negative, double positive) Constructs a new trigger board with the given positive and negative toggle switches.
	TriggerBoard(String parameters) Constructs a new trigger board with the three defining parameter packed together in a string.

Method Summary

boolean	addHit(double value) Adds a new value to this tirgger board.
boolean	equalBoard(TriggerBoard that) Two trigger boards are equal boards if they have the same trigger switches.
boolean	equals(Object that) Two trigger boards are equal if they have the same trigger switches, the same state and the same actual trigger value.
protected double	getNegativeHit(double raw) The impact of a negative value.
double	getNegativeTrigger() Returns the negative toggle value.
protected double	getPositiveHit(double raw) The impact of a positive value.
double	getPositiveTrigger() Returns the positive toggle value.
double	getTriggerValue() Returns the actual trigger value.
boolean	isPositive() Returns the state of the trigger board as a boolean.
protected void	setTriggers(double negative, double positive) Sets the toggle values.

Methods inherited from class java.lang.Object

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

Field Detail

meanTrigger

private double meanTrigger

The trigger mean value. The level around which it should oscilate.

positiveTrigger

private double positiveTrigger

The trigger switch to turn this state to 'positive'.

negativeTrigger

private double negativeTrigger

The trigger switch to turn this state to 'negative'.

triggerValue

private double triggerValue

The actual trigger value.

triggerState

private boolean triggerState

The actual trigger state.

Constructor Detail

TriggerBoard

protected TriggerBoard()

Empty constructor. Do not use.

TriggerBoard

public TriggerBoard(String parameters)

Constructs a new trigger board with the three defining parameter packed together in a string. The String must be coma-separated and consist of the mean value, the negative value and the positive value in this order.

TriggerBoard

public TriggerBoard(double mean,
                    double negative,
                    double positive)

Constructs a new trigger board with the given positive and negative toggle switches. The trigger value is set to zero and the trigger state to positive.

Parameters:

negative - The negative trigger value, ≤ 0

positive - The positive trigger value, ≥ 0

Method Detail

isPositive

public boolean isPositive()

Returns the state of the trigger board as a boolean. The 'positive' state returns true while the 'negative' state returns false.

addHit

public boolean addHit(double value)

Adds a new value to this tirgger board. The new state of the trigger board is returned. Note that this method calls one of the two proteced methods getPositiveHit(double) or getNegativeHit(double) to allow subclasses to add, e.g. quadratic, impact.

Specified by:

addHit in interface Toggling

getNegativeHit

protected double getNegativeHit(double raw)

The impact of a negative value. The default implementation returns the argument. Subclasses may implement a non-linear response here.
Always make sure that this method returns a value less equal zero!

Parameters:

raw - An always-negative value.

getPositiveHit

protected double getPositiveHit(double raw)

The impact of a positive value. The default implementation returns the argument. Subclasses may implement a non-linear response here.
Always make sure that this method returns a value greater equal zero!

Parameters:

raw - An always-positive value.

setTriggers

protected void setTriggers(double negative,
                           double positive)

Sets the toggle values. Checks for allowed value, i.e. whether the negative trigger is less equal zero and the positive trigger is greater equal zero. If either of the trigger is not within the allowed range an IllegalArgumentException is thrown.

Parameters:

negative - The negative trigger value, ≤ 0

positive - The positive trigger value, ≥ 0

Throws:

IllegalArgumentException - if either of the trigger has a forbidden value.

getPositiveTrigger

public double getPositiveTrigger()

Returns the positive toggle value.

getNegativeTrigger

public double getNegativeTrigger()

Returns the negative toggle value.

getTriggerValue

public double getTriggerValue()

Returns the actual trigger value.

equalBoard

public boolean equalBoard(TriggerBoard that)

Two trigger boards are equal boards if they have the same trigger switches.

See Also:

equals(java.lang.Object)

equals

public boolean equals(Object that)

Two trigger boards are equal if they have the same trigger switches, the same state and the same actual trigger value.

Overrides:

equals in class Object

See Also:

equalBoard(stella.util.TriggerBoard)