/*
* Copyright 2004 The Apache Software Foundation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
using System;
using IndexReader = Lucene.Net.Index.IndexReader;
using Hits = Lucene.Net.Search.Hits;
using Searcher = Lucene.Net.Search.Searcher;
namespace Lucene.Net.Documents
{
/// Documents are the unit of indexing and search.
///
/// A Document is a set of fields. Each Field has a name and a textual value.
/// A Field may be {@link Field#IsStored() stored} with the document, in which
/// case it is returned with search hits on the document. Thus each document
/// should typically contain one or more stored fields which uniquely identify
/// it.
///
/// Note that fields which are not {@link Field#IsStored() stored} are
/// not available in documents retrieved from the index, e.g. with {@link
/// Hits#Doc(int)}, {@link Searcher#Doc(int)} or {@link
/// IndexReader#Document(int)}.
///
[Serializable]
public sealed class Document
{
public System.Collections.IList fields = System.Collections.ArrayList.Synchronized(new System.Collections.ArrayList(10));
private float boost = 1.0f;
/// Constructs a new document with no fields.
public Document()
{
}
/// Sets a boost factor for hits on any Field of this document. This value
/// will be multiplied into the score of all hits on this document.
///
/// Values are multiplied into the value of {@link Field#GetBoost()} of
/// each Field in this document. Thus, this method in effect sets a default
/// boost for the fields of this document.
///
///
///
///
public void SetBoost(float boost)
{
this.boost = boost;
}
/// Returns the boost factor for hits on any Field of this document.
///
/// The default value is 1.0.
///
///
Note: This value is not stored directly with the document in the index.
/// Documents returned from {@link IndexReader#Document(int)} and
/// {@link Hits#Doc(int)} may thus not have the same value present as when
/// this document was indexed.
///
///
///
///
public float GetBoost()
{
return boost;
}
/// Adds a Field to a document. Several fields may be added with
/// the same name. In this case, if the fields are indexed, their text is
/// treated as though appended for the purposes of search.
/// Note that add like the removeField(s) methods only makes sense
/// prior to adding a document to an index. These methods cannot
/// be used to change the content of an existing index! In order to achieve this,
/// a document has to be deleted from an index and a new changed version of that
/// document has to be added.
///
public void Add(Field field)
{
fields.Add(field);
}
/// Removes Field with the specified name from the document.
/// If multiple fields exist with this name, this method removes the first Field that has been added.
/// If there is no Field with the specified name, the document remains unchanged.
/// Note that the removeField(s) methods like the add method only make sense
/// prior to adding a document to an index. These methods cannot
/// be used to change the content of an existing index! In order to achieve this,
/// a document has to be deleted from an index and a new changed version of that
/// document has to be added.
///
public void RemoveField(System.String name)
{
System.Collections.IEnumerator it = fields.GetEnumerator();
while (it.MoveNext())
{
Field field = (Field) it.Current;
if (field.Name().Equals(name))
{
fields.Remove(field);
return ;
}
}
}
/// Removes all fields with the given name from the document.
/// If there is no Field with the specified name, the document remains unchanged.
/// Note that the removeField(s) methods like the add method only make sense
/// prior to adding a document to an index. These methods cannot
/// be used to change the content of an existing index! In order to achieve this,
/// a document has to be deleted from an index and a new changed version of that
/// document has to be added.
///
public void RemoveFields(System.String name)
{
for (int i = fields.Count - 1; i >= 0; i--)
{
Field field = (Field) fields[i];
if (field.Name().Equals(name))
{
fields.RemoveAt(i);
}
}
}
/// Returns a Field with the given name if any exist in this document, or
/// null. If multiple fields exists with this name, this method returns the
/// first value added.
///
public Field GetField(System.String name)
{
for (int i = 0; i < fields.Count; i++)
{
Field field = (Field) fields[i];
if (field.Name().Equals(name))
return field;
}
return null;
}
/// Returns the string value of the Field with the given name if any exist in
/// this document, or null. If multiple fields exist with this name, this
/// method returns the first value added.
///
public System.String Get(System.String name)
{
Field field = GetField(name);
if (field != null)
return field.StringValue();
else
return null;
}
/// Returns an Enumeration of all the fields in a document.
public System.Collections.IEnumerable Fields()
{
return (System.Collections.IEnumerable) fields;
}
/// Returns an array of {@link Field}s with the given name.
/// This method can return null
.
///
///
/// the name of the Field
///
/// a Field[]
array
///
public Field[] GetFields(System.String name)
{
System.Collections.ArrayList result = new System.Collections.ArrayList();
for (int i = 0; i < fields.Count; i++)
{
Field field = (Field) fields[i];
if (field.Name().Equals(name))
{
result.Add(field);
}
}
if (result.Count == 0)
return null;
return (Field[]) result.ToArray(typeof(Field));
}
/// Returns an array of values of the Field specified as the method parameter.
/// This method can return null
.
///
///
/// the name of the Field
///
/// a String[]
of Field values
///
public System.String[] GetValues(System.String name)
{
Field[] namedFields = GetFields(name);
if (namedFields == null)
return null;
System.String[] values = new System.String[namedFields.Length];
for (int i = 0; i < namedFields.Length; i++)
{
values[i] = namedFields[i].StringValue();
}
return values;
}
/// Prints the fields of a document for human consumption.
public override System.String ToString()
{
System.Text.StringBuilder buffer = new System.Text.StringBuilder();
buffer.Append("Document<");
for (int i = 0; i < fields.Count; i++)
{
Field field = (Field) fields[i];
buffer.Append(field.ToString());
if (i != fields.Count - 1)
buffer.Append(" ");
}
buffer.Append(">");
return buffer.ToString();
}
}
}