Požadavek do-scan-files

Účel a dopady

Naplánuje na serveru úlohu analýzy (a volitelně výmazu) souborů ve file-systémovém úložišti, které nemají odpovídající referenci v databázi, případně dočasných souborů zanechaných nedokončenými operacemi. Nejde o okamžité provedení, požadavek jen vytvoří novou položku v plánovači serveru (cron). Výsledky proběhlé analýzy se zjišťují samostatným požadavkem get-scan-files. Vedlejší efekt: úspěšné vytvoření zapisuje novou úlohu do databáze plánovače; vlastní běh úlohy později maže soubory a/nebo databázové záznamy o nich.

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-optimize-files aj..
• Smí použít uživatel s r_admin nebo r_manage – na rozdíl od dosavadní dokumentace, která požadovala vlastnost uživatele p_admin; server tuto vlastnost pro do-scan-files vůbec nekontroluje.
• 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-scan-files
    validity="{string}"
    repeat="{string}"
    sched-from-end="{bool}"
    when-off="{bool}"
    failsafe="{string}"
    run-as="{number}"
    by-action="{bool}"
    db-log="{bool}"
    scan="{bool}"
    test="{bool}"
    delete="{bool}"
    temp="{bool}"
    temp-threshold="{number}"
    opt="{bool}"
    opt-threshold="{number}"
    cross="{bool}"
    place-holder="{bool}"
    test-crc="{bool}"
    wait-for-lock="{bool}"
    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-scan-files:

• scan - Základní analýza - Spustí porovnání databáze a file-systému, pokud předchozí analýza neexistuje nebo byly její výsledky smazány. (typ: bool; nepovinný)
• test - Vynutit nový test - Vynutí nové provedení základní analýzy i tehdy, existuje-li už její výsledek. (typ: bool; nepovinný)
• delete - Výmaz souborů - Provede výmaz souborů určených předchozí analýzou k výmazu. (typ: bool; nepovinný)
• temp - Zahrnout dočasné soubory - Zahrne do zpracování i dočasné soubory. (typ: bool; nepovinný)
• temp-threshold - Stáří dočasných souborů - Stáří dočasných souborů v sekundách, od kterého se považují za určené k výmazu. (typ: number; nepovinný; výchozí: 7776000 = 90 dní)
• opt - Výmaz optimalizovaných souborů - Provede výmaz starých optimalizovaných souborů. (typ: bool; nepovinný)
• opt-threshold - Stáří optimalizovaných souborů - Stáří optimalizovaných souborů v sekundách, od kterého se považují za určené k výmazu. (typ: number; nepovinný; výchozí: 86400 = 1 den)
• cross - Rozšíření cross - Aktivuje rozšíření křížové kontroly základního testu. (typ: bool; nepovinný)
• place-holder - Rozšíření place-holder - Aktivuje rozšíření základního testu nad soubory bez odpovídajícího záznamu. (typ: bool; nepovinný)
• test-crc - Ověřit CRC - Na rozdíl od dosavadní dokumentace jde o boolean, ne číslo. Je-li atribut uveden, jeho hodnota ("true"/cokoli jiného) přímo určuje, zda se v rámci rozšíření provede ověření CRC součtů souborů; není-li uveden, použije se výchozí chování dané globální konfigurací serveru. (typ: bool; nepovinný; výchozí: dle konfigurace serveru)
• wait-for-lock - Čekat na zámek - Pro provedení operace 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)
• 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 queryTimeout z konfigurace serveru)

Závislosti

• Nejsou-li uvedeny test, delete, opt ani temp (žádný z nich "true"), server bez ohledu na hodnotu atributu scan sám nastaví scan na true – ve výchozím volání bez atributů se tedy vždy provede aspoň základní analýza.
• Skutečné provedení výmazu dočasných souborů (temp) nastává jen tehdy, když zároveň neběží test ani (efektivní) scan ani delete fáze v témže spuštění – kombinace temp="true" s jinými akcemi tedy sama o sobě nemusí výmaz dočasných souborů provést, přestože byl požadován.
• test-crc, není-li uveden, přebírá výchozí hodnotu z konfigurace serveru, ne pevnou konstantu.

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 JobScanFiles z uzlu požadavku. Selže-li rozpoznání validity/repeat/failsafe/temp-threshold/opt-threshold/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á analýza a případný výmaz proběhnou až později, v čase daném plánováním (validity/repeat), ne synchronně v rámci tohoto požadavku – odpověď proto nenese žádný výsledek analýzy, jen potvrzení naplánování. Výsledky se čtou samostatným požadavkem get-scan-files.

XML odpověď (syntax + popis)

  <response>
   <do-scan-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-scan-files status="ok" id="…" next-run="…"/> – úloha byla úspěšně naplánována.
• <do-scan-files status="error" detail="Systemova chyba pri vkladani pozadavku"/> – vytvoření úlohy selhalo (neplatná syntaxe číselných/plánovacích atributů).
• <do-scan-files status="error" detail="Nemate patricna opravneni"/> – volající nemá r_admin ani r_manage.
• <do-scan-files status="error" detail="Transakce byla odvolana"/> / <do-scan-files status="skip" detail="Transakce byla preskocena"/> – požadavek byl vyřazen standardním transakčním zpracováním obálky.
• Výraz pro identifikaci chyb v odpovědi serveru: do-scan-files[@status='error'].

Související požadavky

• get-scan-files – zjištění výsledků úlohy naplánované tímto požadavkem.
• do-manage, do-optimize-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í.