apache-ignite

1
// Licensed to the Apache Software Foundation (ASF) under one or more
2
// contributor license agreements.  See the NOTICE file distributed with
3
// this work for additional information regarding copyright ownership.
4
// The ASF licenses this file to You under the Apache License, Version 2.0
5
// (the "License"); you may not use this file except in compliance with
6
// the License.  You may obtain a copy of the License at
7
//
8
// http://www.apache.org/licenses/LICENSE-2.0
9
//
10
// Unless required by applicable law or agreed to in writing, software
11
// distributed under the License is distributed on an "AS IS" BASIS,
12
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
// See the License for the specific language governing permissions and
14
// limitations under the License.
15
= Cache Configuration
16

17
== Operation Codes
18

19
Upon successful handshake with an Ignite server node, a client can start performing various cahe configuration operations by sending a request (see request/response structure below) with a specific operation code:
20

21

22
[cols="2,1",opts="header"]
23
|===
24
| Operation | OP_CODE
25
|OP_CACHE_GET_NAMES|  1050
26
|OP_CACHE_CREATE_WITH_NAME|   1051
27
|OP_CACHE_GET_OR_CREATE_WITH_NAME|    1052
28
|OP_CACHE_CREATE_WITH_CONFIGURATION|  1053
29
|OP_CACHE_GET_OR_CREATE_WITH_CONFIGURATION|   1054
30
|OP_CACHE_GET_CONFIGURATION|  1055
31
|OP_CACHE_DESTROY|    1056
32
|OP_QUERY_SCAN|   2000
33
|OP_QUERY_SCAN_CURSOR_GET_PAGE|   2001
34
|OP_QUERY_SQL|    2002
35
|OP_QUERY_SQL_CURSOR_GET_PAGE|    2003
36
|OP_QUERY_SQL_FIELDS| 2004
37
|OP_QUERY_SQL_FIELDS_CURSOR_GET_PAGE| 2005
38
|OP_BINARY_TYPE_NAME_GET| 3000
39
|OP_BINARY_TYPE_NAME_PUT| 3001
40
|OP_BINARY_TYPE_GET|  3002
41
|OP_BINARY_TYPE_PUT|  3003
42
|===
43

44
Note that the above mentioned op_codes are part of the request header, as explained link:binary-client-protocol/binary-client-protocol#standard-message-header[here].
45

46
[NOTE]
47
====
48
[discrete]
49
=== Customs Methods Used in Sample Code Snippets Implementation
50

51
Some of the code snippets below use `readDataObject(...)` introduced in link:binary-client-protocol/binary-client-protocol#data-objects[this section] and little-endian versions of methods for reading and writing multiple-byte values that are covered in link:binary-client-protocol/binary-client-protocol#data-objects[this example].
52
====
53

54

55
== OP_CACHE_CREATE_WITH_NAME
56

57
Creates a cache with a given name. Cache template can be applied if there is '{asterisk}' in the cache name. Throws exception if a cache with specified name already exists.
58

59

60
[cols="1,2",opts="header"]
61
|===
62
|Request Type  |  Description
63
|Header|  Request header.
64
|String|  Cache name.
65
|===
66

67

68
[cols="1,2",opts="header"]
69
|===
70
|Response Type |   Description
71
|Header|  Response header.
72
|===
73

74
[tabs]
75
--
76
tab:Request[]
77

78
[source, java]
79
----
80
DataOutputStream out = new DataOutputStream(socket.getOutputStream());
81

82
String cacheName = "myNewCache";
83

84
int nameLength = cacheName.getBytes("UTF-8").length;
85

86
DataOutputStream out = new DataOutputStream(socket.getOutputStream());
87

88
// Request header
89
writeRequestHeader(5 + nameLength, OP_CACHE_CREATE_WITH_NAME, 1, out);
90

91
// Cache name
92
writeString(cacheName, out);
93

94
// Send request
95
out.flush();
96
----
97
tab:Response[]
98

99
[source, java]
100
----
101
// Read result
102
DataInputStream in = new DataInputStream(socket.getInputStream());
103

