MAGES Data Container

Overview

The MAGES Data Container is a critical component that provides a structured approach to storing and managing data within the application. It facilitates the use of schemas, enabling developers to organize and access data efficiently during RunTime.

A schema, in the context of the MAGES NXT framework, is a predefined structure or blueprint for organizing and storing data related to specific aspects of the application. It serves as a template that defines how data should be stored, accessed, and managed. Each schema is associated with a unique key pattern, allowing for categorization and differentiation between various types of data.

Schema

All the schemas in MAGES NXT implement the following interface. By default MAGES NXT offers the Event Schema, List Schema, and Count Schema.

  • Event Schema

    It stores data like a normal dictionary, if you store the data under an already existing key, it will be overwritten.

    Usage Example:

    DataContainerModule dataContainer = Hub.Instance.Get<DataContainerModule>();
dataContainer.SetSchema("eventSchema.*", typeof(EventSchema));
dataContainer.StoreData("eventSchema.number", 1);
dataContainer.StoreData("eventSchema.number", 1.5);
dataContainer.StoreData("eventSchema.anothernumber", 2);
dataContainer.StoreData("eventSchema.anothernumber", 5.5);

    After this code is executed the keys should contain the numbers 1.5 and 5.5, since the old values are overwritten.

  • List Schema

    It stores lists of data under a certain key. If you store data under an already existing key, the new data will be added to the list.

    Usage Example:

    dataContainer.SetSchema("ListSchema.*", typeof(ListSchema));
dataContainer.StoreData("ListSchema.number", 1);
dataContainer.StoreData("ListSchema.number", 1.5);
dataContainer.StoreData("ListSchema.anothernumber", 2);
dataContainer.StoreData("ListSchema.anothernumber", 5.5);

    Similarly, after executing this code, the keys should contain the List [1, 1.5] and the List [2, 2.5]

  • Count Schema

    Similar to the Event Schema, however, if you store data under an already existing key, it will merge the two values. The merging is done by implementing the IMerger interface for a specific data type you wish to merge. After that, you will also need to register the new Merger inside the MergerRegistry Singleton.

    Usage Example:

    DataContainerModule dataContainer = Hub.Instance.Get<DataContainerModule>();
dataContainer.SetSchema("countSchema.*", typeof(CountSchema));
dataContainer.StoreData("countSchema.number", 1);
dataContainer.StoreData("countSchema.number", 1.5);
dataContainer.StoreData("countSchema.anothernumber", 2);
dataContainer.StoreData("countSchema.anothernumber", 5.5);

    Since there’s already a merger for numbers, that adds the already existing value with the new one, the keys countSchema.number and countSchema.anothernumber should contain the numbers 2.5 and 7.5 after running this code.

You can also implement your own schemas, following your own patterns by implementing the interface.

/// <summary>
/// Interface of the Schema.
/// </summary>
public interface ISchema
{
    /// <summary>
    /// Stores the data under the given key.
    /// </summary>
    /// <param name="key">Dictionary key.</param>
    /// <param name="data">Data to be stored.</param>
    void Store(string key, object data);

    /// <summary>
    /// Retrieves the data under the given key.
    /// </summary>
    /// <param name="key">The lookup key.</param>
    /// <returns>The data under the key.</returns>
    object Get(string key);

    /// <summary>
    /// Gets all the data under the given key pattern.
    /// </summary>
    /// <param name="keyPattern">Given key pattern.</param>
    /// <returns>The data under certain schema.</returns>
    Dictionary<string, object> GetAllData(string keyPattern);

    /// <summary>
    /// Deletes the data under the given key.
    /// </summary>
    /// <param name="key">Given key.</param>
    void DeleteData(string key);

    /// <summary>
    /// Deletes data of subschema under the given key pattern.
    /// </summary>
    /// <param name="keyPattern">Given key pattern.</param>
    void DeleteAllData(string keyPattern);

    /// <summary>
    /// Get specific sub-convention/pattern data under the given key pattern.
    /// </summary>
    /// <param name="keyPattern">Given key pattern.</param>
    /// <returns>Dictionary of data.</returns>
    List<KeyValuePair<string, object>> GetSpecificData(string keyPattern);

