lucene-java-3.5.0/lucene/src/java/org/apache/lucene/index/Payload.java

   1 package org.apache.lucene.index;
   2
   3 /**
   4  * Licensed to the Apache Software Foundation (ASF) under one or more
   5  * contributor license agreements.  See the NOTICE file distributed with
   6  * this work for additional information regarding copyright ownership.
   7  * The ASF licenses this file to You under the Apache License, Version 2.0
   8  * (the "License"); you may not use this file except in compliance with
   9  * the License.  You may obtain a copy of the License at
  10  *
  11  *     http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  */
  19
  20 import java.io.Serializable;
  21
  22 import org.apache.lucene.analysis.TokenStream;
  23 import org.apache.lucene.util.ArrayUtil;
  24
  25 /**
  26  *  A Payload is metadata that can be stored together with each occurrence
  27  *  of a term. This metadata is stored inline in the posting list of the
  28  *  specific term.
  29  *  <p>
  30  *  To store payloads in the index a {@link TokenStream} has to be used that
  31  *  produces payload data.
  32  *  <p>
  33  *  Use {@link TermPositions#getPayloadLength()} and {@link TermPositions#getPayload(byte[], int)}
  34  *  to retrieve the payloads from the index.<br>
  35  *
  36  */
  37 public class Payload implements Serializable, Cloneable {
  38   /** the byte array containing the payload data */
  39   protected byte[] data;
  40
  41   /** the offset within the byte array */
  42   protected int offset;
  43
  44   /** the length of the payload data */
  45   protected int length;
  46
  47   /** Creates an empty payload and does not allocate a byte array. */
  48   public Payload() {
  49     // nothing to do
  50   }
  51
  52   /**
  53    * Creates a new payload with the the given array as data.
  54    * A reference to the passed-in array is held, i. e. no
  55    * copy is made.
  56    *
  57    * @param data the data of this payload
  58    */
  59   public Payload(byte[] data) {
  60     this(data, 0, data.length);
  61   }
  62
  63   /**
  64    * Creates a new payload with the the given array as data.
  65    * A reference to the passed-in array is held, i. e. no
  66    * copy is made.
  67    *
  68    * @param data the data of this payload
  69    * @param offset the offset in the data byte array
  70    * @param length the length of the data
  71    */
  72   public Payload(byte[] data, int offset, int length) {
  73     if (offset < 0 || offset + length > data.length) {
  74       throw new IllegalArgumentException();
  75     }
  76     this.data = data;
  77     this.offset = offset;
  78     this.length = length;
  79   }
  80
  81   /**
  82    * Sets this payloads data.
  83    * A reference to the passed-in array is held, i. e. no
  84    * copy is made.
  85    */
  86   public void setData(byte[] data) {
  87     setData(data, 0, data.length);
  88   }
  89
  90   /**
  91    * Sets this payloads data.
  92    * A reference to the passed-in array is held, i. e. no
  93    * copy is made.
  94    */
  95   public void setData(byte[] data, int offset, int length) {
  96     this.data = data;
  97     this.offset = offset;
  98     this.length = length;
  99   }
 100
 101   /**
 102    * Returns a reference to the underlying byte array
 103    * that holds this payloads data.
 104    */
 105   public byte[] getData() {
 106     return this.data;
 107   }
 108
 109   /**
 110    * Returns the offset in the underlying byte array
 111    */
 112   public int getOffset() {
 113     return this.offset;
 114   }
 115
 116   /**
 117    * Returns the length of the payload data.
 118    */
 119   public int length() {
 120     return this.length;
 121   }
 122
 123   /**
 124    * Returns the byte at the given index.
 125    */
 126   public byte byteAt(int index) {
 127     if (0 <= index && index < this.length) {
 128       return this.data[this.offset + index];
 129     }
 130     throw new ArrayIndexOutOfBoundsException(index);
 131   }
 132
 133   /**
 134    * Allocates a new byte array, copies the payload data into it and returns it.
 135    */
 136   public byte[] toByteArray() {
 137     byte[] retArray = new byte[this.length];
 138     System.arraycopy(this.data, this.offset, retArray, 0, this.length);
 139     return retArray;
 140   }
 141
 142   /**
 143    * Copies the payload data to a byte array.
 144    *
 145    * @param target the target byte array
 146    * @param targetOffset the offset in the target byte array
 147    */
 148   public void copyTo(byte[] target, int targetOffset) {
 149     if (this.length > target.length + targetOffset) {
 150       throw new ArrayIndexOutOfBoundsException();
 151     }
 152     System.arraycopy(this.data, this.offset, target, targetOffset, this.length);
 153   }
 154
 155   /**
 156    * Clones this payload by creating a copy of the underlying
 157    * byte array.
 158    */
 159   @Override
 160   public Object clone() {
 161     try {
 162       // Start with a shallow copy of data
 163       Payload clone = (Payload) super.clone();
 164       // Only copy the part of data that belongs to this Payload
 165       if (offset == 0 && length == data.length) {
 166         // It is the whole thing, so just clone it.
 167         clone.data = data.clone();
 168       }
 169       else {
 170         // Just get the part
 171         clone.data = this.toByteArray();
 172         clone.offset = 0;
 173       }
 174       return clone;
 175     } catch (CloneNotSupportedException e) {
 176       throw new RuntimeException(e);  // shouldn't happen
 177     }
 178   }
 179
 180   @Override
 181   public boolean equals(Object obj) {
 182     if (obj == this)
 183       return true;
 184     if (obj instanceof Payload) {
 185       Payload other = (Payload) obj;
 186       if (length == other.length) {
 187         for(int i=0;i<length;i++)
 188           if (data[offset+i] != other.data[other.offset+i])
 189             return false;
 190         return true;
 191       } else
 192         return false;
 193     } else
 194       return false;
 195   }
 196
 197   @Override
 198   public int hashCode() {
 199     return ArrayUtil.hashCode(data, offset, offset+length);
 200   }
 201 }