104
readResponseHeader(in);
105

106
----
107
--
108

109

110

111
== OP_CACHE_GET_OR_CREATE_WITH_NAME
112

113
Creates a cache with a given name. Cache template can be applied if there is '{asterisk}' in the cache name. Does nothing if the cache exists.
114

115
[cols="1,2",opts="header"]
116
|===
117
|Request Type |    Description
118
|Header|  Request header.
119
|String|  Cache name.
120
|===
121

122

123
[cols="1,2",opts="header"]
124
|===
125
|Response Type |   Description
126
|Header|  Response header.
127
|===
128

129
[tabs]
130
--
131
tab:Request[]
132

133
[source, java]
134
----
135
DataOutputStream out = new DataOutputStream(socket.getOutputStream());
136

137
String cacheName = "myNewCache";
138

139
int nameLength = cacheName.getBytes("UTF-8").length;
140

141
DataOutputStream out = new DataOutputStream(socket.getOutputStream());
142

143
// Request header
144
writeRequestHeader(5 + nameLength, OP_CACHE_GET_OR_CREATE_WITH_NAME, 1, out);
145

146
// Cache name
147
writeString(cacheName, out);
148

149
// Send request
150
out.flush();
151
----
152
tab:Response[]
153

154
[source, java]
155
----
156
// Read result
157
DataInputStream in = new DataInputStream(socket.getInputStream());
158

159
readResponseHeader(in);
160

161
----
162
--
163

164

165
== OP_CACHE_GET_NAMES
166

167
Gets existing cache names.
168

169
[cols="1,2",opts="header"]
170
|===
171
|Request Type |    Description
172
|Header|  Request header.
173
|===
174

175

176
[cols="1,2",opts="header"]
177
|===
178
|Response Type |   Description
179
|Header|  Response header.
180
|int| Cache count.
181
|String|  Cache name.
182

183
Repeat for as many times as the cache count that is obtained in the previous parameter.
184
|===
185

186

187
[tabs]
188
--
189
tab:Request[]
190

191
[source, java]
192
----
193
DataOutputStream out = new DataOutputStream(socket.getOutputStream());
194

195
// Request header
196
writeRequestHeader(5, OP_CACHE_GET_NAMES, 1, out);
197
----
198
tab:Response[]
199

200
[source, java]
201
----
202
// Read result
203
DataInputStream in = new DataInputStream(socket.getInputStream());
204

205
readResponseHeader(in);
206

207
// Cache count
208
int cacheCount = readIntLittleEndian(in);
209

210
// Cache names
211
for (int i = 0; i < cacheCount; i++) {
212
  int type = readByteLittleEndian(in); // type code
213

214
  int strLen = readIntLittleEndian(in); // length
215

216
  byte[] buf = new byte[strLen];
217

218
  readFully(in, buf, 0, strLen);
219

220
  String s = new String(buf); // cache name
221

222
  System.out.println(s);
223
}
224

225
----
226
--
227

228

229
== OP_CACHE_GET_CONFIGURATION
230

231
Gets configuration for the given cache.
232

233
[cols="1,2",opts="header"]
234
|===
235
|Request Type |    Description
236
|Header|  Request header.
237
|int| Cache ID: Java-style hash code of the cache name.
238
|byte|    Flag.
239
|===
240

241

242
[cols="1,2",opts="header"]
243
|===
244
|Response Type |   Description
245
|Header|  Response header.
246
|int| Length of the configuration in bytes (all the configuration parameters).
247
|CacheConfiguration|  Structure of Cache configuration (See below).
248
|===
249

250

251
Cache Configuration
252

253
[cols="1,2",opts="header"]
254
|===
255
|Type |    Description
256
|int| Number of backups.
257
|int| CacheMode:
258

259
LOCAL = 0
260

261
REPLICATED = 1
262

263
PARTITIONED = 2
264

265
|bool|    CopyOnRead
266
|String|  DataRegionName
267
|bool|    EagerTTL
268
|bool|    StatisticsEnabled
269
|String|  GroupName
270
|bool|    Invalidate
271
|long|    DefaultLockTimeout (milliseconds)
272
|int| MaxQueryIterators
273
|String|  Name
274
|bool|    IsOnheapCacheEnabled
275
|int| PartitionLossPolicy:
276

277
READ_ONLY_SAFE = 0
278

279
READ_ONLY_ALL = 1
280

281
READ_WRITE_SAFE = 2
282

283
READ_WRITE_ALL = 3
284

285
IGNORE = 4
286

287
|int| QueryDetailMetricsSize
288
|int| QueryParellelism
289
|bool|    ReadFromBackup
290
|int| RebalanceBatchSize
291
|long|    RebalanceBatchesPrefetchCount
292
|long|    RebalanceDelay (milliseconds)
293
|int| RebalanceMode:
294

295
SYNC = 0
296

297
ASYNC = 1
298

299
NONE = 2
300

301
|int| RebalanceOrder
302
|long|    RebalanceThrottle (milliseconds)
303
|long|    RebalanceTimeout (milliseconds)
304
|bool|    SqlEscapeAll
305
|int| SqlIndexInlineMaxSize
306
|String|  SqlSchema
307
|int| WriteSynchronizationMode:
308

309
FULL_SYNC = 0
310

311
FULL_ASYNC = 1
312

313
PRIMARY_SYNC = 2
314

315
|int| CacheKeyConfiguration count.
316
|CacheKeyConfiguration|   Structure of CacheKeyConfiguration:
317

318
`String` Type name
319

320
`String` Affinity key field name
321

322
Repeat for as many times as the CacheKeyConfiguration count that is obtained in the previous parameter.
323
int QueryEntity count.
324
|QueryEntity * count| Structure of QueryEntity (see below).
325
|===
326

327

328
QueryEntity
329

330
[cols="1,2",opts="header"]
331
|===
332
|Type |    Description
333
|String|  Key type name.
334
|String|  Value type name.
335
|String|  Table name.
336
|String|  Key field name.
337
|String|  Value field name.
338
|int| QueryField count
339
|QueryField * count|  Structure of QueryField:
340

341
`String` Name
342

343
`String` Type name
344

345
`bool` Is key field
346

347
`bool` Is notNull constraint field
348

349
Repeat for as many times as the QueryField count that is obtained in the previous parameter.
350
|int| Alias count
351
|(String + String) * count|   Field name aliases.
352
|int| QueryIndex count
353
|QueryIndex * count | Structure of QueryIndex:
354

355
`String`  Index name
356

357
`byte`    Index type:
358

359
SORTED = 0
360

361
FULLTEXT = 1
362

363
GEOSPATIAL = 2
364

365
`int` Inline size
366

367
`int` Field count
368

369
`(string + bool) * count`  Fields (name + IsDescensing)
370

371
|===
372

373
[tabs]
374
--
375
tab:Request[]
376

377
[source, java]
378
----
379
String cacheName = "myCache";
380

381
DataOutputStream out = new DataOutputStream(socket.getOutputStream());
382

383
// Request header
384
writeRequestHeader(5, OP_CACHE_GET_CONFIGURATION, 1, out);
385

386
// Cache id
387
writeIntLittleEndian(cacheName.hashCode(), out);
388

389
// Flags = none
390
writeByteLittleEndian(0, out);
391
----
392
tab:Response[]
393

394
[source, java]
395
----
396
// Read result
397
DataInputStream in = new DataInputStream(socket.getInputStream());
398

399
readResponseHeader(in);
400

401
// Config length
402
int configLen = readIntLittleEndian(in);
403

404
// CacheAtomicityMode
405
int cacheAtomicityMode = readIntLittleEndian(in);
406

407
// Backups
408
int backups = readIntLittleEndian(in);
409

410
// CacheMode
411
int cacheMode = readIntLittleEndian(in);
412

413
// CopyOnRead
414
boolean copyOnRead = readBooleanLittleEndian(in);
415

416
// Other configurations
417

418
----
419
--
420

421

422
== OP_CACHE_CREATE_WITH_CONFIGURATION
423

424
Creates cache with provided configuration. An exception is thrown if the name is already in use.
425

426
[cols="1,2",opts="header"]
427
|===
428
|Request Type |    Description
429
|Header|  Request header.
430
|int| Length of the configuration in bytes (all the used configuration parameters).
431
|short|   Number of configuration parameters.
432
|short + property type |   Configuration Property data.
433

434
Repeat for as many times as the number of configuration parameters.
435
|===
436

437

438
Any number of configuration parameters can be provided. Note that `Name` is required.
439

440
Cache configuration data is specified in key-value form, where key is the `short` property id and value is property-specific data. Table below describes all available parameters.
441

442

443
[cols="1,1,3",opts="header"]
444
|===
445
|Property Code |   Property Type|   Description
446
|2|   int| CacheAtomicityMode:
447

448
TRANSACTIONAL = 0,
449

450
ATOMIC = 1
451
|3|   int| Backups
452
|1|   int| CacheMode:
453
LOCAL = 0, REPLICATED = 1, PARTITIONED = 2
454
|5|   boolean| CopyOnRead
455
|100| String|  DataRegionName
456
|405| boolean| EagerTtl
457
|406| boolean| StatisticsEnabled
458
|400| String|  GroupName
459
|402| long|    DefaultLockTimeout (milliseconds)
460
|403| int| MaxConcurrentAsyncOperations
461
|206| int| MaxQueryIterators
462
|0|   String|  Name
463
|101| bool|    IsOnheapcacheEnabled
464
|404| int| PartitionLossPolicy:
465

466
READ_ONLY_SAFE = 0,
467

468
 READ_ONLY_ALL = 1,
469

470
 READ_WRITE_SAFE = 2,
471

472
 READ_WRITE_ALL = 3,
473

474
 IGNORE = 4
475
|202| int| QueryDetailMetricsSize
476
|201| int| QueryParallelism
477
|6|   bool|    ReadFromBackup
478
|303| int| RebalanceBatchSize
479
|304| long|    RebalanceBatchesPrefetchCount
480
|301| long|    RebalanceDelay (milliseconds)
481
|300| int| RebalanceMode: SYNC = 0, ASYNC = 1, NONE = 2
482
|305| int| RebalanceOrder
483
|306| long|    RebalanceThrottle (milliseconds)
484
|302| long|    RebalanceTimeout (milliseconds)
485
|205| bool|    SqlEscapeAll
486
|204| int| SqlIndexInlineMaxSize
487
|203| String|  SqlSchema
488
|4|   int| WriteSynchronizationMode:
489

490
FULL_SYNC = 0,
491

492
 FULL_ASYNC = 1,
493

494
PRIMARY_SYNC = 2
495
|401| int + CacheKeyConfiguration * count| CacheKeyConfiguration count + CacheKeyConfiguration
496

497
Structure of CacheKeyConfiguration:
498

499
`String` Type name
500

501
`String` Affinity key field name
502
|200 | int + QueryEntity * count |  QueryEntity count + QueryEntity
503

504
Structure of QueryEntity: (see below)
505
|===
506

507

508

509
QueryEntity
510

511
[cols="1,2",opts="header"]
512
|===
513
|Type |    Description
514
|String|  Key type name.
515
|String|  Value type name.
516
|String|  Table name.
517
|String|  Key field name.
518
|String|  Value field name.
519
|int| QueryField count
520
|QueryField|  Structure of QueryField:
521

522
`String` Name
523

524
`String` Type name
525

526
`bool` Is key field
527

528
`bool` Is notNull constraint field
529

530
Repeat for as many times as the QueryField count.
531
|int| Alias count
532
|String + String| Field name alias.
533

534
Repeat for as many times as the alias count.
535
|int| QueryIndex count
536
|QueryIndex|  Structure of QueryIndex:
537

538
`String`  Index name
539

540
`byte`    Index type:
541

542
SORTED = 0
543

544
FULLTEXT = 1
545

