Class DataModel

A class representing an abstract data model that can be easily encoded and decoded to and from a Bencodex.Types.Dictionary.

Inheriting this class and simply declaring properties allows an instance of the child class to encode its data into a Bencodex.Types.Dictionary where the encoded Bencodex.Types.Dictionary has the concrete class'es each property name as its key and the each corresponding property value as its value.

However, there are certain restrictions that apply when using this class:

The complete list of allowed property types are as follows:
- Primitive types: bool, int, long, BigInteger, ImmutableArray<byte>, Guid, Address, and string.
- Special types: Any type inherited from DataModel.
- Collective types:
  - System.Collections.Immutable.ImmutableList<T> where T is a primitive type.
  - System.Collections.Immutable.ImmutableDictionary<TKey, TValue> where
    - TKey is one of ImmutableArray<byte>, Address, Guid, and string.
    - TValue is a primitive type.
Value types are not allowed to be declared as nullable, not even as a generic type parameter. That is, types such as bool?, Address?, and ImmutableList<int?>are not allowed.
Reference types are not allowed to be assigned null. This will result in an Exception when Encode() is called.
Trying to assign null to any property or to a part of a collection will result in an Exception when DataModel(Dictionary) is called.

Inheritance

Object

DataModel

Inherited Members

Object.Equals(Object)

Object.Equals(Object, Object)

Object.GetHashCode()

System.Object.GetType()

Object.MemberwiseClone()

Object.ReferenceEquals(Object, Object)

System.Object.ToString()

Namespace: Libplanet.Store

Assembly: Libplanet.Store.dll

Syntax

public abstract class DataModel

Remarks

There are certain caveats for using this class:

Encoded data type is fixed to Bencodex.Types.Dictionary. As each property name is encoded into Bencodex.Types.Text as a key, it is advisable to give short names for properties. For example, int HP is better than int HealthPoint to reduce storage size and/or network traffic. As seen in the example above, actively use documented properties instead.
Property type of System.Collections.Immutable.ImmutableDictionary<TKey, TValue> is inefficient to encode and decode. Additional caution is needed when declaring System.Collections.Immutable.ImmutableDictionary<TKey, TValue> property type.
As supported types are limited, in particular, nullable types and nested collection types not being allowed, if a custom data model that isn't supported by this class is needed, manual implementation of encoding and decoding should be done separately.

Examples

The following example shows how this class can be used:

public class CharacterData : DataModel
{
    /// <summary>
    /// Name of the character.
    /// </summary>
    public string Name { get; private set; }

    /// <summary>
    /// Current level of the character.
    /// </summary>
    public int Level { get; private set; }

    /// <summary>
    /// Inventory of the character.
    /// </summary>
    public InventoryData Inv { get; private set; }

    public CharacterData(string name, int level, InventoryData inv)
        : base()
    {
        Name = name;
        Level = level;
        Inv = inv;
    }

    public CharacterData(Bencodex.Types.Dictionary encoded)
        : base(encoded)
    {
    }
}

public class InventoryData : DataModel
{
    /// <summary>
    /// The amount of gold in the inventory.
    /// </summary>
    public int Gold { get; private set; }

    public InventoryData(int gold)
        : base()
    {
        Gold = gold;
    }

    public InventoryData(Bencodex.Types.Dictionary encoded)
        : base(encoded)
    {
    }
}

Then the concrete model defined above can be used as shown below:

CharacterData characterData = new CharacterData("John", 5, new InventoryData(100));
Bencodex.Types.Dictionary encoded = characterData.Encode()

This would result in encoded in a following format:

Bencodex.Types.Dictionary {
  "Name": "John",
  "Level": 5,
  "Inv": {
      "Gold": 100,
  },
}

To decode this back into an instance, simply use it as shown below:

CharacterData decoded = new CharacterData(encoded);

Then decoded.Name, decoded.Level, and decoded.Inv.Gold will have values "John", 5, and 100 respectively.

Constructors

| Improve this Doc View Source

DataModel()

A class representing an abstract data model that can be easily encoded and decoded to and from a Bencodex.Types.Dictionary.

However, there are certain restrictions that apply when using this class:

The complete list of allowed property types are as follows:
- Primitive types: bool, int, long, BigInteger, ImmutableArray<byte>, Guid, Address, and string.
- Special types: Any type inherited from DataModel.
- Collective types:
  - System.Collections.Immutable.ImmutableList<T> where T is a primitive type.
  - System.Collections.Immutable.ImmutableDictionary<TKey, TValue> where
    - TKey is one of ImmutableArray<byte>, Address, Guid, and string.
    - TValue is a primitive type.
Value types are not allowed to be declared as nullable, not even as a generic type parameter. That is, types such as bool?, Address?, and ImmutableList<int?>are not allowed.
Reference types are not allowed to be assigned null. This will result in an Exception when Encode() is called.
Trying to assign null to any property or to a part of a collection will result in an Exception when DataModel(Dictionary) is called.

