KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > lucene > document > Document


1 package org.apache.lucene.document;
2
3 /**
4  * Copyright 2004 The Apache Software Foundation
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */

18
19 import java.util.Enumeration JavaDoc;
20 import java.util.Iterator JavaDoc;
21 import java.util.List JavaDoc;
22 import java.util.ArrayList JavaDoc;
23 import java.util.Vector JavaDoc;
24 import org.apache.lucene.index.IndexReader; // for javadoc
25
import org.apache.lucene.search.Searcher; // for javadoc
26
import org.apache.lucene.search.Hits; // for javadoc
27

28 /** Documents are the unit of indexing and search.
29  *
30  * A Document is a set of fields. Each field has a name and a textual value.
31  * A field may be {@link Field#isStored() stored} with the document, in which
32  * case it is returned with search hits on the document. Thus each document
33  * should typically contain one or more stored fields which uniquely identify
34  * it.
35  *
36  * <p>Note that fields which are <i>not</i> {@link Field#isStored() stored} are
37  * <i>not</i> available in documents retrieved from the index, e.g. with {@link
38  * Hits#doc(int)}, {@link Searcher#doc(int)} or {@link
39  * IndexReader#document(int)}.
40  */

41
42 public final class Document implements java.io.Serializable JavaDoc {
43   List JavaDoc fields = new Vector JavaDoc();
44   private float boost = 1.0f;
45
46   /** Constructs a new document with no fields. */
47   public Document() {}
48
49
50   /** Sets a boost factor for hits on any field of this document. This value
51    * will be multiplied into the score of all hits on this document.
52    *
53    * <p>Values are multiplied into the value of {@link Field#getBoost()} of
54    * each field in this document. Thus, this method in effect sets a default
55    * boost for the fields of this document.
56    *
57    * @see Field#setBoost(float)
58    */

59   public void setBoost(float boost) {
60     this.boost = boost;
61   }
62
63   /** Returns the boost factor for hits on any field of this document.
64    *
65    * <p>The default value is 1.0.
66    *
67    * <p>Note: This value is not stored directly with the document in the index.
68    * Documents returned from {@link IndexReader#document(int)} and
69    * {@link Hits#doc(int)} may thus not have the same value present as when
70    * this document was indexed.
71    *
72    * @see #setBoost(float)
73    */

74   public float getBoost() {
75     return boost;
76   }
77
78   /**
79    * <p>Adds a field to a document. Several fields may be added with
80    * the same name. In this case, if the fields are indexed, their text is
81    * treated as though appended for the purposes of search.</p>
82    * <p> Note that add like the removeField(s) methods only makes sense
83    * prior to adding a document to an index. These methods cannot
84    * be used to change the content of an existing index! In order to achieve this,
85    * a document has to be deleted from an index and a new changed version of that
86    * document has to be added.</p>
87    */

88   public final void add(Field field) {
89     fields.add(field);
90   }
91   
92   /**
93    * <p>Removes field with the specified name from the document.
94    * If multiple fields exist with this name, this method removes the first field that has been added.
95    * If there is no field with the specified name, the document remains unchanged.</p>
96    * <p> Note that the removeField(s) methods like the add method only make sense
97    * prior to adding a document to an index. These methods cannot
98    * be used to change the content of an existing index! In order to achieve this,
99    * a document has to be deleted from an index and a new changed version of that
100    * document has to be added.</p>
101    */

102   public final void removeField(String JavaDoc name) {
103     Iterator JavaDoc it = fields.iterator();
104     while (it.hasNext()) {
105       Field field = (Field)it.next();
106       if (field.name().equals(name)) {
107         it.remove();
108         return;
109       }
110     }
111   }
112   
113   /**
114    * <p>Removes all fields with the given name from the document.
115    * If there is no field with the specified name, the document remains unchanged.</p>
116    * <p> Note that the removeField(s) methods like the add method only make sense
117    * prior to adding a document to an index. These methods cannot
118    * be used to change the content of an existing index! In order to achieve this,
119    * a document has to be deleted from an index and a new changed version of that
120    * document has to be added.</p>
121    */

122   public final void removeFields(String JavaDoc name) {
123     Iterator JavaDoc it = fields.iterator();
124     while (it.hasNext()) {
125       Field field = (Field)it.next();
126       if (field.name().equals(name)) {
127         it.remove();
128       }
129     }
130   }
131
132   /** Returns a field with the given name if any exist in this document, or
133    * null. If multiple fields exists with this name, this method returns the
134    * first value added.
135    */

136   public final Field getField(String JavaDoc name) {
137     for (int i = 0; i < fields.size(); i++) {
138       Field field = (Field)fields.get(i);
139       if (field.name().equals(name))
140     return field;
141     }
142     return null;
143   }
144
145   /** Returns the string value of the field with the given name if any exist in
146    * this document, or null. If multiple fields exist with this name, this
147    * method returns the first value added. If only binary fields with this name
148    * exist, returns null.
149    */

150   public final String JavaDoc get(String JavaDoc name) {
151     for (int i = 0; i < fields.size(); i++) {
152       Field field = (Field)fields.get(i);
153       if (field.name().equals(name) && (!field.isBinary()))
154         return field.stringValue();
155     }
156     return null;
157   }
158
159   /** Returns an Enumeration of all the fields in a document. */
160   public final Enumeration JavaDoc fields() {
161     return ((Vector JavaDoc)fields).elements();
162   }
163
164   /**
165    * Returns an array of {@link Field}s with the given name.
166    * This method can return <code>null</code>.
167    *
168    * @param name the name of the field
169    * @return a <code>Field[]</code> array
170    */

171    public final Field[] getFields(String JavaDoc name) {
172      List JavaDoc result = new ArrayList JavaDoc();
173      for (int i = 0; i < fields.size(); i++) {
174        Field field = (Field)fields.get(i);
175        if (field.name().equals(name)) {
176          result.add(field);
177        }
178      }
179
180      if (result.size() == 0)
181        return null;
182
183      return (Field[])result.toArray(new Field[result.size()]);
184    }
185
186   /**
187    * Returns an array of values of the field specified as the method parameter.
188    * This method can return <code>null</code>.
189    *
190    * @param name the name of the field
191    * @return a <code>String[]</code> of field values
192    */

193   public final String JavaDoc[] getValues(String JavaDoc name) {
194     List JavaDoc result = new ArrayList JavaDoc();
195     for (int i = 0; i < fields.size(); i++) {
196       Field field = (Field)fields.get(i);
197       if (field.name().equals(name) && (!field.isBinary()))
198         result.add(field.stringValue());
199     }
200     
201     if (result.size() == 0)
202       return null;
203     
204     return (String JavaDoc[])result.toArray(new String JavaDoc[result.size()]);
205   }
206
207   /**
208   * Returns an array of byte arrays for of the fields that have the name specified
209   * as the method parameter. This method will return <code>null</code> if no
210   * binary fields with the specified name are available.
211   *
212   * @param name the name of the field
213   * @return a <code>byte[][]</code> of binary field values.
214   */

215   public final byte[][] getBinaryValues(String JavaDoc name) {
216     List JavaDoc result = new ArrayList JavaDoc();
217     for (int i = 0; i < fields.size(); i++) {
218       Field field = (Field)fields.get(i);
219       if (field.name().equals(name) && (field.isBinary()))
220         result.add(field.binaryValue());
221     }
222   
223     if (result.size() == 0)
224       return null;
225   
226     return (byte[][])result.toArray(new byte[result.size()][]);
227   }
228   
229   /**
230   * Returns an array of bytes for the first (or only) field that has the name
231   * specified as the method parameter. This method will return <code>null</code>
232   * if no binary fields with the specified name are available.
233   * There may be non-binary fields with the same name.
234   *
235   * @param name the name of the field.
236   * @return a <code>byte[]</code> containing the binary field value.
237   */

238   public final byte[] getBinaryValue(String JavaDoc name) {
239     for (int i=0; i < fields.size(); i++) {
240       Field field = (Field)fields.get(i);
241       if (field.name().equals(name) && (field.isBinary()))
242         return field.binaryValue();
243     }
244     return null;
245   }
246   
247   /** Prints the fields of a document for human consumption. */
248   public final String JavaDoc toString() {
249     StringBuffer JavaDoc buffer = new StringBuffer JavaDoc();
250     buffer.append("Document<");
251     for (int i = 0; i < fields.size(); i++) {
252       Field field = (Field)fields.get(i);
253       buffer.append(field.toString());
254       if (i != fields.size()-1)
255         buffer.append(" ");
256     }
257     buffer.append(">");
258     return buffer.toString();
259   }
260 }
261
Popular Tags