/*
 Copyright (c) 2026 - SD-Innovation S.A.S. - FRANCE
*/

/*
ver: 2.x.x - build: 2026-04-28
*/

/*
The zlib License

Copyright (c) 2026 SD-Innovation S.A.S.

This software is provided ‘as-is’, without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.

2. Altered source versions must be plainly marked as such, and must not be
misrepresented as being the original software.

3. This notice may not be removed or altered from any source
distribution.
*/

#pragma once

#include "message.h"

namespace sdi_toolBox::desktop::eventBus
{
//--------------------------------------------------------------
/**
 * @class INode
 * @brief Abstract interface representing a subscriber node in the event bus system.
 *
 * INode is the base interface that all subscriber nodes must implement to
 * participate in the event bus. It exposes a single private pure virtual method,
 * @ref append(), which is called exclusively by the @ref Bus when a message is
 * dispatched to this node.
 *
 * The @ref Bus is declared as a friend class to allow it to invoke @ref append()
 * without exposing it to the rest of the codebase, enforcing a strict
 * encapsulation of the message delivery mechanism.
 *
 * @note INode is non-copyable and non-movable.
 * @note Direct instantiation is not possible - this class must be subclassed.
 *       The concrete implementation is provided by @ref Node.
 *
 * @see Bus
 * @see Node
 * @see Message
 */
class INode
{
  friend class Bus;     ///< Allow the Bus class to access private members

  public:
  ///@name Construction & Destruction
  ///@{

  /**
   * @brief Default constructor.
   */
  INode() = default;

  /**
   * @brief Default destructor.
   */
  virtual ~INode() = default;

  /**
   * @brief Copy constructor - deleted.
   *
   * INode is non-copyable.
   */
  INode(const INode &obj) = delete;

  /**
   * @brief Move constructor - deleted.
   *
   * INode is non-movable.
   */
  INode(INode &&obj) noexcept = delete;

  /**
   * @brief Copy assignment operator - deleted.
   *
   * INode is non-copyable.
   */
  INode &operator=(const INode &obj) = delete;

  /**
   * @brief Move assignment operator - deleted.
   *
   * INode is non-movable.
   */
  INode &operator=(INode &&obj) noexcept = delete;

  ///@}

  private:
  /**
   * @brief Insert a message into the node's internal message queue.
   *
   * This method is called exclusively by the @ref Bus when a message matching
   * this node's subscriptions (or a broadcast message) is dispatched.
   * It must be implemented by all concrete subclasses to define how incoming
   * messages are stored or processed.
   *
   * @param message Shared pointer to the message being delivered.
   *
   * @note This method is intentionally private and only accessible to @ref Bus
   *       via the friend declaration, preventing external code from injecting
   *       messages directly into a node.
   */
  virtual void append(const std::shared_ptr<Message> &message) = 0;
};
//--------------------------------------------------------------
}     // namespace sdi_toolBox::desktop::eventBus