Požadavek max-key

Účel a dopady

Vrátí aktuální nejvyšší přidělenou hodnotu identity (primárního klíče) daného dokumentového typu, aniž by ji jakkoli rezervoval nebo posunul čítač. Požadavek nic nemění – jde o čtení hodnoty z paměti serveru.

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

• Dostupné každému přihlášenému uživateli, který má k dokumentu právo čtení, nebo r_admin.
• Na rozdíl od get-key se max-key nikdy nepřeskakuje kvůli selhané/odvolané transakci – zpracuje se vždy, i uvnitř transakčního bloku po předchozí chybě.

XML požadavek (syntax + popis)

  <request>
   <max-key
    doc="{string}"
    opt-roles="{string}"
    />
  </request>

Parametry a pravidla (atributy, potomci)

• doc - Typ dokumentu - Typový název dokumentu definovaného v XDS. Chybí-li, požadavek vždy skončí chybou. (typ: string; nepovinný – fakticky ale nutný pro úspěch)
• opt-roles - Volitelná role - Přepíše efektivní roli použitou pro ověření práva čtení k dokumentu. Prázdný řetězec se chová jako neuvedeno. (typ: string; nepovinný; výchozí: role volajícího)

Požadavek nemá potomky.

Příklady požadavku

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

Zpracování a vedlejší účinky

• Server dohledá dokument podle doc. Neexistuje-li, vrací se chyba „Neznamy dokument“.
• Ověří se právo čtení dokumentu; tuto kontrolu může obejít r_admin.
• Na rozdíl od get-key se u max-key nedohledává žádné konkrétní pole – vrací se přímo aktuální maximální hodnota primárního klíče dokumentu, bez posunu čítače (hodnota se nespotřebovává; opakované volání vrací stejné číslo, dokud nepřibude nová instance dokumentu).
• value v odpovědi je vždy celé číslo – na rozdíl od staré dokumentace nikdy nejde o řetězec se znakem #.

XML odpověď (syntax + popis)

  <response>
   <max-key
    doc="{string}"
    status="ok|error"
    value="{number}"
    detail="{string}"
    />
  </response>

Odpověď je vždy jediná sebeuzavírající značka; nikdy neobsahuje vnořený uzel error.

• doc - Echo dokumentu - Přítomen vždy, když byl doc v požadavku uveden (i při chybě). (typ: string)
• status - Výsledek - "ok"/"error". (typ: enum; povolené hodnoty: ok, error)
• value - Nejvyšší hodnota - Celočíselná hodnota aktuálního maxima primárního klíče. Přítomen jen při status="ok". (typ: number)
• detail - Popis chyby - Přítomen jen při status="error". (typ: string)

Příklady odpovědi

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

Chyby a reakce

• <max-key status="error" detail="Nespravna identifikace klice"/> – atribut doc nebyl uveden.
• <max-key doc="…" status="error" detail="Neznamy dokument"/> – neznámý typ dokumentu.
• <max-key doc="…" status="error" detail="Nemate patricna opravneni"/> – volající nemá právo čtení k dokumentu a nemá r_admin.
• Výraz pro identifikaci chyb v odpovědi serveru: max-key[@status='error'].

Související požadavky

• get-key – sdílí stejný blok zpracování, navíc rezervuje konkrétní pole identity.