Kiterjesztési pont sémájának szerkesztője

A kiterjesztési pont sémájának szerkesztőjét két módon nyithatja meg: egy új kiterjesztési pont létrehozásának melléktermékeként, illetve egy meglévő kiterjesztési pont séma megnyitásával. Egyezményes jelölésként az új sémák neve ugyanaz, mint a kiterjesztési pont azonosítója, de .exsd fájlkiterjesztéssel.A sémák a bedolgozó könyvtárszerkezetének schema könyvtárába kerülnek.  

A PDE-n belül új kiterjesztési pont létrehozásakor a kezdeti sémafájl is létrejön, és megjelenik a sémaszerkesztő. Azonnal megadhatja a sémát, vagy a szerkesztő bezárásával később is megteheti ezt. Egy teljes kiterjesztési pont séma létrehozása lehetővé teszi, hogy a PDE automatizált segítséget nyújtson a kiterjesztési pont felhasználóinak.

A PDE sémaszerkesztő alapjai ugyanazok az alapelvek, mint a bedolgozó leírófájlszerkesztőjének. Két formázási oldallal és egy forrás oldallal rendelkezik. Mivel az XML séma részletes, és az olvasása nehézkes lehet forrás formátumban, a szerkesztések többségénél ajánlott a formázási oldalak használata.  A forrás oldal a kapott forráskód olvasásánál hasznos.

Példa: Séma létrehozása a "Példaértelmező" kiterjesztési ponthoz

Korábban már sor került a "Példaértelmező" kiterjesztési pont és a kezdeti séma létrehozására. Most nyissa meg a sémát a projekt schema mappájában dupla kattintással a parsers.exsd fájlon. Ez megnyitja a sémaszerkesztőt.

A következőt szeretnénk elvégezni:

  1. A kiterjesztési pont érvényes XML elemeinek és attribútumainak meghatározása.
  2. A szintaxis (tartalmi modell) meghatározása.
  3. Dokumentációs részletek megadása, amelyek majd egy referenciadokumentumba kerülnek.

Minden kiterjesztési pont séma az "extension" elem deklarációjával kezdődik. Egy "parser" nevű új XML elemet fogunk felvenni.

  1. Nyomja meg az Új elem gombot a Kiterjesztési pontok elemei részen belül.
  2. Váltson a Tulajdonságok nézetre, és módosítsa a "New_Element" nevet "parser" névre.
  3. Miközben az új elem ki van választva, kattintson az Új attribútum gombra. Ez utódaként létrehozza a "new_attribute" attribútumot. A tulajdonságlapon módosítsa a name értékét "id" értékre, a use értékét pedig "required" értékre.
  4. A tulajdonságok lapon nyomja meg a helyi eszköztárban található "Attribútum klónozása" gombot. Ez létrehozza az attribútum másolatát.  Ez hasznos, mivel az attribútumok gyorsan létrehozhatók anélkül, hogy el kellene hagyni a tulajdonság lapot.
  5. Módosítsa az új attribútum nevét "name" értékre.
  6. Klónozza újra az attribútumot. Ezúttal a nevét "class" értékre módosítsa.  Ez az attribútum tartalmazza annak a Java osztálynak a teljes képzésű nevét, amelynek egy adott Java felületet kell megvalósítania. Meg kell adnunk ezt, hogy a PDE később kihasználhassa az előnyeit. A típust módosítsa "karakterlánc" értékről "java." értékre.  A basedOn tulajdonságot állítsa com.example.xyz.IParser értékre. (Ez a felület még nem létezik, de majd később létrehozzuk.)

Eddig a sémaszerkesztőnek a következőképpen kell kinéznie:

Kiterjesztési pont sémaszerkesztő - meghatározási oldal

Egy további attribútumot veszünk fel, amely egy egyedi listából veszi fel az értékeket. Ez azt jelenti, hogy az alap string típushoz létre kell hozni egy felsorolási megszorítást. Emellett beállítjuk az attribútum alapértékét.

  1. Miközben a "parser" elem ki van választva, nyomja meg az Új attribútum gombot. Módosítsa a nevét a tulajdonság lapon "mode" értékre.
  2. A megszorítási párbeszédpanel megnyitásához kattintson a "restriction" tulajdonság értékcellájába. 
  3. Módosítsa a megszorítás típusát "none" értékről "enumeration" értékre.
  4. Vegye fel a következő három választási lehetőséget: "never", "always" és "manual".  (Ez az értelmező kiterjesztés három feltételezett módja.)

A megszorítások párbeszédpanelnek a következőképp kell kinéznie:

Típusmegszorítási párbeszédpanel

A párbeszédpanel bezárását követően módosítsa a "use" attribútumot "default" értékre, a "value" attribútumot pedig "always" értékre.  Ez megadja az alapértéket. Figyelje meg, hogy az állapotsor hibaüzenetet jelenít meg az érték beírása közben, mivel az érvényes értékeket a három felsorolt lehetőségre korlátozza.A beírást követően a hibaüzenetnek el kell tűnnie, mert az "always" egy érvényes érték.

Most, hogy az összes elem és attribútum megadása megtörtént, meg kell adni a szintaxist. A cél annak megadása, hogy az "extension" elem bármilyen számú "parser" utódelemmel rendelkezhessen. 

  1. Válassza ki az "extension" elemet. A kezdeti tartalmi modellje üres sorrend kompozítort mutat.
  2. Válassza ki a sorrend kompozítort és az előugró menüben válassza az Új->Referencia->parser lehetőséget. Ez felveszi a parser referenciát a sorrend kompozítorba.
  3. A referenciák alapértelmezett számossága [1,1], ami azt jelenti, hogy poontosan egy "parser" elem lehet. Ez nem pont az, amit mi szeretnénk. Válassza ki a "parser" referenciát és módosítsa a maxOccurs értékét "unbounded" értékre.

