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:212-221]

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.

• Concurrency Control: Implements a specialized lock system providing thread-safe Write Isolation and simultaneous Concurrent Reads.

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.

---

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