uk.org.ogsadai.activity.files.regexp
Class AbstractMatcher

java.lang.Object
  |
  +--uk.org.ogsadai.activity.files.regexp.AbstractMatcher

Direct Known Subclasses:

JavaMatcher, OroMatcher

public abstract class AbstractMatcher

extends java.lang.Object

This class is an abstract class representing a regular expression matcher.

It is intended to be used in the following way:

String regexp = ...;
String text = ...;
AbstractMatcher matcher = (new PatternClass(regexp)).matcher();
matcher.setInput(text);
while (matcher.findNextMatch()) {
int matcherStart = matcher.startOffset();
int matcherEnd = matcher.endOffset();
String[] groups = matcher.groups();
...
}

where PatternClass is one of the implementing sub-classes of this class.

Implementing sub-classes should create a matcher object for each regular expression. The objects are informed what text they will be searching for matches within via the setInput(String) method. After this input has been registered, findNextMatch() will search for the first match of the regular expression in the input string, returning true if a match can be found. As a side-effect, it also stores the details of the most recent match. These details can then be accessed using methods startOffset(), endOffset(), groupCount(), group(int), groups(). Repeated calls to findNextMatch() will yield the remaining matches of the regular expression.

An attempt to find a match using findNextMatch() before the input has been registered will result in a ActivitySystemException being thrown. An attempt to access details of the previous match, before any match has been found, will result in an IllegalStateException being thrown.

Author:

The OGSA-DAI Project Team

Field Summary

private static java.lang.String	COPYRIGHT_NOTICE Copyright statement
protected int	mSearchOffset The offset within the input string from which we perform the next search when findNextMatch() is invoked.

Constructor Summary

AbstractMatcher()

Method Summary

abstract int	endOffset() Return the offset of the end of the most recent match of the regular expression found in the input text.
abstract boolean	findNextMatch() Search the input string for the next occurrence of a match of the regular expression.
int	getSearchOffset() Return the current offset within the input string from which we will perform the next search when findNextMatch() is invoked.
abstract java.lang.String	group(int index) Returns the input subsequence captured by the given group during the previous match operation.
abstract int	groupCount() Returns the number of capturing groups in this matcher's regular expression.
java.lang.String[]	groups() Return all the groups of text which were captured by the parenthesised groups in the regular expression in the previous match operation.
abstract void	setInput(java.lang.String input) Register a string of text as the text over which this matcher object searches for occurrences of its regular expression.
void	setSearchOffset(int i) Set the offset within the input string from which we will perform the next search when findNextMatch() is invoked.
abstract int	startOffset() Return the offset of the start of the most recent match of the regular expression found in the input text.

Methods inherited from class java.lang.Object

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

Field Detail

COPYRIGHT_NOTICE

private static final java.lang.String COPYRIGHT_NOTICE

Copyright statement

See Also:

Constant Field Values

mSearchOffset

protected int mSearchOffset

The offset within the input string from which we perform the next search when findNextMatch() is invoked.

Constructor Detail

AbstractMatcher

public AbstractMatcher()

Method Detail

getSearchOffset

public int getSearchOffset()

Return the current offset within the input string from which we will perform the next search when findNextMatch() is invoked.

Returns:

the current offset

setSearchOffset

public void setSearchOffset(int i)

Set the offset within the input string from which we will perform the next search when findNextMatch() is invoked.

Parameters:

i - The new offset

setInput

public abstract void setInput(java.lang.String input)

Register a string of text as the text over which this matcher object searches for occurrences of its regular expression. After this text has been registered, occurrences can be located using the findNextMatch() method.

Parameters:

input - The string of text to search within

findNextMatch

public abstract boolean findNextMatch()
                               throws java.lang.IllegalStateException

Search the input string for the next occurrence of a match of the regular expression. Iff such a match exists, this method returns true and causes the details regarding the match to be stored locally. These details include the offset in the entire input string of the start and the end positions of the match; and the actual text which matched the parenthesised groups in the regular expression this matcher matches.

Returns:

true if another occurrence of a match of the regular expression exists;
false otherwise

Throws:

java.lang.IllegalStateException - if no text input has yet been registered via the setInput(String) method

startOffset

public abstract int startOffset()

Return the offset of the start of the most recent match of the regular expression found in the input text.

Returns:

the start offset

Throws:

java.lang.IllegalStateException - if no match has yet been found via the findNextMatch() method

endOffset

public abstract int endOffset()

Return the offset of the end of the most recent match of the regular expression found in the input text.

Returns:

the end offset

Throws:

java.lang.IllegalStateException - if no match has yet been found via the findNextMatch() method

groupCount

public abstract int groupCount()

Returns the number of capturing groups in this matcher's regular expression. Note that group 0, denoting the entire match, is not included in this count.

Returns:

the number of groups

Throws:

java.lang.IllegalStateException - if no match has yet been found via the findNextMatch() method

group

public abstract java.lang.String group(int index)

Returns the input subsequence captured by the given group during the previous match operation. Group 0 refers to the entire match. If a group was not matched or does not exist then null is returned.

Parameters:

index - the index of the capturing group, or zero

Returns:

the text matching the given group, or null

Throws:

java.lang.IllegalStateException - if no match has yet been found via the findNextMatch() method

groups

public java.lang.String[] groups()

Return all the groups of text which were captured by the parenthesised groups in the regular expression in the previous match operation. The result is returned as an array, with the element at index 0 being the text matching the entire regular expression, and other elements being the text matching groups with those indices.

Returns:

an array of the captured groups

Throws:

java.lang.IllegalStateException - if no match has yet been found via the findNextMatch() method