Connected.Framework/Connected.Globalization/Languages/ILanguageService.cs

using System.Collections.Immutable;
using Connected.Annotations;
using Connected.Notifications;
using Connected.ServiceModel;

namespace Connected.Globalization.Languages;

[Service]
[ServiceUrl(GlobalizationRoutes.Languages)]
public interface ILanguageService : IServiceNotifications<int>
{
	/// <summary>
	/// Returns all valid languages from the environment.
	/// </summary>
	/// <returns>A list of available languages.</returns>
	[ServiceMethod(ServiceMethodVerbs.Get)]
	Task<ImmutableList<ILanguage>> Query();
	/// <summary>
	/// Performs a query on <see cref="ILanguage"/> entities for the specified list of ids.
	/// </summary>
	/// <param name="e">The List of the ids for which the perform query.</param>
	/// <returns>An <see cref="ImmutableList{T}"/> of <see cref="ILanguage"/> entities that matches
	/// the passed ids.</returns>
	[ServiceMethod(ServiceMethodVerbs.Get | ServiceMethodVerbs.Post)]
	Task<ImmutableList<ILanguage>?> Query(PrimaryKeyListArgs<int> e);
	/// <summary>
	/// Selects a language by its id.
	/// </summary>
	/// <param name="args"><see cref="PrimaryKeyArgs{T}"/> containing the language id for which an entity should be returned.</param>
	/// <returns><see cref="ILanguage"/> entity if found, <code>null</code> otherwise.</returns>
	[ServiceMethod(ServiceMethodVerbs.Get | ServiceMethodVerbs.Post)]
	Task<ILanguage> Select(PrimaryKeyArgs<int> args);
	/// <summary>
	/// Selects a language by its name.
	/// </summary>
	/// <param name="args"><see cref="NameArgs"/> containing a language name for which an entity should be returned.</param>
	/// <returns><see cref="ILanguage"/> entity if found, <code>null</code> otherwise.</returns>
	[ServiceMethod(ServiceMethodVerbs.Get | ServiceMethodVerbs.Post)]
	Task<ILanguage> Select(NameArgs args);
	/// <summary>
	/// Resolves a language by mapping criteria.
	/// </summary>
	/// <param name="args"><see cref="ILanguageResolveArgs"/> containing mapping criteria.</param>
	/// <remarks>
	/// Mapping criteria is split into tokens, separated by ',' character. Each string (mapping) is then searched in the
	/// <see cref="ILanguage.Mappings"/> property of each supported and <see cref="Data.Status.Enabled"/> language.
	/// </remarks>
	/// <returns>The first <see cref="ILanguage"/> that has at least one mapping, <code>null</code> if no language meets
	/// the criteria.</returns>
	[ServiceMethod(ServiceMethodVerbs.Get | ServiceMethodVerbs.Post)]
	Task<ILanguage> Resolve(LanguageResolveArgs args);
	/// <summary>
	/// Inserts a new language.
	/// </summary>
	/// <param name="args"><see cref="LanguageInsertArgs"/> arguments containing data about a new language.</param>
	/// <returns>An <see cref="PrimaryKeyArgs{T}.Id"/> of the newly added language.</returns>
	[ServiceMethod(ServiceMethodVerbs.Post)]
	Task<int> Insert(LanguageInsertArgs args);
	/// <summary>
	/// Updates existing language.
	/// </summary>
	/// <param name="args"><see cref="LanguageUpdateArgs"/>arguments with modified values.</param>
	[ServiceMethod(ServiceMethodVerbs.Post | ServiceMethodVerbs.Patch)]
	Task Update(LanguageUpdateArgs args);
	/// <summary>
	/// Deletes language from the environment.
	/// </summary>
	/// <param name="args"><see cref="PrimaryKeyArgs{T}"/> containing an id of the language to be deleted.</param>
	[ServiceMethod(ServiceMethodVerbs.Post | ServiceMethodVerbs.Delete)]
	Task Delete(PrimaryKeyArgs<int> args);
}