Package-level declarations
Types
The operations of JsonStore without coroutines, obtained from JsonStore.blocking. Thread-safe.
The operations of ReadableJsonStore without coroutines, obtained from ReadableJsonStore.blocking. Thread-safe.
The operations of SecondaryJsonStore without coroutines, obtained from SecondaryJsonStore.blocking. Thread-safe.
One side of a comparison (SPEC.md §9): a node of a stored document, or a JSON value given as text.
Stored bytes don't match their format: a CRC mismatch, a truncated structure, an out-of-range field or an inconsistent index entry. location names the file or structure and the byte position.
The options a store is created with, fixed for its whole life: they shape the stored data and the index terms. They are given to JsonStore.create and JsonStore.openOrCreate, recorded in the store, and read back by JsonStore.open, so opening a store never needs them; JsonStore.creationOptions tells what a store was created with. The options that may differ at every open are StoreOptions.
JsonStore.openOrCreate found a store in directory created with other CreationOptions than requested; it was left as it was. JsonStore.open opens it with the stored options.
An opaque position in a result sequence: the hits strictly past (docId, nodePre) in the order of the search that produced it — after it for SearchOrder.ASCENDING, before it for SearchOrder.DESCENDING. toString gives a compact URL-safe text, and parse reads it back. A cursor resumes only what produced it: a search of the same SearchOrder and kind, or JsonStore.objectsOfTypePage for the cursor of a TypePage; anything else throws InvalidCursorException.
Base class of every exception Delva throws for data, state or storage problems. It is sealed, but the constructors of its subclasses are public, so a fake JsonStore in a test (DelvaImplementationApi) can throw what the store throws.
Marks the interfaces that are Delva's to implement: ReadableJsonStore, JsonStore, SecondaryJsonStore, their blocking faces (BlockingReadableJsonStore, BlockingJsonStore, BlockingSecondaryJsonStore), SearchResult, SearchHit, SelectResult and SelectedNode. Calling them needs no opt-in. Implementing one, typically as a fake in a test, requires @OptIn(DelvaImplementationApi::class) and accepts that later minor releases add members to it, which an implementation then has to add too.
One difference between the left and the right value: at path (an RFC 9535 Normalized Path such as $['a'][0], SPEC.md §9.3, $ being the compared values), what kind of difference, and the values involved: left is null for DifferenceKind.ADDED, right for DifferenceKind.REMOVED.
What a Difference reports (SPEC.md §9.3).
How a diff is computed and reported (SPEC.md §9.3): includeTypes, ignoreKeys and ignorePaths compare values as in CompareOptions, and
A value a Difference involves.
A condition on a whole document, which limits a JsonPathQuery to the documents that meet it (JsonPathQuery.documentFilter, SPEC.md §10.5): an RFC 9535 logical expression, what a filter selector holds after its ?, evaluated once on each document with both @ and $ standing for the document's root.
A DocumentFilter with named placeholders, compiled once and bound to values any number of times (SPEC.md §10.6), as JsonPathTemplate is for a query: @.kind == ${kind} && @.version >= ${version}.
A search of documents in key order (SPEC.md §3.3), in a store with a CreationOptions.documentKey: every visible document whose key starts with prefix ("" for all), once, with its root as the hit and SearchHit.documentKey set. Keys compare by code points, which is the order of their UTF-8 bytes; with Normalization.NFC the prefix is normalized as keys are.
The document doesn't exist or the caller can't see it: never inserted, deleted, still being inserted, or the docId of an insert that was rejected.
An insert was rejected; nothing of the document is visible.
When acknowledged writes become durable.
The engine hit an unrecoverable error (for example a failed fsync) and refuses every further operation. Reopening the store runs recovery.
Marks API that is new in this release and may still change, in its signature or its behaviour, in a minor release. Using it requires @OptIn(ExperimentalDelvaApi::class). The mark is lifted from a declaration once a release has shipped it unchanged; the CHANGELOG says when.
What JsonStore.insertAll did with one document.
One document for JsonStore.insertAll: the stream its JSON is read from, which isn't closed, the types to assign with it, JSON paths to type names as JsonStore.insert takes them, the documents it replaces, and in a store with a CreationOptions.documentKey what it does when its key is taken (onExistingKey).
Text that isn't a Cursor (Cursor.parse), or a cursor that doesn't fit where it's used: from a search of the other SearchOrder, or from another kind of result. An IllegalArgumentException, as Cursor.parse has always thrown.
A JSONPath query or document filter that doesn't compile (SPEC.md §10.1, §10.5): a syntax or type error, or text beyond the limits. An IllegalArgumentException, as JsonPath.compile and the type paths of JsonStore.insert have always thrown.
A type name doesn't meet the rules of SPEC.md §6.1.
How a node's JSON is laid out when it's read (SearchHit.writeJsonTo, SelectedNode.writeJsonTo and their readJsonAsString). COMPACT, the default, is the exact output form of SPEC.md §5, with no whitespace. Any other format writes the same tokens with whitespace between them (SPEC.md §5.1), so removing the whitespace outside strings gives the compact text back byte for byte, unless maxLevels cuts nested containers out. Formatting is applied as the node is read; it's never stored.
A compiled RFC 9535 JSONPath query (SPEC.md §10): the whole grammar, with the functions length, count, match, search and value. Compile once, then use it for any number of JsonStore.select and JsonStore.search calls. Immutable and thread-safe; two queries are equal when their texts are.
A JSONPath search (SPEC.md §10.4): the nodes path selects from the documents of the store. Hits are the distinct selected nodes in (docId, nodePre) order, ascending or descending by order — each node once, unlike an RFC 9535 nodelist, which JsonStore.select gives for one value.
An RFC 9535 JSONPath query with named placeholders, compiled once and bound to values any number of times (SPEC.md §10.6). A placeholder ${name} stands where the RFC allows a literal: an operand of a comparison, or a value argument of a function such as the pattern of match.
A query value (SPEC.md §2): equality is typed, numbers compare by decimal value, strings by code points.
An embedded JSON document store. Inserts stream their input, searches return lazily read results (SPEC.md). This is the store's writer, which holds the directory's lock until it's closed, with the read operations of ReadableJsonStore; other processes can read the store beside it with openSecondary. After a failed write or sync, operations throw EngineFailedException until the store is reopened (SPEC.md §8).
What an insert does when a visible document already has its document key (CreationOptions.documentKey).
A key–value search (SPEC.md §4): objects with a member key whose value, or an element of whose array value, equals value.
The process that has a store open, as it recorded itself when it opened the store (StoreLockedException.holder). The record is advisory: a process that can't write it still holds the store.
Handling of hits nested inside other hits of the same document (SPEC.md §4.5).
A node of a stored document (SPEC.md §3.2): its document, docId, and its pre-order number, nodePre, and nothing more. The pair is the whole of a node reference, now and in later versions: it can be stored, compared and rebuilt from its two numbers.
How a store treats the spelling of strings and keys (SPEC.md §2.1). Fixed when the store is created, because it decides the bytes that are stored and the terms that are indexed.
Evaluating a JSONPath query exceeded one of the limits that keep evaluation bounded (SPEC.md §10.2), such as the steps a regular expression of match or search may take.
How a JSONPath search finds its candidate documents, as JsonStore.explain reports it.
A search the store can't answer, refused for reason before anything is read (SPEC.md §4.6, §10.4). Nothing is wrong with the query as such: another store, a narrower query, ScanPolicy.ALLOW_SCAN, or a select of each document answers it.
The read operations of a store, shared by the JsonStore that writes it and the SecondaryJsonStores that read it beside its writer: code that only reads takes a ReadableJsonStore and serves both.
Why an insert was rejected (SPEC.md §1.2).
What a hit stands for (SPEC.md §4.3).
A value is longer than the maxChars characters the caller allowed, for example in SearchHit.readJsonAsString.
What a JSONPath search does when no index term narrows it down (SPEC.md §10.4).
One hit: an object (CONTAINING_ELEMENT) or a document root (WHOLE_DOCUMENT). Readable while its result is open.
The order of a search's hits (SPEC.md §4.4).
One page of hits.
The hits of one KeyValueQuery or JsonPathQuery, read lazily page by page from one snapshot of the store (SPEC.md §4.6, §8, §10.4): the result sees every operation acknowledged before the search started and nothing later, so its pages together return every hit exactly once.
A store read beside its writer, opened with JsonStore.openSecondary: it offers every read of ReadableJsonStore and never writes. It takes no lock, so it works while another process has the store open as a JsonStore, and with no writer at all (SPEC.md §8.1).
One node of a SelectResult. Readable while its result is open.
The nodes one JSONPath query selects from one value, as JsonStore.select returns them: an RFC 9535 nodelist, in the RFC's order and with its duplicates, read lazily from one snapshot of the store (SPEC.md §10.3). Nodes can be read until the result is closed. A result is consumed once: iterator and nodes share one position. Not thread-safe.
The store was closed; reopen it to use it again.
JsonStore.create found a store already in directory; it was left as it was.
What a store holds, as of the moment ReadableJsonStore.info was called; read from memory, without a scan.
Another open store (in this or another process) holds the directory. holder names the process that has it open, as that process recorded itself; it is null when the record is missing, unreadable, or left by a process that is gone.
JsonStore.open found no store in directory; nothing was created there.
The options of one open store, which may differ at every open. Every option has a safe default, so StoreOptions() opens a store that works on any heap; the values below bound what a store does, never how much of the JVM's heap it needs, which the engine derives from the heap it runs on. The options fixed when a store is created are CreationOptions.
A type name and roughly how many objects have it (SPEC.md §6.2), as ReadableJsonStore.listTypes lists them.
One page of the objects of a type, from JsonStore.objectsOfTypePage.
One problem JsonStore.verify found. location names the file and byte position, as CorruptionException.location does; damagedBytes is how many bytes the damage spans where that's known, and 0 otherwise.
What kind of structure a VerifyIssue was found in.
What JsonStore.verify is reading, in the order the phases run.
Called by JsonStore.verify as it works, at least once per phase and then every few MiB.
What JsonStore.verify read and what it found. A store is intact when issues is empty; every issue names data that reads would fail on, not a reason to stop using the store, which keeps serving everything else.
An insert conflicts with the state it would take effect on. Nothing of the insert is visible and nothing was deleted. Nothing is wrong with the document itself: read the current state and try again. Either: