org.apache.lucene.analysis.shingle
Class ShingleFilter

java.lang.Object
  org.apache.lucene.util.AttributeSource
      org.apache.lucene.analysis.TokenStream
          org.apache.lucene.analysis.TokenFilter
              org.apache.lucene.analysis.shingle.ShingleFilter

public class ShingleFilter
extends TokenFilter

A ShingleFilter constructs shingles (token n-grams) from a token stream. In other words, it creates combinations of tokens as a single token.

For example, the sentence "please divide this sentence into shingles" might be tokenized into shingles "please divide", "divide this", "this sentence", "sentence into", and "into shingles".

This filter handles position increments > 1 by inserting filler tokens (tokens with termtext "_"). It does not handle a position increment of 0.

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.lucene.util.AttributeSource

AttributeSource.AttributeFactory, AttributeSource.State

Field Summary

static int	DEFAULT_MAX_SHINGLE_SIZE default maximum shingle size is 2.
static char[]	FILLER_TOKEN filler token for when positionIncrement is more than 1
static String	TOKEN_SEPARATOR The string to use when joining adjacent tokens to form a shingle

Fields inherited from class org.apache.lucene.analysis.TokenFilter

input

Constructor Summary

ShingleFilter(TokenStream input)
Construct a ShingleFilter with default shingle size.

ShingleFilter(TokenStream input, int maxShingleSize)
Constructs a ShingleFilter with the specified single size from the TokenStream input

ShingleFilter(TokenStream input, String tokenType)
Construct a ShingleFilter with the specified token type for shingle tokens.

Method Summary

boolean	incrementToken() Consumers (i.e., IndexWriter) use this method to advance the stream to the next token.
Token	next() Deprecated. Will be removed in Lucene 3.0. This method is final, as it should not be overridden. Delegates to the backwards compatibility layer.
Token	next(Token reusableToken) Deprecated. Will be removed in Lucene 3.0. This method is final, as it should not be overridden. Delegates to the backwards compatibility layer.
void	reset() Reset the filter as well as the input TokenStream.
void	setMaxShingleSize(int maxShingleSize) Set the max shingle size (default: 2)
void	setOutputUnigrams(boolean outputUnigrams) Shall the output stream contain the input tokens (unigrams) as well as shingles? (default: true.)
void	setTokenType(String tokenType) Set the type of the shingle tokens produced by this filter.

Methods inherited from class org.apache.lucene.analysis.TokenFilter

close, end

Methods inherited from class org.apache.lucene.analysis.TokenStream

getOnlyUseNewAPI, setOnlyUseNewAPI

Methods inherited from class org.apache.lucene.util.AttributeSource

addAttribute, addAttributeImpl, captureState, clearAttributes, cloneAttributes, equals, getAttribute, getAttributeClassesIterator, getAttributeFactory, getAttributeImplsIterator, hasAttribute, hasAttributes, hashCode, restoreState, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

FILLER_TOKEN

public static final char[] FILLER_TOKEN

filler token for when positionIncrement is more than 1

DEFAULT_MAX_SHINGLE_SIZE

public static final int DEFAULT_MAX_SHINGLE_SIZE

default maximum shingle size is 2.

See Also:

Constant Field Values

TOKEN_SEPARATOR

public static final String TOKEN_SEPARATOR

The string to use when joining adjacent tokens to form a shingle

See Also:

Constant Field Values

Constructor Detail

ShingleFilter

public ShingleFilter(TokenStream input,
                     int maxShingleSize)

Constructs a ShingleFilter with the specified single size from the TokenStream input

Parameters:

input - input stream

maxShingleSize - maximum shingle size produced by the filter.

ShingleFilter

public ShingleFilter(TokenStream input)

Construct a ShingleFilter with default shingle size.

Parameters:

input - input stream

ShingleFilter

public ShingleFilter(TokenStream input,
                     String tokenType)

Construct a ShingleFilter with the specified token type for shingle tokens.

Parameters:

input - input stream

tokenType - token type for shingle tokens

Method Detail

setTokenType

public void setTokenType(String tokenType)

Set the type of the shingle tokens produced by this filter. (default: "shingle")

Parameters:

tokenType - token tokenType

setOutputUnigrams

public void setOutputUnigrams(boolean outputUnigrams)

Shall the output stream contain the input tokens (unigrams) as well as shingles? (default: true.)

Parameters:

outputUnigrams - Whether or not the output stream shall contain the input tokens (unigrams)

setMaxShingleSize

public void setMaxShingleSize(int maxShingleSize)

Set the max shingle size (default: 2)

Parameters:

maxShingleSize - max size of output shingles

incrementToken

public final boolean incrementToken()
                             throws IOException

Description copied from class: TokenStream

Consumers (i.e., IndexWriter) use this method to advance the stream to the next token. Implementing classes must implement this method and update the appropriate AttributeImpls with the attributes of the next token.

The producer must make no assumptions about the attributes after the method has been returned: the caller may arbitrarily change it. If the producer needs to preserve the state for subsequent calls, it can use AttributeSource.captureState() to create a copy of the current attribute state.

This method is called for every token of a document, so an efficient implementation is crucial for good performance. To avoid calls to AttributeSource.addAttribute(Class) and AttributeSource.getAttribute(Class) or downcasts, references to all AttributeImpls that this stream uses should be retrieved during instantiation.

To ensure that filters and consumers know which attributes are available, the attributes must be added during instantiation. Filters and consumers are not required to check for availability of attributes in TokenStream.incrementToken().

Overrides:

incrementToken in class TokenStream

Returns:

false for end of stream; true otherwise

Note that this method will be defined abstract in Lucene 3.0.

Throws:

IOException

next

public final Token next(Token reusableToken)
                 throws IOException

Deprecated. Will be removed in Lucene 3.0. This method is final, as it should not be overridden. Delegates to the backwards compatibility layer.

Description copied from class: TokenStream

Returns the next token in the stream, or null at EOS. When possible, the input Token should be used as the returned Token (this gives fastest tokenization performance), but this is not required and a new Token may be returned. Callers may re-use a single Token instance for successive calls to this method.

This implicitly defines a "contract" between consumers (callers of this method) and producers (implementations of this method that are the source for tokens):

• A consumer must fully consume the previously returned Token before calling this method again.
• A producer must call Token.clear() before setting the fields in it and returning it

Also, the producer must make no assumptions about a Token after it has been returned: the caller may arbitrarily change it. If the producer needs to hold onto the Token for subsequent calls, it must clone() it before storing it. Note that a TokenFilter is considered a consumer.

Overrides:

next in class TokenStream

Parameters:

reusableToken - a Token that may or may not be used to return; this parameter should never be null (the callee is not required to check for null before using it, but it is a good idea to assert that it is not null.)

Returns:

next Token in the stream or null if end-of-stream was hit

Throws:

IOException

next

public final Token next()
                 throws IOException

Deprecated. Will be removed in Lucene 3.0. This method is final, as it should not be overridden. Delegates to the backwards compatibility layer.

Description copied from class: TokenStream

Returns the next Token in the stream, or null at EOS.

Overrides:

next in class TokenStream

Throws:

IOException

reset

public void reset()
           throws IOException

Description copied from class: TokenFilter

Reset the filter as well as the input TokenStream.

Overrides:

reset in class TokenFilter

Throws:

IOException