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.Reader;
020: import java.io.Serializable;
021:
022: import org.compass.core.engine.SearchEngineException;
023: import org.compass.core.spi.AliasedObject;
024:
025: /**
026: * A Resource holds a list of meta data properties. The Resource is the basic
027: * data that is saved in Compass. Compass provides object to Resource mapping as
028: * well in the CompassSession object.
029: *
030: * @author kimchy
031: */
032: public interface Resource extends AliasedObject, Serializable {
033:
034: /**
035: * Returns the mapping alias of the associated Resource
036: *
037: * @return The alias
038: */
039: String getAlias();
040:
041: /**
042: * Returns the unique id of the resource. Note, the ids must be
043: * set on this resource in order to get the uid, if not a
044: * <code>CompassException</code> will be thrown.
045: */
046: String getUID() throws CompassException;
047:
048: /**
049: * Returns the id of the resource. Used when there is only one id
050: * for the resource.
051: *
052: * @return The id of the resource.
053: */
054: String getId();
055:
056: /**
057: * Returns the id values of the resource.
058: *
059: * @return The id values of the resource
060: */
061: String[] getIds();
062:
063: /**
064: * Returns the id property of the resource
065: *
066: * @return The id properties of the resource
067: */
068: Property getIdProperty();
069:
070: /**
071: * Returns the id properties of the resource
072: *
073: * @return The id properties of the resource
074: */
075: Property[] getIdProperties();
076:
077: /**
078: * Returns the string value of the property with the given name if any exist
079: * in this resource, or null. If multiple properties exist with this name,
080: * this method returns the first value added.
081: *
082: * @param name The name of the property
083: * @return The first value that match the name
084: */
085: String getValue(String name);
086:
087: /**
088: * Returns the object vlaue of the property with the given name if any exists
089: * in the resource, or null. If multiple properties exists with this name,
090: * this methods returns the first value added.
091: * <p/>
092: * If a converter is associated with the property in one of Compass mapping definitions,
093: * it will be used to convert the string value to an object value. If there is no converter
094: * associated with the property, the string value will be returned.
095: *
096: * @param name The name of the property
097: * @return The first object value that match the name (converted if possible)
098: */
099: Object getObject(String name);
100:
101: /**
102: * Returns an array of values of the property specified as the method
103: * parameter. This method can return <code>null</code>.
104: *
105: * @param name the name of the property
106: * @return a <code>String[]</code> of property values
107: */
108: String[] getValues(String name);
109:
110: /**
111: * Adds a property to the resource based on resource mapping definitions. If
112: * the property already exists in the resource (the name exists), it will be
113: * added on top of it (won't replace it). ONLY use this method with resource
114: * mapping.
115: *
116: * @param name the name of the property
117: * @param value the value to be set (will be converted to a string).
118: * @throws SearchEngineException
119: */
120: Resource addProperty(String name, Object value)
121: throws SearchEngineException;
122:
123: /**
124: * Adds a property to the resource based on resource mapping definitions. If
125: * the property already exists in the resource (the name exists), it will be
126: * added on top of it (won't replace it). ONLY use this method with resource
127: * mapping.
128: *
129: * @param name the name of the property
130: * @param value the value to be set (will be converted to a string).
131: * @throws SearchEngineException
132: */
133: Resource addProperty(String name, Reader value)
134: throws SearchEngineException;
135:
136: /**
137: * Add a property to the resource. If the property already exists in the
138: * resource (the name exists), it will be added on top of it (won't replace
139: * it). Note: Compass adds all properties specified in mapping file, adding
140: * extra properties to a Resource will make the index out of sync with
141: * mapping.
142: *
143: * @param property The properyt to add
144: */
145: Resource addProperty(Property property);
146:
147: /**
148: * Sets a property to the resource (removes then adds) based on resource mapping definitions. If
149: * the property already exists in the resource (the name exists), it will be
150: * added on top of it (won't replace it). ONLY use this method with resource
151: * mapping.
152: *
153: * @param name the name of the property
154: * @param value the value to be set (will be converted to a string).
155: * @throws SearchEngineException
156: */
157: Resource setProperty(String name, Object value)
158: throws SearchEngineException;
159:
160: /**
161: * Sets a property to the resource (removes then adds) based on resource mapping definitions. If
162: * the property already exists in the resource (the name exists), it will be
163: * added on top of it (won't replace it). ONLY use this method with resource
164: * mapping.
165: *
166: * @param name the name of the property
167: * @param value the value to be set (will be converted to a string).
168: * @throws SearchEngineException
169: */
170: Resource setProperty(String name, Reader value)
171: throws SearchEngineException;
172:
173: /**
174: * Sest a property to the resource (removes then adds). If the property already exists in the
175: * resource (the name exists), it will be added on top of it (won't replace
176: * it). Note: Compass adds all properties specified in mapping file, adding
177: * extra properties to a Resource will make the index out of sync with
178: * mapping.
179: *
180: * @param property The properyt to add
181: */
182: Resource setProperty(Property property);
183:
184: /**
185: * Remove the latest property added under the given name.
186: *
187: * @param name The last property name to remove
188: */
189: Resource removeProperty(String name);
190:
191: /**
192: * Removes all the properties under the given name.
193: *
194: * @param name The properties name to remove
195: */
196: Resource removeProperties(String name);
197:
198: /**
199: * Returns the first property under the name.
200: *
201: * @param name The name of the property
202: * @return The first proeprty that match the name
203: */
204: Property getProperty(String name);
205:
206: /**
207: * Returns all the properties under the given name.
208: *
209: * @param name The name of the properties
210: * @return An array of properties that match the name
211: */
212: Property[] getProperties(String name);
213:
214: /**
215: * Returns all the properties for the resource.
216: *
217: * @return All the properties
218: */
219: Property[] getProperties();
220:
221: /**
222: * Returns the boost for the property.
223: *
224: * @return The boost value
225: */
226: float getBoost();
227:
228: /**
229: * Sets the boost level for the resource.
230: *
231: * @param boost The boost level for the resource
232: */
233: Resource setBoost(float boost);
234:
235: /**
236: * Copies the content of the give Resource into the current one
237: *
238: * @param resource The resource to copy from
239: */
240: void copy(Resource resource);
241: }
|