Segédanyag az AURORA XML-alapú formátumához

Formális specifikáció és példafájl

Az XSD fájl itt érhető el.

Egy példa XML itt érhető el.

Áttekintő leírás

A document elem egy órarend-dokumentumot reprezentál, amely tartalmazza a teljes nyilvántartást, és több órarendi tábla is szerepelhet benne. Az XML-re vonatkozó megkötéseket figyelembe véve, egy üres dokumentum szabványosan így néz ki:

<?xml version="1.0" encoding="UTF-8"?>
<document
  xmlns="http://orarend-program.hu/xml/schema/document"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="
    http://orarend-program.hu/xml/schema/document http://orarend-program.hu/xml/schema/document/document.xsd
  "
>
</document>

A dokumentum szerkezete az alábbi:

<document>
  <header></header>
  <periods></periods>
  <timingSets></timingSets>
  <tags></tags>
  <resources></resources>
  <blocks></blocks>
  <boards></boards>
  <extraData></extraData>
</document>

A gyermekelemek mindegyike opcionális, bár egy végleges órarendfájlban valószínűleg mindegyikre szükség van.

A header részben a dokumentumhoz tartozó metainformációk adhatók meg. Az elemen belül tetszőleges számú info elem helyezhető el, mindegyik egy kulcs-érték párt tartalmaz, ahol a kulcs a name, az érték pedig a value attribútumban szerepel.

Jelenleg csak a label kulcs alatti adat kerül felhasználásra, mint a dokumentum címe. A többi metaadat a dokumentum újramentésével elveszik. A későbbiekben ezt a viselkedést átalakítjuk, hogy minden adat megőrzésre kerüljön, és a dokumentum címe várhatón a document elem attribútuma lesz.

Kiegészítő adatok tárolásához inkább az extraData elem ajánlott, amely összetett adatstruktúrákat is támogat.

A periods, timingSets, tags, resources, blocks és boards gyűjtőelemek jelenleg a felhasználó által látható nyilvántartással azonosak. Az ezekben definiált objektumoknál megadható az id attribútum, mely alapján az adott objektum más helyeken hivatkozható. Például a <cycle id="felev1"> elem a <cycleRef cycleId="felev1"> elemmel hivatkozható. A hivatkozó elem neve általában az eredeti névnek a Ref végződéssel való megtoldása. A későbbiekben tervezzük bevezetni annak lehetőségét, hogy ezekben a gyűjtőcímkékben rejtett objektumok is elhelyezhetők legyenek, lehetővé téve a nyilvántartásban nem szereplő, de több helyen is felhasznált (megosztott) referenciák kezelését.

A cycles elemben adhatók meg a globálisan definiált ciklusok.

A timingSets elemben [...]

Az extraData elem kiegészítő adatokat tárol. Ezek tetszőlegesek lehetnek, és a program alapértelmezetten azok fel- vagy fel nem használásától függetlenül megtartja az adatokat. Azonban a program egyes alapelemei és kiegészítő funkciói manipulálhatják ezt az adatstruktúrát. Ajánlott ezért saját névtérben dolgozni, amelyhez ajánlott a map gyökérelemben egy kiválasztott egyedi kulcsot használni, és csak a kulcs alatti adatstruktúrát érinteni.

Használható az üres és attribútum nélküli null elem. Példa:

<null />

Használhatók a boolean, byte, short, int, long, float, double, char és string elemek, melyek value attribútumában adható meg az érték, szabványos formátumban. Példák:

<boolean value="1" />
<boolean value="true" />
<long value="24273498" />
<char value="É" />
<string value="Hello Világ!" />

Használhatók a cycle, cycleRef, timingSet, timingSetRef, timeLimit, tag, tagRef, resource, resourceRef, block és blockRef elemek, melyek ad hoc definíciók vagy hivatkozások a nyilvántartási elemekre. A későbbiekben a táblák támogatását is bevezetjük.

Használhatók a list és set elemek, melyek további tetszőleges adatelemeket tartalmazhatnak felsorolva. A set elem egy halmaz típusú adatstruktúrát hoz létre, melyben az elemek sorrendje irreleváns és egy elem csak egyszer szerepelhet (a duplikációk törlésre kerülnek). Az alábbi példa egy háromelemű, egész számokat tartalmazó listát tartalmaz:

<list>
  <int value="1274" />
  <int value="2365" />
  <int value="5770" />
</list>

Használható a map elem. Ez az entry elemekkel definiált bejegyzések halmaza. Minden entry elem egy key és egy value gyermekelemet tartalmaz, melyek a kulcs-érték párnak felelnek meg. Mindkét gyermekelem egyetlen gyermekelemet tartalmazhat, mely tetszőleges adat lehet. Például:

<map>
  <entry>
    <key>
      <string value="name" />
    </key>
    <value>
      <string value="Kiss István" />
    </value>
  </entry>
  <entry>
    <key>
      <string value="city" />
    </key>
    <value>
      <string value="Budapest" />
    </value>
  </entry>
  <entry>
    <key>
      <string value="email" />
    </key>
    <value>
      <string value="kiss.istvan@example.hu" />
    </value>
  </entry>
</map>

Végül használható az object elem, de ennek támogatása egyelőre minimális. Minden fel nem ismert objektum így kerül mentésre. Beolvasáskor jelenleg az ilyen elemekből egyszerű objektumok jönnek létre. A későbbiekben tervezzük ennek az elemnek a teljeskörű támogatását hozzáadni (pl. esetlegesen konstruktorhívás, JAXB binding, JSON serialization, Memento pattern vagy más módokon)

A későbbiekben itt is változás várható: több extra adatstruktúra definiálására lesz lehetőség, melyek eleve külön névtérben léteznek majd. Esetleg egy-egy plugin hozzáférése is limitálva lesz a hozzá párosítható adatstruktúrá(k)hoz.