using Sagitec.Rules.Core.Instance.Attributes;
using Sagitec.Rules.Core.Interface;
using Sagitec.Rules.Interface.Container.Entity;
using System.Collections;
using System.Collections.ObjectModel;
namespace Sagitec.Rules.Interface.Helper.Execution
{
/// <summary>
/// Defines methods for creating new instances of entity types within the execution context.
/// </summary>
/// <remarks>
/// This interface provides functionality to dynamically create instances of entity types that implements the <see cref="IRulesLanguageEntityContainer"/> interface. It is
marked with the <see cref="SingletonInstance"/> attribute to ensure a single instance is used throughout the application.
/// </remarks>
[SingletonInstance]
public interface IExecutionEntityHelper : ICoreInstance, IExecutionContextHelper
{
#region Public Methods
/// <summary>
/// Retrieves the value of a specified attribute from a given entity.
/// </summary>
/// <param name="aobjEntity">The entity container from which the attribute value is retrieved.</param>
/// <param name="astrEntityFieldID">The ID of the entity field (attribute) whose value is to be retrieved.</param>
/// <returns>The value of the specified attribute as a string.</returns>
/// <exception cref="ArgumentNullException">Thrown when the entity container is null.</exception>
/// <exception cref="ArgumentException">Thrown when the entity field ID is null or empty.</exception>
/// <exception cref="EntityNotFoundExceptionInfo">Thrown when the specified entity does not exist.</exception>
/// <exception cref="Exception">Thrown when the specified attribute ID is not found in the entity.</exception>
string GetAttributeValue(IRulesLanguageEntityContainer aobjEntity, string astrEntityFieldID);
/// <summary>
/// Executes a database query and maps the resulting data to a collection of entities of type <typeparamref name="TEntity"/>.
/// </summary>
/// <typeparam name="TEntity">
/// The type of entity which can be used to populate the collection with. Must implement <see cref="IRulesLanguageEntityContainer"/>.
/// </typeparam>
/// <param name="astrEntity">The name of the entity for which instance needs to be created.</param>
/// <param name="astrQuery">The SQL query to execute.</param>
/// <param name="aarrParameters">An array of parameters for the query.</param>
/// <returns>
/// A collection of <typeparamref name="TEntity"/> populated with data from the query, or <c>null</c> if no data is returned or an error occurs.
/// </returns>
/// <exception cref="ArgumentException">
/// Thrown if <paramref name="astrEntity"/> or <paramref name="astrQuery"/> is null, empty, or consists of only white-space characters.
/// </exception>
/// <exception cref="Exception">
/// Re-throws any exception encountered during the execution of the query or entity instantiation.
/// </exception>
Collection<TEntity> GetCollectionByQuery<TEntity>(string astrEntity, string astrQuery, params object[] aarrParameters) where TEntity : class,
IRulesLanguageEntityContainer;
/// <summary>
/// Retrieves a collection of entities based on the specified query and parameters.
/// </summary>
/// <param name="astrEntity">The name of the entity type to instantiate and use it in the collection.</param>
/// <param name="astrQuery">The SQL query to execute in the database.</param>
/// <param name="aarrParameters">Optional parameters for the SQL query.</param>
/// <returns>A collection of entities populated with data from the query, or <c>null</c> if no data is found or an error occurs.</returns>
/// <exception cref="ArgumentException">Thrown when <paramref name="astrEntity"/> or <paramref name="astrQuery"/> is <c>null</c> or only has whitespace.
</exception>
/// <exception cref="InvalidOperationException">Thrown if there is any issue with the database query execution or entity instantiation.</exception>
ICollection GetCollectionByQuery(string astrEntity, string astrQuery, params object[] aarrParameters);
/// <summary>
/// Retrieves an entity based on the specified query and parameters.
/// </summary>
/// <param name="astrEntity">The name of the entity type to instantiate and use it in the query.</param>
/// <param name="astrQuery">The SQL query to execute in the database.</param>
/// <param name="aarrParameters">Optional parameters for the SQL query.</param>
/// <returns>An object representing the entity populated with data from the query.</returns>
/// <exception cref="ArgumentException">Thrown when <paramref name="astrEntity"/> or <paramref name="astrQuery"/> is <c>null</c> or only has whitespace.
</exception>
/// <exception cref="InvalidOperationException">Thrown if there is an issue with the database query execution or entity instantiation.</exception>
object GetEntityByQuery(string astrEntity, string astrQuery, params object[] aarrParameters);
/// <summary>
/// Retrieves an entity based on the specified query and parameters, casting it to the generic type <typeparamref name="TEntity"/>.
/// </summary>
/// <typeparam name="TEntity">The type of the entity that derives from <see cref="IRulesLanguageEntityContainer"/>.</typeparam>
/// <param name="astrEntity">The name of the entity type to instantiate and use it in the query.</param>
/// <param name="astrQuery">The SQL query to execute in the database.</param>
/// <param name="aarrParameters">Optional parameters for the SQL query.</param>
/// <returns>An instance of <typeparamref name="TEntity"/> populated with data from the query.</returns>
/// <exception cref="ArgumentException">Thrown when <paramref name="astrEntity"/> or <paramref name="astrQuery"/> is <c>null</c> or only has whitespace.
</exception>
/// <exception cref="InvalidCastException">Thrown if the created instance cannot be cast to <typeparamref name="TEntity"/>.</exception>
/// <exception cref="InvalidOperationException">Thrown if there is an issue with the database query execution or entity instantiation.</exception>
TEntity GetEntityByQuery<TEntity>(string astrEntity, string astrQuery, params object[] aarrParameters) where TEntity : class, IRulesLanguageEntityContainer;
/// <summary>
/// Retrieves the value of an entity field as an <see cref="object"/>.
/// </summary>
/// <param name="aobjEntity">The entity container from which the field value is retrieved.</param>
/// <param name="astrEntityFieldID">The identifier of the field within the entity container.</param>
/// <returns>The field value as an <see cref="object"/>.</returns>
/// <exception cref="ArgumentNullException">Thrown if <paramref name="aobjEntity"/> is null.</exception>
/// <exception cref="ArgumentException">Thrown if <paramref name="astrEntityFieldID"/> is null or empty.</exception>
/// <exception cref="Exception">Thrown if there is an error retrieving the field value.</exception>
object GetEntityFieldValue(IRulesLanguageEntityContainer aobjEntity, string astrEntityFieldID);
/// <summary>
/// Retrieves the value of an entity field, with the specified return type.
/// </summary>
/// <typeparam name="T">The expected type of the field value.</typeparam>
/// <param name="aobjEntity">The entity container from which to retrieve the field value.</param>
/// <param name="astrEntityFieldID">The identifier of the field within the entity container.</param>
/// <returns>The field value of type <typeparamref name="T"/>.</returns>
/// <exception cref="ArgumentNullException">Thrown if <paramref name="aobjEntity"/> is null.</exception>
/// <exception cref="ArgumentException">Thrown if <paramref name="astrEntityFieldID"/> is null or empty.</exception>
/// <exception cref="Exception">Thrown if there is an error retrieving the field value.</exception>
T GetEntityFieldValue<T>(IRulesLanguageEntityContainer aobjEntity, string astrEntityFieldID);
/// <summary>
/// Maps the data from the source entity to the target entity.
/// Existing dictionary entries in the target entity will be overwritten.
/// </summary>
/// <param name="aentSource">The source entity from which the data is mapped. Must be of the type <see cref="IentBase"/>.</param>
/// <param name="aentTarget">The target entity to which data will be mapped. Must be of the type <see cref="IentBase"/>.</param>
/// <exception cref="ArgumentNullException">Thrown when either <paramref name="aentSource"/> or <paramref name="aentTarget"/> is <c>null</c>.</exception>
/// <exception cref="InvalidCastException">Thrown if either <paramref name="aentSource"/> or <paramref name="aentTarget"/> cannot be cast to <see
cref="IentBase"/>.</exception>
void Map(IRulesLanguageEntityContainer aentSource, IRulesLanguageEntityContainer aentTarget);
/// <summary>
/// Creates a new instance of the specified entity type.
/// </summary>
/// <param name="astrEntity">The name of the entity type to instantiate.</param>
/// <returns>An object representing the newly created instance of the specified entity type.</returns>
object NewInstance(string astrEntity);
/// <summary>
/// Creates a new instance of the specified entity type and casts it to the generic type <typeparamref name="TEntity"/>.
/// </summary>
/// <typeparam name="TEntity">The type of the entity that is derived from <see cref="IRulesLanguageEntityContainer"/>.</typeparam>
/// <param name="astrEntity">The name of the entity type to instantiate.</param>
/// <returns>An instance of <typeparamref name="TEntity"/>.</returns>
TEntity NewInstance<TEntity>(string astrEntity) where TEntity : class, IRulesLanguageEntityContainer;
/// <summary>
/// Converts the specified instance to an entity of the type <typeparamref name="TEntity"/>.
/// </summary>
/// <typeparam name="TEntity">The type of the entity that is derived from <see cref="IRulesLanguageEntityContainer"/>.</typeparam>
/// <param name="aobjInstance">The instance which needs to be converted to an entity.</param>
/// <returns>An instance of <typeparamref name="TEntity"/> on successful conversion; otherwise, <c>null</c>.</returns>
TEntity ToEntity<TEntity>(object aobjInstance) where TEntity : class, IRulesLanguageEntityContainer;
#endregion Public Methods
}
}
#Rules