core/Index/Payload.cs

/*
 * 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 ArrayUtil = Lucene.Net.Util.ArrayUtil;

namespace Lucene.Net.Index
{

	/// <summary>  A Payload is metadata that can be stored together with each occurrence
	/// of a term. This metadata is stored inline in the posting list of the
	/// specific term.
	/// <p/>
	/// To store payloads in the index a <see cref="TokenStream"/> has to be used that
	/// produces payload data.
	/// <p/>
    /// Use <see cref="TermPositions.PayloadLength"/> and <see cref="TermPositions.GetPayload(byte[], int)"/>
	/// to retrieve the payloads from the index.<br/>
	///
	/// </summary>
	[Serializable]
	public class Payload : System.ICloneable
	{
		/// <summary>the byte array containing the payload data </summary>
		protected internal byte[] data;

		/// <summary>the offset within the byte array </summary>
		protected internal int internalOffset;

		/// <summary>the length of the payload data </summary>
		protected internal int internalLength;

		/// <summary>Creates an empty payload and does not allocate a byte array. </summary>
		public Payload()
		{
			// nothing to do
		}

		/// <summary> Creates a new payload with the the given array as data.
		/// A reference to the passed-in array is held, i. e. no
		/// copy is made.
		///
		/// </summary>
		/// <param name="data">the data of this payload
		/// </param>
		public Payload(byte[] data):this(data, 0, data.Length)
		{
		}

		/// <summary> Creates a new payload with the the given array as data.
		/// A reference to the passed-in array is held, i. e. no
		/// copy is made.
		///
		/// </summary>
		/// <param name="data">the data of this payload
		/// </param>
		/// <param name="offset">the offset in the data byte array
		/// </param>
		/// <param name="length">the length of the data
		/// </param>
		public Payload(byte[] data, int offset, int length)
		{
			if (offset < 0 || offset + length > data.Length)
			{
				throw new System.ArgumentException();
			}
			this.data = data;
			this.internalOffset = offset;
			this.internalLength = length;
		}

	    /// <summary> Sets this payloads data.
		/// A reference to the passed-in array is held, i. e. no
		/// copy is made.
		/// </summary>
		public virtual void  SetData(byte[] value, int offset, int length)
		{
			this.data = value;
			this.internalOffset = offset;
			this.internalLength = length;
		}

	    /// <summary> Gets or sets a reference to the underlying byte array
	    /// that holds this payloads data.  Data is not copied.
	    /// </summary>
	    public virtual void SetData(byte[] value)
	    {
	        SetData(value, 0, value.Length);
	    }

	    /// <summary> Gets or sets a reference to the underlying byte array
	    /// that holds this payloads data.  Data is not copied.
	    /// </summary>
	    public virtual byte[] GetData()
	    {
	        return this.data;
	    }

	    /// <summary> Returns the offset in the underlying byte array </summary>
	    public virtual int Offset
	    {
	        get { return this.internalOffset; }
	    }

	    /// <summary> Returns the length of the payload data. </summary>
	    public virtual int Length
	    {
	        get { return this.internalLength; }
	    }

	    /// <summary> Returns the byte at the given index.</summary>
		public virtual byte ByteAt(int index)
		{
			if (0 <= index && index < this.internalLength)
			{
				return this.data[this.internalOffset + index];
			}
			throw new System. IndexOutOfRangeException("Index of bound " + index);
		}

		/// <summary> Allocates a new byte array, copies the payload data into it and returns it. </summary>
		public virtual byte[] ToByteArray()
		{
			byte[] retArray = new byte[this.internalLength];
			Array.Copy(this.data, this.internalOffset, retArray, 0, this.internalLength);
			return retArray;
		}

		/// <summary> Copies the payload data to a byte array.
		///
		/// </summary>
		/// <param name="target">the target byte array
		/// </param>
		/// <param name="targetOffset">the offset in the target byte array
		/// </param>
		public virtual void  CopyTo(byte[] target, int targetOffset)
		{
			if (this.internalLength > target.Length + targetOffset)
			{
				throw new System.IndexOutOfRangeException();
			}
			Array.Copy(this.data, this.internalOffset, target, targetOffset, this.internalLength);
		}

		/// <summary> Clones this payload by creating a copy of the underlying
		/// byte array.
		/// </summary>
		public virtual System.Object Clone()
		{
			try
			{
				// Start with a shallow copy of data
				Payload clone = (Payload) base.MemberwiseClone();
				// Only copy the part of data that belongs to this Payload
				if (internalOffset == 0 && internalLength == data.Length)
				{
					// It is the whole thing, so just clone it.
					clone.data = new byte[data.Length];
					data.CopyTo(clone.data, 0);
				}
				else
				{
					// Just get the part
					clone.data = this.ToByteArray();
					clone.internalOffset = 0;
				}
				return clone;
			}
			catch (System.Exception e)
			{
				throw new System.SystemException(e.Message, e); // shouldn't happen
			}
		}

		public  override bool Equals(System.Object obj)
		{
			if (obj == this)
				return true;
			if (obj is Payload)
			{
				Payload other = (Payload) obj;
				if (internalLength == other.internalLength)
				{
					for (int i = 0; i < internalLength; i++)
						if (data[internalOffset + i] != other.data[other.internalOffset + i])
							return false;
					return true;
				}
				else
					return false;
			}
			else
				return false;
		}

		public override int GetHashCode()
		{
			return ArrayUtil.HashCode(data, internalOffset, internalOffset + internalLength);
		}
	}
}