Java tutorial
/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.lucene.search.suggest; import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; import java.util.Comparator; import java.util.List; import java.util.Set; import org.apache.lucene.search.BooleanQuery; import org.apache.lucene.search.spell.Dictionary; import org.apache.lucene.store.DataInput; import org.apache.lucene.store.DataOutput; import org.apache.lucene.store.InputStreamDataInput; import org.apache.lucene.store.OutputStreamDataOutput; import org.apache.lucene.util.Accountable; import org.apache.lucene.util.BytesRef; import org.apache.lucene.util.IOUtils; import org.apache.lucene.util.PriorityQueue; /** * Simple Lookup interface for {@link CharSequence} suggestions. * @lucene.experimental */ public abstract class Lookup implements Accountable { /** * Result of a lookup. * @lucene.experimental */ public static final class LookupResult implements Comparable<LookupResult> { /** the key's text */ public final CharSequence key; /** Expert: custom Object to hold the result of a * highlighted suggestion. */ public final Object highlightKey; /** the key's weight */ public final long value; /** the key's payload (null if not present) */ public final BytesRef payload; /** the key's contexts (null if not present) */ public final Set<BytesRef> contexts; /** * Create a new result from a key+weight pair. */ public LookupResult(CharSequence key, long value) { this(key, null, value, null, null); } /** * Create a new result from a key+weight+payload triple. */ public LookupResult(CharSequence key, long value, BytesRef payload) { this(key, null, value, payload, null); } /** * Create a new result from a key+highlightKey+weight+payload triple. */ public LookupResult(CharSequence key, Object highlightKey, long value, BytesRef payload) { this(key, highlightKey, value, payload, null); } /** * Create a new result from a key+weight+payload+contexts triple. */ public LookupResult(CharSequence key, long value, BytesRef payload, Set<BytesRef> contexts) { this(key, null, value, payload, contexts); } /** * Create a new result from a key+weight+contexts triple. */ public LookupResult(CharSequence key, long value, Set<BytesRef> contexts) { this(key, null, value, null, contexts); } /** * Create a new result from a key+highlightKey+weight+payload+contexts triple. */ public LookupResult(CharSequence key, Object highlightKey, long value, BytesRef payload, Set<BytesRef> contexts) { this.key = key; this.highlightKey = highlightKey; this.value = value; this.payload = payload; this.contexts = contexts; } @Override public String toString() { return key + "/" + value; } /** Compare alphabetically. */ @Override public int compareTo(LookupResult o) { return CHARSEQUENCE_COMPARATOR.compare(key, o.key); } } /** * A simple char-by-char comparator for {@link CharSequence} */ public static final Comparator<CharSequence> CHARSEQUENCE_COMPARATOR = new CharSequenceComparator(); private static class CharSequenceComparator implements Comparator<CharSequence> { @Override public int compare(CharSequence o1, CharSequence o2) { final int l1 = o1.length(); final int l2 = o2.length(); final int aStop = Math.min(l1, l2); for (int i = 0; i < aStop; i++) { int diff = o1.charAt(i) - o2.charAt(i); if (diff != 0) { return diff; } } // One is a prefix of the other, or, they are equal: return l1 - l2; } } /** * A {@link PriorityQueue} collecting a fixed size of high priority {@link LookupResult} */ public static final class LookupPriorityQueue extends PriorityQueue<LookupResult> { // TODO: should we move this out of the interface into a utility class? /** * Creates a new priority queue of the specified size. */ public LookupPriorityQueue(int size) { super(size); } @Override protected boolean lessThan(LookupResult a, LookupResult b) { return a.value < b.value; } /** * Returns the top N results in descending order. * @return the top N results in descending order. */ public LookupResult[] getResults() { int size = size(); LookupResult[] res = new LookupResult[size]; for (int i = size - 1; i >= 0; i--) { res[i] = pop(); } return res; } } /** * Sole constructor. (For invocation by subclass * constructors, typically implicit.) */ public Lookup() { } /** Build lookup from a dictionary. Some implementations may require sorted * or unsorted keys from the dictionary's iterator - use * {@link SortedInputIterator} or * {@link UnsortedInputIterator} in such case. */ public void build(Dictionary dict) throws IOException { build(dict.getEntryIterator()); } /** * Calls {@link #load(DataInput)} after converting * {@link InputStream} to {@link DataInput} */ public boolean load(InputStream input) throws IOException { DataInput dataIn = new InputStreamDataInput(input); try { return load(dataIn); } finally { IOUtils.close(input); } } /** * Calls {@link #store(DataOutput)} after converting * {@link OutputStream} to {@link DataOutput} */ public boolean store(OutputStream output) throws IOException { DataOutput dataOut = new OutputStreamDataOutput(output); try { return store(dataOut); } finally { IOUtils.close(output); } } /** * Get the number of entries the lookup was built with * @return total number of suggester entries */ public abstract long getCount() throws IOException; /** * Builds up a new internal {@link Lookup} representation based on the given {@link InputIterator}. * The implementation might re-sort the data internally. */ public abstract void build(InputIterator inputIterator) throws IOException; /** * Look up a key and return possible completion for this key. * @param key lookup key. Depending on the implementation this may be * a prefix, misspelling, or even infix. * @param onlyMorePopular return only more popular results * @param num maximum number of results to return * @return a list of possible completions, with their relative weight (e.g. popularity) */ public List<LookupResult> lookup(CharSequence key, boolean onlyMorePopular, int num) throws IOException { return lookup(key, null, onlyMorePopular, num); } /** * Look up a key and return possible completion for this key. * @param key lookup key. Depending on the implementation this may be * a prefix, misspelling, or even infix. * @param contexts contexts to filter the lookup by, or null if all contexts are allowed; if the suggestion contains any of the contexts, it's a match * @param onlyMorePopular return only more popular results * @param num maximum number of results to return * @return a list of possible completions, with their relative weight (e.g. popularity) */ public abstract List<LookupResult> lookup(CharSequence key, Set<BytesRef> contexts, boolean onlyMorePopular, int num) throws IOException; /** * Look up a key and return possible completion for this key. * This needs to be overridden by all implementing classes as the default implementation just returns null * * @param key the lookup key * @param contextFilerQuery A query for further filtering the result of the key lookup * @param num maximum number of results to return * @param allTermsRequired true is all terms are required * @param doHighlight set to true if key should be highlighted * @return a list of suggestions/completions. The default implementation returns null, meaning each @Lookup implementation should override this and provide their own implementation * @throws IOException when IO exception occurs */ public List<LookupResult> lookup(CharSequence key, BooleanQuery contextFilerQuery, int num, boolean allTermsRequired, boolean doHighlight) throws IOException { return null; } /** * Persist the constructed lookup data to a directory. Optional operation. * @param output {@link DataOutput} to write the data to. * @return true if successful, false if unsuccessful or not supported. * @throws IOException when fatal IO error occurs. */ public abstract boolean store(DataOutput output) throws IOException; /** * Discard current lookup data and load it from a previously saved copy. * Optional operation. * @param input the {@link DataInput} to load the lookup data. * @return true if completed successfully, false if unsuccessful or not supported. * @throws IOException when fatal IO error occurs. */ public abstract boolean load(DataInput input) throws IOException; }