1 package org.apache.lucene.queryParser.ext;
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
19 import java.util.HashMap;
22 import org.apache.lucene.queryParser.QueryParser;
25 * The {@link Extensions} class represents an extension mapping to associate
26 * {@link ParserExtension} instances with extension keys. An extension key is a
27 * string encoded into a Lucene standard query parser field symbol recognized by
28 * {@link ExtendableQueryParser}. The query parser passes each extension field
29 * token to {@link #splitExtensionField(String, String)} to separate the
30 * extension key from the field identifier.
32 * In addition to the key to extension mapping this class also defines the field
33 * name overloading scheme. {@link ExtendableQueryParser} uses the given
34 * extension to split the actual field name and extension key by calling
35 * {@link #splitExtensionField(String, String)}. To change the order or the key
36 * / field name encoding scheme users can subclass {@link Extensions} to
37 * implement their own.
39 * @see ExtendableQueryParser
40 * @see ParserExtension
42 public class Extensions {
43 private final Map<String,ParserExtension> extensions = new HashMap<String,ParserExtension>();
44 private final char extensionFieldDelimiter;
46 * The default extension field delimiter character. This constant is set to
49 public static final char DEFAULT_EXTENSION_FIELD_DELIMITER = ':';
52 * Creates a new {@link Extensions} instance with the
53 * {@link #DEFAULT_EXTENSION_FIELD_DELIMITER} as a delimiter character.
56 this(DEFAULT_EXTENSION_FIELD_DELIMITER);
60 * Creates a new {@link Extensions} instance
62 * @param extensionFieldDelimiter
63 * the extensions field delimiter character
65 public Extensions(char extensionFieldDelimiter) {
66 this.extensionFieldDelimiter = extensionFieldDelimiter;
70 * Adds a new {@link ParserExtension} instance associated with the given key.
73 * the parser extension key
75 * the parser extension
77 public void add(String key, ParserExtension extension) {
78 this.extensions.put(key, extension);
82 * Returns the {@link ParserExtension} instance for the given key or
83 * <code>null</code> if no extension can be found for the key.
87 * @return the {@link ParserExtension} instance for the given key or
88 * <code>null</code> if no extension can be found for the key.
90 public final ParserExtension getExtension(String key) {
91 return this.extensions.get(key);
95 * Returns the extension field delimiter
97 * @return the extension field delimiter
99 public char getExtensionFieldDelimiter() {
100 return extensionFieldDelimiter;
104 * Splits a extension field and returns the field / extension part as a
105 * {@link Pair}. This method tries to split on the first occurrence of the
106 * extension field delimiter, if the delimiter is not present in the string
107 * the result will contain a <code>null</code> value for the extension key and
108 * the given field string as the field value. If the given extension field
109 * string contains no field identifier the result pair will carry the given
110 * default field as the field value.
112 * @param defaultField
113 * the default query field
115 * the extension field string
116 * @return a {@link Pair} with the field name as the {@link Pair#cur} and the
117 * extension key as the {@link Pair#cud}
119 public Pair<String,String> splitExtensionField(String defaultField,
121 int indexOf = field.indexOf(this.extensionFieldDelimiter);
123 return new Pair<String,String>(field, null);
124 final String indexField = indexOf == 0 ? defaultField : field.substring(0,
126 final String extensionKey = field.substring(indexOf + 1);
127 return new Pair<String,String>(indexField, extensionKey);
132 * Escapes an extension field. The default implementation is equivalent to
133 * {@link QueryParser#escape(String)}.
136 * the extension field identifier
137 * @return the extension field identifier with all special chars escaped with
138 * a backslash character.
140 public String escapeExtensionField(String extfield) {
141 return QueryParser.escape(extfield);
145 * Builds an extension field string from a given extension key and the default
146 * query field. The default field and the key are delimited with the extension
147 * field delimiter character. This method makes no assumption about the order
148 * of the extension key and the field. By default the extension key is
149 * appended to the end of the returned string while the field is added to the
150 * beginning. Special Query characters are escaped in the result.
152 * Note: {@link Extensions} subclasses must maintain the contract between
153 * {@link #buildExtensionField(String)} and
154 * {@link #splitExtensionField(String, String)} where the latter inverts the
158 public String buildExtensionField(String extensionKey) {
159 return buildExtensionField(extensionKey, "");
163 * Builds an extension field string from a given extension key and the
164 * extensions field. The field and the key are delimited with the extension
165 * field delimiter character. This method makes no assumption about the order
166 * of the extension key and the field. By default the extension key is
167 * appended to the end of the returned string while the field is added to the
168 * beginning. Special Query characters are escaped in the result.
170 * Note: {@link Extensions} subclasses must maintain the contract between
171 * {@link #buildExtensionField(String, String)} and
172 * {@link #splitExtensionField(String, String)} where the latter inverts the
176 * @param extensionKey
179 * the field to apply the extension on.
180 * @return escaped extension field identifier
181 * @see #buildExtensionField(String) to use the default query field
183 public String buildExtensionField(String extensionKey, String field) {
184 StringBuilder builder = new StringBuilder(field);
185 builder.append(this.extensionFieldDelimiter);
186 builder.append(extensionKey);
187 return escapeExtensionField(builder.toString());
191 * This class represents a generic pair.
194 * the pairs first element
196 * the pairs last element of the pair.
198 public static class Pair<Cur,Cud> {
200 public final Cur cur;
201 public final Cud cud;
207 * the pairs first element
209 * the pairs last element
211 public Pair(Cur cur, Cud cud) {