/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You 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 TokenStream = Lucene.Net.Analysis.TokenStream;
using FieldInvertState = Lucene.Net.Index.FieldInvertState;
namespace Lucene.Net.Documents
{
/// Synonymous with {@link Field}.
///
/// WARNING: This interface may change within minor versions, despite Lucene's backward compatibility requirements.
/// This means new methods may be added from version to version. This change only affects the Fieldable API; other backwards
/// compatibility promises remain intact. For example, Lucene can still
/// read and write indices created within the same major version.
///
///
///
///
public interface Fieldable
{
/// Sets the boost factor hits on this field. This value will be
/// multiplied into the score of all hits on this this field of this
/// document.
///
/// The boost is multiplied by {@link Lucene.Net.Documents.Document#GetBoost()} of the document
/// containing this field. If a document has multiple fields with the same
/// name, all such values are multiplied together. This product is then
/// used to compute the norm factor for the field. By
/// default, in the {@link
/// Lucene.Net.Search.Similarity#ComputeNorm(String,
/// FieldInvertState)} method, the boost value is multiplied
/// by the {@link
/// Lucene.Net.Search.Similarity#LengthNorm(String,
/// int)} and then rounded by {@link Lucene.Net.Search.Similarity#EncodeNorm(float)} before it is stored in the
/// index. One should attempt to ensure that this product does not overflow
/// the range of that encoding.
///
///
///
///
///
///
///
///
void SetBoost(float boost);
/// Returns the boost factor for hits for this field.
///
/// The default value is 1.0.
///
/// Note: this value is not stored directly with the document in the index.
/// Documents returned from {@link Lucene.Net.Index.IndexReader#Document(int)} and
/// {@link Lucene.Net.Search.Hits#Doc(int)} may thus not have the same value present as when
/// this field was indexed.
///
///
///
///
float GetBoost();
/// Returns the name of the field as an interned string.
/// For example "date", "title", "body", ...
///
System.String Name();
/// The value of the field as a String, or null.
///
/// For indexing, if isStored()==true, the stringValue() will be used as the stored field value
/// unless isBinary()==true, in which case binaryValue() will be used.
///
/// If isIndexed()==true and isTokenized()==false, this String value will be indexed as a single token.
/// If isIndexed()==true and isTokenized()==true, then tokenStreamValue() will be used to generate indexed tokens if not null,
/// else readerValue() will be used to generate indexed tokens if not null, else stringValue() will be used to generate tokens.
///
System.String StringValue();
/// The value of the field as a Reader, which can be used at index time to generate indexed tokens.
///
///
System.IO.TextReader ReaderValue();
/// The value of the field in Binary, or null.
///
///
byte[] BinaryValue();
/// The TokenStream for this field to be used when indexing, or null.
///
///
TokenStream TokenStreamValue();
/// True if the value of the field is to be stored in the index for return
/// with search hits.
///
bool IsStored();
/// True if the value of the field is to be indexed, so that it may be
/// searched on.
///
bool IsIndexed();
/// True if the value of the field should be tokenized as text prior to
/// indexing. Un-tokenized fields are indexed as a single word and may not be
/// Reader-valued.
///
bool IsTokenized();
/// True if the value of the field is stored and compressed within the index
bool IsCompressed();
/// True if the term or terms used to index this field are stored as a term
/// vector, available from {@link Lucene.Net.Index.IndexReader#GetTermFreqVector(int,String)}.
/// These methods do not provide access to the original content of the field,
/// only to terms used to index it. If the original content must be
/// preserved, use the stored
attribute instead.
///
///
///
///
bool IsTermVectorStored();
/// True if terms are stored as term vector together with their offsets
/// (start and end positon in source text).
///
bool IsStoreOffsetWithTermVector();
/// True if terms are stored as term vector together with their token positions.
bool IsStorePositionWithTermVector();
/// True if the value of the field is stored as binary
bool IsBinary();
/// True if norms are omitted for this indexed field
bool GetOmitNorms();
/// Expert:
///
/// If set, omit normalization factors associated with this indexed field.
/// This effectively disables indexing boosts and length normalization for this field.
///
void SetOmitNorms(bool omitNorms);
/// Renamed to {@link AbstractField#setOmitTermFreqAndPositions}
///
[Obsolete("Renamed to AbstractField.SetOmitTermFreqAndPositions")]
void SetOmitTf(bool omitTf);
/// Renamed to {@link AbstractField#getOmitTermFreqAndPositions}
///
[Obsolete("Renamed to AbstractField.GetOmitTermFreqAndPositions")]
bool GetOmitTf();
/// Indicates whether a Field is Lazy or not. The semantics of Lazy loading are such that if a Field is lazily loaded, retrieving
/// it's values via {@link #StringValue()} or {@link #BinaryValue()} is only valid as long as the {@link Lucene.Net.Index.IndexReader} that
/// retrieved the {@link Document} is still open.
///
///
/// true if this field can be loaded lazily
///
bool IsLazy();
/// Returns offset into byte[] segment that is used as value, if Field is not binary
/// returned value is undefined
///
/// index of the first character in byte[] segment that represents this Field value
///
int GetBinaryOffset();
/// Returns length of byte[] segment that is used as value, if Field is not binary
/// returned value is undefined
///
/// length of byte[] segment that represents this Field value
///
int GetBinaryLength();
/// Return the raw byte[] for the binary field. Note that
/// you must also call {@link #getBinaryLength} and {@link
/// #getBinaryOffset} to know which range of bytes in this
/// returned array belong to the field.
///
/// reference to the Field value as byte[].
///
byte[] GetBinaryValue();
/// Return the raw byte[] for the binary field. Note that
/// you must also call {@link #getBinaryLength} and {@link
/// #getBinaryOffset} to know which range of bytes in this
/// returned array belong to the field.
/// About reuse: if you pass in the result byte[] and it is
/// used, likely the underlying implementation will hold
/// onto this byte[] and return it in future calls to
/// {@link #BinaryValue()} or {@link #GetBinaryValue()}.
/// So if you subsequently re-use the same byte[] elsewhere
/// it will alter this Fieldable's value.
///
/// User defined buffer that will be used if
/// possible. If this is null or not large enough, a new
/// buffer is allocated
///
/// reference to the Field value as byte[].
///
byte[] GetBinaryValue(byte[] result);
}
}