From 1eb41c644a542ef5eec9ca7f58562dcbe8cfc118 Mon Sep 17 00:00:00 2001 From: FarooqKhan Date: Thu, 19 Nov 2026 00:46:00 +0530 Subject: [PATCH] Document jsondb-core 1.1.63. Bump the current version, drop the warnings about the 1.1.16 bugs that 1.1.63 fixes, and document setSyncFolderOnWrite and the JsonDBException now thrown when a write can't be saved. --- astro.config.mjs | 2 +- src/components/CodeAndFile.astro | 2 +- src/content/docs/guides/crud.md | 8 +++----- src/content/docs/guides/documents.md | 4 ++-- .../docs/guides/file-change-listeners.md | 6 +----- src/content/docs/guides/jsondbtemplate.md | 12 ++++++++++++ src/content/docs/index.mdx | 6 +++--- src/content/docs/reference/upgrading.md | 19 ++++++++++++++----- .../docs/reference/xpath-cheatsheet.md | 2 +- src/content/docs/start/installation.mdx | 10 +++++----- src/content/docs/start/quick-start.mdx | 4 ---- 11 files changed, 43 insertions(+), 32 deletions(-) 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

```kotlin - implementation("io.jsondb:jsondb-core:1.1.16") + implementation("io.jsondb:jsondb-core:1.1.63") ``` @@ -36,7 +36,7 @@ import CodeAndFile from '../../components/CodeAndFile.astro'; io.jsondb jsondb-core - 1.1.16 + 1.1.63 ``` diff --git a/src/content/docs/reference/upgrading.md b/src/content/docs/reference/upgrading.md index 228f32c..49b0303 100644 --- a/src/content/docs/reference/upgrading.md +++ b/src/content/docs/reference/upgrading.md @@ -1,20 +1,20 @@ --- -title: Upgrading from 1.0.x -description: What to change, and what behaves differently, when moving from JsonDB 1.0.x to 1.1.16. +title: Upgrading +description: What to change, and what behaves differently, when moving from JsonDB 1.0.x, or from 1.1.16, to 1.1.63. --- 1.1.0 was the first release since 1.0.115 in March 2020. Most code upgrades by changing the version number, but some behaviour has changed. Check this list, especially if you build queries from user input, use `findAndModify`, or migrate schemas. ## Dependency -Change the version to `1.1.16`. Drop any `-j8` or `-j11` suffix; one build now runs on Java 8 and later: +Change the version to `1.1.63`. Drop any `-j8` or `-j11` suffix; one build now runs on Java 8 and later: ```diff lang="xml" io.jsondb jsondb-core - 1.0.115-j11 -+ 1.1.16 ++ 1.1.63 ``` @@ -49,7 +49,7 @@ See [Schema versions](/guides/schema-versions/). ### Errors that used to be hidden now surface - A collection file that exists but can't be parsed is left untouched. `getCollection()` and `createCollection()` throw `InvalidJsonDbApiUsageException` for it, instead of replacing it with an empty file. -- A write whose final file move fails throws `JsonDBException` instead of appearing to succeed. +- A write that can't be saved throws `JsonDBException` instead of appearing to succeed, and leaves the collection unchanged. This covers a failed final file move and, from 1.1.63, an unavailable lock or a temporary file that can't be created (in a read-only folder, for example). The remove methods used to return `null` in those cases, as if nothing had matched. - A `@Document` class without JsonDB's own `@Id`, for example one using `javax.persistence.Id`, fails with an `InvalidJsonDbApiUsageException` naming the class, instead of a `NullPointerException`. ### Quieter logging @@ -67,6 +67,7 @@ JsonDB logs a warning when a second `JsonDBTemplate` opens a folder that's alrea - **`count()`**, instead of `findAll(...).size()`. - **[`backup()` and `restore()`](/guides/backup-restore/)** to and from zip files. - **`remove(object)`** without the class argument. +- **[`setSyncFolderOnWrite(true)`](/guides/jsondbtemplate/#surviving-a-crash)**, if a write that has returned must survive a power cut. ## Bugs fixed @@ -76,5 +77,13 @@ These fixes need no change to your code, but they may explain odd behaviour you - A collection file with one bad line could be emptied by a later `getCollection()`. - A thread that lost the race to create a collection could hang it. - Merge-restore encrypted `@Secret` fields twice on encrypted databases. +- Documents inserted without an id could be lost, and a batch of them failed with "Duplicate object with id: null" (fixed in 1.1.63). +- A crash shortly after a write could leave a collection file empty or partly written (fixed in 1.1.63). +- A misspelt collection name given to `insert`, `save`, `upsert` or `remove` threw a bare `NullPointerException` (fixed in 1.1.63). +- A file-change listener added after the last one was removed received no events (fixed in 1.1.63). + +## From 1.1.16 + +Change the version to `1.1.63`. Every fix marked 1.1.63 above applies to you. The one change to check for is that writes which can't be saved now throw `JsonDBException` instead of returning normally; see [Errors that used to be hidden now surface](#errors-that-used-to-be-hidden-now-surface). The [changelog](https://github.com/Jsondb/jsondb-core/blob/master/CHANGELOG.md) has the full list. diff --git a/src/content/docs/reference/xpath-cheatsheet.md b/src/content/docs/reference/xpath-cheatsheet.md index 5e1dc2c..1646288 100644 --- a/src/content/docs/reference/xpath-cheatsheet.md +++ b/src/content/docs/reference/xpath-cheatsheet.md @@ -3,7 +3,7 @@ title: XPath cheat sheet description: Common JsonDB query patterns at a glance. --- -Every query below has been run against JsonDB 1.1.16. Pass it to `find`, `findOne`, `findAndModify`, `findAllAndModify`, `findAndRemove` or `findAllAndRemove`. See [Querying with XPath](/guides/queries/) for the explanations. +Every query below has been run against JsonDB 1.1.63. Pass it to `find`, `findOne`, `findAndModify`, `findAllAndModify`, `findAndRemove` or `findAllAndRemove`. See [Querying with XPath](/guides/queries/) for the explanations. ## Matching diff --git a/src/content/docs/start/installation.mdx b/src/content/docs/start/installation.mdx index d10865b..d5aa49c 100644 --- a/src/content/docs/start/installation.mdx +++ b/src/content/docs/start/installation.mdx @@ -5,20 +5,20 @@ description: Add JsonDB to a Gradle or Maven project. One artifact, Java 8 and l import { Tabs, TabItem } from '@astrojs/starlight/components'; -JsonDB is published to Maven Central as **`io.jsondb:jsondb-core`**. The current release is **1.1.16**, and it runs on **Java 8 and later**. One artifact covers every Java version, Android, and OSGi. +JsonDB is published to Maven Central as **`io.jsondb:jsondb-core`**. The current release is **1.1.63**, and it runs on **Java 8 and later**. One artifact covers every Java version, Android, and OSGi. ```kotlin title="build.gradle.kts" dependencies { - implementation("io.jsondb:jsondb-core:1.1.16") + implementation("io.jsondb:jsondb-core:1.1.63") } ``` ```groovy title="build.gradle" dependencies { - implementation 'io.jsondb:jsondb-core:1.1.16' + implementation 'io.jsondb:jsondb-core:1.1.63' } ``` @@ -27,7 +27,7 @@ JsonDB is published to Maven Central as **`io.jsondb:jsondb-core`**. The current io.jsondb jsondb-core - 1.1.16 + 1.1.63 ``` @@ -47,7 +47,7 @@ JsonDB logs its routine messages at `DEBUG`, so with the usual settings you see ## Upgrading from 1.0.x -The last 1.0 release was published as two builds, `1.0.115-j8` and `1.0.115-j11`. From 1.1.0 there's one build for every Java version from 8 on. See [Upgrading from 1.0.x](/reference/upgrading/) for that and the other changes to check. +The last 1.0 release was published as two builds, `1.0.115-j8` and `1.0.115-j11`. From 1.1.0 there's one build for every Java version from 8 on. See [Upgrading](/reference/upgrading/) for that and the other changes to check. ## Next diff --git a/src/content/docs/start/quick-start.mdx b/src/content/docs/start/quick-start.mdx index 288cfcb..aeca3f3 100644 --- a/src/content/docs/start/quick-start.mdx +++ b/src/content/docs/start/quick-start.mdx @@ -93,10 +93,6 @@ This page builds a complete program that stores users in JsonDB and queries them Run the program a second time and `insert` fails, because documents with ids `1` and `2` already exist. Use [`upsert`](/guides/crud/#upsert) when you want "insert or replace". -:::tip[Always set an id] -Give every document an id before you insert it. In 1.1.16, documents inserted without an id aren't stored reliably. -::: - ## Where next - [Defining documents](/guides/documents/): the annotations and what a document class needs.