org.tinyjee.maven.dim.spi
Interface SnippetSelector

All Known Implementing Classes:

AbstractSnippetSelector, AbstractStreamingSnippetSelector, AOPLikeSnippetSelector, GrepLikeSnippetSelector, IdDefinitionSelector, IdSnippetSelector, LineRangeSnippetSelector, RegularExpressionSnippetSelector, TokenAndBraceSnippetSelector, XPathSnippetSelector

public interface SnippetSelector

SnippetSelector defines an interface that may be implemented and registered via service loading to add new snippet selection mechanisms.

Implementation:

 package my.package;
 public class MySnippetSelector implements SnippetSelector {
      public String[] getExpressionPrefixes() {
          return new String[] {"my:"};
      }
      public boolean canSelectSnippetsWith(String expression, URL contentUrl, Map macroParameters) {
          return expression.toLowerCase().startsWith("my:");
      }
      public Iterator<Integer> selectSnippets(String expression, URL contentUrl, LineNumberReader content,
                                                    Map<String, Object> macroParameters) throws IOException {
          List<Integer> output = new LinkedList<Integer>();
          for (String line = content.readLine(); line != null; line = content.readLine()) {
              if (... EXPRESSION MATCHES LINE ...) output.add(content.getLineNumber());
          }
          return output.iterator();
      }
 }
 

Register the implementation using service loading:

• Create the following file:

   META-INF/services/
      org.tinyjee.maven.dim.spi.SnippetSelector
   

• Add the fully qualified class name of your implementation to the file "org.tinyjee.maven.dim.spi.SnippetSelector":

   my.package.MySnippetSelector
   

Since:

1.1

Version:

1.1

Author:

Juergen_Kellerer, 2011-10-14

Field Summary

static String	CASE_SENSITIVE Is an optional boolean parameter that toggles whether snippet selection is case sensitive.
static String	EXPAND_SNIPPETS Is a boolean parameters that may be used by snippet selectors to expand the included content to additional regions if matching an element that has belongings in other locations of the same file.
static Iterable<SnippetSelector>	SELECTORS Is an iterable over all selectors within the classpath.

Method Summary

boolean	canSelectSnippetsWith(String expression, URL contentUrl, Map<String,Object> macroParameters) Returns true if the expression is supported by this snippet selector.
String[]	getExpressionPrefixes() Returns all prefixes that are explicitly supported by this snippet selector.
Iterator<Integer>	selectSnippets(String expression, URL contentUrl, LineNumberReader content, Map<String,Object> macroParameters) Selects snippets in the given content and returns an iterator over selected line numbers.

Field Detail

CASE_SENSITIVE

static final String CASE_SENSITIVE

Is an optional boolean parameter that toggles whether snippet selection is case sensitive. Whether this parameter is used by selectors is implementation specific. Some selectors may not support to change this value.

See Also:

Constant Field Values

EXPAND_SNIPPETS

static final String EXPAND_SNIPPETS

Is a boolean parameters that may be used by snippet selectors to expand the included content to additional regions if matching an element that has belongings in other locations of the same file.

E.g. when matching a field, getter or setter a snippet selector may choose to include all 3 code locations if only one of them was originally matched.

See Also:

Constant Field Values

SELECTORS

static final Iterable<SnippetSelector> SELECTORS

Is an iterable over all selectors within the classpath.

Method Detail

getExpressionPrefixes

String[] getExpressionPrefixes()

Returns all prefixes that are explicitly supported by this snippet selector.

Returns:

all prefixes that are explicitly supported by this snippet selector.

canSelectSnippetsWith

boolean canSelectSnippetsWith(String expression,
                              URL contentUrl,
                              Map<String,Object> macroParameters)

Returns true if the expression is supported by this snippet selector.

Parameters:

expression - a single snippet expression.

contentUrl - the resolved URL of the content to include (might be 'null' if the source does not provide a Url).

macroParameters - the parameters used with the macro call.

Returns:

true if the snippet selector supports the given expression.

selectSnippets

Iterator<Integer> selectSnippets(String expression,
                                 URL contentUrl,
                                 LineNumberReader content,
                                 Map<String,Object> macroParameters)
                                 throws IOException

Selects snippets in the given content and returns an iterator over selected line numbers.

Note: The caller reads the returned iterator fully before closing the content stream. This way snippet selectors can truly implement streaming selection (in difference to the provided example).

Parameters:

expression - a single snippet expression.

contentUrl - the resolved URL of the content to include (might be 'null' if the source does not provide a Url).

content - a reader providing the content. Implementations must read content from this reader as the Url may point to an outdated static source that does not reflect the content to include.

macroParameters - the parameters used with the macro call.

Returns:

an iterator containing all selected line numbers.

Throws:

IOException - In case of reading the URL failed.