Požadavek general-lock

Účel a dopady

Zamkne, odemkne, nebo otestuje stav obecného číselného zámku – nástroj pro řízení přístupu ke kritickým zdrojům mezi uživateli/procesy.

Dostupnost, kontext, oprávnění apod.

Dostupné každému přihlášenému uživateli. Odemknutí vlastního zámku nevyžaduje žádné zvláštní oprávnění; násilné odemčení cizího zámku řeší samostatný požadavek admin-unlock (vyžaduje r_admin nebo r_unlock).

XML požadavek (syntax + popis)

  <request>
   <general-lock
    id="{number}"
    doc-type="{string}"
    lock="true|false|test"
    timeout="{number}"
    />
  </request>

Parametry a pravidla (atributy, potomci)

• id - Celočíselný identifikátor zámku. (typ: number; povinný – nepřevoditelné na číslo vede k chybě)
• doc-type - Volitelný řetězcový identifikátor v rámci id (např. typ dokumentu). (typ: string; nepovinný)
• lock - true = zamknout, false = odemknout, cokoli jiné (vč. test i neuvedeno) = jen zjistit stav. (typ: enum; nepovinný; výchozí: test stavu)
• timeout - Doba držení zámku v sekundách; 0 = neomezeně. (typ: number; nepovinný; výchozí: 0)

Požadavek nemá žádné potomky.

Příklady požadavku

(Zatím bez ověřeného příkladu.)

Zpracování a vedlejší účinky

• Opakované zamčení stejným uživatelem prodlouží/aktualizuje existující zámek (descr="Zaznam byl aktualizovan", i tak status="ok").
• Odemčení neexistujícího zámku je považováno za úspěch (descr="Zaznam neexistuje", status="ok"), ne za chybu.

XML odpověď (syntax + popis)

  <response>
   <general-lock
    id="{number}"
    doc-type="{string}"
    userid="{number}"
    untildate="{string}"
    untiltime="{string}"
    lock="True|False|true|false"
    status="ok|fail"
    descr="{string}"
    />
  </response>

Zásadní oprava: běžná odpověď (test/zamčení/odemčení) nemá atribut type – dosavadní dokumentace uváděla type="ok|error" jako vždy přítomný, ve skutečnosti se type="error" objevuje jen ve dvou výjimečných případech (viz Chyby a reakce), jinak je jediným indikátorem úspěchu/neúspěchu status.

• userid - ID uživatele, který zámek drží. (typ: number; přítomen jen v režimu testu, a jen je-li zámek aktuálně držen)
• untildate, untiltime - Datum/čas konce platnosti zámku. (typ: string; přítomny jen v režimu testu u drženého zámku s nastaveným timeout)
• lock - V režimu testu "True"/"False" (s velkým počátečním písmenem!) podle toho, zda je zámek držen; v režimu zamčení/odemčení echo požadovaného stavu ("true"/"false", malá písmena).
• status - ok (test vždy, zamčení/odemčení při úspěchu), fail (zamčení/odemčení selhalo).
• descr - Popis, jen je-li relevantní (chyba, aktualizace existujícího zámku, neexistující zámek při odemčení).

Příklady odpovědi

(Zatím bez ověřeného příkladu.)

Chyby a reakce

• type="error" descr="Nerozpoznane id." – id se nepodařilo převést na číslo (řeší se dřív, než dojde na připojení k databázi).
• id="{id}" doc-type="{…}" lock="true" status="fail" descr="Zaznam zamcen jinym uzivatelem" – pokus o zamčení zámku drženého jiným uživatelem.
• ... lock="true|false" status="fail" descr="Doslo k databazove chybe" – selhání databázové procedury.
• type="error" descr="Pri provadeni doslo k chybe" – selhání na úrovni připojení k databázi; tato větev není sebeuzavírající a může nést vnořené error.

Související požadavky

• admin-unlock – násilné odemčení cizího zámku administrátorem.