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  ;
20  import java.util.Iterator  ;
21  import java.util.List  ;
22  import java.util.ArrayList  ;
23  import java.util.Vector  ;
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   {
43    List   fields = new Vector  ();
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   name) {
103     Iterator   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   name) {
123     Iterator   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   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   get(String   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   fields() {
161     return ((Vector  )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   name) {
172      List   result = new ArrayList  ();
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  [] getValues(String   name) {
194     List   result = new ArrayList  ();
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  [])result.toArray(new String  [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   name) {
216     List   result = new ArrayList  ();
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   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   toString() {
249     StringBuffer   buffer = new StringBuffer  ();
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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags