Package com.flora.db

Class FloraDB

java.lang.Object
com.flora.db.FloraDB
public class FloraDB extends Object
This is the main class of the database. This class is a utility class that provides static methods to perform database operations. You have to initialize this by init(File) method before calling any of the database method. Otherwise, a NullPointerException will be thrown. You also need to commit (commit()) to the database to save the changes. Not all methods requires committing. Methods that requires committing are clearly stated in the javadoc of that method.

  • Constructor Details

    • FloraDB

      public FloraDB()

  • Method Details

    • init

      public static void init(File databaseDir)
      Initialize the database with the directory provided. This may took longer time depending on your data size. This method runs synchronously (and it should be) and blocks thread until completed.
      Parameters:
      databaseDir - The directory where your database is located or should be created. Usually file dir of your application
      Throws:
      RuntimeException - If file is not a directory or is not writable

    • put

      public static void put(String id, Object data)
      Inserts a simple datatype into the database. Updates if id already exist. Requires commit() call.
      Parameters:
      id - ID of the data (like primary key)
      data - A String,Number or boolean value to insert into database

    • get

      public static Object get(String id, Object defaultValue)
      Gets the simple data from the database. (data inserted using put(String, Object) method
      Parameters:
      id - The unique id of the data.
      defaultValue - Value in case it does not exist in the database
      Returns:
      Value or defaultValue if none found.

    • createList

      public static <T> void createList(String id, T[] items)
      Creates and inserts a new list into the database. Updates if it already exist. You need to call commit() for this.
      Parameters:
      id - The id of the list
      items - The default items in the list

    • updateList

      public static <T> void updateList(String id, FloraDB.SyncedDataManager<List<T>> manager)
      Updates the list asynchronously from the interface deification. The FloraDB.SyncedDataManager.update(Object) method contains a list object. That list is the the list which is saved in the database. You can modify it and it will be reflected in the database. You don't need to call commit() for this.
      Parameters:
      id - The id of the list
      manager - Interface defining the list
      Throws:
      IllegalArgumentException - if there is no list with the id

    • createOrGetList

      public static <T> List<T> createOrGetList(String id)
      Creates a new syncable mutable list or gets if already exist. The returned list will be syncable and mutable, it means that any modification made to it will also be modified in the database. You need to however call commit() after calling this if you had modified it, Otherwise not.
      Parameters:
      id - The id of the list
      Returns:
      A syncable and mutable list

    • getList

      public static <T> List<T> getList(String id)
      Gets a non-syncable immutable list from the database. null if not exist
      Parameters:
      id - Id of the list
      Returns:
      List or null if not exist in the database
      Throws:
      ClassCastException - If the id is not of a list

    • createObject

      public static <T extends Syncable> void createObject(String id, T object)
      Creates and inserts a new object into the database. Updates if already exist Requires commit() call.
      Parameters:
      id - The id of the list
      object - Your POJO

    • createOrGetObject

      public static <T extends Syncable> T createOrGetObject(String id, Class<T> objClass)
      Creates a new syncable mutable object (POJO) or gets if already exist. The returned object will be syncable and mutable, it means that any modification made to it will also be modified in the database. You need to however call commit() after calling this if you had modified it, Otherwise not.
      Parameters:
      id - The id of the object
      objClass - The class type of your object.
      Returns:
      A syncable and mutable Object of generic type
      Throws:
      ClassCastException - If id is not of a valid syncable object

    • getObject

      public static <T extends Syncable> T getObject(String id, Class<T> type)
      Gets a syncable object (POJO) from the database. Mutable means that the object returned by this method can be further modified. You need to however call commit() after calling this if you had modified it, Otherwise not.
      Type Parameters:
      T - Type class of your POJO
      Parameters:
      id - Id of the object
      Returns:
      a POJO or null if not exist in the database
      Throws:
      IllegalArgumentException - If the id is not of a 'type' object or if the object cannot be casted to 'type' class.

    • updateObject

      public static <T> void updateObject(String id, FloraDB.SyncedDataManager<T> manager)
      Updates the object asynchronously from the interface deification. The FloraDB.SyncedDataManager.update(Object) method contains a provided class object. That object is the the POJO which is saved in the database. You can modify it and it will be reflected in the database. You don't need to call commit() for this.
      Type Parameters:
      T - Type class of your POJO
      Parameters:
      id - The id of the object
      manager - Interface defining the object
      Throws:
      IllegalArgumentException - if there is no object with the id

    • delete

      public static void delete(String id)
      Does as the name suggest. It require commit() call
      Parameters:
      id - Id of the data to delete

    • query

      public static Query query()

    • commit

      public static void commit()
      Saves and commits all the changes to database. This must be the last call on database as calling this will nullify and close all the streams related to database.
      Throws:
      RuntimeException - A checked-runtime exception when an IOException occurs. Runtime because there are extremely low chances of occurring most common types if IOException like FileNotFoundException (already handled while initializing). This may only occur when the underlying filesystem throws it. It is recommended not to handle it as it would indicate serious bug.

    • commitAsync

      public static void commitAsync(FloraDB.Callback callback)
      Similar as commit() but runs asynchronously. This will not block the thread.
      Parameters:
      callback - A optional callback that indicates success and failure of the commit.