edu.nrao.sss.model.source
Class SourceFilter

java.lang.Object
  edu.nrao.sss.model.source.SourceFilter

All Implemented Interfaces:

Filter<Source>

public class SourceFilter
extends Object
implements Filter<Source>

A filter that operates on sources.

Revision Info:

$Revision: 2314 $

$Date: 2009-05-21 11:56:06 -0600 (Thu, 21 May 2009) $

$Author: btruitt $ (last person to modify)

Since:

2006-06-27

Author:

David M. Harland

Field Summary

static Date	CURRENT_TIME A constant that indicates the current time should be used when evaluating the information held by a source.
static boolean	EXCLUDE_ALIASES
static boolean	INCLUDE_ALIASES

Constructor Summary

SourceFilter()
Creates a new wide-open filter that allows all sources to pass.

Method Summary

void	addBrightnessFilter(SourceBrightnessFilter sbFilter) Adds the given filter to this filter.
void	addForbiddenUserDefinedKey(String udKey) Adds a user-defined key to this filter's set of forbidden keys.
void	addRequiredUserDefinedKey(String udKey) Adds a user-defined key to this filter's set of required keys.
void	addRequiredUserDefinedValues(String udKey, Set<String> additionalUdvs) Adds additional values to the set held by this filter for the given user defined key.
boolean	allows(Source src) Returns true if this filter allows the given source to pass through it.
boolean	blocks(Source src) Returns true if this filter blocks the given source.
void	clearAll() Sets this filter to a wide-open state.
void	clearBrightnessFilters() Removes all brightness filters from this filter.
void	clearCoordSysAndEpoch() Sets the coordinate system to equatorial and the epoch to Epoch.J2000.
void	clearNamePattern() Sets the name criterion to its wide-open state.
void	clearPositionFilter() Removes the position filter from this filter.
void	clearQueryTime() Sets this filter so that it will use the current time when querying sources sent to the allows(Source) or blocks(Source) methods.
void	clearUserDefinedValues() Sets the UDV criterion to its wide-open state.
void	removeForbiddenUserDefinedKey(String udKey) Removes udKey from this filter's collection of UDV keys that passing sources must not possess.
void	removeRequiredUserDefinedValue(String udKey) Removes udKey from this filter's collection of UDV keys that passing sources must possess.
void	replaceRequiredUserDefinedValues(String udKey, Set<String> replacementUdvs) Replaces the values held by this filter for the given user defined key.
Collection<Source>	selectFrom(Collection<?> bag) Selects those objects in bag that are sources and that can pass through this filter.
void	setCoordSysAndEpoch(CelestialCoordinateSystem newSys, Epoch newEpoch) Sets the coordinate system and epoch to use if source positions are to be converted to a common system prior to filtering.
void	setNamePattern(Pattern regex, boolean includeAliases) Sets a regular expression for matching the names of sources.
void	setNamePattern(String regex, boolean includeAliases) Sets a regular expression for matching the names of sources.
void	setPositionFilter(SkyPositionFilter posFilter) Sets this filter's position filter.
void	setQueryTime(Date time) Sets the date and time at which the filtered source is queried for its information.
void	turnOffPositionConversion() Prevents this filter from performing conversions of source positions to a common coordinate system and epoch.
void	turnOnPositionConversion() Tells this filter to perform conversions of source positions to a common coordinate system and epoch before filtering on position.

Methods inherited from class java.lang.Object

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

Field Detail

CURRENT_TIME

public static final Date CURRENT_TIME

A constant that indicates the current time should be used when evaluating the information held by a source.

INCLUDE_ALIASES

public static final boolean INCLUDE_ALIASES

See Also:

Constant Field Values

EXCLUDE_ALIASES

public static final boolean EXCLUDE_ALIASES

See Also:

Constant Field Values

Constructor Detail

SourceFilter

public SourceFilter()

Creates a new wide-open filter that allows all sources to pass. Source position conversion will be on and the default conversion will be to J2000 right ascension and declination.

Method Detail

clearAll

public void clearAll()

Sets this filter to a wide-open state. Also turns on position conversion and sets the system to J2000 right ascension and declination. After this call all filtering criteria will be in their wide-open states and this filter will allow all sources to pass.

clearPositionFilter

public void clearPositionFilter()

Removes the position filter from this filter. This has the effect of putting position filtering into its wide-open state.

clearBrightnessFilters

public void clearBrightnessFilters()

Removes all brightness filters from this filter. This has the effect of putting brightness filtering into its wide-open state.

clearNamePattern

public void clearNamePattern()

Sets the name criterion to its wide-open state.

See Also:

setNamePattern(Pattern, boolean), setNamePattern(String, boolean)

clearUserDefinedValues

public void clearUserDefinedValues()

Sets the UDV criterion to its wide-open state. Both required and forbidden UDVs are erased and UDVs do not enter into the filtering operations once this method has been called.

