1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
|
// Copyright Vespa.ai. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
package com.yahoo.slime;
/**
* Interface for read-write access to any value or object that is part
* of a Slime. All accessors (including meta-data) are inherited from
* the Inspector interface. The navigational methods also work the
* same, except that they return a new Cursor for contained values and
* sub-structures, to permit writes to embedded values.
*
* The write operations are adding a new entry (to arrays), or setting
* a field value (for objects). If adding an entry or setting a field
* cannot be performed for any reason, an invalid Cursor is returned.
*
* This could happen because the current cursor is invalid, or it's
* not connected to an array value (for add methods), or it's not
* connected to an object (for set methods). Also note that you can
* only set() a field once; you cannot overwrite the field in any way.
*
* @author havardpe
*/
public interface Cursor extends Inspector {
/**
* Accesses an array entry.
*
* If the current Cursor doesn't connect to an array value,
* or the given array index is out of bounds, the returned
* Cursor will be invalid.
*
* @param idx array index
* @return a new Cursor for the entry value
*/
@Override
Cursor entry(int idx);
/**
* Accesses a field in an object by symbol id.
*
* If the current Cursor doesn't connect to an object value, or
* the object value does not contain a field with the given symbol
* id, the returned Cursor will be invalid.
*
* @param sym symbol id
* @return a new Cursor for the field value
*/
@Override
Cursor field(int sym);
/**
* Accesses a field in an object by symbol name.
*
* If the current Cursor doesn't connect to an object value, or
* the object value does not contain a field with the given symbol
* name, the returned Cursor will be invalid.
*
* @param name symbol name
* @return a new Cursor for the field value
*/
@Override
Cursor field(String name);
/**
* Appends an array entry containing a new value of NIX type.
* Returns an invalid Cursor if unsuccessful.
*
* @return a valid Cursor referencing the new entry value if successful
*/
Cursor addNix();
/**
* Appends an array entry containing a new value of BOOL type.
* Returns an invalid Cursor if unsuccessful.
*
* @param bit the actual boolean value for initializing a new BoolValue
* @return a valid Cursor referencing the new entry value if successful
*/
Cursor addBool(boolean bit);
/** Adds a new entry of LONG type to an array. */
Cursor addLong(long l);
/** Adds a new entry of DOUBLE type to an array. */
Cursor addDouble(double d);
/** Add a new entry of STRING type to an array. */
Cursor addString(String str);
/** Add a new entry of STRING type to an array. */
Cursor addString(byte[] utf8);
/** Add a new entry of DATA type to an array. */
Cursor addData(byte[] data);
/**
* Appends an array entry containing a new value of ARRAY type.
* Returns a valid Cursor (that may again be used for adding new
* sub-array entries) referencing the new entry value if
* successful; otherwise returns an invalid Cursor.
*
* @return a new Cursor for the new entry value
*/
Cursor addArray();
/**
* Appends an array entry containing a new value of OBJECT type.
* Returns a valid Cursor (that may again be used for setting
* sub-fields inside the new object) referencing the new entry
* value if successful; otherwise returns an invalid Cursor.
*
* @return a new Cursor for the new entry value
*/
Cursor addObject();
/**
* Sets a field (identified with a symbol id) to contain a new
* value of NIX type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param sym symbol id for the field to be set
* @return new Cursor for the new field value
*/
Cursor setNix(int sym);
/**
* Sets a field (identified with a symbol id) to contain a new
* value of BOOL type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param sym symbol id for the field to be set
* @param bit the actual boolean value for the new field
* @return new Cursor for the new field value
*/
Cursor setBool(int sym, boolean bit);
/**
* Sets a field (identified with a symbol id) to contain a new
* value of BOOL type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param sym symbol id for the field to be set
* @param l the actual long value for the new field
* @return new Cursor for the new field value
*/
Cursor setLong(int sym, long l);
/**
* Sets a field (identified with a symbol id) to contain a new
* value of BOOL type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param sym symbol id for the field to be set
* @param d the actual double value for the new field
* @return new Cursor for the new field value
*/
Cursor setDouble(int sym, double d);
/**
* Sets a field (identified with a symbol id) to contain a new
* value of BOOL type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param sym symbol id for the field to be set
* @param str the actual string for the new field
* @return a new Cursor for the new field value
*/
Cursor setString(int sym, String str);
/**
* Sets a field (identified with a symbol id) to contain a new
* value of BOOL type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param sym symbol id for the field to be set
* @param utf8 the actual string (encoded as UTF-8 data) for the new field
* @return a new Cursor for the new field value
*/
Cursor setString(int sym, byte[] utf8);
/**
* Sets a field (identified with a symbol id) to contain a new
* value of BOOL type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param sym symbol id for the field to be set
* @param data the actual data to be put into the new field
* @return a new Cursor for the new field value
*/
Cursor setData(int sym, byte[] data);
/**
* Sets a field (identified with a symbol id) to contain a new
* value of ARRAY type. Returns a valid Cursor (that may again be
* used for adding new array entries) referencing the new field
* value if successful; otherwise returns an invalid Cursor.
*
* @param sym symbol id for the field to be set
* @return a new Cursor for the new field value
*/
Cursor setArray(int sym);
/**
* Sets a field (identified with a symbol id) to contain a new
* value of OBJECT type. Returns a valid Cursor (that may again
* be used for setting sub-fields inside the new object)
* referencing the new field value if successful; otherwise
* returns an invalid Cursor.
*
* @param sym symbol id for the field to be set
* @return a new Cursor for the new field value
*/
Cursor setObject(int sym);
/**
* Sets a field (identified with a symbol name) to contain a new
* value of NIX type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param name symbol name for the field to be set
* @return a new Cursor for the new field value
*/
Cursor setNix(String name);
/**
* Sets a field (identified with a symbol name) to contain a new
* value of BOOL type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param name symbol name for the field to be set
* @param bit the actual boolean value for the new field
* @return a new Cursor for the new field value
*/
Cursor setBool(String name, boolean bit);
/**
* Sets a field (identified with a symbol name) to contain a new
* value of LONG type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param name symbol name for the field to be set
* @param l the actual long value for the new field
* @return a new Cursor for the new field value
*/
Cursor setLong(String name, long l);
/**
* Sets a field (identified with a symbol name) to contain a new
* value of DOUBLE type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param name symbol name for the field to be set
* @param d the actual double value for the new field
* @return a new Cursor for the new field value
*/
Cursor setDouble(String name, double d);
/**
* Sets a field (identified with a symbol name) to contain a new
* value of STRING type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param name symbol name for the field to be set
* @param str the actual string for the new field
* @return a new Cursor for the new field value
*/
Cursor setString(String name, String str);
/**
* Sets a field (identified with a symbol name) to contain a new
* value of STRING type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param name symbol name for the field to be set
* @param utf8 the actual string (encoded as UTF-8 data) for the new field
* @return a new Cursor for the new field value
*/
Cursor setString(String name, byte[] utf8);
/**
* Sets a field (identified with a symbol name) to contain a new
* value of DATA type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param name symbol name for the field to be set
* @param data the actual data to be put into the new field
* @return a new Cursor for the new field value
*/
Cursor setData(String name, byte[] data);
/**
* Sets a field (identified with a symbol name) to contain a new
* value of ARRAY type. Returns a valid Cursor (that may again be
* used for adding new array entries) referencing the new field
* value if successful; otherwise returns an invalid Cursor.
*
* @param name symbol name for the field to be set
* @return a new Cursor for the new field value
*/
Cursor setArray(String name);
/**
* Sets a field (identified with a symbol name) to contain a new
* value of OBJECT type. Returns a valid Cursor (that may again
* be used for setting sub-fields inside the new object)
* referencing the new field value if successful; otherwise
* returns an invalid Cursor.
*
* @param name symbol name for the field to be set
* @return a new Cursor for the new field value
*/
Cursor setObject(String name);
}
|
