Požadavek update-files

Účel a dopady

Přesune soubory ze zdrojové složky DAD a/nebo ze zdrojové složky webu do příslušných cílových složek serveru (adresář, odkud update-dad načítá DAD při aktualizaci a při startu serveru, respektive kořen webového sídla). Nejde o kopírování, ale o přesun – zdrojové soubory jsou po úspěšném přenosu ze zdrojové složky odstraněny. Ostatní soubory v cíli, které se jmenovitě neshodují se zdrojem, zůstanou nedotčeny.

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

• Smí použít jen uživatel s r_admin; 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>
   <update-files
    dad-dir="{string}"
    web-dir="{string}"
    />
  </request>

Parametry a pravidla (atributy, potomci)

• dad-dir - Zdrojová složka DAD - Cesta (platná z pohledu operačního systému serveru), z níž se DAD soubory přesunou do aktualizační složky serveru. Prázdná hodnota se chová, jako by atribut nebyl uveden. (typ: string; nepovinný)
• web-dir - Zdrojová složka webu - Cesta (platná z pohledu operačního systému serveru), z níž se soubory přesunou do kořene webového sídla a přepíší tam stejnojmenné cílové soubory. Prázdná hodnota se chová, jako by atribut nebyl uveden. (typ: string; nepovinný)

Požadavek nemá žádné potomky. Přítomnost aspoň jednoho z obou atributů je potřebná, jinak požadavek neprovede žádný přesun (viz „Zpracování“).

Pořadí elementů

Je-li uveden dad-dir i web-dir zároveň, server nejdřív zpracuje dad-dir a teprve po jeho úspěchu web-dir – viz „Zpracování a vedlejší účinky“.

Příklady požadavku

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

Zpracování a vedlejší účinky

• Nemá-li volající r_admin, žádný přesun neproběhne (viz „Chyby a reakce“).
• Je-li uveden neprázdný dad-dir, server rekurzivně přesune obsah této složky do konfigurované DAD složky serveru (existující stejnojmenné soubory v cíli se přepíší, podsložky se sloučí, prázdné zdrojové podsložky se po přesunu jejich obsahu odstraní).
• Selže-li přesun dad-dir, přesun web-dir se vůbec nepokusí provést, i kdyby byl uveden – zpracování obou atributů je podmíněno úspěchem toho předchozího.
• Je-li uveden neprázdný web-dir (a předchozí krok, pokud proběhl, uspěl), server obdobně rekurzivně přesune obsah této složky do kořene webového sídla serveru.
• Po dokončení souborové aktualizace typicky následuje databázová aktualizace požadavkem update-dad.

XML odpověď (syntax + popis)

  <response>
   <update-files
    dad-dir="{string}"
    web-dir="{string}"
    status="ok"
    />
  </response>

Odpověď je vždy jediná sebeuzavírající značka update-files, jejíž atributy se sestavují postupně podle toho, co bylo skutečně zpracováno – viz „Parametry a pravidla“ níže.

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

• dad-dir - Zpracovaná zdrojová složka DAD - Přítomen, jen když byl v požadavku uveden neprázdný dad-dir a alespoň se o jeho přesun server pokusil (nezávisle na výsledku). Echoem vrací hodnotu z požadavku. (typ: string)
• web-dir - Zpracovaná zdrojová složka webu - Přítomen, jen když byl v požadavku uveden neprázdný web-dir a server se o jeho přesun pokusil (tedy nikdy, pokud předtím selhal dad-dir). Echoem vrací hodnotu z požadavku. (typ: string)
• status - Výsledek - "ok", jen když volající měl oprávnění a všechny pokusy o přesun (dad-dir i web-dir, byly-li uvedeny) uspěly; jinak "error" (viz „Chyby a reakce“). (typ: enum; povolené hodnoty: ok, error)

Nejsou-li dad-dir ani web-dir v požadavku vůbec uvedeny (nebo jsou prázdné), odpověď obsahuje jen <update-files status="ok"/> bez přesunu čehokoli.

Příklady odpovědi

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

Chyby a reakce

• <update-files status="error" detail="Nemate patricna opravneni"/> – volající nemá r_admin.
• <update-files dad-dir="…" status="error" detail="Presun DAD souboru se nezdaril(N)"/> – přesun DAD souborů selhal; N je desítkový kód GetLastError() operačního systému.
• <update-files dad-dir="…" web-dir="…" status="error" detail="Presun WEB souboru se nezdaril(N)"/> – přesun DAD souborů uspěl (nebo nebyl požadován), ale přesun webových souborů selhal; N je desítkový kód GetLastError().
• <update-files status="error" detail="Transakce byla odvolana"/> / <update-files status="skip" detail="Transakce byla preskocena"/> – požadavek byl vyřazen standardním transakčním zpracováním obálky.
• Na rozdíl od staré dokumentace je jméno atributu s výsledkem status, ne type. Výraz pro identifikaci chyb v odpovědi serveru: update-files[@status='error'].

Související požadavky

• update-dad – navazující databázová aktualizace podle DAD souborů přesunutých tímto požadavkem.