4A protokol 2.0

Poslední modifikace: 23.06.2015

Obsah:

Následuje popis protokolu. V definicích zpráv se používají makra, která se uvozují složenými závorkami: {makro}

U některých atributů může klient použít wildcard *. Tento znak se interpretuje stejně, jako výraz .* v regulárních výrazech -- libovolný počet libovolných znaků (včetně prázdného řezězce).

V popisu protokolu se u odpovědí uvažuje pouze kladná odpověď (nenastala žádná chyba). Pokud v komunikaci dojde k chybě, server posílá klientovi chybovou zprávu (tomu je vyhrazená samostatná kapitola tohoto dokumentu).

V protokolu budou postupně představeny typy objektů, které obě strany protokolu používají. Některé z nich mají URI, které jednoznačně identifikuje daný objekt v rámci internetu:

Typ objektu Schéma URI Příklad URI
Anotace {URI serveru}/Annotations/{serv|temp}/{číslo anotace} http://example.com/Annotations/serv/81174
Návrhy anotací {URI serveru}/Annotations/sugg/{číslo návrhu anotace} http://example.com/Annotations/sugg/348
Odběry anotací {URI serveru}/Annotations/subscriptions/{číslo odběru anotace} http://example.com/Annotations/subscriptions/234
Typy anotací {URI serveru}/Annotations/types/g{číslo skupiny}/{cesta typu} http://example.com/Annotations/types/g17/Animal/Human/Artist
Typy atributů --- nemají předepsané formáty --- http://www.w3.org/2001/XMLSchema#string
Uživatelé {URI serveru}/Annotations/users/{číslo uživatele} http://example.com/Annotations/users/6881
Uživatelské skupiny {URI serveru}/Annotations/groups/{číslo skupiny} http://example.com/Annotations/groups/1114
Dokumenty {URI serveru}/Annotations/documents/getDoc?id={číslo dokumentu} http://example.com/Annotations/documents/getDoc?id=1234
Entity kontrolovaného slovníku --- nemají předepsaný formát --- http://www.artnet.com/artwork/426018191/3952/sergei-chepik-sunflowers-from-arles.html
Atributy z ontologie --- nemají předepsané formáty --- http://decipher.open.ac.uk/rdfs/decipher/decipher_v1.rdfs#uses

Komunikace

Veškerá komunikace probíhá v jazyku XML. Používají se dva různé kanály:

Synchronní kanál

Podstatou synchronního kanálu je skutečnost, že v každém okamžiku je otevřeno maximálně jedno spojení se serverem. Pokud klient vygeneruje požadavek v momentě, kdy se čeká na odpověď předchozího požadavku, pak nový požadavek vstupuje do fronty a z ní je vytažen a odeslán serveru až po té, co klient obdrží odpověď na předchozí požadavek.

Dotaz

<?xml version="1.0"?>
<messages sessionID="{ID sezení}">
  {seznam zpráv}
</messages>

Atribut sessionID slouží k identifikaci sezení (viz Sezení a přihlášení uživatele). Tento atribut je povinný s výjimkou situace, kdy klient není připojen k serveru a žádné sezení tedy nemá vytvořené.

Odpověď

<?xml version="1.0"?>
<messages>
  {seznam zpráv}
</messages>

Pokud server obdrží požadavek, u kterého se neočekává žádná užitečná odpověď a zároveň nedojde k žádné chybě, server i tak musí nějak odpovědět. V tomto případě odpovídá jednoduchou zprávou ok:

<?xml version="1.0"?>
<messages>
  <ok/>
</messages>

Asynchronní kanál

Dotaz

Odpovědi na comet požadavky typicky přicházejí po relativně dlouhé době. Počet aktivních spojení se serverem na jednu webovou stránku je přitom omezen prohlížeči. Z tohoto důvodu není možné, aby si více klientů vytvořilo vlastní comet kanál. Na straně klienta tudíž musí existovat mechanismus, který spravuje jediný comet kanál pro všechny připojené anotační editory. Klient musí v požadavku uvést ID sezení daných editorů.

<?xml version="1.0"?>
<messages>
  {seznam ID sezení formátu:
    <session id="{ID sezení}"/>
  }
  <comet/>
</messages>

Odpověď

Server posílá odpověď určenou vždy jen jednomu připojenému editoru. Pokud se v jednom okamžiku objeví více zpráv, které je potřeba poslat různým editorům v rámci jednoho comet kanálu, pak server tyto odpovědi posílá jednotlivě jako odpovědi na nové požadavky.

<?xml version="1.0"?>
<messages sessionID="{ID sezení}">
  {seznam zpráv}
</messages>

Podle atributu sessionID klient pozná, kterému editoru má zprávu předat.

V případech, kdy vyprší časový limit pro poslání odpovědi a server nemá žádná data, která by klientovi poslal, server odpovídá jednoduchou zprávou ok, přičemž v atributu sessionID uvede ID sezení libovolného připojeného editoru:

<?xml version="1.0"?>
<messages sessionID="{ID sezení}">
  <ok/>
</messages>

Po obdržení odpovědi od serveru musí klient poslat další comet požadavek. Ve zprávě znovu specifikuje ID sezení všech připojených editorů.

Sezení a přihlášení uživatele

Navázání spojení

Dotaz

Klient naváže spojení se serverem zprávou typu connect. V elementu messages neuvádí sessionID, protože ho ještě nezná. Zpráva connect má povinný atribut protocolVersion -- klient uvede číslo nejvyšší podporované verze.

Pomocí volitelného atributu attachCometTo je možné donutit server přidat nově vytvořené sezení k již existujícímu comet kanálu. To se hodí v případech, kdy se na jedné webové stránce spustí více anotačních editorů. Klient do tohoto atributu uvede číslo sezení libovolného editoru, který už je k comet kanálu přiřazen.

<connect protocolVersion="{verze protokolu}"
         {volitelně: attachCometTo="{ID sezení}"}/>

Příklad:

<connect protocolVersion="2.0"
         attachCometTo="34"/>

Odpověď

Pokud nenastane žádný problém, server odpoví zprávou typu connected:

<connected protocolVersion="{verze protokolu}"
           sessionID="{id sezení}"/>

Atributy:

Pokud server nepodporuje verzi protokolu, jakou klient požaduje, server vrátí nejvyšší možnou verzi, kterou podporuje a která je zároveň zpětně kompatibilní s verzí, jakou navrhl klient. Klient by měl touto verzí protokolu komunikovat bez problémů. Pokud ale server žádnou takovou verzi nepodporuje, vrátí chybovou zprávu. Pokud je klient schopen komunikovat ještě jinými verzemi protokolu, může postupně zkoušet připojit se k serveru s těmito verzemi.

Příklad:

<connected protocolVersion="2.0"
           sessionID="17"/>

Vytvoření comet kanálu

Klient po obdržení odpovědi vytvoří comet kanál, přes který bude probíhat asynchronní komunikace. Zpráva, kterou se kanál otevře, vypadá následovně:

<comet/>

Vždy, když server vrátí klientovi odpověď, klient musí kanál znovu otevřít zprávou comet. Kanál může být otevřený jen omezenou dobu, protože webový prohlížeč nastavuje časový limit na obdržení odpovědi. Pokud má server už dlouho otevřený kanál a nepotřebuje klientovi zaslat žádné zprávy, odpoví alespoň zprávou ok. Tím se kanál uzavře a klient ho následně znovu otevře.