Declaration

protected DataModel()

Remarks

There are certain caveats for using this class:

Encoded data type is fixed to Bencodex.Types.Dictionary. As each property name is encoded into Bencodex.Types.Text as a key, it is advisable to give short names for properties. For example, int HP is better than int HealthPoint to reduce storage size and/or network traffic. As seen in the example above, actively use documented properties instead.
Property type of System.Collections.Immutable.ImmutableDictionary<TKey, TValue> is inefficient to encode and decode. Additional caution is needed when declaring System.Collections.Immutable.ImmutableDictionary<TKey, TValue> property type.
As supported types are limited, in particular, nullable types and nested collection types not being allowed, if a custom data model that isn't supported by this class is needed, manual implementation of encoding and decoding should be done separately.

Examples

The following example shows how this class can be used:

public class CharacterData : DataModel
{
    /// <summary>
    /// Name of the character.
    /// </summary>
    public string Name { get; private set; }

    /// <summary>
    /// Current level of the character.
    /// </summary>
    public int Level { get; private set; }

    /// <summary>
    /// Inventory of the character.
    /// </summary>
    public InventoryData Inv { get; private set; }

    public CharacterData(string name, int level, InventoryData inv)
        : base()
    {
        Name = name;
        Level = level;
        Inv = inv;
    }

    public CharacterData(Bencodex.Types.Dictionary encoded)
        : base(encoded)
    {
    }
}

public class InventoryData : DataModel
{
    /// <summary>
    /// The amount of gold in the inventory.
    /// </summary>
    public int Gold { get; private set; }

    public InventoryData(int gold)
        : base()
    {
        Gold = gold;
    }

    public InventoryData(Bencodex.Types.Dictionary encoded)
        : base(encoded)
    {
    }
}

Then the concrete model defined above can be used as shown below:

CharacterData characterData = new CharacterData("John", 5, new InventoryData(100));
Bencodex.Types.Dictionary encoded = characterData.Encode()

This would result in encoded in a following format:

Bencodex.Types.Dictionary {
  "Name": "John",
  "Level": 5,
  "Inv": {
      "Gold": 100,
  },
}

To decode this back into an instance, simply use it as shown below:

CharacterData decoded = new CharacterData(encoded);

Then decoded.Name, decoded.Level, and decoded.Inv.Gold will have values "John", 5, and 100 respectively.

| Improve this Doc View Source

DataModel(Dictionary)

Decodes a Bencodex.Types.Dictionary data into an instance.

Declaration

protected DataModel(Dictionary encoded)

Parameters

Type	Name	Description
Bencodex.Types.Dictionary	encoded	The Bencodex.Types.Dictionary instance to decode.

Remarks

There are certain caveats for using this class:

Encoded data type is fixed to Bencodex.Types.Dictionary. As each property name is encoded into Bencodex.Types.Text as a key, it is advisable to give short names for properties. For example, int HP is better than int HealthPoint to reduce storage size and/or network traffic. As seen in the example above, actively use documented properties instead.
Property type of System.Collections.Immutable.ImmutableDictionary<TKey, TValue> is inefficient to encode and decode. Additional caution is needed when declaring System.Collections.Immutable.ImmutableDictionary<TKey, TValue> property type.
As supported types are limited, in particular, nullable types and nested collection types not being allowed, if a custom data model that isn't supported by this class is needed, manual implementation of encoding and decoding should be done separately.

Exceptions

Type	Condition
NotSupportedException	Thrown when null value is encountered while decoding.
ArgumentException	Thrown when invalid encoded type is encountered.
System.NullReferenceException	Thrown when `encoded` is null or null reference is returned by inner instantiation.

Methods

| Improve this Doc View Source

Encode()

Encodes an instance into a Bencodex.Types.Dictionary.

Declaration

[Pure]
public Dictionary Encode()

Returns

Type	Description
Bencodex.Types.Dictionary	An encoded Bencodex.Types.Dictionary instance.

Remarks

There are certain caveats for using this class:

Encoded data type is fixed to Bencodex.Types.Dictionary. As each property name is encoded into Bencodex.Types.Text as a key, it is advisable to give short names for properties. For example, int HP is better than int HealthPoint to reduce storage size and/or network traffic. As seen in the example above, actively use documented properties instead.
Property type of System.Collections.Immutable.ImmutableDictionary<TKey, TValue> is inefficient to encode and decode. Additional caution is needed when declaring System.Collections.Immutable.ImmutableDictionary<TKey, TValue> property type.
As supported types are limited, in particular, nullable types and nested collection types not being allowed, if a custom data model that isn't supported by this class is needed, manual implementation of encoding and decoding should be done separately.

Exceptions

Type	Condition
NotSupportedException	Thrown when `nullable` value type property or null value inside a reference type is encountered.
ArgumentException	Thrown when an unknown invalid property type is encountered.