Package io.nosqlbench.engine.api.util

Class TagFilter

java.lang.Object
io.nosqlbench.engine.api.util.TagFilter
public class TagFilter extends Object

TagFilter Synopsis

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 Values

Any type which implements the Tagged interface can provide a set of tags in the form of a map. These are free-form, although they must

Tag Filters

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.

Tag Filters

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 shell expansion of internal characters or spaces. 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

  • Field Details

    • MATCH_ALL

      public static TagFilter MATCH_ALL

  • Constructor Details

    • 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.

      Parameters:
      filterSpec - a filter spec as explained in the javadoc

  • Method Details

    • 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(io.nosqlbench.engine.api.util.Tagged item)

    • matchesTagged

      public boolean matchesTagged(io.nosqlbench.engine.api.util.Tagged item)

    • getMap

      public Map<String,String> getMap()