Since:

2008-07-28

clearCoordSysAndEpoch

public void clearCoordSysAndEpoch()

Sets the coordinate system to equatorial and the epoch to Epoch.J2000. This method does not effect the decision to turn conversions on or off.

See Also:

turnOffPositionConversion(), turnOnPositionConversion()

turnOffPositionConversion

public void turnOffPositionConversion()

Prevents this filter from performing conversions of source positions to a common coordinate system and epoch. Turning off the conversion will speed up the filtering process and is useful when a client knows that the positions are all already in the same system.

A newly created or cleared filter will have conversion turned on.

turnOnPositionConversion

public void turnOnPositionConversion()

Tells this filter to perform conversions of source positions to a common coordinate system and epoch before filtering on position.

See Also:

turnOffPositionConversion()

clearQueryTime

public void clearQueryTime()

Sets this filter so that it will use the current time when querying sources sent to the allows(Source) or blocks(Source) methods.

setNamePattern

public void setNamePattern(String regex,
                           boolean includeAliases)
                    throws PatternSyntaxException

Sets a regular expression for matching the names of sources. Only sources whose names are matched by regex are allowed to pass through this filter. If sources should not be filtered based on their names, call clearNamePattern().

Parameters:

regex - a regular expression for matching the names of sources.

includeAliases - if true, sources with an alias matching regex will pass this criterion.

Throws:

PatternSyntaxException

setNamePattern

public void setNamePattern(Pattern regex,
                           boolean includeAliases)

Sets a regular expression for matching the names of sources. Only sources whose names are matched by regex are allowed to pass through this filter. If sources should not be filtered based on their names, call clearNamePattern().

Parameters:

regex - a regular expression for matching the names of sources.

includeAliases - if true, sources with an alias matching regex will pass this criterion.

setPositionFilter

public void setPositionFilter(SkyPositionFilter posFilter)

Sets this filter's position filter. The position filter is used by the blocks and allows methods. If sources should not be filtered based on their position, call clearPositionFilter() or send a null to this method.

Parameters:

posFilter - a filter to be used on the position of a source.

setCoordSysAndEpoch

public void setCoordSysAndEpoch(CelestialCoordinateSystem newSys,
                                Epoch newEpoch)

Sets the coordinate system and epoch to use if source positions are to be converted to a common system prior to filtering.

Parameters:

newSys - the new coordinate system. If this value is null, an IllegalArgumentException will be thrown.

newEpoch - the new epoch. If this value is null, it will be treated as Epoch.UNKNOWN.

See Also:

turnOffPositionConversion()

addBrightnessFilter

public void addBrightnessFilter(SourceBrightnessFilter sbFilter)

Adds the given filter to this filter. Brightness filters are used by the blocks and allows methods. If sources should not be filtered based on their brightnesses, call clearBrightnessFilters().

Parameters:

sbFilter - a filter to be used on the brightnesses of a source.

setQueryTime

public void setQueryTime(Date time)

Sets the date and time at which the filtered source is queried for its information.

Parameters:

time - the time used by the allows(Source) and blocks(Source) methods when querying a source.

addRequiredUserDefinedKey

public void addRequiredUserDefinedKey(String udKey)

Adds a user-defined key to this filter's set of required keys. In order for a source to pass through this filter, it must have a UDV for udKey. The particular value it holds for that key, though, is immaterial.

This is a convenience method that is equivalent to both addRequiredUserDefinedValues(udKey, null) and replaceRequiredUserDefinedValues(udKey, null).

Parameters:

udKey - the key for a user defined value that a source must have in order to pass through this filter. A value of null will be ignored.

Since:

2008-07-28

addRequiredUserDefinedValues

public void addRequiredUserDefinedValues(String udKey,
                                         Set<String> additionalUdvs)

Adds additional values to the set held by this filter for the given user defined key. In order for a source to pass through this filter, it must have a UDV for udKey, and the value it has for that key must be in the set of values this filter holds for that key.

The effects of subsequent calls with the same key are cumulative. For example, imagine we have a block of (psuedo-)code like this:

 
   filter.addRequiredUserDefinedValues("stooge", ["Larry", "Moe", "Curly"]);
   ...
   filter.addRequiredUserDefinedValues("stooge", ["Shemp", "Curly Joe"]);
 

After such a setup, filter will continue to allow sources with a UDV key of "stooge" and a value of "Curly" to pass, demonstrating that "Shemp" and "Curly Joe" were added to the original values and did not replace them.

If this filter has no entry for udKey, this method creates one and sets its values to additionalUdvs.

This method will remove udKey from its set of forbidden keys, if present.

Parameters:

udKey - the key for a user defined value that a source must have in order to pass through this filter. A value of null will be ignored.

additionalUdvs - a set of values for udKey. In order for a source to pass through this filter its UDV for udKey must be contained in this set (see note above regarding consecutive calls to this method). A special value of null may be used to indicate that the presence of the key is required, but the value associated with that key is immaterial.