A szintaxis megadását követően a szintaxis szakasz alatti DTD közelítés megmutatja, hogy a kiválasztott elem szintaxisa hogyan nézne ki DTD-ben.  Ezek az információk az olyan fejlesztőket segítik, akik kényelmesebben dolgoznak DTD-vel, mint XML sémákkal.

Kiterjesztési pont sémaszerkesztő - elemnyelvtan

Most, az érvényes elemek, attribútumok és szintaxis meghatározását követően információkat kell megadni a kiterjesztési pontról. A sémadokumentációs részleteknek két típusa van:

A dokumentációs részlet első típusa a sémaleírás Meghatározás oldalán van megadva. Az elemek és attribútumok kiválasztásával a "Leírás" részben rövid szöveget adhat meg hozzájuk. A várt formátum nyers HTML (mint a Javadoc esetén is), és a szöveg módosítás nélkül kerül be a végső referenciadokumentumba.

  1. Válassza ki a "parser" elem "id" attribútumát, és írja be a következőket a Leírás szerkesztőbe:
    az értelmező azonosítására használt egyedi név.
  2. Válassza ki a "name" attribútumot, és vegye fel a következő szöveget:
    egy lefordítható név, amely az értelmezőt jelöli a kezelőfelületen.
  3. Válassza ki a "class" attribútumot és vegye fel a következő szöveget (ne feledje a HTML elemeket):
    A <samp>com.example.xyz.IParser</samp> felületet megvalósító Java osztály teljes képzésű neve.
  4. Válassza ki a "mode" attribútumot és vegye fel a következőket:
    egy választható kapcsoló, amely jelzi, hogy az értelmező példánya milyen gyakran fut (az alapértelmezés <samp>always</samp>).

Ezután magáról a kiterjesztési pontról kell megadni egy rövid szöveges leírást. Ehhez át kell váltani a Dokumentáció oldalra:

  1. Az "Áttekintés" lapot kell látnia. A szövegszerkesztőben vegye fel a következő szöveget:

    Ez a kiterjesztési pont további értelmezők csatlakoztatására szolgál. Az értelmezők valójában nem működnek - csak a kiterjesztési pontok sémájának példájához használtuk őket.

    Nyomja meg az Alkalmaz gombot.
  2. Kattintson a "Példák" lapra, és vegye fel a következő szöveget:

    A következő egy példa a kiterjesztési pont használatára:

       <p>
       <pre>
          <extension point="com.example.xyz.parsers">
             <parser
                id="com.example.xyz.parser1"
                name="Sample Parser 1"
                class="com.example.xyz.SampleParser1">
             </parser>
       </extension>
       </pre>
       </p>
    

    Nyomja meg az Alkalmaz gombot.

  3. Válassza ki az "API információk" lapot, és vegye fel a következő szöveget:

    A jelen kiterjesztési pontot bővítő bedolgozóknak a <samp>com.example.xyz.IParser</samp> felületet kell megvalósítaniuk.

    Nyomja meg az Alkalmaz gombot.
  4. Válassza ki a "Szállított megvalósítás" lapot, és vegye fel a következő szöveget:

    Az XYZ bedolgozó az értelmező alapértelmezett megvalósítását biztosítja.

    Nyomja meg az Alkalmaz gombot.
Megjegyzés: Példák megadásakor különleges szempontokat kell figyelembe venni. A PDE a megadott szöveget szokás szerint nyers HTML-ként kezeli, és az egy karakternél több új sor és szóköz karaktert nem veszi figyelembe (mellőzhető szóköz). Ez hasznos, ha szokásos szövegről van szó, de különösen zavaró lehet példák megadásakor, ahol a tagolásnak és a függőleges igazításnak jelentős szerepe van abban, hogy a példa jól mutasson. A PDE erre az esetre is megoldást nyújt: ha a <pre> HTML elemet észleli, a tartalmat módosítás nélkül kezeli (megtartva az összes karaktert), amíg el nem éri a záró </pre> elemet. Ezért lehet a fentihez hasonló példát megadni, úgy, hogy biztosak lehetünk abban, hogy az a végső referenciadokumentumban is jól fog mutatni.

Feltehetően már észrevette, hogy a dokumentáció begépelése közben a szerkesztő Vázlat nézetében egyre több elem rendelkezik "toll" ikonnal. Ez a kis ikon jelzi, hogy a kérdéses elemhez szöveg is tartozik - így gyorsan leellenőrizheti, hogy a dokumentáció hiányzik-e valahol.

Kiterjesztési pont sémaszerkesztő vázlata

A dokumentáció elkészítését követően megtekinthető a referenciadokumentáció. Ezt két módon teheti meg. A munka során bármikor előzetesen megtekintheti a referenciadokumentumot, ha az előugró menüben a Referenciadokumentum előzetes megtekintése lehetőségre kattint. Ennek alternatívájaként a PDE beállításokat megadhatja úgy (Beállítások>Bedolgozó fejlesztés>Fordítók, a Séma lapon), hogy a sémafájlok minden módosításakor automatikusan létrejöjjön a referenciadokumentáció. A létrehozási módszertől függetlenül a példához eredményül kapott dokumentum így néz ki.