Požadavek uuid

Účel a dopady

Vygeneruje jeden nebo více univerzálních unikátních identifikátorů (UUID) podle RFC4122, ve verzích 0, 1, 3, 4 nebo 5. Požadavek nemá žádné vedlejší účinky – nic nezapisuje do databáze ani do session.

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

• Dostupné každému přihlášenému uživateli bez zvláštního oprávnění.
• Zpracování uuid (na rozdíl od požadavků jako sql-query/action) není podmíněno stavem obálkové transakce – v dispatcheru pro něj taková podmínka chybí, požadavek se provede vždy.

XML požadavek (syntax + popis)

  <request>
   <uuid
    version="{number}"
    count="{number}"
    string="{string}"
    />
  </request>

Parametry a pravidla (atributy, potomci)

• version - Verze UUID - Určuje požadovanou verzi generátoru. (typ: number; nepovinný; výchozí: 4; povolené hodnoty: 0, 1, 3, 4, 5 – hodnota 2, jakákoli hodnota vyšší než 5, nebo hodnota, kterou se nepodaří převést na číslo, vede k chybě, viz „Chyby a reakce“)
• count - Počet generovaných UUID - Kolikrát se má identifikátor vygenerovat. (typ: number; nepovinný; výchozí: 1; hodnota 0 nebo hodnota, kterou se nepodaří převést na číslo, se chová jako 1)
• string - Vstupní řetězec pro hash - Zdrojový text, z jehož hashe se odvozuje UUID verzí 3 a 5. (typ: string; povinný jen pro version="3" a version="5", jinak se nepoužije)

Požadavek nemá žádné potomky.

Závislosti

• Je-li version 3 nebo 5, je atribut string povinný; jeho neuvedení vede k chybě (viz „Chyby a reakce“).
• U verzí 3 a 5 nemá count smysl v tom, že vstup je deterministický – při stejném string generuje generátor pořád stejné UUID, takže count vyšší než 1 jen zopakuje tutéž hodnotu vícekrát. Server to nijak nekontroluje ani neomezuje.

Význam jednotlivých verzí

• 0 – vždy vrátí nil UUID (00000000-0000-0000-0000-000000000000).
• 1 – odvozeno z MAC adresy stroje a aktuálního času (UuidCreateSequential); bez náhodné složky.
• 2 – v této verzi serveru neimplementováno; použití vede k chybě stejně jako neplatná verze.
• 3 – hash zadaného string pomocí MD5.
• 4 (výchozí) – čistě náhodně vygenerované (randomize).
• 5 – hash zadaného string pomocí SHA-1.

Příklady požadavku

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

Zpracování a vedlejší účinky

• U verzí 1, 3, 4 a 5 server po vygenerování surových bajtů nastaví bity varianty/verze podle RFC4122; u verze 0 k této úpravě nedochází (výsledek zůstává čistě nulový).
• Výsledný text má vždy standardní tvar s pomlčkami xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32 hexadecimálních znaků + 4 pomlčky).

XML odpověď (syntax + popis)

  <response>
   <uuid
    type="ok"
    >
    <value
     uuid="{string}"
     /> *
   </uuid>
  </response>

Uzel value je vždy sebeuzavírající a obsahuje jediný atribut uuid s vygenerovanou hodnotou. Počet uzlů value odpovídá count.

Příklady odpovědi

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

Chyby a reakce

• <uuid type="error" detail="Nepodporovana verze UUID"/> – version je 2, je vyšší než 5, nebo se nepodařilo převést na číslo.
• <uuid type="error" detail="Tato verze UUID vy6aduje atribut string"/> – version je 3 nebo 5 a chybí atribut string. Text vy6aduje (místo „vyžaduje“) je doslovná chyba serveru, ne chyba přepisu v této dokumentaci.
• Obě chybové větve jsou sebeuzavírající, bez vnořeného uzlu error.
• Výraz pro identifikaci chyb v odpovědi serveru: uuid[@type='error'].

Související požadavky

• rand – další generátor hodnot ve stejné skupině požadavků.