Since:

2008-07-28

See Also:

addForbiddenUserDefinedKey(String), addRequiredUserDefinedKey(String), replaceRequiredUserDefinedValues(String, Set)

replaceRequiredUserDefinedValues

public void replaceRequiredUserDefinedValues(String udKey,
                                             Set<String> replacementUdvs)

Replaces the values held by this filter for the given user defined key. In order for a source to pass through this filter, it must have a UDV for udKey, and the value it has for that key must be in the replacementUdvs set.

Contrast the behavior of this method with addRequiredUserDefinedValues(String, Set):

 
   filter.addRequiredUserDefinedValues("stooge", ["Larry", "Moe", "Curly"]);
   ...
   filter.addRequiredUserDefinedValues("stooge", ["Larry", "Moe", "Shemp"]);
 

After the second call, sources whose "stooge" is "Curly" will no longer pass through this filter.

If this filter has no entry for udKey, this method creates one and sets its values to replacementUdvs.

This method will remove udKey from its set of forbidden keys, if present.

Parameters:

udKey - the key for a user defined value that a source must have in order to pass through this filter. A value of null will be ignored.

replacementUdvs - a set of values for udKey. In order for a source to pass through this filter its UDV for udKey must be contained in this set. A special value of null may be used to indicate that the presence of the key is required, but the value associated with that key is immaterial.

Since:

2008-07-28

See Also:

addForbiddenUserDefinedKey(String), addRequiredUserDefinedKey(String), addRequiredUserDefinedValues(String, Set)

removeRequiredUserDefinedValue

public void removeRequiredUserDefinedValue(String udKey)

Removes udKey from this filter's collection of UDV keys that passing sources must possess.

Parameters:

udKey - a key for a user-defined value (UDV) of a source.

Since:

2008-07-28

See Also:

addRequiredUserDefinedKey(String), addRequiredUserDefinedValues(String, Set), clearUserDefinedValues(), replaceRequiredUserDefinedValues(String, Set)

addForbiddenUserDefinedKey

public void addForbiddenUserDefinedKey(String udKey)

Adds a user-defined key to this filter's set of forbidden keys. In order for a source to pass through this filter, it must not have a UDV for udKey. Any source holding such a key, no matter the value associated with that key, will be blocked by this filter.

This method will remove udKey from its set of required keys, if present.

Parameters:

udKey - a key for a user-defined value (UDV) of a source. A value of null will be ignored.

Since:

2008-07-28

See Also:

addRequiredUserDefinedKey(String), clearUserDefinedValues(), removeForbiddenUserDefinedKey(String)

removeForbiddenUserDefinedKey

public void removeForbiddenUserDefinedKey(String udKey)

Removes udKey from this filter's collection of UDV keys that passing sources must not possess.

Parameters:

udKey - a key for a user-defined value (UDV) of a source. A value of null will be ignored.

Since:

2008-07-28

See Also:

clearUserDefinedValues(), addForbiddenUserDefinedKey(String)

blocks

public boolean blocks(Source src)

Returns true if this filter blocks the given source. Null sources are always blocked.

The logic for allowing or blocking a source is somewhat complex. Some of the details about which clients should be aware are:

1. Even though an SphericalPositionFilter and a SourceBrightnessFilter each carries its own query time, this filter will ensure that its component filters are using the same time as that specified directly to this filter.


2. Position and brightness information is held at the subsource level, and a source may have multiple subsources. The only subsource examined during filtering is the central subsource.


3. A subsource may have multiple brightnesses. This filter may have several brightness filters. The source will be blocked only if at least one filter blocks all brightnesses.


4. If this filter has a position filter and the central subsource has no position information, the source will be blocked.


5. If this filter has one or more brightness filters and the central subsource has no brightness information, the source will be blocked.


6. If position filtering occurs and position conversion is requested, the filtering will not stop on account of a conversion exception. Instead, the filter will work with the unconverted position and log the conversion failure.

Specified by:

blocks in interface Filter<Source>

Parameters:

src - the source to be filtered.

Returns:

true if this filter blocks src.

allows

public boolean allows(Source src)

Returns true if this filter allows the given source to pass through it. Null sources are always blocked.

The logic for allowing or blocking a source is somewhat complex. See blocks(Source) for details.

Specified by:

allows in interface Filter<Source>

Parameters:

src - the source to be filtered.

Returns:

true if this filter allows src to pass through it.

selectFrom

public Collection<Source> selectFrom(Collection<?> bag)

Selects those objects in bag that are sources and that can pass through this filter. The selections are added to a new collection and returned. If the bag holds no such objects, the returned collection will be empty.

The original collection (bag) is not altered.

Parameters:

bag - a collection of objects.

Returns:

a collection of sources from bag that were able to pass through this filter.