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.annotations;
018:
019: import java.lang.annotation.ElementType;
020: import java.lang.annotation.Retention;
021: import java.lang.annotation.RetentionPolicy;
022: import java.lang.annotation.Target;
023:
024: /**
025: * Specifies a searchable property on property or field of the {@link Searchable} class.
026: *
027: * <p>The searchable property will automatically create a {@link SearchableMetaData},
028: * with its name being the field/property name. It will not be created if the
029: * {@link #name()} is not set AND there are either {@link SearchableMetaData} or
030: * {@link SearchableMetaDatas} annotating the class field/property. Most of
031: * the attributes that can control the meta-data are provided in the searchable
032: * property as well, they are marked in the java doc.
033: *
034: * <p>The searchable property/meta-data is meant to handle basic types (which usually translate to
035: * a String saved in the search engine). The conversion is done using converters, with
036: * Compass providing converters for most basic types. A specialized Converter can be
037: * associated with the auto generated meta-data using {@link #converter()}. The
038: * specialized converter will implement the {@link org.compass.core.converter.Converter}
039: * interface, usually extending the {@link org.compass.core.converter.basic.AbstractBasicConverter}.
040: *
041: * <p>Another way of defining a converter for a class can be done using the {@link SearchableClassConverter}
042: * to annotate the class that needs conversion, with Compass auto detecting it.
043: *
044: * <p>Note, that most of the time, a specialized converter for user classes will not be needed,
045: * since the {@link SearchableComponent} usually makes more sense to use.
046: *
047: * <p>The searchable property can annotate a {@link java.util.Collection} type field/property,
048: * supporting either {@link java.util.List} or {@link java.util.Set}. The searchable property
049: * will try and automatically identify the element type using generics, but if the collection
050: * is not defined with generics, {@link #type()} should be used to hint for the collection
051: * element type.
052: *
053: * <p>The searchable property can annotate an array as well, with the array element type used for
054: * Converter lookups.
055: *
056: * <p>Compass might require an internal meta-data to be created, so it can identify the correct
057: * value that match the property/field. Controlling the creation and specifics of the intenal
058: * meta-data id can be done using {@link #managedId()} and {@link #managedIdIndex()}.
059: *
060: * @author kimchy
061: */
062: @Target({ElementType.METHOD,ElementType.FIELD})
063: @Retention(RetentionPolicy.RUNTIME)
064: public @interface SearchableProperty {
065:
066: /**
067: * Controls if the internal meta-data id creation.
068: */
069: ManagedId managedId() default ManagedId.NA;
070:
071: /**
072: * If the internal meta-data id is created, controls it's
073: * index parameter.
074: */
075: ManagedIdIndex managedIdIndex() default ManagedIdIndex.NA;
076:
077: /**
078: * The class type of the property. Mainly used for <code>Collection</code> properties, without
079: * specific Generic type parameter.
080: */
081: Class type() default Object.class;
082:
083: /**
084: * If there is already an existing id with the same field/property name defined,
085: * will override it.
086: */
087: boolean override() default true;
088:
089: /**
090: * Converter that will apply to the property mapping. Not the generated
091: * meta-data.
092: */
093: String propertyConverter() default "";
094:
095: /**
096: * The property accessor that will be fetch and write the property value.
097: *
098: * <p>It is automatically set based on where the annotation is used, but can be
099: * explicitly set. Compass also supports custom property accessors, registered
100: * under a custom name, which can then be used here as well.
101: */
102: String accessor() default "";
103:
104: // Generated MetaData definitions
105:
106: /**
107: * The name of the auto generated {@link SearchableMetaData}. Maps to
108: * {@link org.compass.annotations.SearchableMetaData#name()}.
109: * If no value is defined, will default to the class field/property name.
110: *
111: * <p>The meta-data will NOT be auto generated if the field/property have
112: * {@link SearchableMetaData}/{@link SearchableMetaDatas} AND the
113: * {@link #name()} is not set.
114: */
115: String name() default "";
116:
117: /**
118: * The boost of the auto generated {@link SearchableMetaData}. Maps to
119: * {@link org.compass.annotations.SearchableMetaData#boost()}.
120: *
121: * <p>The meta-data will NOT be auto generated if the field/property have
122: * {@link SearchableMetaData}/{@link SearchableMetaDatas} AND the
123: * {@link #name()} is not set.
124: */
125: float boost() default 1.0f;
126:
127: /**
128: * The store of the auto generated {@link SearchableMetaData}. Maps to
129: * {@link org.compass.annotations.SearchableMetaData#store()}.
130: *
131: * <p>The meta-data will NOT be auto generated if the field/property have
132: * {@link SearchableMetaData}/{@link SearchableMetaDatas} AND the
133: * {@link #name()} is not set.
134: */
135: Store store() default Store.YES;
136:
137: /**
138: * The index of the auto generated {@link SearchableMetaData}. Maps to
139: * {@link org.compass.annotations.SearchableMetaData#index()}.
140: *
141: * <p>The meta-data will NOT be auto generated if the field/property have
142: * {@link SearchableMetaData}/{@link SearchableMetaDatas} AND the
143: * {@link #name()} is not set.
144: */
145: Index index() default Index.TOKENIZED;
146:
147: /**
148: * The termVector of the auto generated {@link SearchableMetaData}. Maps to
149: * {@link org.compass.annotations.SearchableMetaData#termVector()}.
150: *
151: * <p>The meta-data will NOT be auto generated if the field/property have
152: * {@link SearchableMetaData}/{@link SearchableMetaDatas} AND the
153: * {@link #name()} is not set.
154: */
155: TermVector termVector() default TermVector.NO;
156:
157: /**
158: * The termVector of the auto generated {@link SearchableMetaData}. Maps to
159: * {@link SearchableMetaData#omitNorms()}.
160: *
161: * <p>The meta-data will NOT be auto generated if the field/property have
162: * {@link SearchableMetaData}/{@link SearchableMetaDatas} AND the
163: * {@link #name()} is not set.
164: */
165: boolean omitNorms() default false;
166:
167: /**
168: * The reverse of the auto generated {@link SearchableMetaData}. Maps to
169: * {@link org.compass.annotations.SearchableMetaData#reverse()}.
170: *
171: * <p>The meta-data will NOT be auto generated if the field/property have
172: * {@link SearchableMetaData}/{@link SearchableMetaDatas} AND the
173: * {@link #name()} is not set.
174: */
175: Reverse reverse() default Reverse.NO;
176:
177: /**
178: * The analyzer of the auto generated {@link SearchableMetaData}. Maps to
179: * {@link org.compass.annotations.SearchableMetaData#analyzer()}.
180: *
181: * <p>The meta-data will NOT be auto generated if the field/property have
182: * {@link SearchableMetaData}/{@link SearchableMetaDatas} AND the
183: * {@link #name()} is not set.
184: */
185: String analyzer() default "";
186:
187: /**
188: * The exclude from all of the auto generated {@link SearchableMetaData}. Maps to
189: * {@link org.compass.annotations.SearchableMetaData#excludeFromAll()}.
190: *
191: * <p>The meta-data will NOT be auto generated if the field/property have
192: * {@link SearchableMetaData}/{@link SearchableMetaDatas} AND the
193: * {@link #name()} is not set.
194: */
195: ExcludeFromAll excludeFromAll() default ExcludeFromAll.NO;
196:
197: /**
198: * The converter of the auto generated {@link SearchableMetaData}. Maps to
199: * {@link org.compass.annotations.SearchableMetaData#converter()}.
200: * The meta-data will be auto generated only if the name has a value.
201: *
202: * <p>This converter will also be used for an internal meta-data id (if required to be
203: * generated).
204: */
205: String converter() default "";
206:
207: /**
208: * The format of the auto generated {@link SearchableMetaData}. Maps to
209: * {@link org.compass.annotations.SearchableMetaData#format()}.
210: * The meta-data will be auto generated only if the name has a value.
211: *
212: * <p>This format will also be used for an internal meta-data id (if required to be
213: * generated).
214: */
215: String format() default "";
216:
217: /**
218: * A null value to use to store in the index when the property has a <code>null</code>
219: * value. Defaults to not storing null values if the globabl setting of
220: * <code>compass.mapping.nullvalue</code> is not set. If it set, disabling the null
221: * value can be done by setting it to {@link org.compass.core.config.CompassEnvironment.NullValue#DISABLE_NULL_VALUE_FOR_MAPPING}
222: * value (<code>$disable$</code>).
223: */
224: String nullValue() default "";
225:
226: /**
227: * Should this propety be included in the spell check index.
228: *
229: * <p>Note, most times this is not requried to be configured, since by default, the
230: * spell check index uses the "all" property.
231: */
232: SpellCheck spellCheck() default SpellCheck.EXCLUDE;
233: }
|