001: package org.apache.lucene.index;
002:
003: /**
004: * Licensed to the Apache Software Foundation (ASF) under one or more
005: * contributor license agreements. See the NOTICE file distributed with
006: * this work for additional information regarding copyright ownership.
007: * The ASF licenses this file to You under the Apache License, Version 2.0
008: * (the "License"); you may not use this file except in compliance with
009: * the License. You may obtain a copy of the License at
010: *
011: * http://www.apache.org/licenses/LICENSE-2.0
012: *
013: * Unless required by applicable law or agreed to in writing, software
014: * distributed under the License is distributed on an "AS IS" BASIS,
015: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016: * See the License for the specific language governing permissions and
017: * limitations under the License.
018: */
019:
020: import java.io.Serializable;
021:
022: import org.apache.lucene.analysis.Token;
023: import org.apache.lucene.analysis.TokenStream;
024:
025: /**
026: * A Payload is metadata that can be stored together with each occurrence
027: * of a term. This metadata is stored inline in the posting list of the
028: * specific term.
029: * <p>
030: * To store payloads in the index a {@link TokenStream} has to be used that
031: * produces {@link Token}s containing payload data.
032: * <p>
033: * Use {@link TermPositions#getPayloadLength()} and {@link TermPositions#getPayload(byte[], int)}
034: * to retrieve the payloads from the index.<br>
035: *
036: */
037: public class Payload implements Serializable, Cloneable {
038: /** the byte array containing the payload data */
039: protected byte[] data;
040:
041: /** the offset within the byte array */
042: protected int offset;
043:
044: /** the length of the payload data */
045: protected int length;
046:
047: /** Creates an empty payload and does not allocate a byte array. */
048: public Payload() {
049: // nothing to do
050: }
051:
052: /**
053: * Creates a new payload with the the given array as data.
054: * A reference to the passed-in array is held, i. e. no
055: * copy is made.
056: *
057: * @param data the data of this payload
058: */
059: public Payload(byte[] data) {
060: this (data, 0, data.length);
061: }
062:
063: /**
064: * Creates a new payload with the the given array as data.
065: * A reference to the passed-in array is held, i. e. no
066: * copy is made.
067: *
068: * @param data the data of this payload
069: * @param offset the offset in the data byte array
070: * @param length the length of the data
071: */
072: public Payload(byte[] data, int offset, int length) {
073: if (offset < 0 || offset + length > data.length) {
074: throw new IllegalArgumentException();
075: }
076: this .data = data;
077: this .offset = offset;
078: this .length = length;
079: }
080:
081: /**
082: * Sets this payloads data.
083: * A reference to the passed-in array is held, i. e. no
084: * copy is made.
085: */
086: public void setData(byte[] data) {
087: setData(data, 0, data.length);
088: }
089:
090: /**
091: * Sets this payloads data.
092: * A reference to the passed-in array is held, i. e. no
093: * copy is made.
094: */
095: public void setData(byte[] data, int offset, int length) {
096: this .data = data;
097: this .offset = offset;
098: this .length = length;
099: }
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,
139: this .length);
140: return retArray;
141: }
142:
143: /**
144: * Copies the payload data to a byte array.
145: *
146: * @param target the target byte array
147: * @param targetOffset the offset in the target byte array
148: */
149: public void copyTo(byte[] target, int targetOffset) {
150: if (this .length > target.length + targetOffset) {
151: throw new ArrayIndexOutOfBoundsException();
152: }
153: System.arraycopy(this .data, this .offset, target, targetOffset,
154: this .length);
155: }
156:
157: /**
158: * Clones this payload by creating a copy of the underlying
159: * byte array.
160: */
161: public Object clone() {
162: Payload clone = new Payload(this.toByteArray());
163: return clone;
164: }
165: }
|