MemStoreDB

MemStoreDB is a lightweight, in-memory database library for Java with optional JSON file persistence.
It is designed for scenarios where you need fast in-memory operations but also want to persist data between application runs — for example in simulations or tick-based systems.

---

Features

• Store entities in collections defined by the @Document annotation.
• Fully in-memory with optional persistence to JSON files.
• Persistence modes:
  • Implicit: writes to disk after each modification (default).
  • Explicit: batch persistence — call persistCollections() to flush changes.
• Criteria-based query API with filtering, sorting, offsets, and limits.
• Support for indexes via annotations to speed up queries.
• CRUD operations:
  • Create collections
  • Save and remove documents
  • Find by ID, query, or criteria
  • Find and modify / find and remove operations (note: these are provided by the API but are not guaranteed to be atomic across concurrent threads)
  • Truncate or drop collections
• Simple configuration via MemStoreDBConfig.

---

Quick Start

1. Define a Document

Annotate your entity class with @Document and its identifier with @Id:

import de.golatar.memstoredb.annotation.Document;
import de.golatar.memstoredb.annotation.Id;

@Document
public class Person {

    @Id
    private String id;

    private String name;
    private int age;

    // getters and setters...
}

2. Initialize MemStoreDB

import de.golatar.memstoredb.MemStoreDB;
import de.golatar.memstoredb.config.MemStoreDBConfig;

MemStoreDB db = new MemStoreDB(
    MemStoreDBConfig.builder()
        .dbFilesLocation("/path/to/db/files") // storage location
        .baseScanPackage("com.example") // base scan package for documents
        .build()
);

If you provide the baseScanPackage, that package and all subpackages are scanned for classes annotated with @Document and collections will be created automatically.

3. Use Collections

// Create collection if not created using baseScanPackage
db.createCollection(Person.class);

// Save entity
Person alice = new Person();
alice.setName("Alice");
alice.setAge(30);
db.save(alice);

// Query
var results = db.find(
    Query.query(Criteria.where("age").gt(25)),
    Person.class
);

// Find by ID
Person loaded = db.findById(alice.getId(), Person.class);

// Remove
db.remove(alice);

// Persist all collections (if using explicit mode)
db.persistCollections();

---

Persistence

• Each collection is stored as a JSON file (<collection>.json) in the configured directory.
• In implicit write mode (WriteMode.IMPLICIT), collections are written to disk after each modification.
• In explicit write mode (WriteMode.EXPLICIT), you must call persistCollections() to persist changes.

---

Indexing

Fields can be indexed with @Index or @Indexes. Indexed fields are used automatically in queries to improve performance.

@Document
public class City {
    @Id
    private String id;

    @Index("population")
    private int population;

    // ...
}

---

Limitations

• Not JPA-compatible.
• Designed for simplicity and fast prototyping, not for large-scale relational workloads.
• Each collection is stored in a single JSON file — not suitable for very large datasets.
• The database stores and returns the same object instances (no defensive copies). Mutating a returned object can therefore be persisted implicitly if the object remains in a collection.