Package com.jummania

Interface DataManager

public interface DataManager
Interface for managing data operations such as saving, retrieving, and deleting key-value data, including support for JSON serialization, pagination, and list management.

Implementations of this interface should provide persistent or in-memory storage functionality.

Created by Jummania on 20, November, 2024. Email: sharifuddinjumman@gmail.com Dhaka, Bangladesh.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    DataManager.Converter
     
    static interface 
    DataManager.DataObserver
     

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addDataObserver (DataManager.DataObserver observer)
    Registers a DataManager.DataObserver to listen for data changes.
    default void
    appendToList (String key, int index, Object element)
    Appends an element to a list associated with the given key at the specified index.
    void
    appendToList (String key, int index, Object element, boolean removeDuplicate)
    Appends an element to a list associated with the given key at the specified index.
    default void
    appendToList (String key, Object element)
    Appends an element to a list associated with the given key.
    default void
    appendToList (String key, Object element, boolean removeDuplicate)
    Appends an element to a list associated with the given key.
    void
    clear()
    Clears all entries from the data structure.
    boolean
    contains (String key)
    Checks if the data structure contains an entry associated with the given key.
    <T> T
    fromJson (String value, Type typeOfT)
    Converts a JSON string into an object of the specified type.
    <T> T
    fromReader (Reader json, Type typeOfT)
    Converts a JSON input stream (Reader) into an object of the specified type.
    default boolean
    getBoolean (String key)
    Retrieves a boolean value associated with the given key.
    default boolean
    getBoolean (String key, boolean defValue)
    Retrieves a boolean value associated with the given key.
    default float
    getFloat (String key)
    Retrieves a float value associated with the given key.
    default float
    getFloat (String key, float defValue)
    Retrieves a float value associated with the given key.
    <T> List<T>
    getFullList (String key, Type type)
    Retrieves a list of objects of the specified type associated with the given key.
    default int
    getInt (String key)
    Retrieves an integer value associated with the given key.
    default int
    getInt (String key, int defValue)
    Retrieves an integer value associated with the given key.
    default long
    getLong (String key)
    Retrieves a long value associated with the given key.
    default long
    getLong (String key, long defValue)
    Retrieves a long value associated with the given key.
    <T> T
    getObject (String key, Type type)
    Retrieves an object of the specified type associated with the given key.
    <T> PaginatedData<T>
    getPagedList (String key, Type type, int page)
    Retrieves a paginated list of objects of the specified type associated with the given key.
    Type
    getParameterized (Type rawType, Type... typeArguments)
    Creates a parameterized Type using the specified raw type and type arguments.
    String
    getRawString (String key)
    Retrieves the raw string value associated with the given key.
    default String
    getString (String key)
    Retrieves a string value associated with the given key.
    default String
    getString (String key, String defValue)
    Retrieves a string value associated with the given key.
    void
    remove (String key)
    Removes the entry associated with the given key.
    void
    removeDataObserver()
    Unregisters the currently registered DataManager.DataObserver.
    void
    removeFromList (String key, int index)
    Removes an element from the list associated with the given key at the specified index.
    default void
    saveBoolean (String key, boolean value)
    Saves a boolean value associated with the given key by converting the boolean to a string.
    default void
    saveFloat (String key, float value)
    Saves a float value associated with the given key by converting the float to a string.
    default void
    saveInt (String key, int value)
    Saves an integer value associated with the given key by converting the integer to a string.
    default <E> void
    saveList (String key, List<E> value)
    Saves a list of objects associated with the given key by converting the list to a JSON string.
    <E> void
    saveList (String key, List<E> value, int maxArraySize)
    Saves a list of objects associated with the given key by converting the list to a JSON string.
    default void
    saveLong (String key, long value)
    Saves a long value associated with the given key by converting the long to a string.
    default void
    saveObject (String key, Object value)
    Saves an object associated with the given key by converting the object to a JSON string.
    void
    saveString (String key, String value)
    Saves a string value associated with the given key.
    String
    toJson (Object object)
    Converts an object into its JSON string representation.

  • Method Details

    • getString

      default String getString (String key, String defValue)
      Retrieves a string value associated with the given key. If no value is found or the value is null, returns the provided default value.
      Parameters:
      key - the key to look up the value
      defValue - the default value to return if no value is found or if the result is null
      Returns:
      the retrieved string value or the default value if not found

    • getString

      default String getString (String key)
      Retrieves a string value associated with the given key. If no value is found or the value is null, returns null.

      This is a shorthand method that calls getString(String, String) with a default value of null.

      Parameters:
      key - the key to look up the value
      Returns:
      the retrieved string value or null if not found

    • getInt

      default int getInt (String key, int defValue)
      Retrieves an integer value associated with the given key. If no value is found or the value is null, returns the provided default value.
      Parameters:
      key - the key to look up the value
      defValue - the default value to return if no value is found or if the result is null
      Returns:
      the retrieved integer value or the default value if not found

    • getInt

      default int getInt (String key)
      Retrieves an integer value associated with the given key. If no value is found or the value is null, returns 0.

      This is a shorthand method that calls getInt(String, int) with a default value of 0.

      Parameters:
      key - the key to look up the value
      Returns:
      the retrieved integer value or 0 if not found

    • getLong

      default long getLong (String key, long defValue)
      Retrieves a long value associated with the given key. If no value is found or the value is null, returns the provided default value.
      Parameters:
      key - the key to look up the value
      defValue - the default value to return if no value is found or if the result is null
      Returns:
      the retrieved long value or the default value if not found

    • getLong

      default long getLong (String key)
      Retrieves a long value associated with the given key. If no value is found or the value is null, returns 0.

      This is a shorthand method that calls getLong(String, long) with a default value of 0.

      Parameters:
      key - the key to look up the value
      Returns:
      the retrieved long value or 0 if not found

    • getFloat

      default float getFloat (String key, float defValue)
      Retrieves a float value associated with the given key. If no value is found or the value is null, returns the provided default value.
      Parameters:
      key - the key to look up the value
      defValue - the default value to return if no value is found or if the result is null
      Returns:
      the retrieved float value or the default value if not found

    • getFloat

      default float getFloat (String key)
      Retrieves a float value associated with the given key. If no value is found or the value is null, returns 0.

      This is a shorthand method that calls getFloat(String, float) with a default value of 0.

      Parameters:
      key - the key to look up the value
      Returns:
      the retrieved float value or 0 if not found

    • getBoolean

      default boolean getBoolean (String key, boolean defValue)
      Retrieves a boolean value associated with the given key. If no value is found or the value is null, returns the provided default value.
      Parameters:
      key - the key to look up the value
      defValue - the default value to return if no value is found or if the result is null
      Returns:
      the retrieved boolean value or the default value if not found

    • getBoolean

      default boolean getBoolean (String key)
      Retrieves a boolean value associated with the given key. If no value is found or the value is null, returns false.

      This is a shorthand method that calls getBoolean(String, boolean) with a default value of false.

      Parameters:
      key - the key to look up the value
      Returns:
      the retrieved boolean value or false if not found

    • getRawString

      String getRawString (String key)
      Retrieves the raw string value associated with the given key. The value is returned as-is, without any defaulting behavior.
      Parameters:
      key - the key to look up the value
      Returns:
      the raw string value associated with the key, or null if not found

    • getObject

      <T> T getObject (String key, Type type)
      Retrieves an object of the specified type associated with the given key. The object is deserialized from the underlying data source to match the specified type.
      Type Parameters:
      T - the type of the object to be returned
      Parameters:
      key - the key to look up the object
      type - the type of the object to be returned
      Returns:
      the object of the specified type associated with the key, or null if not found or if the type doesn't match

    • getFullList

      <T> List<T> getFullList (String key, Type type)
      Retrieves a list of objects of the specified type associated with the given key. The list is deserialized from the underlying data source to match the specified type.
      Type Parameters:
      T - the type of the objects in the list
      Parameters:
      key - the key to look up the list of objects
      type - the type of the objects in the list
      Returns:
      the list of objects of the specified type associated with the key, or an empty list if not found

    • getPagedList

      <T> PaginatedData<T> getPagedList (String key, Type type, int page)
      Retrieves a paginated list of objects of the specified type associated with the given key. The list is deserialized from the underlying data source to match the specified type, with pagination support.
      Type Parameters:
      T - the type of the objects in the list
      Parameters:
      key - the key to look up the paginated list of objects
      type - the type of the objects in the list
      page - the page number to retrieve
      Returns:
      a PaginatedData object containing the paginated list of objects of the specified type, or an empty paginated data if no objects are found

    • saveString

      void saveString (String key, String value)
      Saves a string value associated with the given key. If the key already exists, the value will be updated.
      Parameters:
      key - the key to associate with the string value
      value - the string value to save

    • saveInt

      default void saveInt (String key, int value)
      Saves an integer value associated with the given key by converting the integer to a string. If the key already exists, the value will be updated.

      This is a shorthand method that calls saveString(String, String) by converting the integer value to a string.

      Parameters:
      key - the key to associate with the integer value
      value - the integer value to save

    • saveLong

      default void saveLong (String key, long value)
      Saves a long value associated with the given key by converting the long to a string. If the key already exists, the value will be updated.

      This is a shorthand method that calls saveString(String, String) by converting the long value to a string.

      Parameters:
      key - the key to associate with the long value
      value - the long value to save

    • saveFloat

      default void saveFloat (String key, float value)
      Saves a float value associated with the given key by converting the float to a string. If the key already exists, the value will be updated.

      This is a shorthand method that calls saveString(String, String) by converting the float value to a string.

      Parameters:
      key - the key to associate with the float value
      value - the float value to save

    • saveBoolean

      default void saveBoolean (String key, boolean value)
      Saves a boolean value associated with the given key by converting the boolean to a string. If the key already exists, the value will be updated.

      This is a shorthand method that calls saveString(String, String) by converting the boolean value to a string.

      Parameters:
      key - the key to associate with the boolean value
      value - the boolean value to save

    • saveObject

      default void saveObject (String key, Object value)
      Saves an object associated with the given key by converting the object to a JSON string. If the key already exists, the value will be updated.

      This is a shorthand method that calls saveString(String, String) by converting the object to a JSON string using toJson(Object).

      Parameters:
      key - the key to associate with the object
      value - the object to save

    • saveList

      <E> void saveList (String key, List<E> value, int maxArraySize)
      Saves a list of objects associated with the given key by converting the list to a JSON string. If the key already exists, the value will be updated. The size of the list is capped to the specified maximum array size.
      Type Parameters:
      E - the type of elements in the list
      Parameters:
      key - the key to associate with the list of objects
      value - the list of objects to save
      maxArraySize - the maximum number of elements in the list to be saved

    • saveList

      default <E> void saveList (String key, List<E> value)
      Saves a list of objects associated with the given key by converting the list to a JSON string. If the key already exists, the value will be updated. The size of the list is capped to 25 elements.

      This is a shorthand method that calls saveList(String, List, int) with a default maximum array size of 25.

      Type Parameters:
      E - the type of elements in the list
      Parameters:
      key - the key to associate with the list of objects
      value - the list of objects to save

    • appendToList

      void appendToList (String key, int index, Object element, boolean removeDuplicate)
      Appends an element to a list associated with the given key at the specified index. If the list does not exist, a new list will be created. Optionally, duplicates can be removed before appending the element.
      Parameters:
      key - the key to identify the list
      index - the position at which to insert the element in the list
      element - the element to append to the list
      removeDuplicate - whether to remove duplicate elements before appending the new element

    • appendToList

      default void appendToList (String key, int index, Object element)
      Appends an element to a list associated with the given key at the specified index. If the list does not exist, a new list will be created. Duplicates are not removed by default.

      This is a shorthand method that calls appendToList(String, int, Object, boolean) with the `removeDuplicate` flag set to false.

      Parameters:
      key - the key to identify the list
      index - the position at which to insert the element in the list
      element - the element to append to the list

    • appendToList

      default void appendToList (String key, Object element, boolean removeDuplicate)
      Appends an element to a list associated with the given key. The element is added at the end of the list. If the list does not exist, a new list will be created. Optionally, duplicates can be removed before appending the element.

      This is a shorthand method that calls appendToList(String, int, Object, boolean) with the index set to -1, indicating the element should be appended to the end of the list.

      Parameters:
      key - the key to identify the list
      element - the element to append to the list
      removeDuplicate - whether to remove duplicate elements before appending the new element

    • appendToList

      default void appendToList (String key, Object element)
      Appends an element to a list associated with the given key. The element is added at the end of the list. If the list does not exist, a new list will be created. Duplicates are not removed by default.

      This is a shorthand method that calls appendToList(String, Object, boolean) with the index set to -1 and the `removeDuplicate` flag set to false, meaning the element will be added to the end of the list without removing duplicates.

      Parameters:
      key - the key to identify the list
      element - the element to append to the list

    • removeFromList

      void removeFromList (String key, int index)
      Removes an element from the list associated with the given key at the specified index. If the list does not contain an element at the given index, no changes will be made.
      Parameters:
      key - the key to identify the list
      index - the position of the element to remove from the list

    • fromJson

      <T> T fromJson (String value, Type typeOfT)
      Converts a JSON string into an object of the specified type. This method deserializes the given JSON string into an instance of the provided type using the Gson library (or similar).
      Type Parameters:
      T - the type of the object to return
      Parameters:
      value - the JSON string to deserialize
      typeOfT - the Type of the object to convert the JSON string into
      Returns:
      the deserialized object of the specified type

    • fromReader

      <T> T fromReader (Reader json, Type typeOfT)
      Converts a JSON input stream (Reader) into an object of the specified type. This method deserializes the provided JSON from the given reader into an instance of the provided type.
      Type Parameters:
      T - the type of the object to return
      Parameters:
      json - the Reader that contains the JSON data to deserialize
      typeOfT - the Type of the object to convert the JSON data into
      Returns:
      the deserialized object of the specified type

    • toJson

      String toJson (Object object)
      Converts an object into its JSON string representation. This method serializes the given object into a JSON string using a serialization library such as Gson.
      Parameters:
      object - the object to serialize into JSON
      Returns:
      the JSON string representation of the object

    • getParameterized

      Type getParameterized (Type rawType, Type... typeArguments)
      Creates a parameterized Type using the specified raw type and type arguments. This method is useful when dealing with generic types and allows the creation of a Type that can represent a generic type with its actual type parameters.
      Parameters:
      rawType - the raw type of the generic type (e.g., List)
      typeArguments - the type arguments that the generic type should use (e.g., String)
      Returns:
      the parameterized type representing the raw type with the provided type arguments

    • remove

      void remove (String key)
      Removes the entry associated with the given key. If the key does not exist, no changes will be made.
      Parameters:
      key - the key identifying the entry to remove

    • clear

      void clear()
      Clears all entries from the data structure. After calling this method, the data structure will be empty.

    • contains

      boolean contains (String key)
      Checks if the data structure contains an entry associated with the given key.
      Parameters:
      key - the key to check for existence in the data structure
      Returns:
      true if the key exists in the data structure, false otherwise

    • addDataObserver

      void addDataObserver (DataManager.DataObserver observer)
      Registers a DataManager.DataObserver to listen for data changes.
      Parameters:
      observer - The observer to be registered.

    • removeDataObserver

      void removeDataObserver()
      Unregisters the currently registered DataManager.DataObserver.