io.engineblock.util

Class TagFilter

java.lang.Object

io.engineblock.util.TagFilter

public class TagFilter
extends Object

This class makes it easy to associate tags and tag values with Tagged items, filtering matching Tagged items from a set of candidates.

• tags are the actual tags attached to a Tagged item.
• filters are the names and values used to filter the tag sets.

Tag names and filter names must be simple words. Filter values can have regex expressions, however. When a filter value starts and ends with a single quote, the quotes are removed as a convencience for deal with shell escapes, etc. This means that value 'five-oh.*five' is the same as five-oh.*five, except that the former will not cause undesirable shell expansion on command lines.

When a Tagged item is filtered, the following checks are made for each tag specified in the filter:

1. The Tagged item must have a tag with the same name as a filter.
2. If the filter has a value in addition to the tag name, then the Tagged item must also have a value for that tag name. Furthermore, the value has to match.
3. If the filter value, converted to a Regex, matches the tag value, it is deemed to be a match.

Because advanced tag usage can sometimes be unintuitive, the tag filtering logic has a built-in log which can explain why a candidate item did or did not match a particular set of filters.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TagFilter.Result

Field Summary

Fields

Modifier and Type	Field and Description
static TagFilter	MATCH_ALL

Constructor Summary

Constructors

Constructor and Description
TagFilter(String filterSpec) Create a new tag filter.

Method Summary

Modifier and Type	Method and Description
Map<String,String>	getMap()
protected TagFilter.Result	matches(Map<String,String> tags) Although this method could early-exit for certain conditions, the full tag matching logic is allowed to complete in order to present more complete diagnostic information back to the user.
TagFilter.Result	matchesMap(Map<String,String> tags)
boolean	matchesTagged(Tagged item)
TagFilter.Result	matchesTaggedResult(Tagged item)

Methods inherited from class java.lang.Object

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

Field Detail

MATCH_ALL

public static TagFilter MATCH_ALL

Constructor Detail

TagFilter

public TagFilter(String filterSpec)

Create a new tag filter. A tag filter is comprised of zero or more tag names, each with an optional value. The tag spec is a simple string format that contains zero or more tag names with optional values.

All of the following forms are acceptable for a filter spec:

• name1=value1 name2=value2
• name1:value1, name2=value2
• name1=value1 name2=value2,name3:value3
• name1='.*fast.*', name2=1+

That is, you can use spaces or commas between tag (name,value) pairs, and you can also use colons or equals between the actual tag names and values. This is not to support mixed formatting, but it does allow for some flexibility when integrating with other formats. Extra spaces between (name,value) pairs are ignored.

As well, you can include regex patterns in your tag filter values. You can also use single quotes to guard against

However, the following forms are not acceptable for a tag spec:

name1: value1

no extra spaces between the key and value

name-foo__bar:value1

No non-word characters in tag names

name1: value two

no spaces in tag values

name1: 'value two'

no spaces in tag values, even with single-quotes

Parameters:

filterSpec - a filter spec as explained in the javadoc

Method Detail

matches

protected TagFilter.Result matches(Map<String,String> tags)

Although this method could early-exit for certain conditions, the full tag matching logic is allowed to complete in order to present more complete diagnostic information back to the user.

Parameters:

tags - The tags associated with a Tagged item.

Returns:

a Result telling whether the tags matched and why or why not

matchesMap

public TagFilter.Result matchesMap(Map<String,String> tags)

matchesTaggedResult

public TagFilter.Result matchesTaggedResult(Tagged item)

matchesTagged

public boolean matchesTagged(Tagged item)

getMap

public Map<String,String> getMap()