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: * Marks a class as searchable.
026: * A searchable class is assoiated with an alias, and allows to perform full
027: * text search on it's mapped properties/fields.
028: * <p/>
029: * The searchable class is associated with an alias, which can be used to
030: * reference the class when performing search operations, or for other
031: * mappings to extend it.
032: * <p/>
033: * A class mapping has it's own fully functional index, unless using the
034: * {@link #subIndex()} to join several searchable classes into the same
035: * index (when joining several searchalbe classes into the same index,
036: * the search will be much faster, but updates perform locks on the sub index
037: * level, so it might slow it down).
038: * <p/>
039: * A searchable class creates an internal "all" meta-data, which holds
040: * searchable information of all the class searchable content. You can
041: * control if it will be created or not using {@link #enableAll()}, and control
042: * the "all" property using the {@link SearchableAllMetaData} annotation.
043: * <p/>
044: * A searchable class can have constant meta-data associated with it. They
045: * can be defined using the {@link SearchableConstant} and {@link SearchableConstants}.
046: * <p/>
047: * Searchable class can have annotations defined on either it's fields, or
048: * on the field getter accessor. The possible annotions for them are:
049: * {@link SearchableId}, {@link SearchableProperty}, {@link SearchableComponent},
050: * and {@link SearchableReference}. Note that collections are automatically
051: * detected and handled by Compass if annotated.
052: * <p/>
053: * If the searchable class extends a class, or implement intefaces, they
054: * will be automatically detected and added to it in a revrse order. If the
055: * same annotaion is defined in both the searcable class and one of it's
056: * super class / interfaces, it will be overriden unless defined otherwise.
057: * The annotaions will be included even if the inteface/superclass do not
058: * implement the {@link Searchable} annotation.
059: * <p/>
060: * The seachable class can have a specialized analyzer (different from the
061: * default one) associated with it using {@link #analyzer()}. Note, that this
062: * will associate the class statically with an analyzer. Dynamically associating
063: * the class with an analyzer, the {@link SearchableAnalyzerProperty} can be
064: * used to annotated the dynamic value for the analyzer to use.
065: * <p/>
066: * The searchable class can extend other mappings defined elsewhere (either by
067: * the xml mappings, or annotations). Remember, that the searchable class will
068: * already include all the annotations in it's super class or interface (recursivly).
069: * So there is no need to specify them in {@link #extend()}. Note, that xml mapping
070: * <code>contract</code>s can be extended as well.
071: * <p/>
072: * By default, the searchable class is defined as a root class. A root class is
073: * a top level searchable class. A non root class can be used to define mappings
074: * definitions for {@link SearchableComponent}, and it is preferable that classes
075: * that are only used as component mapping definitions, will be defined with {@link #root()}
076: * <code>false</code>.
077: * <p/>
078: * The {@link #poly()} can be used to mapped polymprphic inheritance tree. This is the less
079: * prefable way to map an inhertiance tree, since the fact that a searchable class automatically
080: * inhertis all it's base class and interface mappings, means that the same result can be
081: * acheived by marking the all the inheritance tree classes as {@link Searchable}.
082: * <p/>
083: * Compass provides it's own internal converter for searchable classes
084: * {@link org.compass.core.converter.mapping.osem.ClassMappingConverter}. For advance usage,
085: * the converter can be set using {@link #converter()} IT will convert
086: * the {@link org.compass.core.mapping.osem.ClassMapping} definitions.
087: *
088: * @author kimchy
089: * @see SearchableId
090: * @see SearchableProperty
091: * @see SearchableComponent
092: * @see SearchableReference
093: * @see SearchableAnalyzerProperty
094: */
095: @Target(ElementType.TYPE)
096: @Retention(RetentionPolicy.RUNTIME)
097: public @interface Searchable {
098:
099: /**
100: * The alias that is associated with the class. Can be used to refernce
101: * the searchable class when performing search operations, or for other
102: * mappings to extend it.
103: * <p/>
104: * Default value is the short name of the class.
105: */
106: String alias() default "";
107:
108: /**
109: * The sub index the searchable class will be saved to. A sub index is
110: * a fully functional index.
111: * <p/>
112: * When joining several searchalbe classes into the same index,
113: * the search will be much faster, but updates perform locks on the sub index
114: * level, so it might slow it down.
115: * <p/>
116: * Defaults to the searchable class {@link #alias()} value.
117: */
118: String subIndex() default "";
119:
120: /**
121: * Boost level for the searchable class. Controls the ranking of hits
122: * when performing searches.
123: */
124: float boost() default 1.0f;
125:
126: /**
127: * Defines if the searchable class is a root class. A root class is a top
128: * level searchable class. You should define the searchable class with <code>false</code>
129: * if it only acts as mapping definitions for a {@link SearchableComponent}.
130: */
131: boolean root() default true;
132:
133: /**
134: * Used to mapped polymprphic inheritance tree. This is the less prefable way to map
135: * an inheritance tree, since the fact that a searchable class automatically
136: * inhertis all it's base class and interface mappings, means that the same result can be
137: * acheived by marking the all the inheritance tree classes as {@link Searchable}, in a
138: * more performant way.
139: * <p/>
140: * If poly is set to <code>true</code>, the actual class implementation will be persisted
141: * to the index, later be used to instantiate it when un-marhsalling. If a specific class
142: * need to be used to instantiate all classes, use the {{@link #polyClass()} to set it.
143: */
144: boolean poly() default false;
145:
146: /**
147: * In cases where poly is set to <code>true</code>, allows to set the class that will
148: * be used to instantiate in all inheritance tree cases.
149: * <p/>
150: * If not set, the actual class will be saved to the index,
151: * later be used to instantiate it when un-marhsalling
152: */
153: Class polyClass() default Object.class;
154:
155: /**
156: * A specialized analyzer (different from the default one) associated with the
157: * searchable class. Note, that this will associate the class statically with
158: * an analyzer. Dynamically associating the class with an analyzer can be done
159: * by using the {@link SearchableAnalyzerProperty} to use the property value
160: * to dynamically lookup the value for the analyzer to use.
161: */
162: String analyzer() default "";
163:
164: /**
165: * Controls if the searchable class will support unmarshalling from the search engine
166: * or using {@link org.compass.core.Resource} is enough. Un-marshalling is the process
167: * of converting a raw {@link org.compass.core.Resource} into the actual domain object.
168: * If support un-marshall is enabled extra information will be stored within the search
169: * engine, as well as consumes extra memory.
170: * <p/>
171: * By default Compass global osem setting supportUnmarshall controls it unless exlicitly
172: * set here.
173: */
174: SupportUnmarshall supportUnmarshall() default SupportUnmarshall.NA;
175:
176: /**
177: * Controls the managed id value for all the mapped properties that have no explicit setting
178: * of the managed id (also default to NA). The default value for the managed id is derived from
179: * globabl Compass settings and defaults to AUTO.
180: */
181: ManagedId managedId() default ManagedId.NA;
182:
183: /**
184: * A list of aliases to extend. Extending the aliases allows to include other
185: * mapping definitions, defined via annotations or xml.
186: * <p/>
187: * Remember, that the searchable class will already include all the annotations
188: * in it's super class or interface (recursivly). So there is no need to specify
189: * them in {@link #extend()}. Note, that xml mapping code>contract</code>s can
190: * be extended as well.
191: */
192: String[] extend() default {};
193:
194: /**
195: * What is the default mode for the given searchable class in including/excluding properties from
196: * the spell check index.
197: *
198: * <p>If set to <code>NA</code>, will use the globablly defined mode. If set the <code>INCLUDE</code>
199: * will automatically incldue all the given proeprties mappings unless specific properties are mapped
200: * with <code>EXCLUDE</code>. If set to <code>EXCLUDE</code> will automatically exclude all the given
201: * properties unless they are marked with <code>INCLUDE</code>.
202: *
203: * <p>A special note when both this is set to NA, and the global setting is set to NA as well (which is
204: * the default): In this case, Compass will use the all proeprty as the only property to add to the spell
205: * check index.
206: */
207: SpellCheck spellCheck() default SpellCheck.NA;
208:
209: /**
210: * Allows to set a converter for the {@link org.compass.core.mapping.osem.ClassMapping} of
211: * the searchable class.
212: * <p/>
213: * This is advance setting, since Compass comes with it's own internal
214: * {@link org.compass.core.converter.mapping.osem.ClassMappingConverter}.
215: */
216: String converter() default "";
217: }
|