JSON-Database (Java)

A multi-threaded Client-Server database system designed to manage and optimize JSON data storage using an append-only file architecture.

Project Description

The database is designed to handle nested JSON structures in the most optimized way possible. One of the core architectural choices is the Index-in-RAM, Data-on-Disk approach. The system maintains an internal metadata collection adapted for high-speed multi-threaded reads, while the actual data content resides safely on the disk. The main objective was to create a system where complex JSON documents are treated as a collection of addressable fragments rather than monolithic blobs. This ensures that the database remains performant even as the complexity of the stored data grows.

Key Features

JSON Shredding & Virtual Pointers [Logic]

Incoming JSON is recursively processed, breaking down complex structures into individual objects stored as separate records. To optimize updates, the system implements a chain of **indirection wrappers ** [Implementation].

Shredding Process Visualization (Elon Musk & Starship)

The following table demonstrates the transformation from the Original JSON Object to the Data Stored on Disk.

Original JSON Object	Disk Key (Pointer)	Data Stored on Disk
{ "person": { "name": "Elon Musk", "rocket": { "model": "Starship", "status": "In Development" } } }	elon_profile (Root)	{ "person": "@ptr:h_person_wrap" }
	h_person_wrap (Indirection)	{ "ptr": "@ptr:h_person_data" }
	h_person_data (Content)	{ "name": "Elon Musk", "rocket": "@ptr:h_rocket_wrap" }
	h_rocket_wrap (Indirection)	{ "ptr": "@ptr:h_rocket_data" }
	h_rocket_data (Nested Content)	{ "model": "Starship", "status": "In Development" }

This mechanism allows the database to update deep nested fields by only appending a new small data record and updating its immediate wrapper, leaving the rest of the 1MB document untouched on disk.

Data Deduplication [JsonProcessor.java:210-230]

The database ensures storage efficiency by parsing every JSON object into a sorted TreeMap before hashing. This ensures that identical JSON objects result in the same hash regardless of the original field order, effectively preventing redundant duplicates on disk.

Custom Storage Engine [StorageEngine.java]

• NIO Performance: Leveraging the FileChannel interface for advanced, direct file manipulation.

• Gathering Writes: Utilizes a Zero-copy approach with ByteBuffer to minimize memory cloning during I/O.

• Durability: Every write is followed by an explicit force(false) call, flushing data to physical disk before the operation returns - guaranteeing no data loss on JVM or OS crash.

Nested Path Support [JsonDataBase.java:191]

The database provides a mechanism for interacting with deep JSON structures using a "path" (array of keys).

1. GET: Navigates the tree to return only the target element.

2. SET: Updates or creates a value. If path steps are missing, the system constructs them automatically.

3. DELETE: Permanently removes a key-value pair from a specific nested location.

Optimistic Concurrency Control [JsonDataBase.java]

To prevent lost updates when multiple threads read-modify-write the same key concurrently, every set() and delete() operation captures the key's version at read time and verifies it hasn't changed immediately before committing. If another operation modified the key in between, the write is rejected with a version conflict error instead of silently overwriting or resurrecting deleted data.

---

Installation & Building

Windows

.\mvnw.cmd clean package

Linux / macOS

./mvnw clean package

---

Running the Application

1. Start the Server

java -jar server/target/server-1.0-SNAPSHOT.jar

2. Run the Client

Send request via CLI flags:

java -jar client/target/client-1.0-SNAPSHOT.jar -t set -k "user1" -v '{"name":"John"}'

Send request from a JSON file:

java -jar client/target/client-1.0-SNAPSHOT.jar -in "request.json"

---

Quality Assurance & Static Analysis

Google Checkstyle

The project is 100% compliant with Google's coding standards.

PMD (Static Analysis)

Suppression is used only for local connection IP addresses.

JaCoCo - Code Coverage

• Client: 100% coverage

• Common: 98% coverage

• Server: 95% coverage