Warning: This is a facade provided for use by user code, not for implementation by user code. User implementations of this interface are highly likely to be incompatible with future releases of the product at both binary and source levels.
@mock.generate} by interpreting a {@link Pattern}. A matcher is created from a pattern by invoking the pattern's {@link Pattern#matcher matcher} method. Once created, a matcher can be used toperform three different kinds of match operations:
The {@link #matches matches} method attempts to match the entireinput sequence against the pattern.
The {@link #lookingAt lookingAt} method attempts to match theinput sequence, starting at the beginning, against the pattern.
The {@link #find find} method scans the input sequence looking forthe next subsequence that matches the pattern.
Each of these methods returns a boolean indicating success or failure. More information about a successful match can be obtained by querying the state of the matcher.
A matcher finds matches in a subset of its input called the region. By default, the region contains all of the matcher's input. The region can be modified via the {@link #region region} method and queriedvia the {@link #regionStart regionStart} and {@link #regionEnd regionEnd} methods. The way that the region boundaries interact with some pattern constructs can be changed. See {@link #useAnchoringBounds useAnchoringBounds} and {@link #useTransparentBounds useTransparentBounds}for more details.
This class also defines methods for replacing matched subsequences with new strings whose contents can, if desired, be computed from the match result. The {@link #appendReplacement appendReplacement} and {@link #appendTail appendTail} methods can be used in tandem in order to collectthe result into an existing string buffer, or the more convenient {@link #replaceAll replaceAll} method can be used to create a string in which everymatching subsequence in the input sequence is replaced.
The explicit state of a matcher includes the start and end indices of the most recent successful match. It also includes the start and end indices of the input subsequence captured by each capturing group in the pattern as well as a total count of such subsequences. As a convenience, methods are also provided for returning these captured subsequences in string form.
The explicit state of a matcher is initially undefined; attempting to query any part of it before a successful match will cause an {@link IllegalStateException} to be thrown. The explicit state of a matcher isrecomputed by every match operation.
The implicit state of a matcher includes the input character sequence as well as the append position, which is initially zero and is updated by the {@link #appendReplacement appendReplacement} method.
A matcher may be reset explicitly by invoking its {@link #reset()}method or, if a new input sequence is desired, its {@link #reset(java.lang.CharSequence) reset(CharSequence)} method. Resetting amatcher discards its explicit state information and sets the append position to zero.
Instances of this class are not safe for use by multiple concurrent threads.
@author Mike McCloskey
@author Mark Reinhold
@author JSR-51 Expert Group
@version 1.64, 06/04/07
@since 1.4
@spec JSR-51
} by interpreting a {@link Pattern}. A matcher is created from a pattern by invoking the pattern's {@link Pattern#matcher matcher} method. Once created, a matcher can be usedto perform three different kinds of match operations:
-
The {@link #matches matches} method attempts to match the entire inputsequence against the pattern.
-
The {@link #lookingAt lookingAt} method attempts to match the input sequence,starting at the beginning, against the pattern.
-
The {@link #find find} method scans the input sequence looking for the nextsubsequence that matches the pattern.
Each of these methods returns a boolean indicating success or failure. More information about a successful match can be obtained by querying the state of the matcher.
A matcher finds matches in a subset of its input called the region. By default, the region contains all of the matcher's input. The region can be modified via the {@link #region region} method and queried via the{@link #regionStart regionStart} and {@link #regionEnd regionEnd} methods.The way that the region boundaries interact with some pattern constructs can be changed. See {@link #useAnchoringBounds useAnchoringBounds} and{@link #useTransparentBounds useTransparentBounds} for more details.
This class also defines methods for replacing matched subsequences with new strings whose contents can, if desired, be computed from the match result. The {@link #appendReplacement appendReplacement} and {@link #appendTail appendTail} methods can be used in tandem in order to collect the result intoan existing string buffer, or the more convenient {@link #replaceAll replaceAll} method can be used to create a string in which every matchingsubsequence in the input sequence is replaced.
The explicit state of a matcher includes the start and end indices of the most recent successful match. It also includes the start and end indices of the input subsequence captured by each capturing group in the pattern as well as a total count of such subsequences. As a convenience, methods are also provided for returning these captured subsequences in string form.
The explicit state of a matcher is initially undefined; attempting to query any part of it before a successful match will cause an {@link IllegalStateException} to be thrown. The explicit state of a matcheris recomputed by every match operation.
The implicit state of a matcher includes the input character sequence as well as the append position, which is initially zero and is updated by the {@link #appendReplacement appendReplacement} method.
A matcher may be reset explicitly by invoking its {@link #reset()} method or,if a new input sequence is desired, its {@link #reset(java.lang.CharSequence) reset(CharSequence)} method. Resettinga matcher discards its explicit state information and sets the append position to zero.
Instances of this class are not safe for use by multiple concurrent threads.
@author Mike McCloskey
@author Mark Reinhold
@author JSR-51 Expert Group
@version 1.64, 06/04/07
@since 1.4
@spec JSR-51
Obtaining results
After the search succeded, i.e. if one of above methods returned true one may obtain an information on the match:
An important feature of the mailet container is the ability to fork processing of messages. When a message first arrives at the server, it might have multiple recipients specified. As a message is passed to a matcher, the matcher might only "match" one of the listed recipients. It would then return only the matching recipient in the Collection. The mailet container should then duplicate the message splitting the recipient list across the two messages as per what the matcher returned.
[THIS PARAGRAPH NOT YET IMPLEMENTED] The matcher can extend this forking to further separation by returning a Collection of Collection objects. This allows a matcher to fork multiple processes if there are multiple recipients that require separate processing. For example, we could write a ListservMatcher that handles multiple listservs. When someone cross-posts across multiple listservs that this matcher handles, it could put each listserv address (recipient) that it handles in a separate Collection object. By returning each of these Collections within a container Collection object, it could indicate to the mailet container how many forks to spawn.
This interface defines methods to initialize a matcher, to match messages, and to remove a matcher from the server. These are known as life-cycle methods and are called in the following sequence:
Obtaining results
After the search succeded, i.e. if one of above methods returned true one may obtain an information on the match:
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |