1 /*------------------------------------------------------------------------------
2 * Copyright (C) 2003-2006 Ben van Klinken and the CLucene Team
3 *
4 * Distributable under the terms of either the Apache License (Version 2.0) or
5 * the GNU Lesser General Public License, as specified in the COPYING file.
6 ------------------------------------------------------------------------------*/
7 #ifndef _lucene_index_Payload_
8 #define _lucene_index_Payload_
9
10 #include "CLucene/util/Array.h"
11
CL_NS_DEF(index)12 CL_NS_DEF(index)
13
14 /**
15 * A Payload is metadata that can be stored together with each occurrence
16 * of a term. This metadata is stored inline in the posting list of the
17 * specific term.
18 * <p>
19 * To store payloads in the index a {@link TokenStream} has to be used that
20 * produces {@link Token}s containing payload data.
21 * <p>
22 * Use {@link TermPositions#getPayloadLength()} and {@link TermPositions#getPayload(byte[], int)}
23 * to retrieve the payloads from the index.<br>
24 *
25 */
26 class CLUCENE_EXPORT Payload:LUCENE_REFBASE {
27 protected:
28 CL_NS(util)::ValueArray<uint8_t>& data;
29
30 /** the offset within the byte array */
31 int32_t offset;
32
33 /** the length of the payload data */
34 int32_t _length;
35
36 bool deleteData;
37 bool deleteArray;
38 public:
39
40 /** Creates an empty payload and does not allocate a byte array. */
41 Payload();
42
43 /**
44 * Creates a new payload with the the given array as data.
45 * A reference to the passed-in array is held, i. e. no
46 * copy is made.
47 *
48 * @param data the data of this payload
49 * @param length the length of the data
50 * @param deleteData delete data when payload is deleted
51 */
52 Payload(uint8_t* data, const int32_t length, bool deleteData=false);
53
54 /**
55 * Creates a new payload with the the given array as data.
56 * A reference to the passed-in array is held, i. e. no
57 * copy is made.
58 *
59 * @param data the data of this payload
60 * @param deleteData delete data when payload is deleted
61 */
62 Payload(CL_NS(util)::ValueArray<uint8_t>& data, const int32_t offset=0, const int32_t length=-1, bool deleteData=false);
63
64 /* Desctructor - auto-delete the data container */
65 ~Payload();
66
67 /**
68 * Sets this payloads data.
69 * A reference to the passed-in array is held, i. e. no
70 * copy is made.
71 * @param deleteData delete data when payload is deleted
72 */
73 void setData(uint8_t* data, const int32_t length, bool deleteData=false);
74
75 /**
76 * Sets this payloads data.
77 * A reference to the passed-in array is held, i. e. no
78 * copy is made.
79 * @param deleteData delete data when payload is deleted
80 */
81 void setData(CL_NS(util)::ValueArray<uint8_t>& data, const int32_t offset=0, const int32_t length=-1, bool deleteData=false);
82
83 /**
84 * Returns a reference to the underlying byte array
85 * that holds this payloads data.
86 */
87 const CL_NS(util)::ValueArray<uint8_t>& getData() const;
88
89 /**
90 * Returns the length of the payload data.
91 */
92 int32_t length() const;
93
94 /**
95 * Returns the offset in the underlying byte array
96 */
97 int32_t getOffset() const;
98
99 /**
100 * Returns the byte at the given index.
101 */
102 uint8_t byteAt(int index) const;
103
104 /**
105 * Allocates a new byte array, copies the payload data into it and returns it. Caller is responsible
106 * for deleting it later.
107 * @memory caller is responsible for deleting the returned array
108 */
109 CL_NS(util)::ValueArray<uint8_t>* toByteArray() const;
110
111 /**
112 * Copies the payload data to a byte array.
113 *
114 * @param target the target byte array
115 * @param targetOffset the offset in the target byte array
116 */
117 void copyTo(uint8_t* target, const int32_t targetLen) const;
118
119 /**
120 * Clones this payload by creating a copy of the underlying
121 * byte array.
122 */
123 Payload* clone() const;
124
125 };
126
127 CL_NS_END
128 #endif
129