Požadavek do-optimize-files

Účel a dopady

Naplánuje na serveru úlohu optimalizace souborů – shodné soubory napříč dokumenty se sloučí a ve file-systému uloží jen jednou. Nejde o okamžité provedení, požadavek jen vytvoří novou položku v plánovači serveru (cron). Vedlejší efekt: úspěšné vytvoření zapisuje novou úlohu do databáze plánovače.

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

• Uzel patří do rodiny uzlů s prefixem do-, které server plánuje jako úlohy cron; sdílí společný dispatch s do-import, do-export, do-manage, do-scan-files aj..
• Smí použít uživatel s r_admin nebo r_manage; jinak je požadavek zamítnut.
• 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>
   <do-optimize-files
    validity="{string}"
    repeat="{string}"
    sched-from-end="{bool}"
    when-off="{bool}"
    failsafe="{string}"
    run-as="{number}"
    by-action="{bool}"
    db-log="{bool}"
    del-cache="{bool}"
    wait-for-lock="{bool}"
    max-runtime="{number}"
    query-timeout="{number}"
    />
  </request>

Parametry a pravidla (atributy, potomci)

Atributy validity, repeat, sched-from-end, when-off, failsafe mají stejný význam a syntaxi jako u sdíleného typu do-task. Server u téhož uzlu navíc čte i tři obecné plánovací atributy, které sdílený typ do-task v současné podobě nepopisuje: run-as (typ: number; nepovinný), by-action (typ: bool; nepovinný) a db-log (typ: bool; nepovinný).

Vlastní atributy uzlu do-optimize-files:

• del-cache - Vymazat dokumentovou cache - Po dokončení optimalizace vymaže dokumentovou cache (snižuje šanci na opětovné použití právě optimalizovaného souboru). Na rozdíl od dosavadní dokumentace je výchozí hodnota true – vymazání se neprovede jen tehdy, je-li atribut výslovně uveden s hodnotou "false". (typ: bool; nepovinný; výchozí: true)
• wait-for-lock - Čekat na zámek - Pro optimalizaci je třeba získat výhradní přístup k souborům; "true" znamená čekat na jeho uvolnění, jinak úloha při nezískání zámku skončí neúspěchem. (typ: bool; nepovinný; výchozí: false)
• max-runtime - Maximální doba běhu - Hodnota musí být číselná (jinak je celá úloha odmítnuta jako neznámá); přesný způsob použití (jednotka, chování při vypršení) zde není dokumentován. (typ: number; nepovinný; výchozí: 0)
• query-timeout - Timeout databázových dotazů - Přepíše pro tuto úlohu globální konfigurační timeout dotazů. Atribut v dosavadní dokumentaci vůbec nebyl uveden. (typ: number; nepovinný; výchozí: hodnota z konfigurace serveru)

Příklady požadavku

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

Zpracování a vedlejší účinky

• Server nejprve ověří oprávnění (r_admin nebo r_manage); bez něj se žádná úloha nevytvoří.
• Poté se pokusí sestavit JobOptimizeFiles z uzlu požadavku. Selže-li rozpoznání validity/repeat/failsafe/max-runtime/query-timeout (neplatná syntaxe/hodnota), je výsledná úloha označena jako neznámá a vytvoření selže.
• Uspěje-li vytvoření, úloha se zapíše do databáze plánovače a zařadí do fronty serveru; samotná optimalizace proběhne až později, v čase daném plánováním (validity/repeat), ne synchronně v rámci tohoto požadavku – odpověď proto nenese výsledek optimalizace, jen potvrzení naplánování.

XML odpověď (syntax + popis)

  <response>
   <do-optimize-files
    status="ok|error"
    id="{number}"
    next-run="{datetime}"
    detail="{string}"
    />
  </response>

Parametry a pravidla (atributy, potomci) – odpověď

• status - Výsledek - "ok" při úspěšném naplánování, jinak "error" (nebo "skip" při přeskočené transakci). (typ: enum; povolené hodnoty: ok, error, skip)
• id - Id úlohy - Identifikátor nově vytvořené úlohy v plánovači, přítomen jen při status="ok". (typ: number)
• next-run - Čas dalšího spuštění - Datum a čas (YYYY-MM-DD HH:MM:SS) příštího plánovaného spuštění, přítomen jen při status="ok". Tento atribut dosavadní dokumentace vůbec nezmiňovala. (typ: datetime)
• detail - Popis chyby - Přítomen jen při status="error"/"skip". (typ: string; nepovinný)

Příklady odpovědi

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

Chyby a reakce

• <do-optimize-files status="ok" id="…" next-run="…"/> – úloha byla úspěšně naplánována.
• <do-optimize-files status="error" detail="Systemova chyba pri vkladani pozadavku"/> – vytvoření úlohy selhalo (neplatná syntaxe validity/repeat/failsafe/max-runtime/query-timeout).
• <do-optimize-files status="error" detail="Nemate patricna opravneni"/> – volající nemá r_admin ani r_manage.
• <do-optimize-files status="error" detail="Transakce byla odvolana"/> / <do-optimize-files status="skip" detail="Transakce byla preskocena"/> – požadavek byl vyřazen standardním transakčním zpracováním obálky.
• Odpověď se v dosavadní dokumentaci popisovala jako obecný uzel element bez skutečného jména kořenového elementu a s bezejmenným číselným atributem – ve skutečnosti je kořenový element vždy pojmenován do-optimize-files a číselný atribut úlohy se jmenuje id. Výraz pro identifikaci chyb v odpovědi serveru: do-optimize-files[@status='error'].

Související požadavky

• do-manage, do-scan-files – další úlohy plánované stejným mechanismem do-.
• undo – zrušení naplánované/opakující se úlohy podle id vráceného touto odpovědí.