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
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
|
package org.bukkit.configuration;
import java.util.Map;
import java.util.Set;
import java.util.List;
import org.bukkit.OfflinePlayer;
import org.bukkit.util.Vector;
import org.bukkit.inventory.ItemStack;
/**
* Represents a section of a {@link Configuration}
*/
public interface ConfigurationSection {
/**
* Gets a set containing all keys in this section.
* <p>
* If deep is set to true, then this will contain all the keys within any child
* {@link ConfigurationSection}s (and their children, etc). These will be in a
* valid path notation for you to use.
* <p>
* If deep is set to false, then this will contain only the keys of any direct children,
* and not their own children.
*
* @param deep Whether or not to get a deep list, as opposed to a shallow list.
* @return Set of keys contained within this ConfigurationSection.
*/
public Set<String> getKeys(boolean deep);
/**
* Gets a Map containing all keys and their values for this section.
* <p>
* If deep is set to true, then this will contain all the keys and values within
* any child {@link ConfigurationSection}s (and their children, etc). These
* keys will be in a valid path notation for you to use.
* <p>
* If deep is set to false, then this will contain only the keys and values of any
* direct children, and not their own children.
*
* @param deep Whether or not to get a deep list, as opposed to a shallow list.
* @return Map of keys and values of this section.
*/
public Map<String, Object> getValues(boolean deep);
/**
* Checks if this {@link ConfigurationSection} contains the given path.
* <p>
* If the value for the requested path does not exist but a default value has
* been specified, this will return true.
*
* @param path Path to check for existence.
* @return True if this section contains the requested path, either via default or being set.
* @throws IllegalArgumentException Thrown when path is null.
*/
public boolean contains(String path);
/**
* Checks if this {@link ConfigurationSection} has a value set for the given path.
* <p>
* If the value for the requested path does not exist but a default value has
* been specified, this will still return false.
*
* @param path Path to check for existence.
* @return True if this section contains the requested path, regardless of having a default.
* @throws IllegalArgumentException Thrown when path is null.
*/
public boolean isSet(String path);
/**
* Gets the path of this {@link ConfigurationSection} from its root {@link Configuration}
* <p>
* For any {@link Configuration} themselves, this will return an empty string.
* <p>
* If the section is no longer contained within its root for any reason, such as
* being replaced with a different value, this may return null.
* <p>
* To retrieve the single name of this section, that is, the final part of the path
* returned by this method, you may use {@link #getName()}.
*
* @return Path of this section relative to its root
*/
public String getCurrentPath();
/**
* Gets the name of this individual {@link ConfigurationSection}, in the path.
* <p>
* This will always be the final part of {@link #getCurrentPath()}, unless the
* section is orphaned.
*
* @return Name of this section
*/
public String getName();
/**
* Gets the root {@link Configuration} that contains this {@link ConfigurationSection}
* <p>
* For any {@link Configuration} themselves, this will return its own object.
* <p>
* If the section is no longer contained within its root for any reason, such as
* being replaced with a different value, this may return null.
*
* @return Root configuration containing this section.
*/
public Configuration getRoot();
/**
* Gets the parent {@link ConfigurationSection} that directly contains this
* {@link ConfigurationSection}.
* <p>
* For any {@link Configuration} themselves, this will return null.
* <p>
* If the section is no longer contained within its parent for any reason, such as
* being replaced with a different value, this may return null.
*
* @return Parent section containing this section.
*/
public ConfigurationSection getParent();
/**
* Gets the requested Object by path.
* <p>
* If the Object does not exist but a default value has been specified, this
* will return the default value. If the Object does not exist and no default
* value was specified, this will return null.
*
* @param path Path of the Object to get.
* @return Requested Object.
*/
public Object get(String path);
/**
* Gets the requested Object by path, returning a default value if not found.
* <p>
* If the Object does not exist then the specified default value will returned
* regardless of if a default has been identified in the root {@link Configuration}.
*
* @param path Path of the Object to get.
* @return Requested Object.
*/
public Object get(String path, Object def);
/**
* Sets the specified path to the given value.
* <p>
* If value is null, the entry will be removed. Any existing entry will be
* replaced, regardless of what the new value is.
* <p>
* Some implementations may have limitations on what you may store. See their
* individual javadocs for details. No implementations should allow you to store
* {@link Configuration}s or {@link ConfigurationSection}s, please use
* {@link #createSection(java.lang.String)} for that.
*
* @param path Path of the object to set.
* @param value New value to set the path to.
*/
public void set(String path, Object value);
/**
* Creates an empty {@link ConfigurationSection} at the specified path.
* <p>
* Any value that was previously set at this path will be overwritten. If the
* previous value was itself a {@link ConfigurationSection}, it will be orphaned.
*
* @param path Path to create the section at.
* @return Newly created section
*/
public ConfigurationSection createSection(String path);
// Primitives
/**
* Gets the requested String by path.
* <p>
* If the String does not exist but a default value has been specified, this
* will return the default value. If the String does not exist and no default
* value was specified, this will return null.
*
* @param path Path of the String to get.
* @return Requested String.
*/
public String getString(String path);
/**
* Gets the requested String by path, returning a default value if not found.
* <p>
* If the String does not exist then the specified default value will returned
* regardless of if a default has been identified in the root {@link Configuration}.
*
* @param path Path of the String to get.
* @return Requested String.
*/
public String getString(String path, String def);
/**
* Checks if the specified path is a String.
* <p>
* If the path exists but is not a String, this will return false. If the path does not
* exist, this will return false. If the path does not exist but a default value
* has been specified, this will check if that default value is a String and return
* appropriately.
*
* @param path Path of the String to check.
* @return Whether or not the specified path is a String.
*/
public boolean isString(String path);
/**
* Gets the requested int by path.
* <p>
* If the int does not exist but a default value has been specified, this
* will return the default value. If the int does not exist and no default
* value was specified, this will return null.
*
* @param path Path of the int to get.
* @return Requested int.
*/
public int getInt(String path);
/**
* Gets the requested int by path, returning a default value if not found.
* <p>
* If the int does not exist then the specified default value will returned
* regardless of if a default has been identified in the root {@link Configuration}.
*
* @param path Path of the int to get.
* @return Requested int.
*/
public int getInt(String path, int def);
/**
* Checks if the specified path is an int.
* <p>
* If the path exists but is not a int, this will return false. If the path does not
* exist, this will return false. If the path does not exist but a default value
* has been specified, this will check if that default value is a int and return
* appropriately.
*
* @param path Path of the int to check.
* @return Whether or not the specified path is an int.
*/
public boolean isInt(String path);
/**
* Gets the requested boolean by path.
* <p>
* If the boolean does not exist but a default value has been specified, this
* will return the default value. If the boolean does not exist and no default
* value was specified, this will return false.
*
* @param path Path of the boolean to get.
* @return Requested boolean.
*/
public boolean getBoolean(String path);
/**
* Gets the requested boolean by path, returning a default value if not found.
* <p>
* If the boolean does not exist then the specified default value will returned
* regardless of if a default has been identified in the root {@link Configuration}.
*
* @param path Path of the boolean to get.
* @return Requested boolean.
*/
public boolean getBoolean(String path, boolean def);
/**
* Checks if the specified path is a boolean.
* <p>
* If the path exists but is not a boolean, this will return false. If the path does not
* exist, this will return false. If the path does not exist but a default value
* has been specified, this will check if that default value is a boolean and return
* appropriately.
*
* @param path Path of the boolean to check.
* @return Whether or not the specified path is a boolean.
*/
public boolean isBoolean(String path);
/**
* Gets the requested double by path.
* <p>
* If the double does not exist but a default value has been specified, this
* will return the default value. If the double does not exist and no default
* value was specified, this will return null.
*
* @param path Path of the double to get.
* @return Requested double.
*/
public double getDouble(String path);
/**
* Gets the requested double by path, returning a default value if not found.
* <p>
* If the double does not exist then the specified default value will returned
* regardless of if a default has been identified in the root {@link Configuration}.
*
* @param path Path of the double to get.
* @return Requested double.
*/
public double getDouble(String path, double def);
/**
* Checks if the specified path is a double.
* <p>
* If the path exists but is not a double, this will return false. If the path does not
* exist, this will return false. If the path does not exist but a default value
* has been specified, this will check if that default value is a double and return
* appropriately.
*
* @param path Path of the double to check.
* @return Whether or not the specified path is a double.
*/
public boolean isDouble(String path);
/**
* Gets the requested long by path.
* <p>
* If the long does not exist but a default value has been specified, this
* will return the default value. If the long does not exist and no default
* value was specified, this will return null.
*
* @param path Path of the long to get.
* @return Requested long.
*/
public long getLong(String path);
/**
* Gets the requested long by path, returning a default value if not found.
* <p>
* If the long does not exist then the specified default value will returned
* regardless of if a default has been identified in the root {@link Configuration}.
*
* @param path Path of the long to get.
* @return Requested long.
*/
public long getLong(String path, long def);
/**
* Checks if the specified path is a long.
* <p>
* If the path exists but is not a long, this will return false. If the path does not
* exist, this will return false. If the path does not exist but a default value
* has been specified, this will check if that default value is a long and return
* appropriately.
*
* @param path Path of the long to check.
* @return Whether or not the specified path is a long.
*/
public boolean isLong(String path);
// Java
/**
* Gets the requested List by path.
* <p>
* If the List does not exist but a default value has been specified, this
* will return the default value. If the List does not exist and no default
* value was specified, this will return null.
*
* @param path Path of the List to get.
* @return Requested List.
*/
public List getList(String path);
/**
* Gets the requested List by path, returning a default value if not found.
* <p>
* If the List does not exist then the specified default value will returned
* regardless of if a default has been identified in the root {@link Configuration}.
*
* @param path Path of the List to get.
* @return Requested List.
*/
public List getList(String path, List def);
/**
* Checks if the specified path is a List.
* <p>
* If the path exists but is not a List, this will return false. If the path does not
* exist, this will return false. If the path does not exist but a default value
* has been specified, this will check if that default value is a List and return
* appropriately.
*
* @param path Path of the List to check.
* @return Whether or not the specified path is a List.
*/
public boolean isList(String path);
// Bukkit
/**
* Gets the requested Vector by path.
* <p>
* If the Vector does not exist but a default value has been specified, this
* will return the default value. If the Vector does not exist and no default
* value was specified, this will return null.
*
* @param path Path of the Vector to get.
* @return Requested Vector.
*/
public Vector getVector(String path);
/**
* Gets the requested Vector by path, returning a default value if not found.
* <p>
* If the Vector does not exist then the specified default value will returned
* regardless of if a default has been identified in the root {@link Configuration}.
*
* @param path Path of the Vector to get.
* @return Requested Vector.
*/
public Vector getVector(String path, Vector def);
/**
* Checks if the specified path is a Vector.
* <p>
* If the path exists but is not a Vector, this will return false. If the path does not
* exist, this will return false. If the path does not exist but a default value
* has been specified, this will check if that default value is a Vector and return
* appropriately.
*
* @param path Path of the Vector to check.
* @return Whether or not the specified path is a Vector.
*/
public boolean isVector(String path);
/**
* Gets the requested OfflinePlayer by path.
* <p>
* If the OfflinePlayer does not exist but a default value has been specified, this
* will return the default value. If the OfflinePlayer does not exist and no default
* value was specified, this will return null.
*
* @param path Path of the OfflinePlayer to get.
* @return Requested OfflinePlayer.
*/
public OfflinePlayer getOfflinePlayer(String path);
/**
* Gets the requested OfflinePlayer by path, returning a default value if not found.
* <p>
* If the OfflinePlayer does not exist then the specified default value will returned
* regardless of if a default has been identified in the root {@link Configuration}.
*
* @param path Path of the OfflinePlayer to get.
* @return Requested OfflinePlayer.
*/
public OfflinePlayer getOfflinePlayer(String path, OfflinePlayer def);
/**
* Checks if the specified path is an OfflinePlayer.
* <p>
* If the path exists but is not a OfflinePlayer, this will return false. If the path does not
* exist, this will return false. If the path does not exist but a default value
* has been specified, this will check if that default value is a OfflinePlayer and return
* appropriately.
*
* @param path Path of the OfflinePlayer to check.
* @return Whether or not the specified path is an OfflinePlayer.
*/
public boolean isOfflinePlayer(String path);
/**
* Gets the requested ItemStack by path.
* <p>
* If the ItemStack does not exist but a default value has been specified, this
* will return the default value. If the ItemStack does not exist and no default
* value was specified, this will return null.
*
* @param path Path of the ItemStack to get.
* @return Requested ItemStack.
*/
public ItemStack getItemStack(String path);
/**
* Gets the requested ItemStack by path, returning a default value if not found.
* <p>
* If the ItemStack does not exist then the specified default value will returned
* regardless of if a default has been identified in the root {@link Configuration}.
*
* @param path Path of the ItemStack to get.
* @return Requested ItemStack.
*/
public ItemStack getItemStack(String path, ItemStack def);
/**
* Checks if the specified path is an ItemStack.
* <p>
* If the path exists but is not a ItemStack, this will return false. If the path does not
* exist, this will return false. If the path does not exist but a default value
* has been specified, this will check if that default value is a ItemStack and return
* appropriately.
*
* @param path Path of the ItemStack to check.
* @return Whether or not the specified path is an ItemStack.
*/
public boolean isItemStack(String path);
/**
* Gets the requested ConfigurationSection by path.
* <p>
* If the ConfigurationSection does not exist but a default value has been specified, this
* will return the default value. If the ConfigurationSection does not exist and no default
* value was specified, this will return null.
*
* @param path Path of the ConfigurationSection to get.
* @return Requested ConfigurationSection.
*/
public ConfigurationSection getConfigurationSection(String path);
/**
* Checks if the specified path is a ConfigurationSection.
* <p>
* If the path exists but is not a ConfigurationSection, this will return false. If the path does not
* exist, this will return false. If the path does not exist but a default value
* has been specified, this will check if that default value is a ConfigurationSection and return
* appropriately.
*
* @param path Path of the ConfigurationSection to check.
* @return Whether or not the specified path is a ConfigurationSection.
*/
public boolean isConfigurationSection(String path);
/**
* Gets the equivalent {@link ConfigurationSection} from the default {@link Configuration} defined in {@link #getRoot()}.
* <p>
* If the root contains no defaults, or the defaults doesn't contain a value
* for this path, or the value at this path is not a {@link ConfigurationSection} then
* this will return null.
*
* @return Equivalent section in root configuration
*/
public ConfigurationSection getDefaultSection();
/**
* Sets the default value in the root at the given path as provided.
* <p>
* If no source {@link Configuration} was provided as a default collection,
* then a new {@link MemoryConfiguration} will be created to hold the new default
* value.
* <p>
* If value is null, the value will be removed from the default Configuration source.
* <p>
* If the value as returned by {@link #getDefaultSection()} is null,
* then this will create a new section at the path, replacing anything that
* may have existed there previously.
*
* @param path Path of the value to set.
* @param value Value to set the default to.
* @throws IllegalArgumentException Thrown if path is null.
*/
public void addDefault(String path, Object value);
}
|