Ukončení spojení

Klient ukončí spojení zprávou typu disconnect:

<disconnect/>

V případě neúspěšného připojení k serveru klient tuto zprávu neposílá (není totiž připojen).

Server na tuto zprávu neodpovídá.

Přihlášení uživatele

Dotaz

Uživatel se přihlásí zprávou typu login. Existují 2 alternativy:

Odpověď

Pokud vše proběhne v pořádku, server uživatele přihlásí a klientovi pošle zprávy typu logged a settings:

<logged uri="{URI uživatele}"
        login="{login uživatele}"
        name="{celé jméno uživatele}"
        email="{e-mail uživatele}"
        image="{URI obrázku uživatele}"/>
{zpráva settings}

Atributy elementu logged odpovídají povinným atributům uživatele.

Poznámka: V případě použití OpenID se login nepoužívá, a tím pádem to ani není povinný údaj.

Zpráva settings bude vysvětlena později.

Příklad:

<logged uri="http://example.com/Annotations/users/89"
        login="john"
        name="John Doe"
        email="john.doe@example.com"
        image="http://example.com/images/photo.png"/>

Odhlášení uživatele

Klient odhlásí uživatele zprávou typu logout:

<logout/>

Server na tuto zprávu neodpovídá.

Uživatelé a uživatelské skupiny

Uživatel je osoba, které je umožněno přihlásit se k danému serveru skrze uživatelský účet. Skupina uživatelů je entita, která má schopnost sdružovat více uživatelů do jediného celku.

Uživatel je na serveru reprezentován množinou povinných údajů:

Poznámka: V případě použití OpenID se login nepoužívá, a tím pádem to ani není povinný údaj.

Seznamy uživatelů

Dotaz

Klient může požádat server o seznam uživatelů zasláním zprávy typu getUsers:

<getUsers {filtrovací atributy}/>

Je možné specifikovat až čtyři různé atributy, jež filtrují seznam uživatelů, o který má klient zájem:

První dva atributy by samy o sobě měly vést k seznamu o jediném uživateli.

Následující příklad je dotazem na seznam uživatelů, jejichž jméno nebo příjmení začíná na Adam:

<getUsers name="Adam"/>

Dále je možné použít element includeOnly a do něj vkládat elementy, které mají za cíl omezit odpověď jen na některé uživatelské údaje:

<getUsers {filtrovací atributy}>
  <includeOnly>
    {seznam projekčních elementů}
  </includeOnly>
</getUsers>

Makro {seznam projekčních elementů} je tvořeno následujícími elementy, přičemž každý může být použit maximálně jednou:

Pokud není uveden element includeOnly, server vrací všechny informace o uživateli, které má k dispozici. Pokud je uveden, tak server vrací pouze ty údaje, které jsou explicitně uvedeny. Omezení vrácených údajů může být výhodné v případech mohutných přenosů uživatelů, kde nás zajímají jen některé informace -- například v našeptávačích. Atribut uri vrací server vždy.

Následující příklad je požadavkem na seznam všech uživatelů. Kromě uri bude server vracet jméno a e-mail uživatele, žádné jiné údaje:

<getUsers>
  <includeOnly>
    <name/>
    <email/>
  </includeOnly>
</getUsers>

Odpověď

Odpověď od serveru vypadá následovně:

<users>
  {seznam uživatelů}
</users>

Makro {seznam uživatelů} tvoří elementy user:

<user {uživatelské údaje}/>

Případně:

<user {uživatelské údaje}>
  <groups>
    {seznam skupin formátu
      <group uri="{URI skupiny}"/>
    }
  </groups>
</user>

Příklad odpovědi na dotaz výše:

<users>
  <user uri="http://example.com/Annotations/users/89"
        name="John Doe"
        email="john.doe@example.com"/>
  <user uri="http://example.com/Annotations/users/17"
        name="Frank Doe"
        email="frank.doe@example.com"/>
</users>

Seznamy skupin uživatelů

Dotaz

Seznam skupin může klient od serveru získat zasláním zprávy typu getUserGroups:

<getUserGroups {selekční atributy}
               {volitelně: withUsers="{true|false}"}/>

Makro {selekční atributy} tvoří tyto volitelné atributy:

Atribut withUsers udává, zda se u každé skupiny má také zahrnout seznam jejích uživatelů, výchozí je false.

Příklad:

<getUserGroups uri="http://example.com/Annotations/groups/27"
               withUsers="true"/>

Pokud je withUsers nastaveno na true, tak jako u seznamu uživatelů je možné použít element includeOnly, který má shodnou syntaxi i sémantiku:

<getUserGroups {atributy}>
  <includeOnly>
    {seznam projekčních elementů}
  </includeOnly>
</getUserGroups>

Odpověď

Server odpovídá následující zprávou:

<userGroups>
  {seznam skupin}
</userGroups>

Kde jednotlivé skupiny mají formát

<group name="{jméno skupiny}"
       uri="{URI skupiny}"/>

nebo

<group name="{jméno skupiny}"
       uri="{URI skupiny}">
  {seznam uživatelů}
</group>

Příklad celé zprávy:

<userGroups>
  <group name="Administrators"
         uri="http://example.com/Annotations/groups/27">
    <user uri="http://example.com/Annotations/users/17"/>
    <user uri="http://example.com/Annotations/users/89"/>
  </group>
</userGroups>

Vstup uživatele do skupiny

Přihlášený uživatel může vstoupit do skupiny zasláním zprávy typu joinUserGroup:

<joinUserGroup uri="{URI skupiny}"/>

Příklad:

<joinUserGroup uri="http://example.com/Annotations/groups/27"/>

Server na tuto zprávu neodpovídá.

Odchod uživatele ze skupiny

Přihlášený uživatel může vystoupit ze skupiny zasláním zprávy typu leaveUserGroup:

<leaveUserGroup uri="{URI skupiny}"/>

Příklad:

<leaveUserGroup uri="http://example.com/Annotations/groups/27"/>

Server na tuto zprávu neodpovídá.

Odběry anotací

Odběr anotací je objekt, který má specifikované zdroje anotací. Zdroje anotací vybírají anotace podle jejího typu, autora a skupiny autora. Každý odběr je tak jakási šablona pro selekci určité množiny anotací. Každý uživatel je oprávněn se k jakémukoliv odběru přihlásit a získávat tak anotace, o které má zájem, bez toho, aby tyto anotace musel ručně vytvářet. Přihlášení k odběru je platné jen v rámci session. Pokud klient potřebuje odběry odebírat v každé session, musí o ně vždy znovu žádat.

Vytvoření odběru

Dotaz

Klient u odběru vytvoří dočasný identifikátor tmpId. Od serveru přijde mapování dočasného identifikátoru na trvalý identifikátor (URI). Server tedy klientovi neposílá zpátky celý odběr. Klient u odběru smaže tmpId a přiřadí správné uri. Zpráva na vytvoření odběru vypadá takto:

<createSubscription tmpId="{dočasné id odběru}"
                    name="{jméno odběru}">
  {seznam zdrojů formátu
    <source subscribe="{true|false}"
            {selekční atributy zdroje}/>
  }
</createSubscription>

Zdroj source má atribut subscribe, který udává, zda se anotace z tohoto zdroje mají odebírat nebo ne. Lze totiž pomocí pozitivního zdroje (subscribe="true") nastavit odebírání jisté množiny anotací a následně tuto množinu filtrovat dalším negativním zdrojem (subscribe="false").

Makro {selekční atributy zdroje} tvoří volitelné atributy:

Příklad:

<createSubscription tmpId="138"
                    name="My Favorite Art Movements">
  <source subscribe="true"
          typeUri="http://example.com/Annotations/types/g17/Movement"
          authorUri="http://example.com/Annotations/users/123456"
          groupUri="http://example.com/Annotations/groups/27"/>
  <source subscribe="false"
          typeUri="http://example.com/Annotations/types/g17/Movement/Expressionism"/>
</createSubscription>

Odpověď

<subscriptionCreated tmpId="{dočasné id odběru}"
                     uri="{URI odběru}"/>

Příklad:

<subscriptionCreated tmpId="138"
                     uri="http://example.com/Annotations/subscriptions/65"/>

Rušení odběru

Klient může zrušit odběr zasláním zprávy:

<removeSubscription uri="{URI odběru}"/>

Příklad:

<removeSubscription uri="http://example.com/Annotations/subscriptions/438"/>

Server na tuto zprávu neodpovídá.

Modifikace odběru

Klient může modifikovat odběr zasláním následující zprávy:

<modifySubscription uri="{URI odběru}"
                    name="{jméno odběru}">
  {seznam zdrojů formátu
    <source subscribe="{true|false}"
            {selekční atributy zdroje}/>
  }
</modifySubscription>

Příklad:

<modifySubscription uri="http://example.com/Annotations/subscriptions/71"
                    name="My Favorite Art Movements (Modified)">
  <source subscribe="true"
          typeUri="http://example.com/Annotations/types/g17/Movement"
          authorUri="http://example.com/Annotations/users/123456"
          groupUri="http://example.com/Annotations/groups/27"/>
  <source subscribe="false"
          typeUri="http://example.com/Annotations/types/g17/Movement/Expressionism"/>
  <source subscribe="false"
          typeUri="http://example.com/Annotations/types/g17/Movement/Impressionism"/>
</modifySubscription>

Server na tuto zprávu neodpovídá.

Seznamy odběrů

Dotaz

Klient může od serveru požadovat seznam odběrů filtrovaný různými atributy. Pokud žádné atributy nejsou zadány, server vrací seznam všech odběrů od všech uživatelů.

<getSubscriptions {filtrovací atributy}/>

Makro {filtrovací atributy} tvoří volitelné atributy:

Příklad:

<getSubscriptions authorUri="http://example.com/Annotations/users/84"/>

Odpověď

<subscriptions>
  {seznam odběrů formátu
    <subscription uri="{URI odběru}"
                  name="{jméno odběru}"
                  authorUri="{URI autora odběru}">
      {seznam zdrojů formátu
        <source subscribe="{true|false}"
                {filtrovací atributy}/>
      }
    </subscription>
  }
</subscriptions>

Příklad:

<subscriptions>
  <subscription uri="http://example.com/Annotations/subscriptions/71"
                name="My Favorite Art Movements"
                authorUri="http://example.com/Annotations/users/8394">
    <source subscribe="true"
            typeUri="http://example.com/Annotations/types/g17/Movement"
            authorUri="http://example.com/Annotations/users/67"
            groupUri="http://example.com/Annotations/groups/27"/>
    <source subscribe="false"
            typeUri="http://example.com/Annotations/types/g17/Movement/Expressionism"/>
  </subscription>
</subscriptions>

Přihlášení se k odběru

Uživatel se přihlásí k již existujícímu odběru zasláním následující zprávy:

<subscribe subscriptionUri="{URI odběru}"/>

Příklad:

<subscribe subscriptionUri="http://example.com/Annotations/subscriptions/4"/>

Server na tuto zprávu neodpovídá.

Odhlášení se z odběru

Uživatel se může odhlásit z odběru, ke kterému je přihlášen, zasláním následující zprávy:

<unsubscribe subscriptionUri="{URI odběru}"/>

Příklad:

<unsubscribe subscriptionUri="http://example.com/Annotations/subscriptions/4"/>

Server na tuto zprávu neodpovídá.

Synchronizace dokumentu

Všechny dokumenty, které klienti otevřou v anotačním editoru, si server ukládá a klientům vrací URI těchto kopií. Všechny anotace, které dokument anotují, jako cíl anotace uvádějí právě toto URI.

Proces synchronizace

Klienti při procesu synchronizace předávají serveru URI a obsah dokumentu, který mají načtený v editoru. Server se podívá, zda už má dané URI v databázi. Pokud ne, tak jen daný dokument uloží. V případech, kdy se obsahy dokumentů liší, server může přepsat svůj dokument tím, který mu klient poslal. Pak ale také musí zhodnotit, jak se jednotlivé změny v obsahu dotýkají anotací, které dokument anotují, a případně odpovídajícím způsobem aktualizovat jejich fragmenty. V nejhorším případě nebude možné nové fragmenty určit a novým cílem anotace se tak stane celý dokument. Uživatel pak má možnost ručně přenastavit cíle dotyčných anotací.

Dotaz

Zpráva na provedení synchronizace vypadá takto:

<synchronize uri="{URI načteného dokumentu}"
            {volitelné atributy}>
  <![CDATA[{obsah dokumentu}]]>
</synchronize>

Poznámka: Oproti verzi 1.1 chybí obalující element content.

Poznámka: Atribut uri se v protokolu 1.1 jmenuje resource. K přejmenování tady došlo proto, aby se snadněji rozlišovalo:

Makro {volitelné atributy} tvoří volitelné atributy:

Příklad synchronizační zprávy:

<synchronize uri="http://example.com/Annotations/documents/getDoc?id=1234doc1.txt"
             linearized="false"
             overwrite="false">
  <![CDATA[<html><head></head><body><p>Hello World!</p></body></html>]]>
</synchronize>

Odpověď

Server porovná svou verzi dokumentu s tou, kterou posílá klient.

Zpráva synchronized

Tuto zprávu posílá server při úspěšné synchronizaci.

<synchronized resource="{URI serverového dokumentu}"
              lastModification="{ID poslední modifikace}"/>

Atribut resource obsahuje URI serverového dokumentu -- kopie toho dokumentu, jež klient poslal ve zprávě synchronize. Toto URI klient používá u anotací.

Atribut lastModification obsahuje identifikátor poslední modifikace provedené na dokumentu.

Příklad:

<synchronized resource="http://example.com/Annotations/documents/getDoc?id=1234"
              lastModification="72"/>
Varovací zpráva

Pokud budou změněny fragmenty některých anotací uživatele, pak server spolu se zprávou synchronized pošle klientovi varovací zprávu, ve které uvede URI daných anotací:

<warning code="annotations changed">
  <message>
    <![CDATA[Targets of some annotations have been changed due to a document modification.]]>
  </message>
  <annotations>
    {seznam anotací formátu
      <annotation uri="{URI anotace}"/>
    }
  </annotations>
