Požadavek admin-unlock

Účel a dopady

Administrativně vynutí odemčení obecného zámku (viz general-lock) bez ohledu na to, kdo zámek vytvořil. Používá stejnou uloženou proceduru pro odemčení jako běžné general-lock, ale vlastníka zámku jí předává jako NULL, takže kontrola vlastnictví zámku na straně databáze se obchází.

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

• Dostupné jen uživateli s r_admin nebo r_unlock.
• Kontrola oprávnění proběhne až poté, co server rozpozná platné číselné id – u neplatného/chybějícího id vrací chybu "Nerozpoznane id." ještě před jakoukoli kontrolou oprávnění.
• Podléhá standardnímu transakčnímu zpracování obálky <request> (transactional/přeskočení při odvolané transakci) – viz obálka požadavku.

XML požadavek (syntax + popis)

  <request>
   <admin-unlock
    id="{number}"
    doc-type="{string}"
    timeout="{number}"
    />
  </request>

Parametry a pravidla (atributy, potomci)

• id - Číslo zámku - Identifikátor zamykané položky. Nejde-li hodnotu převést na celé číslo (včetně případu, kdy atribut chybí), požadavek vždy skončí chybou "Nerozpoznane id.". (typ: number; nepovinný podle syntaxe, ale bez platné hodnoty požadavek vždy selže)
• doc-type - Typový název - Volitelný řetězcový identifikátor zámku (např. název dokumentového typu); přenáší se beze změny do odpovědi. (typ: string; nepovinný)
• timeout - Délka trvání - Atribut se čte, ale pro admin-unlock nemá žádný efekt – odemykací procedura žádný časový limit nepřijímá, timeout ovlivňuje jen zamykací větev sdílené funkce, kterou admin-unlock nikdy nevyvolá. (typ: number; nepovinný; fakticky bez vlivu na zpracování)

Oprava oproti starší dokumentaci: požadavek nemá a nikdy neměl atribut lock – narozdíl od general-lock provádí admin-unlock vždy jen odemčení (nikdy zamčení ani test stavu); typ operace je pevně daný a nelze jej měnit atributem.

Příklady požadavku

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

Zpracování a vedlejší účinky

• Je-li id neplatné nebo chybí, vrací se okamžitě chyba bez zápisu do databáze a bez kontroly oprávnění.
• Je-li id platné, ale volající nemá r_admin ani r_unlock, vrací se chyba oprávnění. V této konkrétní větvi odpověď neobsahuje uzavírací uvozovku a mezeru před lock="false", takže atribut doc-type v odpovědi zůstane neuzavřený a splyne s následujícím textem – výsledkem je řetězec tvaru doc-type="…lock="false" status="fail" descr="Nemate dostatecna opravneni"/>, což není platné XML. Jde o anomálii odpovědi serveru, ne o zamýšlený formát; nastává jen při kombinaci platného id a chybějícího oprávnění.
• Je-li oprávnění v pořádku, provede se odemčení voláním uložené procedury pro unlock, přičemž vlastník zámku se předává jako NULL – tedy nezávisle na tom, kdo zámek reálně vytvořil.
• Selže-li připojení k databázi, vzniká obecná chyba se vnořeným diagnostickým error (viz „Chyby a reakce“).

XML odpověď (syntax + popis)

  <response>
   <admin-unlock
    id="{number}"
    doc-type="{string}"
    lock="false"
    status="ok|fail"
    descr="{string}"
    />
  </response>

Úspěšná/neúspěšná odpověď o výsledku odemčení má vždy lock="false", protože admin-unlock provádí jen odemykací operaci. Chybové odpovědi mimo tuto větev (neplatné id, chyba připojení k databázi) mají jinou podobu – viz „Chyby a reakce“.

Příklady odpovědi

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

Chyby a reakce

• <admin-unlock type="error" descr="Nerozpoznane id."/> – atribut id chybí nebo není číslo.
• <admin-unlock type="error" descr="Pri provadeni doslo k chybe"> … vnořené uzly error … </admin-unlock> – selhalo připojení k databázi.
• Platné id, ale chybějící oprávnění: viz popis malformovaného výstupu výše – obsahově jde o lock="false" status="fail" descr="Nemate dostatecna opravneni".
• id="…" doc-type="…" lock="false" status="fail" descr="Zaznam zamcen jinym uzivatelem"/> – odemykací procedura vrátila výsledek 3. Otevřený bod: podmínky, za nichž databázová procedura tuto větev pro admin-unlock skutečně vrací, nejsou součástí tohoto popisu.
• id="…" doc-type="…" descr="Zaznam neexistuje" lock="false" status="ok"/> – odemykací procedura vrátila výsledek 2 (záznam/zámek neexistuje); odpověď je přesto status="ok".
• id="…" doc-type="…" lock="false" status="ok"/> – úspěšné odemčení, výsledek 1.
• id="…" doc-type="…" lock="false" status="fail" descr="Doslo k databazove chybe"/> – jiný výsledek databázové procedury.
• Výraz pro identifikaci chyb v odpovědi serveru: admin-unlock[@type='error'] nebo admin-unlock[@status='fail'].

Související požadavky

• general-lock – běžné (neadministrativní) zamykání/odemykání/test stavu zámku; sdílí stejnou implementační funkci generalLock.