Edytor schematów punktów rozszerzeń

Edytor schematów punktów rozszerzeń można otworzyć na dwa sposoby: jako wynik uboczny procesu tworzenia nowego punktu rozszerzenia lub otwierając istniejący schemat punktu rozszerzenia.  Zgodnie z konwencją nowe schematy mają taką samą nazwę, jak identyfikator punktu rozszerzenia, i rozszerzenie nazwy pliku .exsd. Są one zapisywane w katalogu schema w drzewie katalogów modułu dodatkowego.  

Podczas tworzenia nowego punktu rozszerzenia w środowisku PDE zostanie także utworzony początkowy plik schematu i otwarty do edycji w edytorze. Można od razu przystąpić do definiowania schematu lub odłożyć tę czynność na później i zamknąć edytor. Zdefiniowanie kompletnego schematu punktu rozszerzenia pozwala środowisku PDE zaoferować zautomatyzowaną asystę użytkownikom tego punktu.

Edytor schematów w środowisku PDE opiera się na tych samych koncepcjach, co edytor manifestów modułów dodatkowych.  Ma on dwie strony formularzy i jedną stronę kodu źródłowego.  Ponieważ schemat XML jest szczegółowy i mało czytelny w swej formie źródłowej, większość czynności edycyjnych należy wykonywać, korzystając ze stron formularzy.  Strona kodu źródłowego jest przydatna do przeglądania gotowego kodu źródłowego.

Przykład: Tworzenie schematu dla punktu rozszerzenia "Sample Parsers"

W poprzednich sekcjach utworzono punkt rozszerzenia "Sample Parsers" oraz początkowy schemat. Teraz można otworzyć schemat, przechodząc do folderu schema w danym projekcie i klikając dwukrotnie plik parsers.exsd.  Spowoduje to otwarcie edytora schematów.

Do wykonania są następujące czynności:

  1. Definiowanie poprawnych atrybutów i elementów XML dla punktu rozszerzenia.
  2. Definiowanie gramatyki (model treści).
  3. Dostarczenie fragmentów kodu dokumentacji, które zostaną scalone w dokumentację referencyjną.

Każdy schemat punktu rozszerzenia zaczyna się od deklaracji elementu "extension".  Następnie jest dodawany nowy element XML o nazwie "parser".

  1. Kliknij przycisk Nowy element w sekcji Elementy punktu rozszerzenia.
  2. Przejdź do widoku Właściwości i zmień jego nazwę z "Nowy_element" na "parser".
  3. Gdy nowy element będzie w dalszym ciągu zaznaczony, kliknij przycisk Nowy atrybut. Spowoduje to utworzenie atrybutu "nowy_atrybut" jako elementu podrzędnego tego elementu. W polu name na arkuszu właściwości wpisz "id", a w polu use - "required".
  4. Pozostając w arkuszu właściwości, kliknij przycisk "Klonuj ten atrybut" dostępny na lokalnym pasku narzędzi. Spowoduje to utworzenie kopii atrybutu.  Opcja ta jest użyteczna, ponieważ pozwala szybko zdefiniować wszystkie atrybuty, bez konieczności zamykania arkusza właściwości za każdym razem.
  5. Zmień nazwę nowego atrybutu na "name".
  6. Ponownie sklonuj atrybut. Tym razem zmień jego nazwę na "class" . Ten atrybut będzie reprezentował pełną nazwę klasy Java, która musi implementować konkretny interfejs Java. Atrybut ten jest potrzebny, aby środowisko PDE mogło później z niego skorzystać. Zmień wartość w polu kind z "string" na "java".  Właściwości basedOn nadaj wartość com.example.xyz.IParser.  (Ten interfejs jeszcze nie istnieje, ale zostanie utworzony później).

Po wykonaniu powyższych czynności edytor powinien wyglądać tak, jak na poniższej ilustracji:

Edytor schematów punktów rozszerzeń - strona Definicja

Teraz zostanie dodany kolejny atrybut, którego wartości będą wybierane z listy wartości.  Oznacza to, że należy utworzyć ograniczenie typu wyliczenie (enumeration) dla podstawowego typu string. Ponadto nowemu atrybutowi zostanie nadana wartość domyślna.

  1. Po zaznaczeniu elementu "parser" kliknij przycisk Nowy atrybut. Zmień jego nazwę w arkuszu właściwości na "mode".
  2. Kliknij w komórce wartości właściwości "restriction", aby wyświetlić okno dialogowe ograniczeń. 
  3. Zmień typ ograniczenia z "none" na "enumeration".
  4. Dodaj następujące trzy opcje: "never", "always" i "manual".  (Są to trzy hipotetyczne tryby dla rozszerzenia z analizatorem składni).

Okno dialogowe ograniczeń powinno wyglądać następująco:

Okno dialogowe Ograniczenie typu

Po zamknięciu okna dialogowego zmień wartość atrybutu "use" na "default" i wartość atrybutu "value" na "always".  W ten sposób zostanie ustanowiona nowa wartość domyślna.  Zwróć uwagę, że podczas wpisywania tej wartości w wierszu statusu wyświetlany jest komunikat o błędzie, ponieważ poprawne wartości są ograniczone do trzech opcji (na podstawie typu ograniczenia enumeration). Po zakończeniu wpisywania komunikat powinien zniknąć, gdyż wartość "always" jest poprawna.

Teraz po zdefiniowaniu wszystkich elementów i atrybutów należy zdefiniować gramatykę. Zadanie polega na zdefiniowaniu reguły mówiącej, że element "extension" może mieć dowolną liczbę elementów potomnych "parser". 

  1. Wybierz element "extension". Jego początkowy model treści zawiera pustego kompozytora sekwencji.
  2. Zaznacz kompozytora sekwencji i wybierz kolejno opcje: Nowy -> Odwołanie -> parser z menu wywoływanego. W ten sposób do kompozytora sekwencji zostanie dodane odwołanie do elementu parser.
  3. Domyślna liczność odwołań to [1,1] co oznacza, że może być dokładnie jeden element "parser". Ale nie całkiem o to chodziło. Trzeba zaznaczyć odwołanie do elementu "parser" i zmienić wartość atrybutu maxOccurs na "unbounded".

Po zdefiniowaniu gramatyki w oknie Przybliżenie DTD (znajdującym się poniżej sekcji gramatyki) zostanie wyświetlona gramatyka dla zaznaczonego elementu w postaci, w jakiej powinna występować w gotowej deklaracji DTD.  Informacje te są pomocne dla programistów, którzy nadal wolą korzystać z deklaracji DTD niż ze schematów XML.

Edytor schematów punktów rozszerzeń - gramatyka elementu

Teraz, po zdefiniowaniu poprawnych elementów, atrybutów i gramatyki, należy dostarczyć pewnych informacji na temat punktu rozszerzenia. Wyróżnia się dwa rodzaje fragmentów kodu z dokumentacją schematu:

Pierwszy typ fragmentów kodu jest dostępny na stronie Definicja manifestu schematu. Po wybraniu elementów i atrybutów można dodać krótki tekst z ich opisem w sekcji "Opis". Oczekiwany format to zwykły HTML (podobnie jak w dokumentacji Javadoc). Tekst zostanie skopiowany bez zmian do końcowego dokumentu referencyjnego.

  1. Zaznacz atrybut "id" elementu "parser" i wpisz w edytorze Opis następujący tekst:
    unikalna nazwa, która będzie używana w odwołaniach do tego analizatora składni
  2. Zaznacz atrybut "name" i dodaj następujący tekst:
    możliwa do przetłumaczenia nazwa, która będzie używana do prezentacji tego analizatora w interfejsie użytkownika
  3. Zaznacz atrybut "class" i dodaj następujący tekst (zwróć uwagę na znaczniki HTML):
    pełna nazwa klasy Java, która implementuje interfejs <samp>com.example.xyz.IParser</samp>
  4. Zaznacz atrybut "mode" i dodaj następujący tekst:
    opcjonalna flaga, która wskazuje, jak często ta instancja analizatora będzie uruchamiana (wartość domyślna to <samp>always</samp>).

Teraz należy dodać krótki opis tekstowy samego punktu rozszerzenia. W tym celu należy przejść na stronę Dokumentacja:

  1. Powinna zostać wyświetlona karta "Przegląd". W edytorze tekstu wpisz:

    Ten punkt rozszerzenia służy do podłączania dodatkowych analizatorów składni. W rzeczywistości analizatory te nie działają - zostały one użyte tylko jako przykład schematu punktu rozszerzenia.

    Kliknij przycisk Zastosuj.
  2. Kliknij kartę "Przykłady" i wpisz następujący tekst:

    Poniżej przedstawiono przykład składni punktu rozszerzenia:

       <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>
    

    Kliknij przycisk Zastosuj.

  3. Kliknij kartę "Informacje o interfejsie API" i wpisz poniższy tekst:

    Moduły dodatkowe, które mają rozszerzać ten punkt rozszerzenia muszą implementować interfejs <samp>com.example.xyz.IParser</samp>.

    Kliknij przycisk Zastosuj.
  4. Zaznacz kartę "Dostarczone implementacje" i wpisz następujący tekst:

    Moduł dodatkowy XYZ udostępnia domyślną implementację tego analizatora składni.

    Kliknij przycisk Zastosuj.
Uwaga: Podczas udostępniania przykładów należy wziąć pod uwagę następujące kwestie. Normalnie środowisko PDE traktuje podany tekst jak zwykły HTML i nie uwzględnia znaków nowych wierszy i wielu znaków odstępu (czyli pomijalnych znaków odstępu). Jest to zgodne z oczekiwaniami w przypadku normalnego tekstu, ale staje się niesłychanie irytujące w przypadku przykładów, kiedy to wcięcia poszczególnych wierszy oraz wyrównanie w pionie mają podstawowe znaczenie dla czytelności przykładu. W takiej sytuacji środowisko PDE oferuje rozwiązanie kompromisowe: w razie wykrycia znacznika HTML <pre> wczyta treść bez zmian (zachowując wszystkie znaki), aż do znacznika zamykającego </pre>. W ten sposób można dokumentować przykłady, jak powyżej, i mieć pewność, że będą one dobrze wyglądały w końcowym dokumencie referencyjnym.

W miarę wpisywania tekstu dokumentacji, coraz więcej elementów w widoku Schemat w edytorze jest oznaczanych ikoną "ołówka". Ten mały wskaźnik informuje, że z danym elementem jest powiązany jakiś tekst - dzięki niemu można szybko sprawdzić, czy w dokumencie referencyjnym nie będzie brakowało opisów niektórych elementów.

Widok Schemat w edytorze schematów punktów rozszerzeń

Po zakończeniu tworzenia dokumentacji referencyjnej można ją obejrzeć. Można to zrobić na dwa sposoby. W dowolnym momencie podczas pracy można wyświetlić podgląd dokumentu referencyjnego, wybierając opcję Podgląd dokumentu referencyjnego z menu wywoływanego. Rozwiązaniem alternatywnym jest skonfigurowanie w preferencjach środowiska PDE (Preferencje > Programowanie modułów dodatkowych > Kompilatory, karta Schemat) funkcji automatycznego tworzenia dokumentacji referencyjnej po każdej zmianie w pliku schematu. Niezależnie od metody tworzenia, dokument wynikowy dla tego przykładu będzie wyglądał mniej więcej tak.