546
GEOSPATIAL = 2
547

548
`int` Inline size
549

550
`int` Field count
551

552
`string + bool` Fields (name + IsDescensing)
553

554
Repeat for as many times as the field count that is passed in the previous parameter.
555

556
Repeat for as many times as the QueryIndex count.
557
|===
558

559

560
[cols="1,2",opts="header"]
561
|===
562
|Response Type |   Description
563
|Header|  Response header.
564
|===
565

566
[tabs]
567
--
568
tab:Request[]
569

570
[source, java]
571
----
572
DataOutputStream out = new DataOutputStream(socket.getOutputStream());
573

574
// Request header
575
writeRequestHeader(30, OP_CACHE_CREATE_WITH_CONFIGURATION, 1, out);
576

577
// Config length in bytes
578
writeIntLittleEndian(16, out);
579

580
// Number of properties
581
writeShortLittleEndian(2, out);
582

583
// Backups opcode
584
writeShortLittleEndian(3, out);
585
// Backups: 2
586
writeIntLittleEndian(2, out);
587

588
// Name opcode
589
writeShortLittleEndian(0, out);
590
// Name
591
writeString("myNewCache", out);
592
----
593
tab:Response[]
594

595
[source, java]
596
----
597
// Read result
598
DataInputStream in = new DataInputStream(socket.getInputStream());
599

600
// Response header
601
readResponseHeader(in);
602

603
----
604
--
605

606

607
== OP_CACHE_GET_OR_CREATE_WITH_CONFIGURATION
608

609
Creates cache with provided configuration. Does nothing if the name is already in use.
610

611
[cols="1,2",opts="header"]
612
|===
613
|Request Type |    Description
614
|Header|  Request header.
615
|CacheConfiguration|  Cache configuration (see format above).
616
|===
617

618

619
[cols="1,2",opts="header"]
620
|===
621
|Response Type |   Description
622
|Header|  Response header.
623
|===
624

625
[tabs]
626
--
627
tab:Request[]
628

629
[source, java]
630
----
631
DataOutputStream out = new DataOutputStream(socket.getOutputStream());
632

633
writeRequestHeader(30, OP_CACHE_GET_OR_CREATE_WITH_CONFIGURATION, 1, out);
634

635
// Config length in bytes
636
writeIntLittleEndian(16, out);
637

638
// Number of properties
639
writeShortLittleEndian(2, out);
640

641
// Backups opcode
642
writeShortLittleEndian(3, out);
643

644
// Backups: 2
645
writeIntLittleEndian(2, out);
646

647
// Name opcode
648
writeShortLittleEndian(0, out);
649

650
// Name
651
writeString("myNewCache", out);
652
----
653
tab:Response[]
654

655
[source, java]
656
----
657
// Read result
658
DataInputStream in = new DataInputStream(socket.getInputStream());
659

660
// Response header
661
readResponseHeader(in);
662

663
----
664
--
665

666

667
== OP_CACHE_DESTROY
668

669
Destroys the cache with a given name.
670

671
[cols="1,2",opts="header"]
672
|===
673
|Request Type |    Description
674
|Header|  Request header.
675
|int| Cache ID: Java-style hash code of the cache name.
676
|===
677

678

679
[cols="1,2",opts="header"]
680
|===
681
|Response Type |   Description
682
|Header|  Response header.
683
|===
684

685
[tabs]
686
--
687
tab:Request[]
688

689
[source, java]
690
----
691
String cacheName = "myCache";
692

693
DataOutputStream out = new DataOutputStream(socket.getOutputStream());
694

695
// Request header
696
writeRequestHeader(4, OP_CACHE_DESTROY, 1, out);
697

698
// Cache id
699
writeIntLittleEndian(cacheName.hashCode(), out);
700

701
// Send request
702
out.flush();
703
----
704
tab:Response[]
705

706
[source, java]
707
----
708
// Read result
709
DataInputStream in = new DataInputStream(socket.getInputStream());
710

711
readResponseHeader(in);
712
----
713
--
714

715