Lucene.Net  3.0.3
Lucene.Net is a port of the Lucene search engine library, written in C# and targeted at .NET runtime users.
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Properties Pages
Document.cs
Go to the documentation of this file.
1 /*
2  * Licensed to the Apache Software Foundation (ASF) under one or more
3  * contributor license agreements. See the NOTICE file distributed with
4  * this work for additional information regarding copyright ownership.
5  * The ASF licenses this file to You under the Apache License, Version 2.0
6  * (the "License"); you may not use this file except in compliance with
7  * the License. You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 
18 using System;
19 
20 // for javadoc
21 using IndexReader = Lucene.Net.Index.IndexReader;
22 using ScoreDoc = Lucene.Net.Search.ScoreDoc;
23 using Searcher = Lucene.Net.Search.Searcher;
24 
25 namespace Lucene.Net.Documents
26 {
27 
28  /// <summary>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 <see cref="IFieldable.IsStored()">stored</see> 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> <see cref="IFieldable.IsStored()">stored</see> are
37  /// <i>not</i> available in documents retrieved from the index, e.g. with <see cref="ScoreDoc.Doc" />,
38  /// <see cref="Searcher.Doc(int)" /> or <see cref="IndexReader.Document(int)" />.
39  /// </summary>
40 
41  [Serializable]
42  public sealed class Document
43  {
44  private class AnonymousClassEnumeration : System.Collections.IEnumerator
45  {
46  public AnonymousClassEnumeration(Document enclosingInstance)
47  {
48  InitBlock(enclosingInstance);
49  }
50  private void InitBlock(Document enclosingInstance)
51  {
52  this.enclosingInstance = enclosingInstance;
53  iter = Enclosing_Instance.fields.GetEnumerator();
54  }
55  private System.Object tempAuxObj;
56  public bool MoveNext()
57  {
58  bool result = HasMoreElements();
59  if (result)
60  {
61  tempAuxObj = NextElement();
62  }
63  return result;
64  }
65  public void Reset()
66  {
67  tempAuxObj = null;
68  }
69  public System.Object Current
70  {
71  get
72  {
73  return tempAuxObj;
74  }
75 
76  }
77  private Document enclosingInstance;
78  public Document Enclosing_Instance
79  {
80  get
81  {
82  return enclosingInstance;
83  }
84 
85  }
86  internal System.Collections.IEnumerator iter;
87  public bool HasMoreElements()
88  {
89  return iter.MoveNext();
90  }
91  public System.Object NextElement()
92  {
93  return iter.Current;
94  }
95  }
96  internal System.Collections.Generic.IList<IFieldable> fields = new System.Collections.Generic.List<IFieldable>();
97  private float boost = 1.0f;
98 
99  /// <summary>Constructs a new document with no fields. </summary>
100  public Document()
101  {
102  }
103 
104 
105  /// <summary>Gets or sets, at indexing time, the boost factor.
106  /// <para>
107  /// The default is 1.0
108  /// </para>
109  /// <p/>Note that once a document is indexed this value is no longer available
110  /// from the index. At search time, for retrieved documents, this method always
111  /// returns 1. This however does not mean that the boost value set at indexing
112  /// time was ignored - it was just combined with other indexing time factors and
113  /// stored elsewhere, for better indexing and search performance. (For more
114  /// information see the "norm(t,d)" part of the scoring formula in
115  /// <see cref="Lucene.Net.Search.Similarity">Similarity</see>.)
116  /// </summary>
117  public float Boost
118  {
119  get { return boost; }
120  set { this.boost = value; }
121  }
122 
123  /// <summary> <p/>Adds a field to a document. Several fields may be added with
124  /// the same name. In this case, if the fields are indexed, their text is
125  /// treated as though appended for the purposes of search.<p/>
126  /// <p/> Note that add like the removeField(s) methods only makes sense
127  /// prior to adding a document to an index. These methods cannot
128  /// be used to change the content of an existing index! In order to achieve this,
129  /// a document has to be deleted from an index and a new changed version of that
130  /// document has to be added.<p/>
131  /// </summary>
132  public void Add(IFieldable field)
133  {
134  fields.Add(field);
135  }
136 
137  /// <summary> <p/>Removes field with the specified name from the document.
138  /// If multiple fields exist with this name, this method removes the first field that has been added.
139  /// If there is no field with the specified name, the document remains unchanged.<p/>
140  /// <p/> Note that the removeField(s) methods like the add method only make sense
141  /// prior to adding a document to an index. These methods cannot
142  /// be used to change the content of an existing index! In order to achieve this,
143  /// a document has to be deleted from an index and a new changed version of that
144  /// document has to be added.<p/>
145  /// </summary>
146  public void RemoveField(System.String name)
147  {
148  System.Collections.Generic.IEnumerator<IFieldable> it = fields.GetEnumerator();
149  while (it.MoveNext())
150  {
151  IFieldable field = it.Current;
152  if (field.Name.Equals(name))
153  {
154  fields.Remove(field);
155  return ;
156  }
157  }
158  }
159 
160  /// <summary> <p/>Removes all fields with the given name from the document.
161  /// If there is no field with the specified name, the document remains unchanged.<p/>
162  /// <p/> Note that the removeField(s) methods like the add method only make sense
163  /// prior to adding a document to an index. These methods cannot
164  /// be used to change the content of an existing index! In order to achieve this,
165  /// a document has to be deleted from an index and a new changed version of that
166  /// document has to be added.<p/>
167  /// </summary>
168  public void RemoveFields(System.String name)
169  {
170  for (int i = fields.Count - 1; i >= 0; i--)
171  {
172  IFieldable field = fields[i];
173  if (field.Name.Equals(name))
174  {
175  fields.RemoveAt(i);
176  }
177  }
178  }
179 
180  /// <summary>Returns a field with the given name if any exist in this document, or
181  /// null. If multiple fields exists with this name, this method returns the
182  /// first value added.
183  /// Do not use this method with lazy loaded fields.
184  /// </summary>
185  public Field GetField(System.String name)
186  {
187  return (Field) GetFieldable(name);
188  }
189 
190 
191  /// <summary>Returns a field with the given name if any exist in this document, or
192  /// null. If multiple fields exists with this name, this method returns the
193  /// first value added.
194  /// </summary>
195  public IFieldable GetFieldable(System.String name)
196  {
197  foreach(IFieldable field in fields)
198  {
199  if (field.Name.Equals(name))
200  return field;
201  }
202  return null;
203  }
204 
205  /// <summary>Returns the string value of the field with the given name if any exist in
206  /// this document, or null. If multiple fields exist with this name, this
207  /// method returns the first value added. If only binary fields with this name
208  /// exist, returns null.
209  /// </summary>
210  public System.String Get(System.String name)
211  {
212  foreach(IFieldable field in fields)
213  {
214  if (field.Name.Equals(name) && (!field.IsBinary))
215  return field.StringValue;
216  }
217  return null;
218  }
219 
220  /// <summary>Returns a List of all the fields in a document.
221  /// <p/>Note that fields which are <i>not</i> <see cref="IFieldable.IsStored()">stored</see> are
222  /// <i>not</i> available in documents retrieved from the
223  /// index, e.g. <see cref="Searcher.Doc(int)" /> or <see cref="IndexReader.Document(int)" />.
224  /// </summary>
225  public System.Collections.Generic.IList<IFieldable> GetFields()
226  {
227  return fields;
228  }
229 
230  private static readonly Field[] NO_FIELDS = new Field[0];
231 
232  /// <summary> Returns an array of <see cref="Field" />s with the given name.
233  /// Do not use with lazy loaded fields.
234  /// This method returns an empty array when there are no
235  /// matching fields. It never returns null.
236  ///
237  /// </summary>
238  /// <param name="name">the name of the field
239  /// </param>
240  /// <returns> a <c>Field[]</c> array
241  /// </returns>
242  public Field[] GetFields(System.String name)
243  {
244  var result = new System.Collections.Generic.List<Field>();
245  foreach(IFieldable field in fields)
246  {
247  if (field.Name.Equals(name))
248  {
249  result.Add((Field)field);
250  }
251  }
252 
253  if (result.Count == 0)
254  return NO_FIELDS;
255 
256  return result.ToArray();
257  }
258 
259 
260  private static readonly IFieldable[] NO_FIELDABLES = new IFieldable[0];
261 
262  /// <summary> Returns an array of <see cref="IFieldable" />s with the given name.
263  /// This method returns an empty array when there are no
264  /// matching fields. It never returns null.
265  ///
266  /// </summary>
267  /// <param name="name">the name of the field
268  /// </param>
269  /// <returns> a <c>Fieldable[]</c> array
270  /// </returns>
271  public IFieldable[] GetFieldables(System.String name)
272  {
273  var result = new System.Collections.Generic.List<IFieldable>();
274  foreach(IFieldable field in fields)
275  {
276  if (field.Name.Equals(name))
277  {
278  result.Add(field);
279  }
280  }
281 
282  if (result.Count == 0)
283  return NO_FIELDABLES;
284 
285  return result.ToArray();
286  }
287 
288 
289  private static readonly System.String[] NO_STRINGS = new System.String[0];
290 
291  /// <summary> Returns an array of values of the field specified as the method parameter.
292  /// This method returns an empty array when there are no
293  /// matching fields. It never returns null.
294  /// </summary>
295  /// <param name="name">the name of the field
296  /// </param>
297  /// <returns> a <c>String[]</c> of field values
298  /// </returns>
299  public System.String[] GetValues(System.String name)
300  {
301  var result = new System.Collections.Generic.List<string>();
302  foreach(IFieldable field in fields)
303  {
304  if (field.Name.Equals(name) && (!field.IsBinary))
305  result.Add(field.StringValue);
306  }
307 
308  if (result.Count == 0)
309  return NO_STRINGS;
310 
311  return result.ToArray();
312  }
313 
314  private static readonly byte[][] NO_BYTES = new byte[0][];
315 
316  /// <summary> Returns an array of byte arrays for of the fields that have the name specified
317  /// as the method parameter. This method returns an empty
318  /// array when there are no matching fields. It never
319  /// returns null.
320  ///
321  /// </summary>
322  /// <param name="name">the name of the field
323  /// </param>
324  /// <returns> a <c>byte[][]</c> of binary field values
325  /// </returns>
326  public byte[][] GetBinaryValues(System.String name)
327  {
328  var result = new System.Collections.Generic.List<byte[]>();
329  foreach(IFieldable field in fields)
330  {
331  if (field.Name.Equals(name) && (field.IsBinary))
332  result.Add(field.GetBinaryValue());
333  }
334 
335  if (result.Count == 0)
336  return NO_BYTES;
337 
338  return result.ToArray();
339  }
340 
341  /// <summary> Returns an array of bytes for the first (or only) field that has the name
342  /// specified as the method parameter. This method will return <c>null</c>
343  /// if no binary fields with the specified name are available.
344  /// There may be non-binary fields with the same name.
345  ///
346  /// </summary>
347  /// <param name="name">the name of the field.
348  /// </param>
349  /// <returns> a <c>byte[]</c> containing the binary field value or <c>null</c>
350  /// </returns>
351  public byte[] GetBinaryValue(System.String name)
352  {
353  foreach(IFieldable field in fields)
354  {
355  if (field.Name.Equals(name) && (field.IsBinary))
356  return field.GetBinaryValue();
357  }
358  return null;
359  }
360 
361  /// <summary>Prints the fields of a document for human consumption. </summary>
362  public override System.String ToString()
363  {
364  System.Text.StringBuilder buffer = new System.Text.StringBuilder();
365  buffer.Append("Document<");
366  for (int i = 0; i < fields.Count; i++)
367  {
368  IFieldable field = fields[i];
369  buffer.Append(field.ToString());
370  if (i != fields.Count - 1)
371  buffer.Append(" ");
372  }
373  buffer.Append(">");
374  return buffer.ToString();
375  }
376 
377  public System.Collections.Generic.IList<IFieldable> fields_ForNUnit
378  {
379  get { return fields; }
380  }
381  }
382 }