Package dev.galasa.textscan

Interface ITextScanner

public interface ITextScanner
Provides utility text scanning routines for tests and Managers to use, intended for use with logs or batch jobs etc.
The implementation of this interface will not record the text being searched, so the implementation can be reused against different resources.
If you require the ability to remember where the scan reached in a "log", use the ILogScanner.
You can obtain an implementation of this interface using the TextScanner annotation.

  • Method Details

    • scan

      ITextScanner scan(String text, Pattern searchPattern, Pattern failPattern, int count) throws FailTextFoundException, MissingTextException, IncorrectOccurrencesException, TextScanException
      Search a String for regex patterns. It will search initially search for any occurrence of the failPattern before searching for the searchPattern. The search will find at least "count" number of searchPatterns in the text.
      Parameters:
      text - The text to be searched
      searchPattern - The regex to search for
      failPattern - Failure regex to search for, can be null meaning no fail search
      count - At least how many occurrences of the searchPattern must exist
      Returns:
      This text scanner for fluent calls
      Throws:
      FailTextFoundException - If the failurePattern was found
      MissingTextException - If no occurrences of the searchPattern were found
      IncorrectOccurrencesException - If incorrect number of occurrences were found
      TextScanException - If any other problem found

    • scan

      ITextScanner scan(String text, String searchLiteral, String failLiteral, int count) throws FailTextFoundException, MissingTextException, IncorrectOccurrencesException, TextScanException
      Convenience method for scan(text, Pattern.Compile("\Q" + searchString + "\E"), Pattern.Compile("\Q" + failString + "\E"), count)
      Parameters:
      text - The text to be searched
      searchLiteral - The exact text to search for
      failLiteral - The exact failure text to search for, can be null meaning no fail search
      count - At least how many occurrences of the searchLiteral must exist
      Returns:
      This text scanner for fluent calls
      Throws:
      FailTextFoundException - If the failureLiteral was found
      MissingTextException - If no occurrences of the searchLiteral were found
      IncorrectOccurrencesException - If incorrect number of occurrences were found
      TextScanException - If any other problem found

    • scan

      ITextScanner scan(ITextScannable scannable, Pattern searchPattern, Pattern failPattern, int count) throws FailTextFoundException, MissingTextException, IncorrectOccurrencesException, TextScanException
      Search a IScannable for regex patterns. It will search initially search for any occurrence of the failPattern before searching for the searchPattern. The search will find at least "count" number of searchPatterns in the text.
      Parameters:
      scannable - The scannable to be searched
      searchPattern - The regex to search for
      failPattern - Failure regex to search for, can be null meaning no fail search
      count - At least how many occurrences of the searchPattern must exist
      Returns:
      This text scanner for fluent calls
      Throws:
      FailTextFoundException - If the failurePattern was found
      MissingTextException - If no occurrences of the searchPattern were found
      IncorrectOccurrencesException - If incorrect number of occurrences were found
      TextScanException - If any other problem found

    • scan

      ITextScanner scan(ITextScannable scannable, String searchLiteral, String failLiteral, int count) throws FailTextFoundException, MissingTextException, IncorrectOccurrencesException, TextScanException
      Convenience method for scan(scannable, Pattern.Compile("\Q" + searchString + "\E"), Pattern.Compile("\Q" + failString + "\E"), count)
      Parameters:
      scannable - The scannable to be searched
      searchLiteral - The exact text to search for
      failLiteral - The exact failure text to search for, can be null meaning no fail search
      count - At least how many occurrences of the searchLiteral must exist
      Returns:
      This text scanner for fluent calls
      Throws:
      FailTextFoundException - If the failureLiteral was found
      MissingTextException - If no occurrences of the searchLiteral were found
      IncorrectOccurrencesException - If incorrect number of occurrences were found
      TextScanException - If any other problem found

    • scan

      ITextScanner scan(InputStream inputStream, Pattern searchPattern, Pattern failPattern, int count) throws FailTextFoundException, MissingTextException, IncorrectOccurrencesException, TextScanException
      Search an InputStream for regex patterns. It will search initially search for any occurrence of the failPattern before searching for the searchPattern. The search will find at least "count" number of searchPatterns in the text.
      NOTE: unlike the scannable/string scans, this method will scan the text on a line by line basis, using a BufferedReader, to prevent the JVM Heap from being exceeded. therefore you will not be able to use multiline patterns
      Parameters:
      inputStream - The inputStream to be searched
      searchPattern - The regex to search for
      failPattern - Failure regex to search for, can be null meaning no fail search
      count - At least how many occurrences of the searchPattern must exist
      Returns:
      This text scanner for fluent calls
      Throws:
      FailTextFoundException - If the failurePattern was found
      MissingTextException - If no occurrences of the searchPattern were found
      IncorrectOccurrencesException - If incorrect number of occurrences were found
      TextScanException - If any other problem found

    • scan

      ITextScanner scan(InputStream inputStream, String searchLiteral, String failLiteral, int count) throws FailTextFoundException, MissingTextException, IncorrectOccurrencesException, TextScanException
      Convenience method for scan(inputStream, Pattern.Compile("\Q" + searchString + "\E"), Pattern.Compile("\Q" + failString + "\E"), count)
      Parameters:
      inputStream - The inputStream to be searched
      searchLiteral - The exact text to search for
      failLiteral - The exact failure text to search for, can be null meaning no fail search
      count - At least how many occurrences of the searchText must exist
      Returns:
      This text scanner for fluent calls
      Throws:
      FailTextFoundException - If the failureLiteral was found
      MissingTextException - If no occurrences of the searchLiteral were found
      IncorrectOccurrencesException - If incorrect number of occurrences were found
      TextScanException - If any other problem found

    • scanForMatch

      String scanForMatch(String text, Pattern searchPattern, Pattern failPattern, int occurrence) throws MissingTextException, IncorrectOccurrencesException, TextScanException
      Search a String for regex patterns. It will search initially search for any occurrence of the failPattern before searching for the searchPattern. The search will find at least "count" number of searchPatterns in the text.
      Useful for returning the actual value of the searchPattern or failPattern
      Parameters:
      text - the text being searched
      searchPattern - The regex to search for
      failPattern - Failure regex to search for, can be null meaning no fail search
      occurrence - The occurrence to be returned
      Returns:
      The text of the searchPattern or failPattern found
      Throws:
      MissingTextException - The searchPattern was not found at all
      IncorrectOccurrencesException - If the specified occurrence was not found
      TextScanException - If any other problem found

    • scanForMatch

      String scanForMatch(String text, String searchLiteral, String failLiteral, int occurrence) throws MissingTextException, IncorrectOccurrencesException, TextScanException
      Convenience method for scanForMatch(text, Pattern.Compile("\Q" + searchString + "\E"), Pattern.Compile("\Q" + searchString + "\E"), occurrence)
      Parameters:
      text - the text being searched
      searchLiteral - The exact text to search for
      failLiteral - The exact failure text to search for, can be null meaning no fail search
      occurrence - The occurrence to be returned
      Returns:
      The text of the searchLiteral or failLiteral found
      Throws:
      MissingTextException - The searchLiteral was not found at all
      IncorrectOccurrencesException - If the specified occurrence was not found
      TextScanException - If any other problem found

    • scanForMatch

      String scanForMatch(ITextScannable scannable, Pattern searchPattern, Pattern failPattern, int occurrence) throws MissingTextException, IncorrectOccurrencesException, TextScanException
      Search a IScannable for regex patterns. It will search initially search for any occurrence of the failPattern before searching for the searchPattern. The search will find at least "count" number of searchPatterns in the text.
      Useful for returning the actual value of the searchPattern or failPattern.
      Parameters:
      scannable - the scannable being searched
      searchPattern - The regex to search for
      failPattern - Failure regex to search for, can be null meaning no fail search
      occurrence - The occurrence to be returned
      Returns:
      The text of the searchPattern or failPattern found
      Throws:
      MissingTextException - The searchPattern was not found at all
      IncorrectOccurrencesException - If the specified occurrence was not found
      TextScanException - If any other problem found

    • scanForMatch

      String scanForMatch(ITextScannable scannable, String searchLiteral, String failLiteral, int occurrence) throws MissingTextException, IncorrectOccurrencesException, TextScanException
      Convenience method for scanForMatch(scannable, Pattern.Compile("\Q" + searchString + "\E"), Pattern.Compile("\Q" + searchString + "\E"), occurrence)
      Parameters:
      scannable - the text being searched
      searchLiteral - The exact text to search for
      failLiteral - The exact failure text to search for, can be null meaning no fail search
      occurrence - The occurrence to be returned
      Returns:
      The text of the searchLiteral or failLiteral found
      Throws:
      MissingTextException - The searchLiteral was not found at all
      IncorrectOccurrencesException - If the specified occurrence was not found
      TextScanException - If any other problem found

    • scanForMatch

      String scanForMatch(InputStream inputStream, Pattern searchPattern, Pattern failPattern, int occurrence) throws MissingTextException, IncorrectOccurrencesException, TextScanException
      Search an InputStream for regex patterns. It will search initially search for any occurrence of the failPattern before searching for the searchPattern. The search will find at least "count" number of searchPatterns in the text.
      NOTE: unlike the scannable/string scans, this method will scan the text on a line by line basis, using a BufferedReader, to prevent the JVM Heap from being exceeded. therefore you will not be able to use multiline patterns.
      Useful for returning the actual value of the searchPattern or failPattern.
      Parameters:
      inputStream - the inputStream being searched
      searchPattern - The regex to search for
      failPattern - Failure regex to search for, can be null meaning no fail search
      occurrence - The occurrence to be returned
      Returns:
      The text of the searchPattern or failPattern found
      Throws:
      MissingTextException - The searchPattern was not found at all
      IncorrectOccurrencesException - If the specified occurrence was not found
      TextScanException - If any other problem found

    • scanForMatch

      String scanForMatch(InputStream inputStream, String searchLiteral, String failLiteral, int occurrence) throws MissingTextException, IncorrectOccurrencesException, TextScanException
      Convenience method for scanForMatch(inputStream, Pattern.Compile("\Q" + searchString + "\E"), Pattern.Compile("\Q" + searchString + "\E"), occurrence)
      Parameters:
      inputStream - the text being searched
      searchLiteral - The exact text to search for
      failLiteral - The exact failure text to search for, can be null meaning no fail search
      occurrence - The occurrence to be returned
      Returns:
      The text of the searchLiteral or failLiteral found
      Throws:
      MissingTextException - The searchLiteral was not found at all
      IncorrectOccurrencesException - If the specified occurrence was not found
      TextScanException - If any other problem found