Mappers¶

public interface IRdfEntityMapper<TRdfDefinition, TEntity>
    where TRdfDefinition : class, IRdfDefinition
    where TEntity : class, IEntity
{
    /// <summary>
    /// Returns true if this mapper can handle the given RDF class (type) of this resource.
    /// Matches both unqualified (e.g., "BaseVoltage") and qualified (e.g., "cim:BaseVoltage") names.
    /// </summary>
    bool CanMap(string className);

    /// <summary>
    /// Creates a domain entity from the given RDF definition.
    /// Returns null if the definition does not have required data.
    /// </summary>
    /// <param name="definition">The RDF definition to map from.</param>
    /// <returns>The mapped domain entity, or null if mapping is not possible.</returns>
    TEntity? Map(TRdfDefinition definition);

    /// <summary>
    /// Gets a value indicating whether this mapper supports reverse mapping (entity to RDF definition).
    /// </summary>
    /// <returns><c>true</c> if reverse mapping is supported; otherwise, <c>false</c>.</returns>
    bool CanUnmap => false;

    /// <summary>
    /// Creates an RDF definition from the given domain entity.
    /// Returns null if reverse mapping is not supported or the entity cannot be converted.
    /// </summary>
    /// <param name="entity">The entity to convert to an RDF definition.</param>
    /// <returns>An RDF definition representing the entity, or null if conversion fails or is not supported.</returns>
    TRdfDefinition? Unmap(TEntity entity) => null;
}

public interface IRdfEntityMapper<TRdfDefinition, TEntity, TKey> : IRdfEntityMapper<TRdfDefinition, TEntity>
    where TRdfDefinition : class, IRdfDefinition
    where TEntity : class, IEntity<TKey>
{
    // Inherits all methods from IRdfEntityMapper<TRdfDefinition, TEntity>
    // Used for type safety when working with keyed entities
}

public interface IRdfEntityMapperFactory
{
    /// <summary>
    /// Gets the RDF entity mapper for the specified entity type.
    /// </summary>
    IRdfEntityMapper<TRdfDefinition, TEntity> GetMapper<TRdfDefinition, TEntity>()
        where TRdfDefinition : class, IRdfDefinition
        where TEntity : class, IEntity;

    /// <summary>
    /// Gets the RDF entity mapper for the specified entity type and key type.
    /// </summary>
    IRdfEntityMapper<TRdfDefinition, TEntity, TKey> GetMapper<TRdfDefinition, TEntity, TKey>()
        where TRdfDefinition : class, IRdfDefinition
        where TEntity : class, IEntity<TKey>;
}

public interface IRdfDefinition
{
    /// <summary>
    /// The resource identifier, as used in rdf:ID or rdf:about.
    /// </summary>
    string Id { get; }

    /// <summary>
    /// The RDF type (class) of this resource, expressed as a qualified name.
    /// Example: "cim:ACLineSegment" in <cim:ACLineSegment rdf:ID="...">
    /// </summary>
    string ClassName { get; }

    /// <summary>
    /// Collection of properties defined on this resource.
    /// </summary>
    IList<IRdfProperty> Properties { get; }
}

public interface IRdfDescription
{
    /// <summary>
    /// Gets the resource URI referenced by rdf:about.
    /// </summary>
    string About { get; }

    /// <summary>
    /// Collection of properties defined on this resource.
    /// </summary>
    IList<IRdfProperty> Properties { get; }
}

public interface IRdfProperty
{
    /// <summary>
    /// Gets the qualified property name.
    /// </summary>
    string Name { get; }
}

public class MyEntityMapper : IRdfEntityMapper<MyRdfDefinition, MyEntity, Guid>
{
    private readonly ICimIdentifierParser _identifierParser;
    private readonly ICimValueParser _valueParser;

    public MyEntityMapper(ICimIdentifierParser identifierParser, ICimValueParser valueParser)
    {
        _identifierParser = identifierParser;
        _valueParser = valueParser;
    }

    #region Forward Mapping (RDF → Entity)

    public bool CanMap(string className)
    {
        if (string.IsNullOrWhiteSpace(className))
            return false;

        var name = className.Trim();
        return name.Equals("MyEntity", StringComparison.Ordinal)
            || name.EndsWith(":MyEntity", StringComparison.Ordinal);
    }

    public MyEntity? Map(MyRdfDefinition definition)
    {
        if (definition == null)
            return null;

        // 1. Extract and validate identity using CIM identifier parser
        if (!_identifierParser.TryParseGuid(definition.Id, out var entityId))
            return null;

        // 2. Extract properties from definition
        var name = GetPropertyValue(definition, "name") ?? $"MyEntity:{entityId:D}";

        // 3. Parse typed values using value parser
        var valueStr = GetPropertyValue(definition, "value");
        if (!_valueParser.TryParseFloat(valueStr, out var value))
            return null;

        // 4. Construct domain entity with validated data
        return new MyEntity(entityId, name, value);
    }

    private string? GetPropertyValue(MyRdfDefinition definition, string propertyName)
    {
        // Implementation depends on your RdfDefinition structure
        return definition.Properties
            .FirstOrDefault(p => p.Name.EndsWith(propertyName, StringComparison.Ordinal))
            ?.ToString();
    }

    #endregion

    #region Reverse Mapping (Entity → RDF)

    public bool CanUnmap => true;

    public MyRdfDefinition? Unmap(MyEntity entity)
    {
        if (entity == null)
            return null;

        // Create definition with ID and type
        var definition = new MyRdfDefinition(
            id: entity.Id.ToString("D"),
            type: "ns:MyEntity"
        );

        // Add properties
        definition.Properties.Add(new MyLiteralProperty("ns:name", entity.Name));
        definition.Properties.Add(new MyLiteralProperty("ns:value", entity.Value.ToString()));

        return definition;
    }

    #endregion
}

public class RdfEntityMapperFactory : IRdfEntityMapperFactory, ITransientDependency
{
    private readonly IServiceProvider _serviceProvider;
    private readonly Lazy<Dictionary<Type, Type>> _mapperTypes;

    public RdfEntityMapperFactory(IServiceProvider serviceProvider)
    {
        _serviceProvider = serviceProvider;
        _mapperTypes = new Lazy<Dictionary<Type, Type>>(DiscoverMapperTypes);
    }

    private Dictionary<Type, Type> DiscoverMapperTypes()
    {
        var result = new Dictionary<Type, Type>();

        var assemblyFinder = _serviceProvider.GetService<IAssemblyFinder>();
        if (assemblyFinder == null)
            return result;

        foreach (var assembly in assemblyFinder.Assemblies)
        {
            Type[] types;
            try { types = assembly.GetTypes(); }
            catch { continue; }

            foreach (var type in types)
            {
                if (type.IsAbstract || type.IsInterface)
                    continue;

                var interfaces = type.GetInterfaces()
                    .Where(i => i.IsGenericType)
                    .Where(i =>
                    {
                        var def = i.GetGenericTypeDefinition();
                        return def == typeof(IRdfEntityMapper<,>) 
                            || def == typeof(IRdfEntityMapper<,,>);
                    });

                foreach (var iface in interfaces)
                {
                    result[iface] = type;
                }
            }
        }

        return result;
    }

    public virtual IRdfEntityMapper<TRdfDefinition, TEntity> GetMapper<TRdfDefinition, TEntity>()
        where TRdfDefinition : class, IRdfDefinition
        where TEntity : class, IEntity
    {
        var targetInterface = typeof(IRdfEntityMapper<TRdfDefinition, TEntity>);

        if (_mapperTypes.Value.TryGetValue(targetInterface, out var mapperType))
        {
            return (IRdfEntityMapper<TRdfDefinition, TEntity>)_serviceProvider.GetRequiredService(mapperType);
        }

        var mapper = _serviceProvider.GetService<IRdfEntityMapper<TRdfDefinition, TEntity>>();
        if (mapper != null)
            return mapper;

        throw new InvalidOperationException(
            $"No IRdfEntityMapper<{typeof(TRdfDefinition).Name}, {typeof(TEntity).Name}> implementation was found or registered. " +
            "Ensure a concrete mapper class implements IRdfEntityMapper<TRdfDefinition, TEntity> and is registered in DI.");
    }

    public virtual IRdfEntityMapper<TRdfDefinition, TEntity, TKey> GetMapper<TRdfDefinition, TEntity, TKey>()
        where TRdfDefinition : class, IRdfDefinition
        where TEntity : class, IEntity<TKey>
    {
        var targetInterface = typeof(IRdfEntityMapper<TRdfDefinition, TEntity, TKey>);

        if (_mapperTypes.Value.TryGetValue(targetInterface, out var mapperType))
        {
            return (IRdfEntityMapper<TRdfDefinition, TEntity, TKey>)_serviceProvider.GetRequiredService(mapperType);
        }

        var mapper = _serviceProvider.GetService<IRdfEntityMapper<TRdfDefinition, TEntity, TKey>>();
        if (mapper != null)
            return mapper;

        // Fallback: Try non-keyed mapper if it also implements keyed interface
        var nonKeyedMapper = _serviceProvider.GetService<IRdfEntityMapper<TRdfDefinition, TEntity>>();
        if (nonKeyedMapper is IRdfEntityMapper<TRdfDefinition, TEntity, TKey> keyedMapper)
            return keyedMapper;

        throw new InvalidOperationException(
            $"No IRdfEntityMapper<{typeof(TRdfDefinition).Name}, {typeof(TEntity).Name}, {typeof(TKey).Name}> implementation was found or registered. " +
            "Ensure a concrete mapper class implements IRdfEntityMapper<TEntity, TRdfDefinition, TKey> and is registered in DI.");
    }
}

public class ReadOnlyEntityMapper : IRdfEntityMapper<MyRdfDefinition, ReadOnlyEntity, Guid>
{
    public bool CanMap(string className) => className.EndsWith(":ReadOnlyEntity");

    public ReadOnlyEntity? Map(MyRdfDefinition definition)
    {
        // Forward mapping implementation
    }

    // CanUnmap defaults to false (from interface default)
    // Unmap defaults to returning null (from interface default)
}

public class CrudEntityMapper : IRdfEntityMapper<MyRdfDefinition, CrudEntity, Guid>
{
    // Forward mapping
    public bool CanMap(string className) => className.EndsWith(":CrudEntity");
    public CrudEntity? Map(MyRdfDefinition definition) { /* ... */ }

    // Reverse mapping - override defaults
    public bool CanUnmap => true;
    public MyRdfDefinition? Unmap(CrudEntity entity)
    {
        if (entity == null) return null;

        var definition = new MyRdfDefinition(entity.Id.ToString("D"), "ns:CrudEntity");
        // Add properties...
        return definition;
    }
}

public class RdfGraphRepository<TGraphContext, TRdfDefinition, TEntity> : RdfRepositoryBase<TEntity>, IRdfGraphRepository<TEntity>
    where TGraphContext : class, IRdfGraphContext
    where TRdfDefinition : class, IRdfDefinition
    where TEntity : class, IEntity
{
    protected TGraphContext GraphContext { get; }
    protected IRdfInstanceReader<TRdfDefinition> Reader { get; }
    protected IRdfInstanceWriter<TRdfDefinition> Writer { get; }
    protected IRdfEntityMapperFactory MapperFactory { get; }

    protected IRdfEntityMapper<TRdfDefinition, TEntity> Mapper => 
        _mapper ??= MapperFactory.GetMapper<TRdfDefinition, TEntity>();
    private IRdfEntityMapper<TRdfDefinition, TEntity>? _mapper;

    // Repository uses Mapper.CanMap() and Mapper.Map() for read operations
    // Repository uses Mapper.CanUnmap and Mapper.Unmap() for write operations
}

// Repository checks mapper capability before write operations
public virtual TEntity Insert(TEntity entity)
{
    if (!Mapper.CanUnmap)
        throw new NotSupportedException(
            $"Mapper for {typeof(TEntity).Name} does not support reverse mapping. " +
            "Implement CanUnmap and Unmap in your mapper.");

    var definition = Mapper.Unmap(entity);
    if (definition == null)
        throw new InvalidOperationException(
            $"Mapper returned null when converting {typeof(TEntity).Name} to RDF definition.");

    if (Writer.Exists(graph, definition.Id))
        throw new InvalidOperationException($"Instance with id '{definition.Id}' already exists. Use Update instead.");

    Writer.Insert(graph, definition);
    return entity;
}

// RdfEntityMapperFactory discovers mappers automatically
// because they implement IRdfEntityMapper<TRdfDefinition, TEntity> 
// or IRdfEntityMapper<TRdfDefinition, TEntity, TKey>

// Get repository with graph context
var repository = serviceProvider.GetRequiredService<IRdfGraphRepository<MyEntity, Guid>>();

// Find by ID - uses Map() internally
var entity = repository.Find(Guid.Parse("c24a1f3e-..."));

// Get list - uses Map() for each definition
var entities = repository.GetList();

// Create new entity
var newEntity = new MyEntity(Guid.NewGuid(), "Name", 42.0f);

// Insert uses Unmap() internally
repository.Insert(newEntity);

// Update uses Unmap() internally  
entity.Name = "Updated Name";
repository.Update(entity);

// Upsert uses Unmap() internally
repository.Upsert(newEntity);

var mapper = serviceProvider.GetRequiredService<IRdfEntityMapper<MyRdfDefinition, MyEntity, Guid>>();

// Forward mapping (RDF → Entity)
var entity = mapper.Map(rdfDefinition);

// Reverse mapping (Entity → RDF)
if (mapper.CanUnmap)
{
    var definition = mapper.Unmap(entity);
    // definition can be used with IRdfInstanceWriter
}

src/GridLab.Abp.Rdf/GridLab/Abp/
├── Cim/
│   ├── Parsers/
│   │   ├── ICimIdentifierParser.cs       # CIM ID parsing contract
│   │   ├── CimIdentifierParser.cs        # CIM ID parsing implementation
│   │   ├── ICimValueParser.cs            # Value parsing contract
│   │   ├── CimValueParser.cs             # Value parsing implementation
│   │   └── README.md                     # Parsers documentation
│   ├── Resolvers/
│   │   ├── ICimNodeResolver.cs           # Node resolution contract
│   │   └── CimNodeResolver.cs            # Node resolution implementation
│   └── Factories/
│       ├── ICimNodeFactory.cs            # Node factory contract
│       └── CimNodeFactory.cs             # Node factory implementation
├── Rdf/
│   ├── Core/
│   │   ├── IRdfDefinition.cs             # Resource definition contract
│   │   ├── IRdfDescription.cs            # Difference model description contract
│   │   └── IRdfProperty.cs               # Property contract
│   ├── Mappers/
│   │   ├── IRdfEntityMapper.cs           # Base and keyed interfaces
│   │   ├── IRdfEntityMapperFactory.cs    # Factory interface
│   │   ├── RdfEntityMapperFactory.cs     # Factory implementation
│   │   └── README.md                     # This documentation
│   ├── Readers/
│   │   └── IRdfInstanceReader.cs         # Read definitions from graph
│   ├── Writers/
│   │   └── IRdfInstanceWriter.cs         # Write definitions to graph
│   └── Repositories/
│       └── Graph/
│           ├── IRdfGraphRepository.cs    # Repository interface
│           └── RdfGraphRepository.cs     # Repository implementation

// Float parsing
if (_valueParser.TryParseFloat("110.5", out var voltage))
    Console.WriteLine($"Voltage: {voltage}kV");  // 110.5kV

// Integer parsing
if (_valueParser.TryParseInt("42", out var count))
    Console.WriteLine($"Count: {count}");  // 42

// Boolean parsing (multiple formats)
_valueParser.TryParseBool("true", out var b1);  // true
_valueParser.TryParseBool("1", out var b2);     // true
_valueParser.TryParseBool("yes", out var b3);   // true
_valueParser.TryParseBool("0", out var b4);     // false

// Enum parsing (case-insensitive)
if (_valueParser.TryParseEnum<UnitMultiplier>("k", out var multiplier))
    Console.WriteLine($"Multiplier: {multiplier}");  // UnitMultiplier.k

public interface ICimIdentifierParser
{
    // Parse methods (throw on failure)
    string ParseId(string uri);
    Guid ParseGuid(string uri);

    // TryParse methods (return false on failure)
    bool TryParseId(string uri, out string result);
    bool TryParseGuid(string uri, out Guid result);

    // Validation methods
    bool IsValidCimUri(string uri);
    bool IsUrnUuidFormat(string uri);
    bool IsHashFormat(string uri);
}