diff --git a/astro.config.mjs b/astro.config.mjs index fbb4a4d..afb3b49 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -70,7 +70,7 @@ export default defineConfig({ 'reference/xpath-cheatsheet', 'reference/upgrading', 'reference/security', - { label: 'Javadoc', link: 'https://javadoc.io/doc/io.jsondb/jsondb-core/1.1.16/', attrs: { target: '_blank' } }, + { label: 'Javadoc', link: 'https://javadoc.io/doc/io.jsondb/jsondb-core/1.1.63/', attrs: { target: '_blank' } }, { label: 'Changelog', link: 'https://github.com/Jsondb/jsondb-core/blob/master/CHANGELOG.md', attrs: { target: '_blank' } }, { label: 'Releases', link: 'https://github.com/Jsondb/jsondb-core/releases', attrs: { target: '_blank' } }, ], diff --git a/src/components/CodeAndFile.astro b/src/components/CodeAndFile.astro index c64a300..8ed9e98 100644 --- a/src/components/CodeAndFile.astro +++ b/src/components/CodeAndFile.astro @@ -21,7 +21,7 @@ */ // The landing page's demo: Java code beside the users.json it writes. -// The file contents are real output from JsonDB 1.1.16 running this code. +// The file contents are real output from JsonDB 1.1.63 running this code. import { Code } from '@astrojs/starlight/components'; const java = `@Document(collection = "users", schemaVersion = "1.0") diff --git a/src/content/docs/guides/crud.md b/src/content/docs/guides/crud.md index c74ce8a..d93db16 100644 --- a/src/content/docs/guides/crud.md +++ b/src/content/docs/guides/crud.md @@ -18,6 +18,8 @@ The examples use the `User` class from the [quick start](/start/quick-start/). "Fails" means an `InvalidJsonDbApiUsageException` (a `RuntimeException`), and nothing is written. +Any write can also fail because JsonDB can't save the file, for example when the database folder is read-only. It then throws `JsonDBException`, also a `RuntimeException`, and the collection is left as it was, both in memory and on disk. This applies to `findAndModify` and the other [query-based writes](/guides/find-and-modify/) too. + ## insert ```java @@ -95,11 +97,7 @@ int total = db.count(User.class); ## By class or by collection name -Every method has a form that takes the collection name instead of the class, such as `db.insert(user, "users")` and `db.findAll("users")`. Prefer the class form. - -:::caution[Misspelt collection names in 1.1.16] -In 1.1.16, `insert`, `save`, `upsert` and `remove` given a collection name that no `@Document` class has (a typo such as `"usres"`) fail with a bare `NullPointerException`. The read methods fail with `InvalidJsonDbApiUsageException: Collection by name 'usres' not found`. The class form avoids both. -::: +Every method has a form that takes the collection name instead of the class, such as `db.insert(user, "users")` and `db.findAll("users")`. Prefer the class form: it can't be misspelt. A name that no `@Document` class has, such as `"usres"`, fails with `InvalidJsonDbApiUsageException: Collection by name 'usres' not found`. ## Read-only collections diff --git a/src/content/docs/guides/documents.md b/src/content/docs/guides/documents.md index 6da5d86..727a1e1 100644 --- a/src/content/docs/guides/documents.md +++ b/src/content/docs/guides/documents.md @@ -46,7 +46,7 @@ Marks the one field that identifies a document within its collection. Every `@Do - Use JsonDB's own `io.jsondb.annotation.Id`. Another framework's annotation, such as `javax.persistence.Id`, isn't recognised: JsonDB rejects the class with an `InvalidJsonDbApiUsageException` that names it. - Ids are compared with `equals()`, so `String` and the boxed number types work well. Most examples use `String`. -- Set the id yourself before inserting. In 1.1.16, documents inserted without an id aren't stored reliably. +- If a document's id is `null` when you insert or upsert it, JsonDB stores it under a random UUID. The object you passed keeps its `null` id, so to read the document back by id you have to find it first. If you need the id, set it yourself. ## `@Secret` @@ -74,4 +74,4 @@ if (!db.collectionExists(Server.class)) { `createCollection` writes the new file with its schema-version line. `dropCollection(Server.class)` deletes the file and its documents. `getCollectionNames()` lists the collections that are currently loaded. -Every operation comes in two forms: one takes the class (`find(query, Server.class)`), and one takes the collection name (`find(query, "servers")`). Prefer the class form. It can't be misspelt, and in 1.1.16 a misspelt name makes some write operations fail with a bare `NullPointerException` instead of a clear error. +Every operation comes in two forms: one takes the class (`find(query, Server.class)`), and one takes the collection name (`find(query, "servers")`). Prefer the class form. It can't be misspelt; a misspelt name fails at run time with an `InvalidJsonDbApiUsageException`. diff --git a/src/content/docs/guides/file-change-listeners.md b/src/content/docs/guides/file-change-listeners.md index 8b39ec4..5bb23d1 100644 --- a/src/content/docs/guides/file-change-listeners.md +++ b/src/content/docs/guides/file-change-listeners.md @@ -48,8 +48,4 @@ db.removeCollectionFileChangeListener(listener); db.hasCollectionFileChangeListener(); // false when none are left ``` -Removing the last listener stops the watcher thread. [Closing the template](/guides/jsondbtemplate/#closing) stops it too. - -:::caution[Re-adding listeners in 1.1.16] -In 1.1.16, if you remove the last listener and then add one again, the watcher doesn't restart and the new listener receives no events. Keep at least one listener registered for as long as you need events, or create a new `JsonDBTemplate`. -::: +Removing the last listener stops the watcher thread, and adding one again restarts it. [Closing the template](/guides/jsondbtemplate/#closing) stops it too. diff --git a/src/content/docs/guides/jsondbtemplate.md b/src/content/docs/guides/jsondbtemplate.md index ac4742b..aa4f227 100644 --- a/src/content/docs/guides/jsondbtemplate.md +++ b/src/content/docs/guides/jsondbtemplate.md @@ -71,6 +71,18 @@ For a long-lived template, call `close()` when your application shuts down. Clos Data is never waiting to be written: every write has already reached the file by the time the method returns. Closing releases resources; it doesn't flush anything. +## Surviving a crash + +JsonDB writes each change to a temporary file, forces that file to disk, and then renames it over the collection file. A crash or power loss part-way through leaves either the old file or the new one, never a partial one. + +The rename itself can still be lost: after a power cut, a write that had already returned may be missing, with the file as it was before that write. If your application can't accept that, turn on folder syncing (new in 1.1.63): + +```java +db.setSyncFolderOnWrite(true); +``` + +After every write, JsonDB then also forces the database folder to disk, so a write that has returned survives a crash. It makes writes several times slower, so it's off by default. Not every platform can sync a folder; Windows can't, and there the setting has no effect. + ## Reloading from disk JsonDB assumes it's the only writer of its folder. If another program changes the files, reload them: diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index fa6d1a3..1a370f4 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -22,13 +22,13 @@ import { Card, CardGrid, Tabs, TabItem } from '@astrojs/starlight/components'; import CodeAndFile from '../../components/CodeAndFile.astro';
v1.1.16 · Java 8+ · Android & OSGi · MIT licensed
+v1.1.63 · Java 8+ · Android & OSGi · MIT licensed