qdr.fnd/qdr.fnd.core.pqueue/Storages/IPsQueueStorage.cs

using qdr.fnd.core.pqueue.Enums;
using Quadarax.Foundation.Core.Data;

namespace qdr.fnd.core.pqueue.Storages
{
    /// <summary>
    /// PsQueue persistence storage interface. Manipulates with <see cref="IPsQueueItem"/> entities.
    /// <remarks>
    /// Has no any business logic. Just a storage interface.
    /// Throws directly exceptions if something goes wrong.
    /// </remarks>
    /// </summary>
    public interface IPsQueueStorage : IDisposable
    {
        #region *** Operations ***

        #region **** Transactions ****
        /// <summary>
        /// Creates a new transaction and returns its id
        /// </summary>
        /// <returns>Transaction identifier</returns>
        public string CreateTransaction();
        /// <summary>
        /// Commits all changes on the transaction specified by the <paramref name="transactionId"/> and closes transaction.
        /// <remarks>
        /// If <paramref name="transactionId"/> not exists, the method should throw an exception.
        /// </remarks>
        /// </summary>
        /// <param name="transactionId">Transaction identifier</param>
        public void CommitTransaction(string transactionId);
        /// <summary>
        /// Rollbacks all changes on the transaction specified by the <paramref name="transactionId"/> and closes transaction.
        /// <remarks>
        /// If <paramref name="transactionId"/> not exists, the method should throw an exception.
        /// </remarks>
        /// </summary>
        /// <param name="transactionId">Transaction identifier</param>
        public void RollbackTransaction(string transactionId);
        #endregion
        
        #region **** Items ****
        /// <summary>
        /// Creates a new item in the queue storage and returns its identifier.
        /// <remarks>
        /// If <paramref name="transactionId"/> not exists, the method should throw an exception.
        /// </remarks>
        /// </summary>
        /// <param name="transactionId">Transaction identifier generated by <see cref="CreateTransaction"/> operation.</param>
        /// <param name="owner">Owner identifier</param>
        /// <param name="ownerRef">Owner reference identifier</param>
        /// <param name="providerClass">Process provider qualified type name</param>
        /// <param name="created">Timestamp when record will be created. If null use current datetime.</param>
        /// <returns>Item identifier.</returns>
        public string CreateItem(string transactionId, string owner, string ownerRef, string providerClass, DateTime? created);
        /// <summary>
        /// Deletes (force) the item (and all related entities) specified by the <paramref name="itemId"/> no matter what status item has.
        /// <remarks>
        /// If <paramref name="transactionId"/> not exists, the method should throw an exception.
        /// If <paramref name="itemId"/> not exists, the method should throw an exception.
        /// </remarks>
        /// </summary>
        /// <param name="transactionId">Transaction identifier generated by <see cref="CreateTransaction"/> operation.</param>
        /// <param name="itemId">Item identifier.</param>
        public void DeleteItem(string transactionId, string itemId);
        /// <summary>
        /// Updates the priority of the item specified by the <paramref name="itemId"/>.
        /// <remarks>
        /// If <paramref name="transactionId"/> not exists, the method should throw an exception.
        /// If <paramref name="itemId"/> not exists, the method should throw an exception.
        /// </remarks>
        /// </summary>
        /// <param name="transactionId">Transaction identifier generated by <see cref="CreateTransaction"/> operation.</param>
        /// <param name="itemId">Item identifier.</param>
        /// <param name="priority">Process priority value.</param>
        public void UpdateItemPriority(string transactionId, string itemId, int priority);
        
        /// <summary>
        /// Updates the validity of the item specified by the <paramref name="itemId"/>.
        /// <remarks>
        /// If <paramref name="transactionId"/> not exists, the method should throw an exception.
        /// If <paramref name="itemId"/> not exists, the method should throw an exception.
        /// </remarks>
        /// </summary>
        /// <param name="transactionId">Transaction identifier generated by <see cref="CreateTransaction"/> operation.</param>
        /// <param name="itemId">Item identifier.</param>
        /// <param name="validForm">Timestamp for validFrom value.</param>
        /// <param name="validTo">Timespamp for validTo value.</param>
        public void UpdateItemValidity(string transactionId, string itemId, DateTime validForm, DateTime? validTo);
        
