← Back to branch summary

~slub.team/goobi-indexserver/3.x

« back to all changes in this revision

Viewing changes to lucene/src/java/org/apache/lucene/analysis/TokenStream.java

  • Committer: Sebastian Meyer
  • Date: 2012-08-03 09:12:40 UTC
  • Revision ID: sebastian.meyer@slub-dresden.de-20120803091240-x6861b0vabq1xror
https://launchpad.net/bugs/985487
Remove Lucene and Solr source code and add patches instead
Fix Bug #985487: Auto-suggestion for the search interface

Show diffs side-by-side

added added

removed removed

Lines of Context:
lucene/src/java/org/apache/lucene/analysis/TokenStream.java
1
 
package org.apache.lucene.analysis;
2
 
 
3
 
/**
4
 
 * Licensed to the Apache Software Foundation (ASF) under one or more
5
 
 * contributor license agreements.  See the NOTICE file distributed with
6
 
 * this work for additional information regarding copyright ownership.
7
 
 * The ASF licenses this file to You under the Apache License, Version 2.0
8
 
 * (the "License"); you may not use this file except in compliance with
9
 
 * the License.  You may obtain a copy of the License at
10
 
 *
11
 
 *     http://www.apache.org/licenses/LICENSE-2.0
12
 
 *
13
 
 * Unless required by applicable law or agreed to in writing, software
14
 
 * distributed under the License is distributed on an "AS IS" BASIS,
15
 
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16
 
 * See the License for the specific language governing permissions and
17
 
 * limitations under the License.
18
 
 */
19
 
 
20
 
import java.io.IOException;
21
 
import java.io.Closeable;
22
 
import java.lang.reflect.Modifier;
23
 
 
24
 
import org.apache.lucene.document.Document;
25
 
import org.apache.lucene.document.Field;
26
 
import org.apache.lucene.index.IndexWriter;
27
 
import org.apache.lucene.util.Attribute;
28
 
import org.apache.lucene.util.AttributeImpl;
29
 
import org.apache.lucene.util.AttributeSource;
30
 
 
31
 
/**
32
 
 * A <code>TokenStream</code> enumerates the sequence of tokens, either from
33
 
 * {@link Field}s of a {@link Document} or from query text.
34
 
 * <p>
35
 
 * This is an abstract class; concrete subclasses are:
36
 
 * <ul>
37
 
 * <li>{@link Tokenizer}, a <code>TokenStream</code> whose input is a Reader; and
38
 
 * <li>{@link TokenFilter}, a <code>TokenStream</code> whose input is another
39
 
 * <code>TokenStream</code>.
40
 
 * </ul>
41
 
 * A new <code>TokenStream</code> API has been introduced with Lucene 2.9. This API
42
 
 * has moved from being {@link Token}-based to {@link Attribute}-based. While
43
 
 * {@link Token} still exists in 2.9 as a convenience class, the preferred way
44
 
 * to store the information of a {@link Token} is to use {@link AttributeImpl}s.
45
 
 * <p>
46
 
 * <code>TokenStream</code> now extends {@link AttributeSource}, which provides
47
 
 * access to all of the token {@link Attribute}s for the <code>TokenStream</code>.
48
 
 * Note that only one instance per {@link AttributeImpl} is created and reused
49
 
 * for every token. This approach reduces object creation and allows local
50
 
 * caching of references to the {@link AttributeImpl}s. See
51
 
 * {@link #incrementToken()} for further details.
52
 
 * <p>
53
 
 * <b>The workflow of the new <code>TokenStream</code> API is as follows:</b>
54
 
 * <ol>
55
 
 * <li>Instantiation of <code>TokenStream</code>/{@link TokenFilter}s which add/get
56
 
 * attributes to/from the {@link AttributeSource}.
57
 
 * <li>The consumer calls {@link TokenStream#reset()}.
58
 
 * <li>The consumer retrieves attributes from the stream and stores local
59
 
 * references to all attributes it wants to access.
60
 
 * <li>The consumer calls {@link #incrementToken()} until it returns false
61
 
 * consuming the attributes after each call.
62
 
 * <li>The consumer calls {@link #end()} so that any end-of-stream operations
63
 
 * can be performed.
64
 
 * <li>The consumer calls {@link #close()} to release any resource when finished
65
 
 * using the <code>TokenStream</code>.
66
 
 * </ol>
67
 
 * To make sure that filters and consumers know which attributes are available,
68
 
 * the attributes must be added during instantiation. Filters and consumers are
69
 
 * not required to check for availability of attributes in
70
 
 * {@link #incrementToken()}.
71
 
 * <p>
72
 
 * You can find some example code for the new API in the analysis package level
73
 
 * Javadoc.
74
 
 * <p>
75
 
 * Sometimes it is desirable to capture a current state of a <code>TokenStream</code>,
76
 
 * e.g., for buffering purposes (see {@link CachingTokenFilter},
77
 
 * {@link TeeSinkTokenFilter}). For this usecase
78
 
 * {@link AttributeSource#captureState} and {@link AttributeSource#restoreState}
79
 
 * can be used.
80
 
 * <p>The {@code TokenStream}-API in Lucene is based on the decorator pattern.
81
 
 * Therefore all non-abstract subclasses must be final or have at least a final
82
 
 * implementation of {@link #incrementToken}! This is checked when Java
83
 
 * assertions are enabled.
84
 
 */
85
 
public abstract class TokenStream extends AttributeSource implements Closeable {
86
 
 
87
 
  /**
88
 
   * A TokenStream using the default attribute factory.
89
 
   */
90
 
  protected TokenStream() {
91
 
    super();
92
 
    assert assertFinal();
93
 
  }
94
 
  
95
 
  /**
96
 
   * A TokenStream that uses the same attributes as the supplied one.
97
 
   */
98
 
  protected TokenStream(AttributeSource input) {
99
 
    super(input);
100
 
    assert assertFinal();
101
 
  }
102
 
  
103
 
  /**
104
 
   * A TokenStream using the supplied AttributeFactory for creating new {@link Attribute} instances.
105
 
   */
106
 
  protected TokenStream(AttributeFactory factory) {
107
 
    super(factory);
108
 
    assert assertFinal();
109
 
  }
110
 
  
111
 
  private boolean assertFinal() {
112
 
    try {
113
 
      final Class<?> clazz = getClass();
114
 
      if (!clazz.desiredAssertionStatus())
115
 
        return true;
116
 
      assert clazz.isAnonymousClass() ||
117
 
        (clazz.getModifiers() & (Modifier.FINAL | Modifier.PRIVATE)) != 0 ||
118
 
        Modifier.isFinal(clazz.getMethod("incrementToken").getModifiers()) :
119
 
        "TokenStream implementation classes or at least their incrementToken() implementation must be final";
120
 
      return true;
121
 
    } catch (NoSuchMethodException nsme) {
122
 
      return false;
123
 
    }
124
 
  }
125
 
  
126
 
  /**
127
 
   * Consumers (i.e., {@link IndexWriter}) use this method to advance the stream to
128
 
   * the next token. Implementing classes must implement this method and update
129
 
   * the appropriate {@link AttributeImpl}s with the attributes of the next
130
 
   * token.
131
 
   * <P>
132
 
   * The producer must make no assumptions about the attributes after the method
133
 
   * has been returned: the caller may arbitrarily change it. If the producer
134
 
   * needs to preserve the state for subsequent calls, it can use
135
 
   * {@link #captureState} to create a copy of the current attribute state.
136
 
   * <p>
137
 
   * This method is called for every token of a document, so an efficient
138
 
   * implementation is crucial for good performance. To avoid calls to
139
 
   * {@link #addAttribute(Class)} and {@link #getAttribute(Class)},
140
 
   * references to all {@link AttributeImpl}s that this stream uses should be
141
 
   * retrieved during instantiation.
142
 
   * <p>
143
 
   * To ensure that filters and consumers know which attributes are available,
144
 
   * the attributes must be added during instantiation. Filters and consumers
145
 
   * are not required to check for availability of attributes in
146
 
   * {@link #incrementToken()}.
147
 
   * 
148
 
   * @return false for end of stream; true otherwise
149
 
   */
150
 
  public abstract boolean incrementToken() throws IOException;
151
 
  
152
 
  /**
153
 
   * This method is called by the consumer after the last token has been
154
 
   * consumed, after {@link #incrementToken()} returned <code>false</code>
155
 
   * (using the new <code>TokenStream</code> API). Streams implementing the old API
156
 
   * should upgrade to use this feature.
157
 
   * <p/>
158
 
   * This method can be used to perform any end-of-stream operations, such as
159
 
   * setting the final offset of a stream. The final offset of a stream might
160
 
   * differ from the offset of the last token eg in case one or more whitespaces
161
 
   * followed after the last token, but a {@link WhitespaceTokenizer} was used.
162
 
   * 
163
 
   * @throws IOException
164
 
   */
165
 
  public void end() throws IOException {
166
 
    // do nothing by default
167
 
  }
168
 
 
169
 
  /**
170
 
   * Resets this stream to the beginning. This is an optional operation, so
171
 
   * subclasses may or may not implement this method. {@link #reset()} is not needed for
172
 
   * the standard indexing process. However, if the tokens of a
173
 
   * <code>TokenStream</code> are intended to be consumed more than once, it is
174
 
   * necessary to implement {@link #reset()}. Note that if your TokenStream
175
 
   * caches tokens and feeds them back again after a reset, it is imperative
176
 
   * that you clone the tokens when you store them away (on the first pass) as
177
 
   * well as when you return them (on future passes after {@link #reset()}).
178
 
   */
179
 
  public void reset() throws IOException {}
180
 
  
181
 
  /** Releases resources associated with this stream. */
182
 
  public void close() throws IOException {}
183
 
  
184
 
}