Module com.renomad.minum
Package com.renomad.minum.database

Class DbData<T>

java.lang.Object
com.renomad.minum.database.DbData<T>
Direct Known Subclasses:
Inmate
public abstract class DbData<T> extends Object
An abstract data type meant to be used with Db

The Minum database is very plain - data is stored in a strongly-typed Java data collection in memory, and also written to disk.

Each database is responsible for one type of data. For example, you might create a database for Person information, such as name, age, and favorite ice cream flavor. To do so, you would need a class representing the Person, and that is where the DbData class comes into play.

The properties of a person are defined as an implementation of this abstract class. It is necessary to supply an implementation of the serialize and deserialize methods, which are used to write this data to a string form, and back, respectively. There are examples provided on those methods suggesting serialization approaches, and it is highly recommended to stick close to that, since framework testing relied on it.

See the code at Inmate for a realistic example.

  • Constructor Summary

    Constructors
    Constructor
    Description
    DbData()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    protected abstract T
    deserialize(String serializedText)
    deserializes the text back into an object.
    protected abstract long
    getIndex()
    We need an index so that each piece of data is distinct, even if it has the same data.
    protected abstract String
    serialize()
    Serializes this object into a string representation.
    protected abstract void
    setIndex(long index)
    It is necessary for this method to exist because it is used by the Db code to add the new index into this data.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • DbData

      public DbData()

  • Method Details

    • serialize

      protected abstract String serialize()
      Serializes this object into a string representation. It will be the values of this object as strings, encoded with URL encoding, separated by pipe symbols.

      An example: 

              import static com.renomad.minum.utils.SerializationUtils.serializeHelper;

        public String serialize() {
            return serializeHelper(index, a, b);
        }
      Returns:
      this type serialized to a string - use SerializationUtils.serializeHelper(Object[])
      See Also:

    • deserialize

      protected abstract T deserialize(String serializedText)
      deserializes the text back into an object. See helper method SerializationUtils.deserializeHelper(String) to split a serialized string into tokens for rebuilding the object. See also serialize()

      An example: 

              import static com.renomad.minum.utils.SerializationUtils.deserializeHelper;

        public Foo deserialize(String serializedText) {
            final var tokens =  deserializeHelper(serializedText);
            return new Foo(
                    Integer.parseInt(tokens.get(0)),
                    Integer.parseInt(tokens.get(1)),
                    tokens.get(2)
                    );
        }
      Parameters:
      serializedText - the serialized string
      Returns:
      this type deserialized from a string
      See Also:

    • getIndex

      protected abstract long getIndex()
      We need an index so that each piece of data is distinct, even if it has the same data.
      Returns:
      an index for this data, used to name a file for this particular instance of data

    • setIndex

      protected abstract void setIndex(long index)
      It is necessary for this method to exist because it is used by the Db code to add the new index into this data.

      Let me unpack that a bit.

      The way our database works, it's expected that when you are creating a new instance of data, you won't know its index yet, because that is something the database manages for you.

      The index is an AtomicLong value that allows us to create new data without worrying about race conditions between threads (that is, we don't have to worry about two threads accidentally adding the same index value to two different datas).

      This value is also used as the name for the file of this data stored on disk, when using the Db database. (The DbEngine2 uses a different approach)