</warning>

Příklad:

<warning code="annotations changed">
  <message>
    <![CDATA[Targets of some annotations have been changed due to document modification.]]>
  </message>
  <annotations>
    <annotation uri="http://example.com/Annotations/serv/3985"/>
    <annotation uri="http://example.com/Annotations/serv/1545"/>
    <annotation uri="http://example.com/Annotations/serv/148868"/>
    <annotation uri="http://example.com/Annotations/serv/88916"/>
    <annotation uri="http://example.com/Annotations/serv/35486"/>
    <annotation uri="http://example.com/Annotations/serv/99"/>
  </annotations>
</warning>
Chybová zpráva

Při neúspěšné synchronizaci se klientovi pošle chybová zpráva:

<error code="sync error">
  <message>
    <![CDATA[Targets of some annotations would be significantly changed if the server's version of the document was updated.]]>
  </message>
  <serverVersion>
    <![CDATA[{obsah serverové verze dokumentu}]]>
  </serverVersion>
</error>

Příklad:

<error code="sync error">
  <message>
    <![CDATA[Targets of some annotations would be significantly changed if the server's version of the document was updated.]]>
  </message>
  <serverVersion>
    <![CDATA[<html><body><p>Konnichiwa sekai!</p></body></html>]]>
  </serverVersion>
</error>

Spolu se zprávou synchronized posílá server klientovi anotace a všechny typy, které jsou potřeba pro interpretaci daných anotací.

Znovuposlání obsahu dokumentu

Zpráva od serveru

Pokud server detekuje neshodu již jednou synchronizovaných verzí dokumentu, ať již k tomuto dojde jakkoliv, server pošle klientovi příkaz, aby mu vrátil momentální obsah dokumentu. Server zprávu posílá přes AJAX kanál, pokud se neshoda týká požadavku klienta (např. požadavek na vytvoření anotace s chybným obsahem fragmentu). V opačném případě zprávu posílá přes comet kanál.

<resynchronize resource="{URI zdroje}"
               method="{soft|hard}"/>

Atributy:

Příklad:

<resynchronize resource="http://example.com/Annotations/documents/getDoc?id=12341234567"
               method="soft"/>

Klientova reakce

Modifikace dokumentu

Klient obsahuje WYSIWYG editor. Uživatel tedy může text libovolně měnit. Klient by měl posílat serveru modifikace textu, které uživatel provedl, co možná nejčastěji, nejlépe s každou změnou -- tj. s každým změněným znakem v dokumentu.

Dotaz

<modification lastApplied="{číslo poslední modifikace}">
  {seznam modifikačních zpráv}
</modification>

Makro {číslo poslední modifikace} zastupuje identifikátor poslední modifikace, kterou klient provedl na svém dokumentu, než vytvořil novou změnu (viz níže).

Makro {seznam modifikačních zpráv} tvoří seznam modifikací. Existují 3 různé typy modifikací:

Odpověď

Aktuální oficiální verze anotovaného dokumentu je uložena na serveru. Modifikování dokumentu je omezeno výlučným přístupem. Když server obdrží nový požadavek na modifikaci ve chvíli, kdy ještě není dokončená obsluha předchozího požadavku, nový požadavek je zařazen do FIFO fronty, kde čeká na uvolnění kritické sekce. Server si kromě obsahu aktuální verze dokumentu vede také čítač jeho změn a určitý počet naposledy aplikovaných změn. Když od klienta přijde požadavek na aplikaci změn, server vyhodnotí, zda je možné provést požadované změny na serverové verzi dokumentu tak, aby výsledek byl korektní z pohledu klienta.

Pokud se verze dokumentu, ze které klient vychází, shoduje s verzí, kterou má server, tak ten bez dalších kontrol dané změny provede, zvýší čítač modifikací a spolu s modifikační zprávou odešle zbývajícím klientům, kteří pracují s dokumentem.

Pokud se verze dokumentů neshodují, je dalším kritériem počet požadavků na změny, které serveru poslali ostatní klienti od doby poslední změny, jakou daný klient zaregistroval. Modifikace z těchto požadavků klient neměl k dispozici a proto je ve své vlastní modifikaci nezohlednil. Pokud je těchto požadavků více než jistá hodnota (prozatím stanoveno na 3), server klientovi posílá chybovou zprávu se sdělením, že klientova verze dokumentu je příliš neaktualní na to, aby bylo možné na ní provádět změny.

Pokud je uniklých požavků na změny méně než daná konstanta, server vyhodnotí, zda kterákoliv ze změn může nějak ovlivnit nové změny. Pokud ano, server posílá klientovi chybovou zprávu, ve které mu oznámí, že změny nemohly být aplikovány kvůli konfliktu s jinými změnami. V opačném případě je změny možné provést -- server zvýší čítač modifikací a spolu s modifikační zprávou odešle zbývajícím klientům, kteří pracují s dokumentem.

Klientovi, který o modifikaci žádá, server v případě úspěchu posílá následující zprávu:

<modificationApplied id="{číslo modifikace}"/>

Číslo modifikace se klient musí dozvědet proto, aby věděl, že toto číslo nemá očekávat u příchozích modifikací od jiných klientů (viz níže).

Ostatním klientům server distribuuje modifikační zprávy v tomto formátu:

<modification id="{číslo modifikace}">
  {seznam modifikačních zpráv}
</modification>

Také klient si vede čítač modifikací provedených na svém dokumentu. Příchozí modifikace vytvářejí frontu, ze které jsou odebrány až v momentě, kdy v čítači modifikací je hodnota o 1 menší, než číslo dané modifikace. Pak je změna provedena a čítač inkrementován.

V době, kdy klient čeká na odpověď na svůj modifikační požadavek, klient neaplikuje žádné příchozí modifikace a všechny případné modifikace provedené uživatelem vkládá do fronty. Pokud server odpovídá na požadavek modifikace chybou, klient má následující možnosti:

Typy

Anotace může nabývat pouze typu anotace (strukturovaný typ). Strukturovaný typ může obsahovat atributy, které mohou nabývat jednoduchých, ale i strukturovaných typů.

Poznámka: Pokud není uvedeno jinak, v celém protokolu platí, že pokud se po klientovi žádá uvedení nějakého typu anotace, server uvažuje i všechny podtypy daného typu. Pokud například klient vyšle požadavek na návrhy anotací s typem Person, server klientovi vrací návrhy anotací i např. typů Person->Employee nebo Person->Artist.

Jednoduché typy

Název URI Popis Příklad hodnoty
String http://www.w3.org/2001/XMLSchema#string ASCII řetězec John Doe
URI http://www.w3.org/2001/XMLSchema#anyUri URI http://example.com
DateTime http://www.w3.org/2001/XMLSchema#dateTime datum a čas v souladu s RFC 3339 (iso-date-time with datespec-full) 2002-10-10T12:00:00-05:00
Date http://www.w3.org/2001/XMLSchema#date datum v souladu s RFC 3339 (datespec-full) 2002-10-10+05:00
Time http://www.w3.org/2001/XMLSchema#time čas v souladu s RFC 3339 (time) 13:20:00-05:00
Integer http://www.w3.org/2001/XMLSchema#integer celé číslo -518
Decimal http://www.w3.org/2001/XMLSchema#decimal desetinné číslo 1.23
Boolean http://www.w3.org/2001/XMLSchema#boolean pravdivostní hodnota true
GeoPoint http://www.w3.org/2003/01/geo/wgs84_pos#Point geografický bod dle Basic Geo (WGS84 lat/long) Vocabulary (basic) 
<geo:Point>
  <geo:lat>55.701</geo:lat>
  <geo:long>12.552</geo:long>
</geo:Point>
AnyAnnotation http://knot.fit.vutbr.cz/annotations/knotOAExtension#anyAnnotation vnořená anotace nebo odkaz na anotaci nenabývá žádné hodnoty
AnyEntity http://knot.fit.vutbr.cz/annotations/knotOAExtension#anyEntity entita nenabývá žádné hodnoty
Duration http://www.w3.org/2001/XMLSchema#duration trvání dle RFC 3339 (duration) - rozšířeno oproti duration z XMLSchema P1Y2MT2H
Binary http://www.w3.org/2001/XMLSchema#base64binary binární data (soubory, např. v OpenDocument formátu); data se kódují do base64; velikost souboru může být limitovaná serverem 0FB8
Text http://knot.fit.vutbr.cz/annotations/knotOAExtension#text dlouhý řetězec Nějaký text
Image http://knot.fit.vutbr.cz/annotations/knotOAExtension#imageUri URI obrázku http://upload.wikimedia.org/wikipedia
/commons/a/a0/Bruegge_View_from
_Rozenhoedkaai.jpg
Entity http://knot.fit.vutbr.cz/annotations/knotOAExtension#entity entita z kontrolovaného slovníku Serializace atributu toto typu je odlišná od serializace atributů všech ostatních jednoduchých typů -- viz Formát anotace.

Formát typu anotace

<type name="{jméno typu}"
      uri="{URI typu}"
      groupUri="{URI skupiny}"
      restrictedAttributes="{omezení atributů}"
      {volitelně: ontologyUri="{URI z ontologie}"}>
  <directAncestors primary="{URI primárního předka}">
    {seznam přímých předků formátu
      <ancestor uri="{URI typu}"/>
    }
  </directAncestors>
  <attributes>
    {seznam atributů}
  </attributes>
  {volitelný komentář formátu
    <comment>
      <![CDATA[{komentář}]]>
    </comment>
  }
</type>

Povinné atributy elementu type:

Atribut ontologyUri se uvádí v případě, že se daný typ nachází v ontologii. Hodnotou atributu je URI typu v dané ontologii.

Element directAncestors má atribut primary, který obsahuje primárního přímého předka, který, je-li prázdný, reprezentuje kořen stromu typů. Podelementy typu ancestor obsahují ostatní přímé předky typu.

Makro {seznam atributů} tvoří prvky attribute:

<attribute valueType="{simple|linked|nested}"
           name="{jméno atributu}"
           typeUri="{URI typu}"
           required="{povinnost atributu}"
           {volitelně: ontologyUri="{URI atributu z ontologie}"}
           {volitelně: priority="{priorita atributu}"}/>
  {volitelně: <comment><![CDATA[{komentář atributu}]]></comment>}
</attribute>

Parametr valueType určuje typ hodnoty:

Parametr ontologyUri je uveden pouze v případě, že atribut patří k nějaké ontologii. V takovém případě se uvede URI atributu z ontologie.

Atributy mohou nabývat jednoduchých i strukturovaných typů.

Příklad serializovaného typu:

<type name="Picture"
      uri="http://example.com/Annotations/types/g17/Art/Artwork/Picture"
      groupUri="http://example.com/Annotations/groups/27"
      restrictedAttributes="true">
  <directAncestors primary="http://example.com/Annotations/types/g17/Art/Artwork">
    <ancestor uri="http://example.com/Annotations/types/g17/Art"/>
    <ancestor uri="http://example.com/Annotations/types/g17/Art/Artist/Work"/>
  </directAncestors>
  <attributes>
    <attribute name="Created"
               typeUri="http://www.w3.org/2001/XMLSchema#date"
               required="true">
      <comment>
        <![CDATA[Date of creation]]>
      </comment>
    </attribute>
    <attribute name="Price"
               typeUri="http://www.w3.org/2001/XMLSchema#integer"
               required="true">
      <comment>
        <![CDATA[Current price of the picture]]>
      </comment>
    </attribute>
  </attributes>
  <comment>
    <![CDATA[Picture is a kind of an artwork.]]>
  </comment>
</type>

Manipulace s typy anotací

Server může ovládat množinou typů anotací, které klient obsahuje. Když klient požaduje typy, server posílá zpět příkaz na přidání typů, které mu blíže specifikuje. Když klient vytvoří nový typ, server přes comet posílá příkaz na přidání typů ostatním klientům, kteří pracují s daným dokumentem. Také klient může přidávat, měnit nebo odebírat typy, které si server uchovává. Komunikaci tvoří tři typy zpráv:

Získání typů anotací od serveru

Dotaz

Klient nemusí vždy potřebovat všechny typy. Typů totiž může být dohromady tolik, že by to klienta mohlo zahltit. Klient si sám žádá o typy a server mu je vrací. Požadavek si server ovšem pamatuje, a když dojde ke změně v nějakém typu (jiný klient modifikoval), o který klient dříve požádal, server mu tyto změny pošle bez požádání.

Klient si může vyžádat typy anotací zasláním následující zprávy:

<getTypes {volitelně: uri="{URI typu}"}/>

Příklad:

<getTypes uri="http://example.com/Annotations/types/g17/Person/Artist"/>

Parametrem uri se vybírá typ a celý jeho podstrom. Je možné použít wildcard *. Pokud atribut není uveden, server vrátí všechny typy anotací ve skupinách daného uživatele.

Odpovědí od serveru je zpráva typu addTypes.

Získání atributů z ontologie

Klient může požádat o atributy z ontologie. Tyto atributy mají již definované jméno a typ. Uživatel se při přidávání nového atributu může rozhodnout, zda si vytvoří vlastní atribut (vyplní jméno a typ) nebo použije již definovaný atribut z ontologie.

Dotaz

<getOntologyAttributes {volitelně: groupUri="{URI skupiny}"}/>

Poznámka: tento element byl přejmenován z queryAttrFromOnto, jak jej definoval protokol 1.1.

Atribut groupUri vyjadřuje URI skupiny, na kterou se omezí seznam atributů. Pokud není uveden, server vrací atributy ze všech skupin.

Příklad:

<getOntologyAttributes groupUri="http://example.com/Annotations/groups/27"/>

Odpověď

<ontologyAttributes>
  {seznam atributů}
</ontologyAttributes>

Poznámka: tento element byl přejmenován z attrsFromOntology, jak jej definoval protokol 1.1.

Seznam atributů je tvořen elementy typu attribute:

<attribute name="{jméno atributu}"
           uri="{URI atributu}"
           typeUri="{URI typu}"
           groupUri="{URI skupiny}">
  {volitelně: <comment><![CDATA[{komentář atributu}]]></comment>}
</attribute>

Anotace

Anotace je strukturovaný komentář k úseku textu v dokumentu. Má typ a atributy. Atributy mohou obsahovat vnořené anotace či odkazy na další anotace a vytvářet tak komplexnější hierarchii.

Formát anotace

Anotace se serializují s respektováním standardu Open Annotation Data Model. Více o tomto standardu: http://www.openannotation.org/spec/core/

<oa:Annotation rdf:about="{URI anotace}">
  <oa:hasBody>
    <oa:SemanticTag rdf:about="{URI typu anotace}"/>
  </oa:hasBody>
  <oa:hasBody>
    <cnt:ContentAsText rdf:about="{URI anotace}#body">
      <rdf:type rdf:resource="http://purl.org/dc/dcmitype/Text"/>
      <cnt:chars>
        <![CDATA[{obsah anotace}]]>
      </cnt:chars>
      <dc:format>text/plain</dc:format>
    </cnt:ContentAsText>
  </oa:hasBody>
    {TARGET}
  <oa:hasBody>
    <cnt:ContentAsText rdf:about="{URI dokumentu}">
      <rdf:type rdf:resource="http://www.w3.org/2004/03/trix/rdfg-1/Graph"/>
      <trix:TriX>
        <trix:graph>
        {SEZNAM ATRIBUTŮ ANOTACE}
        </trix:graph>
      </trix:TriX>
      <dc:format>text/xml</dc:format>
    </cnt:ContentAsText>
  </oa:hasBody>
  <oa:annotatedBy>
    <foaf:Person rdf:about="{URI autora}">
      <foaf:name>{jméno autora}</foaf:name>
      <foaf:mbox>mailto:{emailová adresa autora}</foaf:mbox>
    </foaf:Person>
  </oa:annotatedBy>
  <oa:annotatedAt>{čas vytvoření anotace}</oa:annotatedAt>
  <oa:serializedAt>{čas vytvoření anotace}</oa:serializedAt>
</oa:Annotation>

Poznámka: elementy oa:annotatedAt a oa:serializedAt nesou stejný časový údaj

Popis maker

Manipulace s anotacemi klienta

Server může ovlivňovat množinou anotací, které klient obsahuje. Využívá k tomu následující zprávy:

Vytvoření anotace klientem

Dotaz

Klient může poslat serveru nově vytvořené anotace zasláním této zprávy:

<createAnnotations>
  {seznam anotací}
</createAnnotations>

Makro {seznam anotací} tvoří prvky oa:Annotation. Trvalé URI (prefix serv) musí vytvořit server. Klient vygeneruje dočasnou URI s prefixem temp.

Odpověď

<annotationsCreated>
  {seznam anotací formátu
    <annotation tempUri="{dočasné URI anotace}"
                servUri="{trvalé URI anotace}"/>
  }
</annotationsCreated>

Příklad:

<annotationsCreated>
  <annotation tempUri="http://example.com/Annotations/temp/268"
              servUri="http://example.com/Annotations/serv/13"/>
  <annotation tempUri="http://example.com/Annotations/temp/42"
              servUri="http://example.com/Annotations/serv/711"/>
</annotationsCreated>

Jde o mapování URI s prefixem temp na URI s prefixem serv. Klient musí všechny výskyty URI anotace přepsat trvalým URI.

Modifikace a rušení anotace klientem

Klient může modifikovat a rušit anotace zprávami modifyAnnotations a removeAnnotations. Tyto zprávy jsou shodné s těmi, které posílá server klientovi. Server na ně neodpovídá.

Znovuposlání anotací

Klient může požádat o znovuposlání jedné anotace nebo všech anotací, které jsou v dokumentech, jež má klient otevřené.

<reloadAnnotation {volitelně: uri="{URI anotace}}"/>

Příklad:

<reloadAnnotation uri="http://example.com/Annotations/serv/5556"/>

Atribut uri udává URI anotace, která má být znovu poslána. Pokud není tento atribut uveden, server znovu pošle všechny anotace otevřených dokumentů. Odpovědí serveru je zpráva typu addAnnotations.

Návrhy anotací

Návrh anotace je anotace, kterou nevytváří uživatel anotováním, ale stroj, který v dokumentech vyhledává textové řetězce. Při pozitivním nálezu daný kus textu anotuje a vytvořenou anotaci nabídne uživateli. Návrh anotace se liší od anotace prefixem sugg.

Manipulace s návrhy

Server může ovládat množinu návrhů anotací, které klient obsahuje. Může tak činit těmito dvěma zprávami:

Získání návrhů

Klient může požádat o návrhy anotací zasláním následující zprávy:

<suggestAnnotations minConfidence="{minimální důvěryhodnost}"
                    {volitelně: autoConfirm="{automatické potvrzení}"}>
  {volitelně:
    <types>
      {seznam typů ve formátu
        <type uri="{URI typu anotace}"/>
      }
    </types>
  }
  {volitelně:
    <fragments>
      {seznam fragmentů formátu
        <fragment path="{XPath fragmentu}"
                  {volitelně:
                    offset="{offset}"
                    length="{délka}"
                  }/>
      }
    </fragments>
  }
</suggestAnnotations>

Atributy elementu suggestAnnotations:

Pokud není uveden element types, navrhují se anotace všech typů. Pokud uveden je, navrhují se pouze anotace typů daných elementy type.

Pokud není uveden element fragments, navrhuje se v celém dokumentu. Pokud uveden je, navrhuje se pouze ve fragmentech, které jsou specifikovány elementy fragment.

Atributy elementu fragment:

Pokud ve fragmentu nejsou uvedeny atributy offset a length, server vyhledává v celém uzlu.

Příklad:

<suggestAnnotations>
  <types>
    <type uri="http://example.com/Annotations/types/g17/City"/>
    <type uri="http://example.com/Annotations/types/g17/Person"/>
  </types>
  <fragments>
    <fragment path="html[1]/body[1]/p[3]"
              offset="268"
              length="354"/>
    <fragment path="html[1]/body[1]/p[4]"/>
  </fragments>
</suggestAnnotations>

Odpovědí od serveru je zpráva typu addSuggestions.

Získání alternativ k návrhům

Klient může požádat o alternativy k vybraným návrhům zasláním následující zprávy:

<getAlternativesFor>
  {seznam návrhů anotací formátu:
    <suggestion uri="{URI návrhu anotace}"/>
  }
</getAlternativesFor>

Příklad zprávy:

<getAlternativesFor>
  <suggestion uri="http://example.com/Annotations/sugg/458784"/>
  <suggestion uri="http://example.com/Annotations/sugg/547"/>
  <suggestion uri="http://example.com/Annotations/sugg/35"/>
</getAlternativesFor>

Potvrzení návrhu

Potvrzení návrhu anotace je proces, který iniciuje uživatel. Cílem operace je vytvořit běžnou anotaci z návrhu anotace, který uživatel potvrzuje.

Poznámka: Při potvrzování návrhů si musí klient být vědom toho, že má-li návrh vnořené nebo linkované návrhy anotací, pak je potřeba také potvrdit i všechny tyto návrhy. Pro ně platí stejná pravidla, což ve výsledku znamená, že uživatel může potvrzením jedné anotace potvrdit složitější hierarchii návrhů.

Dotaz

Klient může potvrdit návrhy zasláním následující zprávy:

<confirmSuggestions>
  {seznam návrhů anotací formátu
    <suggestion modified="false"
                uri="{URI návrhu anotace}"/>
  }
</confirmSuggestions>

Případně:

<confirmSuggestions>
  {seznam návrhů anotací formátu
    <suggestion modified="true">
      {anotace formátu oa:Annotation}
    </suggestion>
  }
</confirmSuggestions>

Atribut modified serveru říká, jestli byl návrh upraven před potvrzením. Možné hodnoty:

Příklad celé zprávy:

<confirmSuggestions>
  <suggestion uri="http://example.com/Annotations/sugg/111684"
              modified="false"/>
  <suggestion uri="http://example.com/Annotations/sugg/58568"
              modified="false"/>
</confirmSuggestions>

Odpověď

Od serveru přijde mapování suggUri na servUri:

<suggestionsConfirmed>
  {seznam návrhů formátu
    <suggestion suggUri="{URI návrhu anotace}"
                servUri="{URI anotace}"/>
  }
<suggestionsConfirmed>

Příklad:

<suggestionsConfirmed>
  <suggestion suggUri="http://example.com/Annotations/sugg/111684"
              servUri="http://example.com/Annotations/serv/5557"/>
  <suggestion suggUri="http://example.com/Annotations/sugg/481"
              servUri="http://example.com/Annotations/serv/1"/>
</suggestionsConfirmed>

Klient pak musí nahradit všechny výskyty suggUri za servUri a transformovat návrhy na anotace.

Odmítnutí návrhu

Klient může odmítnout návrh zasláním následující zprávy:

<refuseSuggestions>
  {seznam návrhů anotací formátu
    <suggestion uri="{URI návrhu anotace}"/>
  }
</refuseSuggestions>

Příklad zprávy:

<refuseSuggestions>
  <suggestion uri="http://example.com/Annotations/sugg/111684"/>
  <suggestion uri="http://example.com/Annotations/sugg/1878"/>
</refuseSuggestions>

Na tuto zprávu server neodpovídá.

Kontrolovaný slovník

Kontrolovaný slovník je databáze entit, jež představují reálně existující objekty (i abstraktní). Tyto entity se pak dají používat jako hodnoty atributů anotací. Entity mají své typy, například:

Získání typů entit

Klient může získat seznam typů entit následujícím požadavkem:

Dotaz

<getEntityTypes/>

Odpověď

<entityTypes>
  {seznam typů formátu
    <type name="{název typu}"
          description="{popis typu}"/>
  }
</entityTypes>

Příklad odpovědi:

<entityTypes>
  <type name="artwork"
        description="A work of an artist, considered to has both spiritual and monetary value."/>
</entityTypes>

Získání entit

Dotaz

Klient může požádat server o entity ze slovníku. Komunikace v tomto případě probíhá asynchronně. Požadavek vypadá následovně:

<getEntities name="{jméno entity}"
             {volitelně: type="{typ entity}"}
             {volitelně: maxResults="{maximální počet výsledků}"}/>

Atributy:

Poznámka: Neuvedení limitu počtu vyhledávaných entit nebo jeho vysoká hodnota může způsobit výkonnostní problémy.

Příklad požadavku:

<getEntities type="artwork"
             name="Sunflowers"/>

Odpověď

<entities name="{jméno entity z požadavku}"
          {volitelně: type="{typ entity z požadavku}"}>
  {seznam entit formátu
    <entity name="{jméno entity}"
            uri="{URI entity}"
            type="{typ entity}"
            image="{URI obrázku entity}">
      {volitelně:
        <description>
          <![CDATA[{popis entity}]]>
        </description>
      }
      {další volitelné atributy entity}
    </entity>
  }
</entities>

Atribut type elementu entities udává server v odpovedi pouze v případě, že ho klient uvedl v dotazu.

Příklad odpovědi:

<entities type="artwork"
          name="Sunflowers">
  <entity name="Four Cut Sunflowers"
          uri="http://www.freebase.com/m/04d7gfr"
          type="artwork"
          image="http://athena3.fit.vutbr.cz/kb/images/freebase/04d8b77.jpg">
    <description>
      <![CDATA[Four Cut Sunflowers (Aug.-Sept. 1887) is one of a series of sunflower-themed paintings by Dutch painter Vincent van Gogh. The painting is currently owned by the Krller-Mller Museum in Otterlo.]]>
    </description>
    <artist>Vincent van Gogh</artist>
    <subject>Sunflower</subject>
    <location>Kröller-Müller Museum</location>
    <owner>Kröller-Müller Museum</owner>
    <more_information type="http://www.w3.org/2001/XMLSchema#anyUri">http://artmight.com/Artists/Vincent-van-Gogh-1853-1890/four-cut-sunflowers-paris-51204p.html</more_information>
  </entity>
  <entity name="Vase with Five Sunflowers"
          uri="http://www.freebase.com/m/044dnb2"
          type="artwork"
          image="http://athena3.fit.vutbr.cz/kb/images/freebase/044dnjv.jpg"/>
</entities>

Volitelný atribut type ostatních atributů entity může mít jako hodnotu URI typu String nebo URI z tabulky výše. Výchozí hodnota je http://www.w3.org/2001/XMLSchema#string.

Nastavení

Nastavení je množina parametrů týkajících se klienta nebo serveru. Každý uživatel má na serveru vyhrazenou vlastní sadu parametrů, které může skrze klientskou aplikaci číst a měnit dle potřeby.

Přenos nastavení ze serveru

Pro přenos nastavení ze serveru na klienta se používá zpráva settings:

<settings>
  {seznam parametrů formátu
    <param name="{jméno parametru}"
           value="{hodnota parametru}"
           {volitelně: description="{popis parametru}"}/>
  }
</settings>

Jméno parametru by mělo mít formát

Popis parametru má význam pouze u nestandardních parametrů, i když jeho využití není nijak omezováno.

Příklad zprávy:

<settings>
  <param name="ClientAnnotationTypeColor:Animal->Human"
         value="green"/>
  <param name="ClientAnnotationTypeColor:City"
         value="blue"/>
</settings>

Server tuto zprávu posílá při přihlášení uživatele (spolu se zprávou logged) a při jakékoliv změně v seznamu parametrů. Klient na tuto zprávu reaguje tak, že zahodí dříve získaný seznam parametrů a nahradí ho novým, včetně všech úkonů s tím souvisejících.

Změna parametrů

Klient může měnit parametry na seznamu s nastavením. Do následující zprávy umisťuje pouze ty parametry, které chce změnit:

<updateParameters>
  {seznam parametrů formátu
    <param name="{jméno parametru}"
           {volitelně: value="{hodnota parametru}"}
           {volitelně: description="{popis parametru}"}/>
  }
</updateParameters>

Poznámka: Pokud chce klient odebrat hodnotu parametru, nastaví atribut value na prázdný řetězec. Pokud chce celý parametr odstranit, atribut value neuvádí.

Příklad:

<updateParameters>
  <param name="ClientAnnotationTypeColor:Animal->Human"
         value="red"/>
  <param name="ClientAnnotationTypeColor:City"
         value="silver"/>
</updateParameters>

Server na tuto zprávu neodpovídá, a to ani zprávou settings.

Chyby a varování

Chybová zpráva

<error code="{kód chyby}">
  <message>
    <![CDATA[{popis chyby}]]>
  </message>
  {volitelný kontext chyby}
</error>

Atribut code označuje kód chyby.

V některých speciálních případech může být atribut code nahrazen atributem number. Toto je nutné pro zpětnou kompatibilitu s protokolem verze 1.0 v případech, kdy na straně serveru není možné spolehlivě určit verzi protokolu (např. neznámé číslo sezení či chybný požadavek).

Makro {popis chyby} tvoří detailnější popis chyby, který může klient zobrazit uživateli. Jazyk zprávy je závislý na parametru ServerLanguage v nastavení. Hodnoty tohotu parametru odpovídají ISO 639-2 (pro bibliografické účely). Výchozí hodnotou je eng (angličtina).

Makro {volitelný kontext chyby} tvoří volitelné elementy, které blíže specifikují vzniklou chybu.

Příklad zprávy:

<error code="access denied">
  <message>
    <![CDATA[Access to selected annotation denied.]]>
  </message>
  <annotation uri="http://example.com/Annotations/serv/482"/>
</error>

Varovací zpráva

Varovací zpráva má shodný formát s chybovou zprávou, jen se element zprávy jmenuje warning:

<warning code="{kód varování}">
  <message>
    <![CDATA[{popis varování}]]>
  </message>
  {volitelný kontext varování}
</warning>

Příklad zprávy:

<warning code="fragments changed">
  <message>
    <![CDATA[Fragments of your annotations has been changed.]]>
  </message>
  <annotations>
    <annotation uri="http://example.com/Annotations/serv/17"/>
    <annotation uri="http://example.com/Annotations/serv/232"/>
    <annotation uri="http://example.com/Annotations/serv/88"/>
  </annotations>
</warning>

Seznam chybových kódů

"0" - Nepodporovaná verze protokolu.
"bad credentials" - Chybné přihlašovací jméno nebo heslo.
"permission denied" - Nemáte oprávnění ke zvolené anotaci.
"read only" - Přístup pouze pro čtení - anotace nebyla uložena.
"change not permitted" - Editace není povolena.
"removing not permitted" - Mazání není povolené.
"attribute required" - Chybí povinné atributy.
"attribute value" - Chybná hodnota atributu.
"sug fragment" - Chybná volba fragmentu - nabízení není možné.
"sync error different" - Synchronizace selhala - pro danou URI je již uložen jiný obsah dokumentu.
"sync error not possible" - Synchronizace není možná.
"sync error need resync" - Chyba synchronizace.
"type add not permitted" - Přidávání typů anotací není povolené.
"attribute type unavailable" - Typ atributu neexistuje.
"type malformed" - Typ anotace je chybný.
"type attributes malformed" - Atributy typu anotace jsou chybné.
"type unknown" - Typ anotace neexistuje.
"type name modify" - Změna názvu, předka či skupiny typu anotace není možná.
"settings malformed" - Chyba v nastavení.
"missing document uri" - Synchronizační zpráva bez adresy zdrojového dokumentu.
"missing document content" - Synchronizační zpráva bez obsahu dokumentu.
"bad fragment" - Chybný anotovaný fragment.
"attribute malformed" - Chybný atribut anotace.
"bad confirm" - Chybný indikátor změny nebo identifikátor nabídky.
"changed annot not found" - Editovaná anotace nebyla nalezena. Změny nelze uložit.
"rem annot not found" - Mazaná anotace nebyla nalezena. Anotaci nelze vymazat.
"session expired" nebo "31" - Identifikátor sezení je neplatný - sezení pravděpodobně expirovalo.
"bad request" nebo "32" - Chybný požadavek. Chyba klienta či nekompatibilní verze protokolu.
"module error" - Chyba v modulu serveru.
"reload annot not found" - Požadovaná anotace nebyla nalezena.
"bad document" - Chyba v anotovaném dokumentu.
"annot malformed" - Chyby v anotaci.
"modification not applicable" - Modifikaci textu nelze aplikovat.
"bad sugg type" - Neznámý typ anotace - nabízení není možné.
"not synchronized" - Dokument nebyl synchronizován. Manipulace s anotacemi není možná.
"unknown group" - Neznámá skupina uživatelů.
"used type del" - Mazání využitých typů anotací není dovoleno. Nejprve je nutné smazat všechny anotace daného typu.
"persistence error" - Data nebylo možné uložit kvůli interní chybě serveru.
"duplicit type" - Duplicitní URI typu anotace.
"bad modification" - Popis modifikace textu je chybný.
"type w subtype del" - Mazání typů anotací s podtypy není dovoleno. Nejprve je nutné vymazat všechny podtypy.
"ambiguous fragment" - Nejednoznačný fragment (lze jej nalézt na více místech v dokumentu).
"bad document uri" - Chybný URI anotovaného dokumentu.
"type ancestors malformed" - Seznam předků přidávaného typu anotace je chybný.
"join administrators" - Nelze se přidat do skupiny administrátorů. Tuto operaci smí provést pouze administrátor.
"last admin" - Nemůžete opustit skupinu administrátorů, protože jste jejím posledním členem.
"auto update failed" - Některé anotace by měly být aktualizovány, ale tyto změny nebylo možné uložit.
"SEC not available" - "SEC (Semantic Enrichment Component) server není dostupný (nabídky anotací nebudou dostupné).
"sync error other different" - Jiný klient pracuje s jinou verzí tohoto dokumentu.
"empty entity filter" - Špatný filtr pro název v požadavku na entity.
"unknown sub uri" - Identifikátor odběru nebyl nalezen.
"subscription malformed" - Odběr je chybný.
"empty composite" - Composite fragmentu je prázdný.
"duplicit attribute of type" - Duplicitní atribut typu anotace.
"missing confidence" - V požadavku o nabídky chybí minimální důvěryhodnost.
"bad max entities" - Chybný formát maximálního počtu výsledků v požadavku o entity.
"not in group" - Nejste v žádné skupině uživatelů - nelze manipulovat s typy anotací, anotacemi apod.
"unsupported operation" - Nepodporovaná operace.
"unknown error" - Neznámá chyba.
"suggestions not ready" - Nabídky ještě nejsou připraveny, zkuste to prosím později.
"missing modified sug" - Chybí modikovaný návrh anotace.
"modification specification" - Chybně specifikovaná modifikace.
"duplicit subscription" - Byl nalezen duplicitní odběr.
"bad autoconfirm" - Chybná míra důvěryhodnosti pro automatické potvrzování návrhů.

Seznam kódů varování

"server error" - Nekritická interní chyba serveru.
"annot superseded" - Anotace odstraněna.
"annot orphaned" - Anotace osiřela (fragmenty byly zneplatněny).
"annot updated" - Anotace byla automaticky aktualizována.
"annot partially orphaned" - Anotace částečně osiřela (některé fragmenty byly zneplatněny).
"not logged" - Nejste přihlášen. Můžete se pouze přihlásit nebo odpojit (ostatní zprávy budou ignorovány).
"fragments updated" - Fragmenty anotace byly aktualizovány.