        /// <summary>
        /// Updates the status of the item specified by the <paramref name="itemId"/>. Doesn't affects the status journal or logs.
        /// <remarks>
        /// If <paramref name="transactionId"/> not exists, the method should throw an exception.
        /// If <paramref name="itemId"/> not exists, the method should throw an exception.
        /// Doesn't validate the status transitions. Force update.
        /// </remarks>
        /// </summary>
        /// <param name="transactionId">Transaction identifier generated by <see cref="CreateTransaction"/> operation.</param>
        /// <param name="itemId">Item identifier.</param>
        /// <param name="status">New item status. If null status will be kept.</param>
        /// <param name="isTransient">New transient flag.</param>
        public void UpdateItemStatus(string transactionId, string itemId, PsStatusEnum? status, bool isTransient);
        
        /// <summary>
        /// Updates the attempts left value of the item specified by the <paramref name="itemId"/>.
        /// <remarks>
        /// If <paramref name="transactionId"/> not exists, the method should throw an exception.
        /// If <paramref name="itemId"/> not exists, the method should throw an exception.
        /// Doesn't validate attempts counter. Force update.
        /// </remarks>
        /// </summary>
        /// <param name="transactionId">Transaction identifier generated by <see cref="CreateTransaction"/> operation.</param>
        /// <param name="itemId">Item identifier.</param>
        /// <param name="attemptsLeft">New attempt value.</param>
        public void UpdateItemAttempts(string transactionId, string itemId, int attemptsLeft);
        
        /// <summary>
        /// Updates the process started timestamp of the item specified by the <paramref name="itemId"/>.
        /// <remarks>
        /// If <paramref name="transactionId"/> not exists, the method should throw an exception.
        /// If <paramref name="itemId"/> not exists, the method should throw an exception.
        /// </remarks>
        /// </summary>
        /// <param name="transactionId">Transaction identifier generated by <see cref="CreateTransaction"/> operation.</param>
        /// <param name="itemId">Item identifier.</param>
        /// <param name="started">New timestamp value or null.</param>
        public void UpdateItemStarted(string transactionId, string itemId, DateTime? started);
        
        /// <summary>
        /// Updates the process finished timestamp of the item specified by the <paramref name="itemId"/>.
        /// <remarks>
        /// If <paramref name="transactionId"/> not exists, the method should throw an exception.
        /// If <paramref name="itemId"/> not exists, the method should throw an exception.
        /// </remarks>
        /// </summary>
        /// <param name="transactionId">Transaction identifier generated by <see cref="CreateTransaction"/> operation.</param>
        /// <param name="itemId">Item identifier.</param>
        /// <param name="finished">New timestamp value or null.</param>
        public void UpdateItemFinished(string transactionId, string itemId, DateTime? finished);

        #endregion
        #region **** Item Attributes ****

        /// <summary>
        /// Creates a new item attribute with the specified <paramref name="name"/> and <paramref name="value"/> for the item specified by the <paramref name="itemId"/>.
        /// <remarks>
        /// If <paramref name="transactionId"/> not exists, the method should throw an exception.
        /// If <paramref name="itemId"/> not exists, the method should throw an exception.
        /// If <paramref name="name"/> already exists, the method should throw an exception.
        /// </remarks>
        /// </summary>
        /// <param name="transactionId">Transaction identifier generated by <see cref="CreateTransaction"/> operation.</param>
        /// <param name="itemId">Item identifier.</param>
        /// <param name="name">Unique attribute name in <paramref name="itemId"/> scope.</param>
        /// <param name="value">Value serialized as string or null.</param>
        /// <param name="valueTypeClass">Value type qualified class name.</param>
        /// <param name="isOutput">Flag defines if attribute is input/output.</param>
        public void CreateItemAttribute(string transactionId, string itemId, string name, string? value, string valueTypeClass,bool isOutput);
        
