<?php
namespace nur\mapper\base\oobd;

/**
 * Class IOobdManager: un gestionnaire de données out-of-band
 */
interface IOobdManager {
  /** obtenir l'instance partagée, ou null s'il n'y en a pas */
  function getSharedOobdManager(): ?IOobdManager;

  /** spécifier l'instance partagée */
  function setSharedOobdManager(IOobdManager $sharedOobdManager);

  /** s'assurer de l'existence d'une instance partagée */
  function ensureSharedOobdManager(): void;

  /** vérifier si la valeur spécifiée existe */
  function hasOvalue(string $name): bool;

  /** obtenir la valeur spécifiée, ou $default si elle n'existe pas */
  function getOvalue(string $name, $default=null);

  /**
   * spécifier la valeur
   *
   * si $value est une valeur booléenne, le traitement est particulier: la
   * valeur courante n'est modifiée que si elle ne vaut pas exactement true.
   * cela permet de spécifier un flag qui ne change plus une fois qu'il reçoit
   * la valeur vraie
   *
   * si $shared==true, attaquer l'éventuelle instance partagée. sinon, c'est la
   * valeur locale qui est modifiée.
   *
   * retourner la valeur finale du paramètre
   */
  function setOvalue(string $name, $value, bool $shared=true);

  /**
   * incrémenter la valeur. si la valeur n'existait pas au préalable, considèrer
   * que sa valeur était zéro
   *
   * si $shared==true, attaquer l'éventuelle instance partagée. sinon, c'est la
   * valeur locale qui est modifiée.
   *
   * retourner la valeur finale du paramètre
   */
  function incOvalue(string $name, bool $shared=true): int;

  /**
   * décrémenter la valeur. si la valeur n'existait pas au préalable, considèrer
   * que sa valeur était zéro
   *
   * si $shared==true, attaquer l'éventuelle instance partagée. sinon, c'est la
   * valeur locale qui est modifiée.
   *
   * retourner la valeur finale du paramètre
   */
  function decOvalue(string $name, bool $shared=true): int;

  /**
   * spécifier la valeur de façon inconditionnelle
   *
   * si $value===null, la valeur courante est supprimée. il n'y a pas de
   * traitement particulier si $value est une valeur booléenne
   *
   * si $shared==true, attaquer l'éventuelle instance partagée. sinon, c'est la
   * valeur locale qui est modifiée.
   *
   * retourner la valeur finale du paramètre
   */
  function resetOvalue(string $name, $value=null, bool $shared=true);
}