beagled/Lucene.Net/Document/Document.cs

   1 /*
   2  * Copyright 2004 The Apache Software Foundation
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16 using System;
  17 using IndexReader = Lucene.Net.Index.IndexReader;
  18 using Hits = Lucene.Net.Search.Hits;
  19 using Searcher = Lucene.Net.Search.Searcher;
  20 namespace Lucene.Net.Documents
  21 {
  22
  23         /// <summary>Documents are the unit of indexing and search.
  24         ///
  25         /// A Document is a set of fields.  Each Field has a name and a textual value.
  26         /// A Field may be {@link Field#IsStored() stored} with the document, in which
  27         /// case it is returned with search hits on the document.  Thus each document
  28         /// should typically contain one or more stored fields which uniquely identify
  29         /// it.
  30         ///
  31         /// <p>Note that fields which are <i>not</i> {@link Field#IsStored() stored} are
  32         /// <i>not</i> available in documents retrieved from the index, e.g. with {@link
  33         /// Hits#Doc(int)}, {@link Searcher#Doc(int)} or {@link
  34         /// IndexReader#Document(int)}.
  35         /// </summary>
  36
  37         [Serializable]
  38         public sealed class Document
  39         {
  40                 public System.Collections.IList fields = System.Collections.ArrayList.Synchronized(new System.Collections.ArrayList(10));
  41                 private float boost = 1.0f;
  42
  43                 /// <summary>Constructs a new document with no fields. </summary>
  44                 public Document()
  45                 {
  46                 }
  47
  48
  49                 /// <summary>Sets a boost factor for hits on any Field of this document.  This value
  50                 /// will be multiplied into the score of all hits on this document.
  51                 ///
  52                 /// <p>Values are multiplied into the value of {@link Field#GetBoost()} of
  53                 /// each Field in this document.  Thus, this method in effect sets a default
  54                 /// boost for the fields of this document.
  55                 ///
  56                 /// </summary>
  57                 /// <seealso cref="Field#SetBoost(float)">
  58                 /// </seealso>
  59                 public void  SetBoost(float boost)
  60                 {
  61                         this.boost = boost;
  62                 }
  63
  64                 /// <summary>Returns the boost factor for hits on any Field of this document.
  65                 ///
  66                 /// <p>The default value is 1.0.
  67                 ///
  68                 /// <p>Note: This value is not stored directly with the document in the index.
  69                 /// Documents returned from {@link IndexReader#Document(int)} and
  70                 /// {@link Hits#Doc(int)} may thus not have the same value present as when
  71                 /// this document was indexed.
  72                 ///
  73                 /// </summary>
  74                 /// <seealso cref="#SetBoost(float)">
  75                 /// </seealso>
  76                 public float GetBoost()
  77                 {
  78                         return boost;
  79                 }
  80
  81                 /// <summary> <p>Adds a Field to a document.  Several fields may be added with
  82                 /// the same name.  In this case, if the fields are indexed, their text is
  83                 /// treated as though appended for the purposes of search.</p>
  84                 /// <p> Note that add like the removeField(s) methods only makes sense
  85                 /// prior to adding a document to an index. These methods cannot
  86                 /// be used to change the content of an existing index! In order to achieve this,
  87                 /// a document has to be deleted from an index and a new changed version of that
  88                 /// document has to be added.</p>
  89                 /// </summary>
  90                 public void  Add(Field field)
  91                 {
  92                         fields.Add(field);
  93                 }
  94
  95                 /// <summary> <p>Removes Field with the specified name from the document.
  96                 /// If multiple fields exist with this name, this method removes the first Field that has been added.
  97                 /// If there is no Field with the specified name, the document remains unchanged.</p>
  98                 /// <p> Note that the removeField(s) methods like the add method only make sense
  99                 /// prior to adding a document to an index. These methods cannot
 100                 /// be used to change the content of an existing index! In order to achieve this,
 101                 /// a document has to be deleted from an index and a new changed version of that
 102                 /// document has to be added.</p>
 103                 /// </summary>
 104                 public void  RemoveField(System.String name)
 105                 {
 106                         System.Collections.IEnumerator it = fields.GetEnumerator();
 107                         while (it.MoveNext())
 108                         {
 109                                 Field field = (Field) it.Current;
 110                                 if (field.Name().Equals(name))
 111                                 {
 112                                         fields.Remove(field);
 113                                         return ;
 114                                 }
 115                         }
 116                 }
 117
 118                 /// <summary> <p>Removes all fields with the given name from the document.
 119                 /// If there is no Field with the specified name, the document remains unchanged.</p>
 120                 /// <p> Note that the removeField(s) methods like the add method only make sense
 121                 /// prior to adding a document to an index. These methods cannot
 122                 /// be used to change the content of an existing index! In order to achieve this,
 123                 /// a document has to be deleted from an index and a new changed version of that
 124                 /// document has to be added.</p>
 125                 /// </summary>
 126                 public void  RemoveFields(System.String name)
 127                 {
 128             for (int i = fields.Count - 1; i >= 0; i--)
 129             {
 130                 Field field = (Field) fields[i];
 131                 if (field.Name().Equals(name))
 132                 {
 133                     fields.RemoveAt(i);
 134                 }
 135             }
 136                 }
 137
 138                 /// <summary>Returns a Field with the given name if any exist in this document, or
 139                 /// null.  If multiple fields exists with this name, this method returns the
 140                 /// first value added.
 141                 /// </summary>
 142                 public Field GetField(System.String name)
 143                 {
 144                         for (int i = 0; i < fields.Count; i++)
 145                         {
 146                                 Field field = (Field) fields[i];
 147                                 if (field.Name().Equals(name))
 148                                         return field;
 149                         }
 150                         return null;
 151                 }
 152
 153                 /// <summary>Returns the string value of the Field with the given name if any exist in
 154                 /// this document, or null.  If multiple fields exist with this name, this
 155                 /// method returns the first value added.
 156                 /// </summary>
 157                 public System.String Get(System.String name)
 158                 {
 159                         Field field = GetField(name);
 160                         if (field != null)
 161                                 return field.StringValue();
 162                         else
 163                                 return null;
 164                 }
 165
 166                 /// <summary>Returns an Enumeration of all the fields in a document. </summary>
 167                 public System.Collections.IEnumerable Fields()
 168                 {
 169             return (System.Collections.IEnumerable) fields;
 170                 }
 171
 172                 /// <summary> Returns an array of {@link Field}s with the given name.
 173                 /// This method can return <code>null</code>.
 174                 ///
 175                 /// </summary>
 176                 /// <param name="name">the name of the Field
 177                 /// </param>
 178                 /// <returns> a <code>Field[]</code> array
 179                 /// </returns>
 180                 public Field[] GetFields(System.String name)
 181                 {
 182             System.Collections.ArrayList result = new System.Collections.ArrayList();
 183                         for (int i = 0; i < fields.Count; i++)
 184                         {
 185                                 Field field = (Field) fields[i];
 186                                 if (field.Name().Equals(name))
 187                                 {
 188                                         result.Add(field);
 189                                 }
 190                         }
 191
 192                         if (result.Count == 0)
 193                                 return null;
 194
 195             return (Field[]) result.ToArray(typeof(Field));
 196                 }
 197
 198                 /// <summary> Returns an array of values of the Field specified as the method parameter.
 199                 /// This method can return <code>null</code>.
 200                 ///
 201                 /// </summary>
 202                 /// <param name="name">the name of the Field
 203                 /// </param>
 204                 /// <returns> a <code>String[]</code> of Field values
 205                 /// </returns>
 206                 public System.String[] GetValues(System.String name)
 207                 {
 208                         Field[] namedFields = GetFields(name);
 209                         if (namedFields == null)
 210                                 return null;
 211                         System.String[] values = new System.String[namedFields.Length];
 212                         for (int i = 0; i < namedFields.Length; i++)
 213                         {
 214                                 values[i] = namedFields[i].StringValue();
 215                         }
 216                         return values;
 217                 }
 218
 219                 /// <summary>Prints the fields of a document for human consumption. </summary>
 220                 public override System.String ToString()
 221                 {
 222                         System.Text.StringBuilder buffer = new System.Text.StringBuilder();
 223                         buffer.Append("Document<");
 224                         for (int i = 0; i < fields.Count; i++)
 225                         {
 226                                 Field field = (Field) fields[i];
 227                                 buffer.Append(field.ToString());
 228                                 if (i != fields.Count - 1)
 229                                         buffer.Append(" ");
 230                         }
 231                         buffer.Append(">");
 232                         return buffer.ToString();
 233                 }
 234         }
 235 }