        /// <summary>
        /// Updates the value of the item attribute specified by the <paramref name="name"/> for the item specified by the <paramref name="itemId"/>.
        /// <remarks>
        /// If <paramref name="transactionId"/> not exists, the method should throw an exception.
        /// If <paramref name="itemId"/> not exists, the method should throw an exception.
        /// If <paramref name="name"/> not exists, the method should throw an exception.
        /// </remarks>
        /// </summary>
        /// <param name="transactionId">Transaction identifier generated by <see cref="CreateTransaction"/> operation.</param>
        /// <param name="itemId">Item identifier.</param>
        /// <param name="name">Unique attribute name in <paramref name="itemId"/> scope.</param>
        /// <param name="value">Value serialized as string or null.</param>
        public void UpdateItemAttribute(string transactionId, string itemId, string name, string value);

        /// <summary>
        /// Deletes the item attribute specified by the <paramref name="name"/> for the item specified by the <paramref name="itemId"/>.
        /// <remarks>
        /// If <paramref name="transactionId"/> not exists, the method should throw an exception.
        /// If <paramref name="itemId"/> not exists, the method should throw an exception.
        /// If <paramref name="name"/> not exists, the method should throw an exception.
        /// </remarks>
        /// </summary>
        /// <param name="transactionId">Transaction identifier generated by <see cref="CreateTransaction"/> operation.</param>
        /// <param name="itemId">Item identifier.</param>
        /// <param name="name">Unique attribute name in <paramref name="itemId"/> scope.</param>
        public void DeleteItemAttribute(string transactionId, string itemId, string name);

        #endregion
        #region **** Item Collections ****
        /// <summary>
        /// Appends a new log record to the item specified by the <paramref name="itemId"/>.
        /// <remarks>
        /// If <paramref name="transactionId"/> not exists, the method should throw an exception.
        /// If <paramref name="itemId"/> not exists, the method should throw an exception.
        /// </remarks>
        /// </summary>
        /// <param name="transactionId">Transaction identifier generated by <see cref="CreateTransaction"/> operation.</param>
        /// <param name="itemId">Item identifier.</param>
        /// <param name="message">Log message.</param>
        /// <param name="code">Message code</param>
        /// <param name="messageType">Message type</param>
        public void AppendLog(string transactionId, string itemId, string message, int code, ErrorLevelEnum messageType);
        /// <summary>
        /// Appends a new status journal record to the item specified by the <paramref name="itemId"/>.
        /// <remarks>
        /// If <paramref name="transactionId"/> not exists, the method should throw an exception.
        /// If <paramref name="itemId"/> not exists, the method should throw an exception.
        /// </remarks>
        /// </summary>
        /// <param name="transactionId">Transaction identifier generated by <see cref="CreateTransaction"/> operation.</param>
        /// <param name="itemId">Item identifier.</param>
        /// <param name="status">Previous status.</param>
        /// <param name="isTransient">Previous isTransient flag.</param>
        /// <param name="message">Message.</param>
        public void AppendStatusJournal(string transactionId, string itemId, PsStatusEnum status, bool isTransient, string message);
        #endregion

        #region **** Queries & Get ****
        /// <summary>
        /// Returns collection of process item by input conditions.
        /// <remarks>
        /// Query items outside the transaction scope (must be committed).
        /// </remarks>
        /// </summary>
        /// <param name="owner">Owner identifier. If null then condition is skipped.</param>
        /// <param name="ownerRef">Owner reference identifier. If null then condition is skipped.</param>
        /// <param name="status">Collection of requested complex statuses (isTransient, Status).</param>
        /// <returns>Queryable collection of requested items.</returns>
        public IQueryable<IPsQueueItem> Query(string? owner, string? ownerRef, params Tuple<bool,PsStatusEnum>[] status);
        
        /// <summary>
        /// Gets the item specified by the <paramref name="itemId"/>.
        /// <remarks>
        /// If <paramref name="transactionId"/> not exists, the method should throw an exception.
        /// If <paramref name="itemId"/> not exists, the method should throw an exception.
        /// </remarks>
        /// </summary>
        /// <param name="transactionId">Transaction identifier generated by <see cref="CreateTransaction"/> operation. If null works outside transaction scope.</param>
        /// <param name="itemId">Item identifier.</param>
        /// <returns>Requested item.</returns>
        public IPsQueueItem GetItem(string? transactionId, string itemId);
        #endregion
        #endregion
    }

}