org.netbeans.spi.editor.bracesmatching
Interface BracesMatcher

public interface BracesMatcher

The common interface for all matchers. Implementations of this interface are supposed to be created from the BracesMatcherFactory and will be used by the editor infrastructure to find areas of matching characters in a document.

Generally, BracesMatchers operate within a MatcherContext that describes a position in a document where the search should start. The matcher first looks in the document at that position to determine if it contains a character or a sequence of characters that normally come in pairs. This can be a single brace or an XML tag or anything that the matcher wishes to recognize. This area is called the original area and its boundaries - beginning and ending offsets - should be returned from findOrigin() method. The infrastructure will then ask the matcher to find the other matching areas by calling its findMatches() method.

Besides of describing the position in a document where the search should start the MatcherContext also tells the matcher in which direction it should be looking for the original area. The direction can either be backward to look towards the beginning of the document or it can be forward to look towards the end of the document. The search direction can be determined by calling MatcherContext.isSearchingBackward().

The search for the original area should only be attempted in the near proximity of the caret. The maximum distance from the caret where the matcher is supposed to look can be obtained from MatcherContext.getSearchLookahead().

While there can only be one original area, the area in the document where the search start, the matcher may report multiple areas matching the original one. Typically, though, there will only be one matching area too.

In the situation when the matcher reported an original area, but was unable to find any matching areas, the original area will be marked as mismatched, which may be indicated visually to a user.

Cancellable tasks

It is important to understand that matching is generally initiated in response to a moving caret in a text component on screen. Therefore there can be many requests for matching started, but only the last one provides results interesting for a user. In order not to flood the system with background tasks that are computing results nobody is interested in, it is essential to implement both findOrigin and findMatches methods in a way that makes their work possible to interrupt and cancel.

The infrastructre uses RequestProcessor for spawning a background thread that runs the asynchronous matching tasks. When the infrastructure wants to cancel a task it simply interrupts its thread. The task must check up on its thread status periodically and quit immediately when the thread is interruped. The example below shows how this can be implemented:

 public int [] findMatches() {
     while(stillSearching) {
         
         // look a bit furter in the document ....
 
         if (MatcherContext.isTaskCanceled()) {
             return null;
         }
     }
 }
 

Method Summary

int[]	findMatches() Finds all areas matching the original one.
int[]	findOrigin() Checks if the MatcherContext is positioned in an area suitable for matching.

Method Detail

findOrigin

int[] findOrigin()
                 throws InterruptedException,
                        BadLocationException

Checks if the MatcherContext is positioned in an area suitable for matching. This check should be very simple and fast. The matcher should only try to find the original area within the search lookahead from the caret offset that it obtains from MatcherContext.

Normally this method is supposed to return offset boundaries of the original area or null if the original area can't be found. The infrastructure will highlight the whole original area according to the result of the findMatches call. If for some reason the matcher does not want to highlight the whole original area it can return additional offset pairs for areas that should be highlighted instead.

The infrastructure does not lock the document prior calling this method.

Returns:

The starting and ending offset of the original area or null if the matcher can't detect the origin area within the lookahead distance. If null is returned the infrastructure will never call the findMatches method on this instance.

Throws:

InterruptedException - If the thread was engaged in a call that resulted in InterruptedException, the exception should be rethrown.

BadLocationException - If a document operation fails.

findMatches

int[] findMatches()
                  throws InterruptedException,
                         BadLocationException

Finds all areas matching the original one. This method is called by the infrastructure to find all areas that are matching the original area of the document in the MatcherContext.

The infrastructure does not lock the document prior calling this method.

It is essential for all implementations to respond when thread running this method is interrupted and abort the task and return immediately. This can be done simply by checking the thread's status like in the code below.

 if (MatcherContext.isTaskCanceled()) {
     return;
 }
 

Returns:

Starting and ending offsets of all areas matching the original area or null if no matching areas can be found. If the returned array is not null, it should have even number of elements.

Throws:

InterruptedException - If the thread was engaged in a call that resulted in InterruptedException, the exception should be rethrown.

BadLocationException - If a document operation fails.