    /// <summary>
    /// Delete specific sub-convention/pattern data under the given key pattern.
    /// </summary>
    /// <param name="keyPattern">Given key pattern.</param>
    void DeleteSpecificData(string keyPattern);

    /// <summary>
    /// Clears all data.
    /// </summary>
    void ClearAllData();
}

Merger

In order to implement Mergers for the Count Schema, you need to implement the following interface.

/// <summary>
/// Interface for merging two objects of the same type.
/// </summary>
public interface IMerger
{
    /// <summary>
    /// Gets target type of the merger.
    /// </summary>
    Type TargetType { get; }

    /// <summary>
    /// Merge two objects of the same type.
    /// </summary>
    /// <param name="obj1">The first object.</param>
    /// <param name="obj2">The second object.</param>
    /// <returns>The merged object.</returns>
    object Merge(object obj1, object obj2);
}

And then add the Merger you implemented to the MergerRegistry likeso.

MergerRegistry.Instance.RegisterMerger(new MyMerger());

Data Container

The MAGES Data Container implements the following interface.

/// <summary>
/// The data container module base class.
/// </summary>
public abstract class DataContainerModule : HubModule
{
    /// <summary>
    /// Sets the schema for the data container.
    /// </summary>
    /// <param name="keyPattern">The convention/pattern the Schema is created under, i.e mages.actions.* .</param>
    /// <param name="schemaType">The type of the Schema.</param>
    public abstract void SetSchema(string keyPattern, Type schemaType);

    /// <summary>
    /// Stores value in the data container under the given key.
    /// </summary>
    /// <param name="key">The key of the data container.</param>
    /// <param name="value">The value to be stored.</param>
    public abstract void StoreData(string key, object value);

    /// <summary>
    /// Get the data from the data container under the given key.
    /// </summary>
    /// <param name="key">The given key.</param>
    /// <returns>The value under the given key.</returns>
    public abstract object GetData(string key);

    /// <summary>
    /// Returns the schema data for the given key pattern.
    /// </summary>
    /// <param name="keyPattern">The convention/pattern.</param>
    /// <returns>A dictionary with the data of the whole Schema under the given convention/pattern.</returns>
    public abstract Dictionary<string, object> GetSchemaData(string keyPattern);

    /// <summary>
    /// Deletes the data under the given key.
    /// </summary>
    /// <param name="key">The key to be deleted.</param>
    public abstract void DeleteData(string key);

    /// <summary>
    /// Deletes the schema under the given key pattern.
    /// </summary>
    /// <param name="keyPattern">The convention/pattern of the schema to be deleted.</param>
    public abstract void DeleteSchema(string keyPattern);

    /// <summary>
    /// Returns the data of the schema under the given key pattern.
    /// </summary>
    /// <param name="keyPattern">The key pattern of the data under the Schema.</param>
    /// <returns>Returns a dictionary of the data that are stored under the given keyPattern.</returns>
    public abstract List<KeyValuePair<string, object>> GetSpecificSchemaData(string keyPattern);

    /// <summary>
    ///  Deletes the data of the schema under the given key pattern.
    /// </summary>
    /// <param name="keyPattern">The key pattern of the data under the Schema.</param>
    public abstract void DeleteSpecificSchemaData(string keyPattern);

    /// <summary>
    /// Clears all data and all schemas.
    /// </summary>
    public abstract void ClearAllData();
}

Examples of Usage

For more information regarding the Hub refer to TODO ADD HUB PAGE.

Access MAGES Data Container:

var dataContainer = Hub.Instance.Get<DataContainerModule>()

Set Schema and Store Data:

dataContainer.SetSchema("mages.actions.*", typeof(MyActionSchema));
dataContainer.StoreData("mages.actions.myAction.dataKey", myData);

Retrieve Data:

var retrievedData = dataContainer.GetData("mages.actions.myAction.dataKey");

Delete Schema and Specific Schema Data:

dataContainer.DeleteSpecificSchemaData("mages.actions.myAction.*");
dataContainer.DeleteSchema("mages.actions.*");