001: /*
002: * Copyright 2004-2006 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.compass.core;
018:
019: import java.io.Serializable;
020:
021: import org.compass.core.util.Parameter;
022:
023: /**
024: * The basic Compass meta data holder. A property is a name value pair representing the mapped object attribute and
025: * value. Can be used to fetch meta data values from a resource in an abstract way.
026: * <p/>
027: * As an example:
028: * <p/>
029: * <pre>
030: * resource.getProperty("authorName").getStringValue();
031: * </pre>
032: * <p/>
033: * </p>
034: * <p/>
035: * Note that there are internal properties (that compass uses for the marshlling of objects) and meta data properties.
036: * </p>
037: *
038: * @author kimchy
039: */
040: public interface Property extends Serializable {
041:
042: /**
043: * Specifies whether and how a meta-data property will be stored.
044: */
045: public static final class Store extends Parameter {
046:
047: private static final long serialVersionUID = 3833746603143278642L;
048:
049: private Store(String name) {
050: super (name);
051: }
052:
053: /**
054: * Do not store the property value in the index.
055: */
056: public static final Store NO = new Store("NO");
057:
058: /**
059: * Store the original property value in the index. This is useful for short texts like a document's title which
060: * should be displayed with the results. The value is stored in its original form, i.e. no analyzer is used
061: * before it is stored.
062: */
063: public static final Store YES = new Store("YES");
064:
065: /**
066: * Store the original property value in the index in a compressed form. This is useful for long documents and
067: * for binary valued fields.
068: */
069: public static final Store COMPRESS = new Store("COMPRESS");
070:
071: public static String toString(Property.Store propertyStore) {
072: if (propertyStore == Property.Store.NO) {
073: return "no";
074: } else if (propertyStore == Property.Store.YES) {
075: return "yes";
076: } else if (propertyStore == Property.Store.COMPRESS) {
077: return "compress";
078: }
079: throw new IllegalArgumentException(
080: "Can't find property store for [" + propertyStore
081: + "]");
082: }
083:
084: public static Property.Store fromString(String propertyStore) {
085: if ("no".equalsIgnoreCase(propertyStore)) {
086: return Property.Store.NO;
087: } else if ("yes".equalsIgnoreCase(propertyStore)) {
088: return Property.Store.YES;
089: } else if ("compress".equalsIgnoreCase(propertyStore)) {
090: return Property.Store.COMPRESS;
091: }
092: throw new IllegalArgumentException(
093: "Can't find property store for [" + propertyStore
094: + "]");
095: }
096: }
097:
098: /**
099: * Specifies whether and how a meta-data property should be indexed.
100: */
101: public static final class Index extends Parameter {
102:
103: private static final long serialVersionUID = 3761973756863985718L;
104:
105: private Index(String name) {
106: super (name);
107: }
108:
109: /**
110: * Do not index the property value. This property can thus not be searched, but one can still access its
111: * contents provided it is {@link Property.Store stored}.
112: */
113: public static final Index NO = new Index("NO");
114:
115: /**
116: * Index the property's value so it can be searched. An Analyzer will be used to tokenize and possibly further
117: * normalize the text before its terms will be stored in the index. This is useful for common text.
118: */
119: public static final Index TOKENIZED = new Index("TOKENIZED");
120:
121: /**
122: * Index the property's value without using an Analyzer, so it can be searched. As no analyzer is used the value
123: * will be stored as a single term. This is useful for unique Ids like product numbers.
124: */
125: public static final Index UN_TOKENIZED = new Index(
126: "UN_TOKENIZED");
127:
128: public static String toString(Property.Index propertyIndex) {
129: if (propertyIndex == Property.Index.NO) {
130: return "no";
131: } else if (propertyIndex == Property.Index.TOKENIZED) {
132: return "tokenized";
133: } else if (propertyIndex == Property.Index.UN_TOKENIZED) {
134: return "un_tokenized";
135: }
136: throw new IllegalArgumentException(
137: "Can't find property index for [" + propertyIndex
138: + "]");
139: }
140:
141: public static Property.Index fromString(String propertyIndex) {
142: if ("no".equalsIgnoreCase(propertyIndex)) {
143: return Property.Index.NO;
144: } else if ("tokenized".equalsIgnoreCase(propertyIndex)) {
145: return Property.Index.TOKENIZED;
146: } else if ("un_tokenized".equalsIgnoreCase(propertyIndex)) {
147: return Property.Index.UN_TOKENIZED;
148: }
149: throw new IllegalArgumentException(
150: "Can't find property index for [" + propertyIndex
151: + "]");
152: }
153: }
154:
155: /**
156: * Specifies whether and how a meta-data property should have term vectors.
157: */
158: public static final class TermVector extends Parameter {
159:
160: private static final long serialVersionUID = 3256728372590948921L;
161:
162: private TermVector(String name) {
163: super (name);
164: }
165:
166: /**
167: * Do not store term vectors.
168: */
169: public static final TermVector NO = new TermVector("NO");
170:
171: /**
172: * Store the term vectors of each document. A term vector is a list of the document's terms and their number of
173: * occurences in that document.
174: */
175: public static final TermVector YES = new TermVector("YES");
176:
177: /**
178: * Store the term vector + token position information
179: *
180: * @see #YES
181: */
182: public static final TermVector WITH_POSITIONS = new TermVector(
183: "WITH_POSITIONS");
184:
185: /**
186: * Store the term vector + Token offset information
187: *
188: * @see #YES
189: */
190: public static final TermVector WITH_OFFSETS = new TermVector(
191: "WITH_OFFSETS");
192:
193: /**
194: * Store the term vector + Token position and offset information
195: *
196: * @see #YES
197: * @see #WITH_POSITIONS
198: * @see #WITH_OFFSETS
199: */
200: public static final TermVector WITH_POSITIONS_OFFSETS = new TermVector(
201: "WITH_POSITIONS_OFFSETS");
202:
203: public static String toString(
204: Property.TermVector propertyTermVector) {
205: if (propertyTermVector == Property.TermVector.NO) {
206: return "no";
207: } else if (propertyTermVector == Property.TermVector.YES) {
208: return "yes";
209: } else if (propertyTermVector == Property.TermVector.WITH_POSITIONS) {
210: return "positions";
211: } else if (propertyTermVector == Property.TermVector.WITH_OFFSETS) {
212: return "offsets";
213: } else if (propertyTermVector == Property.TermVector.WITH_POSITIONS_OFFSETS) {
214: return "positions_offsets";
215: }
216: throw new IllegalArgumentException(
217: "Can't find property term vector for ["
218: + propertyTermVector + "]");
219: }
220:
221: public static Property.TermVector fromString(
222: String propertyTermVector) {
223: if ("no".equalsIgnoreCase(propertyTermVector)) {
224: return Property.TermVector.NO;
225: } else if ("yes".equalsIgnoreCase(propertyTermVector)) {
226: return Property.TermVector.YES;
227: } else if ("positions".equalsIgnoreCase(propertyTermVector)) {
228: return Property.TermVector.WITH_POSITIONS;
229: } else if ("offsets".equalsIgnoreCase(propertyTermVector)) {
230: return Property.TermVector.WITH_OFFSETS;
231: } else if ("positions_offsets"
232: .equalsIgnoreCase(propertyTermVector)) {
233: return Property.TermVector.WITH_POSITIONS_OFFSETS;
234: }
235: throw new IllegalArgumentException(
236: "Can't find property term vector for ["
237: + propertyTermVector + "]");
238: }
239: }
240:
241: /**
242: * Returns the name of the property.
243: *
244: * @return the name of the property
245: */
246: String getName();
247:
248: /**
249: * Returns the string value of the proerty.
250: *
251: * @return the string value
252: */
253: String getStringValue();
254:
255: /**
256: * Returns the object value of the property. If a converter is associated
257: * with the property in one of Compass mapping definitions, it will be used
258: * to convert the string value to an object value. If there is no converter
259: * associated with the property, the string value will be returned.
260: *
261: * @return The converted object value
262: */
263: Object getObjectValue();
264:
265: /**
266: * Returns the binary values of the property. Only valid if <code>isBinary</code> is true.
267: *
268: * @return the binary value
269: */
270: byte[] getBinaryValue();
271:
272: /**
273: * Returns the boost for the property.
274: *
275: * @return the boost value
276: */
277: float getBoost();
278:
279: /**
280: * Sets the boost level for the property. The boost value can be specified in the mapping file to influence the
281: * order of search results.
282: *
283: * @param boost
284: */
285: void setBoost(float boost);
286:
287: /**
288: * True iff the value of the field is to be indexed, so that it may be searched on.
289: */
290: boolean isIndexed();
291:
292: /**
293: * True iff the value of the field is to be stored in the index for return with search hits. It is an error for this
294: * to be true if a field is Reader-valued.
295: */
296: boolean isStored();
297:
298: /**
299: * True if the value of the field is stored and compressed within the index
300: */
301: boolean isCompressed();
302:
303: /**
304: * True iff the value of the field should be tokenized as text prior to indexing. Un-tokenized fields are indexed as
305: * a single word and may not be Reader-valued.
306: */
307: boolean isTokenized();
308:
309: /**
310: * True iff the term or terms used to index this field are stored as a term vector, available from TODO. These
311: * methods do not provide access to the original content of the field, only to terms used to index it. If the
312: * original content must be preserved, use the <code>stored</code> attribute instead.
313: */
314: boolean isTermVectorStored();
315:
316: /**
317: * True iff the value of the filed is stored as binary
318: */
319: boolean isBinary();
320:
321: /**
322: * Expert:
323: *
324: * If set, omit normalization factors associated with this indexed field.
325: * This effectively disables indexing boosts and length normalization for this field.
326: */
327: boolean isOmitNorms();
328:
329: /**
330: * Expert:
331: *
332: * If set, omit normalization factors associated with this indexed field.
333: * This effectively disables indexing boosts and length normalization for this field.
334: */
335: void setOmitNorms(boolean omitNorms);
336: }
|