Package org.codice.util.tlmatcher

Class TimeLimitedMatcher

java.lang.Object
org.codice.util.tlmatcher.TimeLimitedMatcher
public class TimeLimitedMatcher extends Object
Customized and reduced-scope RegEx matcher class to protect against runaway searches.

Instances of this class, created through one of its two factory methods, will either succeed or timeout, throwing a TimeLimitedMatcher.TimeoutException. It is incumbent on the caller to handle the exception.

N.B. This matcher differs from the standard Matcher in that the factory method executes the matches() check directly, failing and throwing an exception if it times out. Subsequent calls to the matches() method merely return the result of the initial check; they do not re-execute the search.

Example usage: 

   try {
     Pattern pattern = Pattern.compile("bc");
     TimeLimitedMatcher matcher = TimeLimitedMatcher.create(pattern, "abc123");
   } catch (TimeLimitedMatcher.TimeoutException e) {
     // handle exception
   }
   if (matcher.matches()) {
     // do something with the match
   }

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    TimeLimitedMatcher.TimeoutException
    Public, checked exception that is thrown when RegEx times out.

  • Method Summary

    Modifier and Type
    Method
    Description
    static TimeLimitedMatcher
    create(Pattern pattern, CharSequence inputString)
    Creates a new Time-limited matcher instance to search for the regular expression pattern against the inputString.
    static TimeLimitedMatcher
    create(Pattern pattern, CharSequence inputString, Duration duration)
    Creates a new Time-limited matcher instance to search for the regular expression pattern against the inputString.
    String
    group()
    Returns the input subsequence matched by the previous match.
    String
    group(int group)
    Returns the input subsequence captured by the given group during the previous match operation.
    String
    group(String name)
    Returns the input subsequence captured by the given named-capturing group during the previous match operation.
    int
    groupCount()
    Returns the number of capturing groups in this matcher's pattern.
    boolean
    matches()
    True if the entire region matched against the pattern.
    String
    toString()
     

    Methods inherited from class java.lang.Object

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

  • Method Details

    • create

      public static TimeLimitedMatcher create(Pattern pattern, CharSequence inputString) throws TimeLimitedMatcher.TimeoutException
      Creates a new Time-limited matcher instance to search for the regular expression pattern against the inputString.

      This method executes the search before returning, throwing a TimeLimitedMatcher.TimeoutException if the RegEx search runs longer than DEFAULT_DURATION.

      Parameters:
      pattern - RegEx search pattern
      inputString - String to match against.
      Returns:
      TimeLimitedMatcher instance to use for reporting out match details
      Throws:
      TimeLimitedMatcher.TimeoutException - if the RegEx search runs longer than DEFAULT_DURATION

    • create

      public static TimeLimitedMatcher create(Pattern pattern, CharSequence inputString, Duration duration) throws TimeLimitedMatcher.TimeoutException
      Creates a new Time-limited matcher instance to search for the regular expression pattern against the inputString.

      This method executes the search before returning, throwing a TimeoutException if the RegEx search runs longer than duration.

      Parameters:
      pattern - RegEx search pattern
      inputString - String to match against.
      duration - the length of time to continue processing the RegEx before failing
      Returns:
      TimeLimitedMatcher instance to use for reporting out match details
      Throws:
      TimeLimitedMatcher.TimeoutException - if the RegEx search runs longer than duration

    • group

      public String group()
      Returns the input subsequence matched by the previous match.
      Returns:
      The (possibly empty) subsequence matched by the previous match, in string form
      See Also:

    • group

      public String group(int group)
      Returns the input subsequence captured by the given group during the previous match operation.
      Parameters:
      group - The index of a capturing group in this matcher's pattern
      Returns:
      The (possibly empty) subsequence captured by the group during the previous match, or null if the group failed to match part of the input
      See Also:

    • group

      public String group(String name)
      Returns the input subsequence captured by the given named-capturing group during the previous match operation.
      Parameters:
      name - The name of a named-capturing group in this matcher's pattern
      Returns:
      The (possibly empty) subsequence captured by the named group during the previous match, or null if the group failed to match part of the input
      See Also:

    • groupCount

      public int groupCount()
      Returns the number of capturing groups in this matcher's pattern.
      Returns:
      The number of capturing groups in this matcher's pattern
      See Also:

    • matches

      public boolean matches()
      True if the entire region matched against the pattern.
      Returns:
      true if the entire region matched against the pattern.
      See Also:

    • toString

      public String toString()
      Overrides:
      toString in class Object