Package io.engineblock.util

Class TagFilter

  • public class TagFilter
extends java.lang.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 Description
      static class  TagFilter.Result  

    • Constructor Summary

      Constructors 
      Constructor Description
      TagFilter​(java.lang.String filterSpec)
      Create a new tag filter.

    • Method Summary

      Modifier and Type Method Description
      java.util.Map<java.lang.String,​java.lang.String> getMap()  
      protected TagFilter.Result matches​(java.util.Map<java.lang.String,​java.lang.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​(java.util.Map<java.lang.String,​java.lang.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​(java.lang.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​(java.util.Map<java.lang.String,​java.lang.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​(java.util.Map<java.lang.String,​java.lang.String> tags)

      • matchesTagged

        public boolean matchesTagged​(Tagged item)

      • getMap

        public java.util.Map<java.lang.String,​java.lang.String> getMap()