Db.java

package com.renomad.minum.database;

import com.renomad.minum.logging.ILogger;

import com.renomad.minum.queue.AbstractActionQueue;

import com.renomad.minum.queue.ActionQueue;

import com.renomad.minum.state.Context;

import com.renomad.minum.utils.FileUtils;

import com.renomad.minum.utils.IFileUtils;

import java.io.IOException;

import java.nio.file.Path;

import java.text.ParseException;

import java.util.Collection;

import java.util.Collections;

import java.util.concurrent.atomic.AtomicLong;

import java.util.concurrent.locks.ReentrantLock;

import java.util.function.Function;

import static com.renomad.minum.utils.Invariants.mustBeFalse;

import static com.renomad.minum.utils.Invariants.mustBeTrue;

/**

 * a memory-based disk-persisted database class.

 * @param <T> the type of data we'll be persisting (must extend from {@link DbData}

 */

public final class Db<T extends DbData<?>> extends AbstractDb<T> {

    /**

     * The suffix we will apply to each database file

     */

    static final String DATABASE_FILE_SUFFIX = ".ddps";

    private final AbstractActionQueue actionQueue;

    /**

     * A lock around loading the data - so we can't find ourselves

     * in a situation where multiple threads are loading the data.

     */

    /**

     * The full path to the file that contains the most-recent index

     * for this data.  As we add new files, each gets its own index

     * value.  When we start the program, we use this to determine

     * where to start counting for new indexes.

     */

    private final Path fullPathForIndexFile;

    volatile boolean hasLoadedData;

    /**

     * Constructs an in-memory disk-persisted database.

     * Loading of data from disk happens at the first invocation of any command

     * changing or requesting data, such as {@link #write(DbData)}, {@link #delete(DbData)},

     * or {@link #values()}.  See the private method loadData() for details.

     * @param dbDirectory this uniquely names your database, and also sets the directory

     *                    name for this data.  The expected use case is to name this after

     *                    the data in question.  For example, "users", or "accounts".

     * @param context used to provide important state data to several components

     * @param instance an instance of the {@link DbData} object relevant for use in this database. Note

     *                 that each database (that is, each instance of this class), focuses on just one

     *                 data, which must be an implementation of {@link DbData}.

     */

    public Db(Path dbDirectory, Context context, T instance) {

    Db(Path dbDirectory, Context context, T instance, IFileUtils fileUtils) {

            try {

                long indexValue;

        } else {

        }

    /**

     * Write data to the database.  Use an index of 0 to store new data, and a positive

     * non-zero value to update data.

     * <p><em>

     *     Example of adding new data to the database:

     * </em></p>

     * {@snippet :

     *          final var newSalt = StringUtils.generateSecureRandomString(10);

     *          final var hashedPassword = CryptoUtils.createPasswordHash(newPassword, newSalt);

     *          final var newUser = new User(0L, newUsername, hashedPassword, newSalt);

     *          userDb.write(newUser);

     * }

     * <p><em>

     *     Example of updating data:

     * </em></p>

     * {@snippet :

     *         // write the updated salted password to the database

     *         final var updatedUser = new User(

     *                 user().getIndex(),

     *                 user().getUsername(),

     *                 hashedPassword,

     *                 newSalt);

     *         userDb.write(updatedUser);

     * }

     *

     * @param newData the data we are writing

     * @return the data with its new index assigned.

     */

    @Override

    public T write(T newData) {

        // load data if needed

        try {

            // *** now handle the disk portion ***

                            newElementCreated, fullPathForIndexFile, logger));

            // returning the data at this point is the most convenient

            // way users will have access to the new index of the data.

        } finally {

    }

    static <T extends DbData<?>> void writeToDisk(T newData, Path dbDirectory, IFileUtils fileUtils, T emptyInstance,

                                                  boolean newItemCreated, Path fullPathForIndexFile, ILogger logger) {

                "the serialized form of data must not be blank. " +

                        "Is the serialization code written properly? Our datatype: " + emptyInstance);

        try {

            }

    /**

     * Delete data

     * <p><em>Example:</em></p>

     * {@snippet :

     *      userDb.delete(user);

     * }

     * @param dataToDelete the data we are serializing and writing

     */

    @Override

    public void delete(T dataToDelete) {

        // load data if needed

        try {

            // deal with the in-memory portion

            // get the current index

                            shouldResetIndexOnDisk, fullPathForIndexFile, logger));

        } finally {

    static <T extends DbData<?>> void deleteFromDisk(T dataToDelete, Path dbDirectory, IFileUtils fileUtils,

                                                     boolean shouldResetIndexOnDisk, Path fullPathForIndexFile, ILogger logger) {

        try {

            }

            }

    /**

     * Grabs all the data from disk and returns it as a list.  This

     * method is run by various programs when the system first loads.

     */

    private void loadDataFromDisk() throws IOException, ParseException {

        // check if the folder has content for a DbEngine2 database, meaning we

        // need to convert it back to the classic DB file structure.

        }

        }

    void walkAndLoad(Path dbDirectory) throws IOException {

        // walk through all the files in this directory, collecting

        // all regular files (non-subdirectories) except for index.ddps

    /**

     * Carry out the process of reading data files into our in-memory structure

     * @param p the path of a particular file

     */

    void readAndDeserialize(Path p) {

        }

        String fileContents;

        try {

        } else {

            try {

                @SuppressWarnings("unchecked")

                        " resulted in a null value. Was the serialization method implemented properly?");

                        "The filename must correspond to the data's index. e.g. 1.ddps must have an id of 1");

                // put the data into the in-memory data structure

        }

    @Override

    public Collection<T> values() {

        // load data if needed

    }

    /**

     * This is what loads the data from disk the

     * first time someone needs it.  Because it is

     * locked, only one thread can enter at

     * a time.  The first one in will load the data,

     * and the second will encounter a branch which skips loading.

     */

    @Override

    public Db<T> loadData() {

        try {

            }

        } finally {

    }

    /**

     * Register an index in the database for higher performance data access.

     * <p>

     *     This command should be run immediately after database declaration,

     *     or more specifically, before any data is loaded from disk. Otherwise,

     *     it would be possible to skip indexing that data.

     * </p>

     * <br>

     * Example:

     *  {@snippet :

     *           final var myDatabase = context.getDb("photos", Photograph.EMPTY);

     *           myDatabase.registerIndex("url", photo -> photo.getUrl());

     *  }

     * @param indexName a string used to distinguish this index.  This string will be used again

     *                  when requesting data in a method like {@link #getIndexedData} or {@link #findExactlyOne}

     * @param keyObtainingFunction a function which obtains data from the data in this database, used

     *                             to partition the data into groups (potentially up to a 1-to-1 correspondence

     *                             between id and object)

     * @return the database instance if the registration succeeded

     * @throws DbException if the parameters are not entered properly, if the index has already

     * been registered, or if the data has already been loaded. It is necessary that

     * this is run immediately after declaring the database. To explain further: the data is not

     * actually loaded until the first time it is needed, such as running a write or delete, or

     * if the {@link #loadDataFromDisk()} method is run.  Creating an index map for the data that

     * is read from disk only occurs once, at data load time.  Thus, it is crucial that the

     * registerIndex command is run before any data is loaded.

     */

    @Override

    public Db<T> registerIndex(String indexName, Function<T, String> keyObtainingFunction) {

                    "it should be run immediately after the database is created.  See this method's documentation");

        }

    }

    /**

     * Given the name of a registered index (see {@link #registerIndex(String, Function)}),

     * use the key to find the collection of data that matches it.

     * @param indexName the name of an index

     * @param key a string value that matches a partition calculated from the partition

     *            function provided to {@link #registerIndex(String, Function)}

     * @return a collection of data, an empty collection if nothing found

     */

    @Override

    public Collection<T> getIndexedData(String indexName, String key) {

        // load data if needed

    }

    /**

     * This function will stop the minum.database persistence cleanly.

     * <p>

     * In order to do this, we need to wait for our threads

     * to finish their work.  In particular, we

     * have offloaded our file writes to [actionQueue], which

     * has an internal thread for serializing all actions

     * on our minum.database

     * </p>

     */

    @Override

    public void stop() {

    /**

     * Similar to {@link #stop()} but gives more control over how long

     * we'll wait before crashing it closed.  See {@link ActionQueue#stop(int, long)}

     */

    @Override

    public void stop(int count, long sleepTime) {

}

Mutations