A Interfejs API — materiał referencyjny

Niniejszy dodatek zawiera krótki materiał referencyjny. Przedstawione są stutaj najważniejsze in­ter­fejsy API Javy: SAX, DOM, a także JDOM, omówiony w rozdziale 8. oraz wspomniany w in­nych częściach książki. Rozdział podzielony jest na części opisujące poszczególne interfejsy.

SAX 2.0

SAX 2.0 umożliwia sekwencyjną obsługę dokumentu XML. Został przedstawiony w rozdziałach 3. i 5. SAX zawiera interfejsy, które użytkownik implementuje w aplikacji i uruchamia jako wy­wo­łania następujące w trakcie przetwarzania danych XML. Poniżej opisane są pakiety SAX, wraz z alfabetycznymi listami klas i interfejsów. W pakiecie org.xml.sax.helpers duży odsetek metod w klasach pomocniczych to implementacje interfejsów już zdefiniowanych w podsta­wo­wym pakiecie SAX (org.xml.sax). W celu zachowania zwięzłości te zdublowane definicje me­tod pominięto; zamiast tego wstawiono komentarz mówiący, że zaimplementowano metody da­nego interfejsu.

Pakiet org.xml.sax

Ten pakiet zawiera podstawowe interfejsy i klasy SAX 2.0. Większość zdefiniowanych inter­fej­sów została zaprojektowana z myślą o implementacji przez nas, programistów Javy; wyjątkiem są właściwe implementacje XMLReader oraz Attributes. Interfejsy te powinny być imple­men­to­wane przez oprogramowanie do przetwarzania XML, pochodzące od określonego producenta. Oprócz tego w niniejszym pakiecie zdefiniowano szereg wyjątków, jakie mogą zostać zgłoszone przez metody SAX. Niektóre interfejsy stanowią pozostałość po wersjach SAX 1.0 oraz 2.0 alfa i obecnie nie zaleca się korzystania z nich.

AttributeList

Ten interfejs został zdefiniowany w SAX 1.0 i obecnie nie zaleca się korzystania z niego. Zamiast niego w implementacjach SAX 2.0 należy używać interfejsu Attributes.

public interface AttributeList {

public abstract int getLength ();

public abstract String getName (int i);

public abstract String getType (int i);

public abstract String getValue (int i);

public abstract String getType (String name);

public abstract String getValue (String name);

}

Attributes

Interfejs ten reprezentuje listę atrybutów języka XML. Jest przekazywany do wywołań funkcji związanych z początkiem elementu (startElement() w klasie ContentHanlder) i przy­po­mina w pewnym sensie Vector języka Java. Można uzyskać liczbę reprezentowanych atrybutów, a także ich nazwy w różnych postaciach (lokalne, przedrostek przestrzeni nazw i identyfikator URI oraz w postaci „surowej”) oraz wartości. Ponadto dostępne są metody odnajdujące indeks atrybutu po podaniu jego nazwy. Zasadnicza różnica pomiędzy tym interfejsem a jego poprzednikiem AttributeList polega na tym, że Attributes „rozumie” przestrzenie nazw.

--> public interface Attributes {

public abstract int getLength ();

public abstract String getURI (int index);

public abstract String getLocalName (int index);

public abstract String getQName (int index);

public abstract String getType (int index);

public abstract String getValue (int index);

public int getIndex (String uri, String localPart);

public int getIndex (String qName);

public abstract String getType (String uri, String localName);

public abstract String getType (String qName);

public abstract String getValue (String uri, String localName);

public abstract String getValue (String qName);

}[Author:AJ]

ContentHanlder

W interfejsie tym zdefiniowano metody operujące na zawartości przetwarzanego dokumentu XML. Zgłaszają one rozpoczęcie i zakończenie przetwarzania (odpowiednio, przed i po wszelkich innych wywołaniach), napotkanie instrukcji przetwarzania oraz encji, które mogą zostać pominięte w parserach nie wykonujących sprawdzania poprawności. Dostępne są również wywołania dla elementów; w wywołaniach tych brane są pod uwagę przestrzenie nazw. Pełny opis interfejsu moż­na znaleźć w rozdziale 3.

public interface ContentHandler

{

public void setDocumentLocator (Locator locator);

public void startDocument ()

throws SAXException;

public void endDocument()

throws SAXException;

public void startPrefixMapping (String prefix, String uri)

throws SAXException;

public void endPrefixMapping (String prefix)

throws SAXException;

public void startElement (String namespaceURI, String localName,

String qName, Attributes atts)

throws SAXException;

public void endElement (String namespaceURI, String localName,

String qName)

throws SAXException;

public void characters (char ch[], int start, int length)

throws SAXException;

public void ignorableWhitespace (char ch[], int start, int length)

throws SAXException;

public void processingInstruction (String target, String data)

throws SAXException;

public void skippedEntity (String name)

throws SAXException;

}

DocumentHandler

Ten interfejs został zdefiniowany w SAX 1.0 i obecnie nie zaleca się korzystania z niego. Zamiast niego w implementacjach SAX 2.0 należy używać interfejsu ContentHandler.

public interface DocumentHandler {

public abstract void setDocumentLocator (Locator locator);

public abstract void startDocument ()

throws SAXException;

public abstract void endDocument ()

throws SAXException;

public abstract void startElement (String name, AttributeList atts)

throws SAXException;

public abstract void endElement (String name)

throws SAXException;

public abstract void characters (char ch[], int start, int length)

throws SAXException;

public abstract void ignorableWhitespace (char ch[], int start, int length)

throws SAXException;

public abstract void processingInstruction (String target, String data)

throws SAXException;

}

DTDHandler

W interfejsie tym zdefiniowano funkcje wywoływane w czasie przetwarzania definicji DTD. In­terfejs ten nie udostępnia informacji o zawężeniach określonych w DTD, ale o odwołaniach do nie­przetworzonych encji i deklaracji NOTATION, czyli wskazuje na obiekty stanowiące nie­prze­tworzone dane. Pełny opis interfejsu znajduje się w rozdziale 5.

public interface DTDHandler {

public abstract void notationDecl (String name,

String publicId,

String systemId)

throws SAXException;

public abstract void unparsedEntityDecl (String name,

String publicId,

String systemId,

String notationName)

throws SAXException;

}

EntityResolver

Interfejs ten umożliwia obsługę zewnętrznych encji z poziomu aplikacji, np. gdy w dokumencie XML znajduje się odwołanie do definicji DTD czy arkusza stylu. Po zaimplementowaniu tego interfejsu możliwe jest zwrócenie do programu wywołującego zmodyfikowanego lub nawet cał­ko­wi­cie innego obiektu SAX InputSource. Ponadto, jeśli dla określonego identyfikatora syste­mo­wego powinno zostać otwarte zwykłe połączenie URI, zwracana jest wartość null.

public interface EntityResolver {

public abstract InputSource resolveEntity (String publicId,

String systemId)

throws SAXException, IOException;

}

ErrorHandler

Interfejs ten umożliwia określenie, jak ma się zachować aplikacja po napotkaniu jednego z trzech błędów, jakie mogą być zgłoszone w trakcie przetwarzania kodu XML. Każda z metod otrzymuje wyjątek SAXParseException, wskazujący, jaki problem spowodował wywołanie. Interfejs zgła­sza wyjątek SAXException, oznaczający sytuację, w której dalsze przetwarzanie nie jest moż­liwe. Pełny opis interfejsu zamieszczono w rozdziałach 3 i 5.

public interface ErrorHandler {

public abstract void warning (SAXParseException exception)

throws SAXException;

public abstract void error (SAXParseException exception)

throws SAXException;

public abstract void fatalError (SAXParseException exception)

throws SAXException;

}

HandlerBase

Ta klasa pomocnicza udostępnia puste implementacje wszystkich podstawowych interfejsów pro­ce­dur obsługi SAX 1.0. Można ją rozszerzyć tak, by umożliwiała szybkie dodawanie procedur obsługi poprzez „nadpisywanie” metod kodem specyficznym dla danej aplikacji. Tak klasa została zdefiniowana w SAX 1.0 i obecnie nie zaleca się korzystania z niej. Zamiast niej w im­ple­men­ta­cjach SAX 2.0 należy używać klasy org.xml.sax.helpers.DefaultHandler.

public class HandlerBase

implements EntityResolver, DTDHandler, DocumentHandler, ErrorHandler

{

// implementacja EntityResolver

public InputSource resolveEntity (String publicId, String systemId);

//implementacja DTDHandler

public void notationDecl (String name, String publicId, String systemId);

public void unparsedEntityDecl (String name, String publicId,

String systemId, String notationName);

// implementacja DocumentHandler

public void setDocumentLocator (Locator locator);

public void startDocument ()

throws SAXException;

public void endDocument ()

throws SAXException;

public void startElement (String name, AttributeList attributes)

throws SAXException;

public void endElement (String name)

throws SAXException;

public void characters (char ch[], int start, int length)

throws SAXException;

public void ignorableWhitespace (char ch[], int start, int length)

throws SAXException;

public void processingInstruction (String target, String data)

throws SAXException;

// implementacja ErrorHandler

public void warning (SAXParseException e)

throws SAXException;

public void error (SAXParseException e)

throws SAXException;

public void fatalError (SAXParseException e)

throws SAXException;

}

InputSource

Ta klasa pełni rolę „kapsułki” zawierającej wszystkie informacje o zasobie wykorzystywanym w przetwarzaniu kodu XML. Może to być po prostu obiekt String lub InputStream, ale może to być także obiekt bardzo złożony, np. encja zawierająca identyfikator publiczny i sys­te­mowy czy identyfikator URI określający publiczną definicję DTD. Klasy tej powinno się używać jako „opakowania” danych wejściowych przekazywanych do parsera SAX.

public class InputSource {

public InputSource ();

public InputSource (String systemId);

public InputSource (InputStream byteStream);

public InputSource (Reader characterStream);

public void setPublicId (String publicId);

public String getPublicId ();

public void setSystemId (String systemId);

public String getSystemId ();

public void setByteStream (InputStream byteStream);

public InputStream getByteStream ();

public void setEncoding (String encoding);

public void setCharacterStream (Reader characterStream);

public Reader getCharacterStream ();

}

Locator

Klasa ta stanowi uzupełnienie dokumentu XML lub innej przetwarzanej konstrukcji. Udostępnia identyfikator systemowy i publiczny dokumentu oraz informacje o tym, w którym miejscu pliku ma miejsce przetwarzanie w danej chwili. Klasa szczególnie przydaje się w aplikacjach typu IDE oraz do określania, w którym momencie przetwarzania występują błędy. Pełny opis tego interfejsu znajduje się w rozdziale 3.

public interface Locator {

public abstract String getPublicId ();

public abstract String getSystemId ();

public abstract int getLineNumber ();

public abstract int getColumnNumber ();

}

Parser

Ten interfejs został zdefiniowany w SAX 1.0 i obecnie nie zaleca się korzystania z niego. Zamiast niego w implementacjach SAX 2.0 należy używać interfejsu XMLReader.

public interface Parser

{

public abstract void setLocale (Locale locale)

throws SAXException;

public abstract void setEntityResolver (EntityResolver resolver);

public abstract void setDTDHandler (DTDHandler handler);

public abstract void setDocumentHandler (DocumentHandler handler);

public abstract void setErrorHandler (ErrorHandler handler);

public abstract void parse (InputSource source)

throws SAXException, IOException;

public abstract void parse (String systemId)

throws SAXException, IOException;

}

SAXException

Podstawowy wyjątek zgłaszany przez wywołania SAX i implementacje parsera. Ponieważ często zgłaszany jest w wyniku zgłoszenia innych wyjątków, posiada konstruktor pozwalający na prze­ka­za­nie wyjątku Exception „niższego poziomu” oraz metody umożliwiające pobranie informacji o tym wyjątku. Zawiera również klasę podstawową dla wszystkich innych klas SAX Exception.

public class SAXException extends Exception {

public SAXException (String message);

public SAXException (Exception e);

public SAXException (String message, Exception e);

public String getMessage ();

public Exception getException ();

public String toString ();

}

SAXNotRecognizedException

Klasa ta umożliwia zgłaszanie przez implementację XMLReader wyjątku informującego, że otrzy­many identyfikator nie został rozpoznany. Jest to sytuacja najbardziej typowa w metodach set­Property() oraz setFeature() (oraz ich odpowiednikach w postaci akcesorów) i oznacza, że otrzymano identyfikator URI, o którym parser nie posiada żadnych informacji.

public class SAXNotRecognizedException extends SAXException {

public SAXNotRecognizedException (String message);

}

SAXNotSupportedException

Klasa ta umożliwia zgłaszanie przez implementację XMLReader --> wyjątku informującego[Author:RG] , że otrzy­many identyfikator został rozpoznany, ale nie jest obsługiwany. Jest to sytuacja najbardziej ty­powa w metodach setProperty() oraz setFeature() (oraz ich odpowiednikach w po­sta­ci akcesorów) i oznacza, że otrzymano identyfikator URI, który nie jest obsługiwany.

public class SAXNotSupportedException extends SAXException {

public SAXNotSupportedException (String message);

}

SAXParseException

Klasa ta reprezentuje wyjątki, jakie mogą zostać zgłoszone w czasie procesu przetwarzania. In­formacje o miejscu wystąpienia błędu w dokumencie XML są dostępne poprzez akcesory tej klasy. Zaleca się dostarczanie tej informacji do klasy poprzez Locator, ale wiersz i kolumnę, w której wystąpiły problemy, można zgłosić bezpośrednio przez przeładowane konstruktory. Iden­ty­fi­ka­to­ry: systemowy i publiczny dokumentu, w którym wystąpiły problemy, są także udostępniane na różne sposoby poprzez konstruktory.

public class SAXParseException extends SAXException {

public SAXParseException (String message, Locator locator);

public SAXParseException (String message, Locator locator,

Exception e);

public SAXParseException (String message, String publicId, String systemId,

int lineNumber, int columnNumber);

public SAXParseException (String message, String publicId, String systemId,

int lineNumber, int columnNumber, Exception e);

public String getPublicId ();

public String getSystemId ();

public int getLineNumber ();

public int getColumnNumber ();

}

XMLFilter

Jest to klasa analogiczna do XMLReader, jednak uzyskuje informacje o zdarzeniach z innej klasy XMLReader, a nie ze statycznego dokumentu czy zasobu sieciowego. Filtry tego typu można również łączyć w łańcuchy. Klasa służy głównie do modyfikacji wyjścia z interfejsu XMLReader znajdującego się „na niższym poziomie” i do odfiltrowania danych zgłaszanych metodom, jeszcze zanim informacje o tych danych otrzyma aplikacja.

public interface XMLFilter extends XMLReader

{

public abstract void setParent (XMLReader parent);

public abstract XMLReader getParent ();

}

XMLReader

Podstawowy interfejs definiujący sposób przetwarzania SAX 2.0. Oprogramowanie do prze­twa­rzania danych XML dowolnego producenta musi zawierać przynajmniej jedną implementację tego interfejsu. Interfejs ten zastępuje Parser z SAX 1.0; względem swojego poprzednika został wzbo­gacony o obsługę przestrzeni nazw w elementach i atrybutach dokumentu. Za jego pomocą od­by­wa się przetwarzanie (poprzez pobranie jako parametru wejściowego identyfikatora systemowego lub obiektu InputSource); interfejs ten umożliwia również zarejestrowanie różnych procedur obsługi dostępnych w ramach SAX 2.0. Poprzez ten interfejs zostają także odpowiednio ustawione funkcje i właściwości udostępniane implementacji parsera SAX. Pełny opis interfejsu można zna­leźć w rozdziale 3., a pełną listę podstawowych funkcji i właściwości SAX - w dodatku B.

public interface XMLReader

{

public boolean getFeature (String name)

throws SAXNotRecognizedException, SAXNotSupportedException;

public void setFeature (String name, boolean value)

throws SAXNotRecognizedException, SAXNotSupportedException;

public Object getProperty (String name)

throws SAXNotRecognizedException, SAXNotSupportedException;

public void setProperty (String name, Object value)

throws SAXNotRecognizedException, SAXNotSupportedException;

public void setEntityResolver (EntityResolver resolver);

public EntityResolver getEntityResolver ();

public void setDTDHandler (DTDHandler handler);

public DTDHandler getDTDHandler ();

public void setContentHandler (ContentHandler handler);

public ContentHandler getContentHandler ();

public void setErrorHandler (ErrorHandler handler);

public ErrorHandler getErrorHandler ();

public void parse (InputSource input)

throws IOException, SAXException;

public void parse (String systemId)

throws IOException, SAXException;

}

Pakiet org.xml.sax.ext

Ten pakiet zawiera rozszerzenia podstawowych klas i interfejsów SAX. Zdefiniowano tutaj w szcze­­gólności dodatkowe procedury obsługi odpowiadające mniej typowym zdarzeniom w procesie prze­twarzania SAX. Od implementacji XMLReader nie wymaga się obsługi tych dodatkowych pro­cedur obsługi.

DeclHandler

Interfejs ten definiuje wywołania zwracające specyficzne informacje o deklaracjach DTD. De­fi­ni­cje elementów i atrybutów powodują wywołanie odpowiednich metod z parametrami w postaci nazw napotkanych obiektów (w przypadku atrybutów podawany jest także parametr w postaci na­zwy elementu, do którego atrybut przynależy); przekazywana jest również informacja o zawę­że­niach. W przypadku atrybutów przekazywane informacje są bardzo zwięzłe; w przypadku elementów jest to tylko String zawierający zawężony model w postaci czystego tekstu. Ponadto w interfejsie tym zdefiniowano metody powiadamiające o wewnętrznych i zewnętrznych encjach.

public interface DeclHandler

{

public abstract void elementDecl (String name, String model)

throws SAXException;

public abstract void attributeDecl (String eName,

String aName,

String type,

String valueDefault,

String value)

throws SAXException;

public abstract void internalEntityDecl (String name, String value)

throws SAXException;

public abstract void externalEntityDecl (String name, String publicId,

String systemId)

throws SAXException;

}

LexicalHandler

W tym interfejsie zdefiniowano wywołania związane z różnymi zdarzeniami na poziomie do­ku­mentu, związanymi z przetwarzaniem, ale nie wpływającymi na dane wynikowe. Wywołania tego interfejsu uruchamiane będą na przykład w czasie obsługi deklaracji DTD, komentarzy i encji. Ponadto sygnalizowany jest początek i koniec sekcji CDATA (choć zgłaszane dane będą zawsze takie same).

public interface LexicalHandler

{

public abstract void startDTD (String name, String publicId,

String systemId)

throws SAXException;

public abstract void endDTD ()

throws SAXException;

public abstract void endEntity (String name)

throws SAXException;

public abstract void startCDATA ()

throws SAXException;

public abstract void endCDATA ()

throws SAXException;

public abstract void comment (char ch[], int start, int length)

throws SAXException;

}

Pakiet org.xml.sax.helpers

Ten pakiet zawiera rozszerzenia podstawowych klas i interfejsów SAX. Zdefiniowano tutaj w szcze­gólności dodatkowe procedury obsługi odpowiadające mniej typowym zdarzeniom w procesie prze­twarzania SAX. Od implementacji XMLReader nie wymaga się obsługi tych dodatkowych procedur obsługi.

AttributeListImpl

Jest to domyślna implementacja interfejsu org.xml.sax.AttributeList. Nie zaleca się jej stosowania w SAX 2.0. Umożliwia dodawanie i usuwanie atrybutów oraz czyszczenie listy atrybutów.

public class AttributeListImpl implements AttributeList

{

public AttributeListImpl ();

public AttributeListImpl (AttributeList atts);

// Implementacja interfejsu AttributeList

// Dodatkowe metody

public void setAttributeList (AttributeList atts);

public void addAttribute (String name, String type, String value);

public void removeAttribute (String name);

public void clear ();

}

AttributesImpl

Domyślna implementacja interfejsu org.xml.sax.Attributes. Umożliwia dodawanie i usu­wanie atrybutów oraz czyszczenie listy atrybutów.

public class AttributesImpl implements Attributes

{

public AttributesImpl ();

public AttributesImpl (Attributes atts);

// Implementacja interfejsu Attributes

// Dodatkowe metody

public void addAttribute (String uri, String localName, String qName,

String type, String value);

public void setAttribute (int index, String uri, String localName,

String qName, String type, String value);

public void clear ();

}

DefaultHandler

Ta klasa pomocnicza zawiera puste implementacje wszystkich podstawowych interfejsów pro­ce­dur obsługi SAX 2.0. Może zostać tak rozszerzona, aby umożliwić szybkie dodawanie procedur obsługi poprzez „nadpisywanie” metod kodem specyficznym dla danej aplikacji. Klasa ta za­stę­puje klasę org.xml.sax.HandlerBase z interfejsu SAX 1.0.

public class DefaultHandler

implements EntityResolver, DTDHandler, ContentHandler, ErrorHandler

{

// (Pusta) implementacja interfejsu EntityResolver

// (Pusta) implementacja interfejsu DTDHandler

// (Pusta) implementacja interfejsu ContentHandler

// (Pusta) implementacja interfejsu ErrorHandler

}

LocatorImpl

Domyślna implementacja interfejsu org.xml.sax.Locator. Umożliwia również bezpośre­dnie ustawienie numerów wiersza i kolumny.

public class LocatorImpl implements Locator

{

public LocatorImpl ();

public LocatorImpl (Locator locator);

// Implementacja interfejsu Locator

// Dodatkowe metody

public void setPublicId (String publicId);

public void setSystemId (String systemId);

public void setLineNumber (int lineNumber);

public void setColumnNumber (int columnNumber);

}

NamespaceSupport

Ta klasa stanowi „kapsułkę” obejmującą wszystkie czynności wykonywane na przestrzeniach nazw. Dzięki niej w aplikacjach nie trzeba samodzielnie obsługiwać przestrzeni nazw, chyba że jest to konieczne ze względu na wydajność. Konteksty przestrzeni nazw mogą być obsługiwane poprzez „stos”. Możliwe jest również uzyskiwanie odpowiedników nazw dokumentu XML 1.0, opatrzo­nych przedrostkami zawierającymi przestrzenie nazw.

public class NamespaceSupport

{

public NamespaceSupport ();

public void reset ();

public void pushContext ();

public void popContext ();

public boolean declarePrefix (String prefix, String uri);

public String [] processName (String qName, String parts[],

boolean isAttribute);

public String getURI (String prefix);

public Enumeration getPrefixes (String prefix);

public Enumeration getDeclaredPrefixes ();

}

ParserAdapter

Ta klasa pomocnicza stanowi „opakowanie” implementacji SAX 1.0 Parser i powoduje, że za­chowuje się ona jak implementacja 2.0 XMLReader (obsługuje przestrzenie nazw). Jedyna me­to­da, która nie będzie zachowywała się „zwyczajnie”, to skippedEntity() z interfejsu Content­Hand­ler(); nigdy nie zostanie ona nawet wywołana.

public class ParserAdapter implements XMLReader, DocumentHandler

{;

public ParserAdapter ()

throws SAXException;

public ParserAdapter (Parser parser);

// Implementacja interfejsu XMLReader

// Implementacja interfejsu DocumentHandler

}

ParserFactory

Zawiera metody dynamicznie tworzące egzemplarz implementacji Parser po podaniu określonej nazwy klasy lub — jeśli nazwy nie podano — z właściwości systemowej „org.xml.sax.driver”.

public class ParserFactory {

public static Parser makeParser ()

throws ClassNotFoundException,

IllegalAccessException,

InstantiationException,

NullPointerException,

ClassCastException;

public static Parser makeParser (String className)

throws ClassNotFoundException,

IllegalAccessException,

InstantiationException,

ClassCastException;

}

XMLFilterImpl

Domyślna implementacja interfejsu org.xml.sax.XMLFilter.

public class XMLFilterImpl

implements XMLFilter, EntityResolver, DTDHandler, ContentHandler, ErrorHandler

{

public XMLFilterImpl ();

public XMLFilterImpl (XMLReader parent);

// Implementacja interfejsu XMLFilter

// Implementacja interfejsu XMLReader

// Implementacja interfejsu EntityResolver

// Implementacja interfejsu DTDHandler

// Implementacja interfejsu ContentHandler

// Implementacja interfejsu ErrorHandler

}

XMLReaderAdapter

Ta klasa pomocnicza pełni rolę „opakowania” implementacji SAX 2.0 XMLReader, powodując, że zachowuje się ona jak implementacja 1.0 Parser (brak obsługi przestrzeni nazw). Funkcja przestrzeni nazw (http://xml.org/sax/features/namespace) musi być obsługiwana; w przeciwnym razie w czasie przetwarzania wystąpią błędy.

public class XMLReaderAdapter implements Parser, ContentHandler

{

public XMLReaderAdapter ()

throws SAXException;

public XMLReaderAdapter (XMLReader xmlReader);

// Implementacja interfejsu Parser

// Implementacja interfejsu ContentHandler

}

XMLReaderFactory

Zawiera metody dynamicznie tworzące egzemplarz implementacji XMLReader po podaniu okreś­lonej nazwy klasy lub — jeśli nazwy nie podano — z właściwości systemowej „org.xml.sax.driver”.

final public class XMLReaderFactory

{

public static XMLReader createXMLReader ()

throws SAXException;

public static XMLReader createXMLReader (String className)

throws SAXException;

}

DOM Level 2

Interfejs DOM opracowany przez konsorcjum W3C służy do budowania w pamięci pełnej re­pre­zen­tacji dokumentu XML. Użytkownikowi oferuje szczegółowe informacje o strukturze doku­men­tu po jego całkowitym przetworzeniu. Krążą plotki, że DOM Level 3 będzie definiował interfejs pozwalający na uzyskanie obiektu DOM Document; obecnie mechanizm taki nie istnieje w mo­delu DOM. Podobnie jak w interfejsie SAX, na większą część pakietu DOM składają się interfejsy definiujące struktury wewnątrz dokumentu XML oraz odwzorowujące je na język Java (te same od­wzorowania stosowane są w standardzie CORBA, w języku JavaScript i innych).

Pakiet org.w3c.dom

Pakiet ten zawiera podstawowe interfejsy i klasy DOM Level 2. Zazwyczaj w aplikacji wyko­rzys­ty­wane są implementacje tych interfejsów pochodzące od konkretnego producenta.

Attr

Interfejs ten reprezentuje atrybut (lub element) XML w języku Java. Umożliwia dostęp do nazwy i wartości atrybutu oraz pozwala na ustawienie jego wartości (na potrzeby mutacji). Metoda getSpecified() wskazuje, czy atrybut (oraz jego wartość) został jawnie użyty w dokumencie XML lub czy jego wartość nie została określona, a zamiast tego pobrano wartość domyślną z de­finicji DTD. Poprzez ten interfejs można także pobrać informacje o elemencie „nadrzędnym”.

public interface Attr extends Node {

public String getName();

public boolean getSpecified();

public String getValue();

public void setValue(String value)

throws DOMException;

public Element getOwnerElement();

}

CDATASection

W tym interfejsie nie zdefiniowano żadnych metod; dziedziczy on wszystkie metody interfejsu Text. Jednak dzięki jego obecności (a więc również dzięki istnieniu oddzielnego typu węzła) można do­konać rozróżnienia pomiędzy tekstem w sekcjach XML CDATA a zwykłym tekstem w ele­mencie (nie znajdującym się w takiej sekcji).

public interface CDATASection extends Text {

}

CharacterData

Jest to interfejs „nadrzędny” względem wszystkich typów Node modelu DOM (Text, Comment i — pośrednio — CDATASection). Zdefiniowano w nim metody pozwalające na uzyskanie do­stępu do węzła tekstowego i ustawienie jego wartości. Są tu również metody umożliwiające ope­ro­wanie na danych tekstowych bezpośrednio (jako na znakach) — pozwalają uzyskać długość łań­cu­cha, dopisać, wstawić i usunąć dane albo zamienić wszystkie lub część znaków na inne. Wszystkie te metody zgłaszają wyjątek DOMException, jeśli węzeł jest tylko do odczytu.

public interface CharacterData extends Node {

public String getData()

throws DOMException;

public void setData(String data)

throws DOMException;

public int getLength();

public String substringData(int offset,

int count)

throws DOMException;

public void appendData(String arg)

throws DOMException;

public void insertData(int offset,

String arg)

throws DOMException;

public void deleteData(int offset,

int count)

throws DOMException;

public void replaceData(int offset,

int count,

String arg)

throws DOMException;

}

Comment

Interfejs ten umożliwia uzyskanie w języku Java reprezentacji komentarza XML. Podobnie jak CDATASection, sam nie zawiera żadnych metod, ale pozwala na rozróżnienie (na podstawie typu interfejsu) pomiędzy tekstem a komentarzami w dokumencie XML.

public interface Comment extends CharacterData {

}

Document

Interfejs ten reprezentuje w modelu DOM kompletny dokument XML. Umożliwia również two­rze­nie nowych elementów, atrybutów, instrukcji przetwarzania oraz elementów XML. Pozwala nie tylko uzyskać informacje o deklaracji DTD (getDocType()) oraz elemencie głównym (get­Do­cumentElement()), ale także przeszukiwać drzewo dokumentu pod kątem wystąpienia konkretnego elementu (getElementByTagName()). Ponieważ model DOM wymaga dowią­za­nia wszystkich implementacji Node do obiektu Document, interfejs ten pozwala tworzyć różne typy węzłów Node DOM. Każda metoda z serii createXXX() posiada swój odpowiednik obsługujący przestrzenie nazw (createXXXNS()). Ponadto możliwe jest importowanie węzłów do obiektu Document za pomocą metody importNode(); wartość boolean wskazuje, czy ele­menty potomne zaimportowanego węzła Node powinny również zostać rekurencyjnie zaim­portowane.

public interface Document extends Node {

public DocumentType getDoctype();

public DOMImplementation getImplementation();

public Element getDocumentElement();

public Element createElement(String tagName)

throws DOMException;

public DocumentFragment createDocumentFragment();

public Text createTextNode(String data);

public Comment createComment(String data);

public CDATASection createCDATASection(String data)

throws DOMException;

public ProcessingInstruction createProcessingInstruction(String target,

String data)

throws DOMException;

public Attr createAttribute(String name)

throws DOMException;

public EntityReference createEntityReference(String name)

throws DOMException;

public NodeList getElementsByTagName(String tagname);

public Node importNode(Node importedNode,

boolean deep)

throws DOMException;

public Element createElementNS(String namespaceURI,

String qualifiedName)

throws DOMException;

public Attr createAttributeNS(String namespaceURI,

String qualifiedName)

throws DOMException;

public NodeList getElementsByTagNameNS(String namespaceURI,

String localName);

public Element getElementById(String elementId);

}

DocumentFragment

Ten interfejs jednorazowo umożliwia operowanie tylko na fragmencie obiektu Document. Służy do manipulacji częściami drzewa DOM bez konieczności przechowywania całego dokumentu w pamięci.

public interface DocumentFragment extends Node {

}

DocumentType

Ten interfejs reprezentuje deklarację DOCTYPE w dokumencie XML. W tym przypadku nazwą (Name) jest nazwa elementu występującego zaraz po łańcuchu <!DOCTYPE; dostępne są również identyfikatory — systemowy i publiczny — definicji DTD, do których następuje odwołanie. Po­nadto, jeśli obecne są encje lub inne zapisy typu „inline”, stają się one dostępne poprzez od­po­wiednie metody getXXX().

public interface DocumentType extends Node {

public String getName();

public NamedNodeMap getEntities();

public NamedNodeMap getNotations();

public String getPublicId();

public String getSystemId();

public String getInternalSubset();

}

DOMException

Poprzez tę klasę interfejsy DOM zgłaszają wyjątek Exception w przypadku wystąpienia błę­dów. W klasie tej opisano również zestaw kodów błędów odpowiadających różnym problemom, jakie mogą wystąpić w czasie korzystania z modelu DOM i spowodować zgłoszenie wyjątku Exception.

public class DOMException extends RuntimeException {

public DOMException(short code, String message);

// Kody wyjątków

public static final short INDEX_SIZE_ERR;

public static final short DOMSTRING_SIZE_ERR;

public static final short HIERARCHY_REQUEST_ERR;

public static final short WRONG_DOCUMENT_ERR;

public static final short INVALID_CHARACTER_ERR;

public static final short NO_DATA_ALLOWED_ERR;

public static final short NO_MODIFICATION_ALLOWED_ERR;

public static final short NOT_FOUND_ERR;

public static final short NOT_SUPPORTED_ERR;

public static final short INUSE_ATTRIBUTE_ERR;

public static final short INVALID_STATE_ERR;

public static final short SYNTAX_ERR;

public static final short INVALID_MODIFICATION_ERR;

public static final short NAMESPACE_ERR;

public static final short INVALID_ACCESS_ERR;

}

DOMImplementation

Interfejs ten stanowi standardowy „punkt wyjścia”, poprzez który zostaje udostępniona implemen­tacja DOM określonego producenta. Umożliwia utworzenie w tej implementacji obiektów Do­cumentType oraz Document. Pozwala także na odpytanie implementacji (za pomocą metody hasFeature()) odnośnie obsługi określonej funkcji.

public interface DOMImplementation {

public boolean hasFeature(String feature,

String version);

public DocumentType createDocumentType(String qualifiedName,

String publicId,

String systemId)

throws DOMException;

public Document createDocument(String namespaceURI,

String qualifiedName,

DocumentType doctype)

throws DOMException;

}

Element

Interfejs ten reprezentuje w języku Java element XML. Udostępnia metody pozwalające na uzys­kanie nazwy i atrybutów elementu, a także na ustawienie tych wartości. Oferuje także różne spo­so­by uzyskania dostępu do atrybutów XML, włącznie z metodami getXXX() i setXXX() w wer­sjach z obsługą przestrzeni nazw.

public interface Element extends Node {

public String getTagName();

public String getAttribute(String name);

public void setAttribute(String name,

String value)

throws DOMException;

public void removeAttribute(String name)

throws DOMException;

public Attr getAttributeNode(String name);

public Attr setAttributeNode(Attr newAttr)

throws DOMException;

public Attr removeAttributeNode(Attr oldAttr)

throws DOMException;

public NodeList getElementsByTagName(String name);

public String getAttributeNS(String namespaceURI,

String localName);

public void setAttributeNS(String namespaceURI,

String qualifiedName,

String value)

throws DOMException;

public void removeAttributeNS(String namespaceURI,

String localName)

throws DOMException;

public Attr getAttributeNodeNS(String namespaceURI,

String localName);

public Attr setAttributeNodeNS(Attr newAttr)

throws DOMException;

public NodeList getElementsByTagNameNS(String namespaceURI,

String localName);

public boolean hasAttribute(String name);

public boolean hasAttributeNS(String namespaceURI,

String localName);

}

Entity

Interfejs reprezentujący w języku Java encję (przetworzoną lub nie). Odpowiednie akcesory umoż­liwiają uzyskanie dostępu do identyfikatorów — systemowego i publicznego, oraz do zapisu encji (pobranej z DTD).

public interface Entity extends Node {

public String getPublicId();

public String getSystemId();

public String getNotationName();

}

EntityReference

Interfejs reprezentujący wartość powstałą w wyniku „przetłumaczenia” encji. Zakłada się, że przed wykorzystaniem interfejsu przez aplikację encje (znakowa lub definiowana przez użytkownika) już wystąpiły w dokumencie.

public interface EntityReference extends Node {

}

NamedNodeMap

W tym interfejsie zdefiniowano listę podobną do NodeList, ale wymagającą, aby każdy na­le­żący do niej węzeł Node był nazwany (czyli był np. obiektem Element lub Attr). Dzięki temu wymogowi możliwe było udostępnienie metod do pobierania pozycji z listy właśnie poprzez naz­wę (z lub bez przestrzeni nazw). Poprzez listę można także usuwać lub modyfikować poszcze­gólne obiekty. Wszystkie te metody zgłaszają DOMException, jeśli określony węzeł jest tylko do odczytu.

public interface NamedNodeMap {

public Node getNamedItem(String name);

public Node setNamedItem(Node arg)

throws DOMException;

public Node removeNamedItem(String name)

throws DOMException;

public Node item(int index);

public int getLength();

public Node getNamedItemNS(String namespaceURI,

String localName);

public Node setNamedItemNS(Node arg)

throws DOMException;

public Node removeNamedItemNS(String namespaceURI,

String localName)

throws DOMException;

}

Node

Centralny interfejs wszystkich obiektów DOM. Oferuje szeroki zestaw metod udostępniających in­formacje o węźle Node drzewa modelu DOM. Umożliwia także obsługę elementów potomnych tego węzła (o ile takie istnieją). Działania większości metod nie trzeba właściwie wyjaśniać, nato­miast na cechy niektórych z nich warto zwrócić uwagę: getAttributes() zwraca dane inne niż null tylko wtedy, gdy węzeł Node to Element; cloneNode() pozwala na „płytkie” lub „głębokie” kopiowanie węzła Node; normalize() przenosi cały tekst do nieprzystających wę­złów Text (żadne dwa węzły Text nie mogą być przystające; wszystkie „przetłumaczone” encje tekstowe są konsolidowane do postaci węzłów Text); zaś supports() oferuje informacje o fun­kcjach udostępnianych przez Node. Są tu również metody obsługujące przestrzenie nazw (get­Na­mespaceURI(), getPrefix() oraz getLocalName()).Ponadto, zdefiniowano tutaj sta­łe określające typ węzła (porównuje się je z wartością zwróconą przez getNodeType()).

public interface Node {

public String getNodeName();

public String getNodeValue()

throws DOMException;

public void setNodeValue(String nodeValue)

throws DOMException;

public short getNodeType();

public Node getParentNode();

public NodeList getChildNodes();

public Node getFirstChild();

public Node getLastChild();

public Node getPreviousSibling();

public Node getNextSibling();

public NamedNodeMap getAttributes();

public Document getOwnerDocument();

public Node insertBefore(Node newChild,

Node refChild)

throws DOMException;

public Node replaceChild(Node newChild,

Node oldChild)

throws DOMException;

public Node removeChild(Node oldChild)

throws DOMException;

public Node appendChild(Node newChild)

throws DOMException;

public boolean hasChildNodes();

public Node cloneNode(boolean deep);

public void normalize();

public boolean supports(String feature,

String version);

public String getNamespaceURI();

public String getPrefix();

public void setPrefix(String prefix)

throws DOMException;

public String getLocalName();

public boolean hasAttributes();

// Stałe określające typ węzła

public static final short ELEMENT_NODE;

public static final short ATTRIBUTE_NODE;

public static final short TEXT_NODE;

public static final short CDATA_SECTION_NODE;

public static final short ENTITY_REFERENCE_NODE;

public static final short ENTITY_NODE;

public static final short PROCESSING_INSTRUCTION_NODE;

public static final short COMMENT_NODE;

public static final short DOCUMENT_NODE;

public static final short DOCUMENT_TYPE_NODE;

public static final short DOCUMENT_FRAGMENT_NODE;

public static final short NOTATION_NODE;

}

NodeList

Interfejs ten jest strukturą DOM analogiczną do struktur Vector lub List w języku Java. Jest to typ wartości zwracanej przez każdą metodę, która udostępnia jednocześnie wiele implementacji Node. Możliwa jest iteracja po pozycjach listy oraz pobieranie węzła Node według indeksu.

public interface NodeList {

public Node item(int index);

public int getLength();

}

Notation

Interfejs ten reprezentuje konstrukcję NOTATION występującą w definicji DTD i służącą do de­klarowania nieprzetworzonej encji lub instrukcji przetwarzania (PI). Udostępnia identyfikatory publiczny i systemowy, znajdujące się w deklaracji. W obu przypadkach, jeśli identyfikatory nie są obecne, zwracana jest wartość null.

public interface Notation extends Node {

public String getPublicId();

public String getSystemId();

}

ProcessingInstruction

Interfejs ten reprezentuje instrukcję przetwarzania (PI). Oferuje metody służące do pobrania obie­ktu docelowego (ang. target) oraz danych instrukcji. Nie ma możliwości uzyskania dostępu do in­dywidualnych par nazwa-wartość w instrukcji. Istnieje możliwość ustawiania danych w PI:

public interface ProcessingInstruction extends Node {

public String getTarget();

public String getData();

public void setData(String data)

throws DOMException;

}

Text

Ten interfejs stanowi reprezentację danych tekstowych elementu XML w języku Java. Do metod zdefiniowanych w klasie CharacterData dodaje tylko jedną, rozdzielającą dany węzeł na dwa oddzielne. Pierwotny węzeł Text będzie zawierał tylko tekst do pewnego (określonego przez pro­gramistę) miejsca; pozostały tekst zostanie zwrócony jako wynik działania metody w postaci no­wego węzła Text. Podobnie jak w innych metodach dokonujących mutacji, jeśli węzeł jest tylko do odczytu, zostanie zgłoszony wyjątek DOMException.

public interface Text extends CharacterData {

public Text splitText(int offset)

throws DOMException;

}

JAXP 1.0

JAXP stanowi abstrakcyjną warstwę, poprzez którą pobierana jest implementacja parsera SAX lub DOM określonego producenta. Obecnie JAXP obsługuje tylko implementacje parserów SAX 1.0 oraz DOM Level 1.

Pakiet javax.xml.parsers

Jest to jedyny pakiet JAXP. Zawiera klasy konieczne do stworzenia abstrakcyjnej warstwy JAXP.

DocumentBuilder

Klasa ta stanowi „opakowanie” wykorzystywanej klasy implementacji parsera. Pozwala na prze­twa­rzanie dokumentu XML w sposób niezależny od producenta klasy.

public abstract class DocumentBuilder {

public Document parse(InputStream stream)

throws SAXException, IOException, IllegalArgumentException;

public Document parse(String uri)

throws SAXException, IOException, IllegalArgumentException;

public Document parse(File file)

throws SAXException, IOException, IllegalArgumentException;

public abstract Document parse(InputSource is)

throws SAXException, IOException, IllegalArgumentException;

public abstract boolean isNamespaceAware();

public abstract boolean isValidating();

public abstract void setEntityResolver(EntityResolver er);

public abstract void setErrorHandler(ErrorHandler eh);

public abstract Document newDocument();

}

DocumentBuilderFactory

Ta klasa służy do tworzenia egzemplarzy klasy DocumentBuilder. Przy jej tworzeniu możliwe jest włączenie lub wyłączenie obsługi przestrzeni nazw oraz sprawdzania poprawności.

public abstract class DocumentBuilderFactory {

protected DocumentBuilderFactory ();

public static DocumentBuilderFactory newInstance();

public abstract DocumentBuilder newDocumentBuilder()

throws ParserConfigurationException;

public void setNamespaceAware(boolean aware);

public void setValidating(boolean validating);

public boolean isNamespaceAware();

public boolean isValidating();

}

FactoryConfigurationException

W tej klasie zdefiniowano wyjątek Error zgłaszany w przypadku, gdy nie jest możliwe utwo­rzenie egzemplarza klasy.

public class FactoryConfigurationError extends Error {

public FactoryConfigurationError();

public FactoryConfigurationError(String msg);

public FactoryConfigurationError(Exception e);

public FactoryConfigurationError(Exception e, String msg);

public String getMessage ();

public Exception getException ();

}

ParserConfigurationException

W tej klasie zdefiniowano wyjątek Exception zgłaszany w przypadku, gdy wysyłane jest zgło­szenie pobrania egzemplarza parsera, ale nie jest możliwe jego utworzenie przy podanych przez programistę ustawieniach odnośnie obsługi przestrzeni nazw oraz sprawdzania poprawności.

public class ParserConfigurationException extends Exception {

public ParserConfigurationException();

public ParserConfigurationException(String msg);

}

SAXParser

Ta klasa stanowi „opakowanie” (interfejs) wykorzystywanej klasy implementacji parsera SAX 1.0 i umożliwia przeprowadzenie procesu przetwarzania w sposób niezależny od producenta.

public abstract class SAXParser {

public void parse(InputStream stream, HandlerBase base)

throws SAXException, IOException, IllegalArgumentException;

public void parse(String uri, HandlerBase base)

throws SAXException, IOException, IllegalArgumentException;

public void parse(File file, HandlerBase base)

throws SAXException, IOException, IllegalArgumentException;

public void parse(InputSource source, HandlerBase base)

throws SAXException, IOException, IllegalArgumentException;

public abstract org.xml.sax.Parser getParser() throws SAXException;

public abstract boolean isNamespaceAware();

public abstract boolean isValidating();

}

SAXParserFactory

Ta klasa służy do tworzenia egzemplarzy klasy SAXParser. Przy jej tworzeniu możliwe jest włączenie lub wyłączenie obsługi przestrzeni nazw oraz sprawdzania poprawności.

public abstract class SAXParserFactory {

public static SAXParserFactory newInstance();

public abstract SAXParser newSAXParser()

throws ParserConfigurationException, SAXException;

public void setNamespaceAware(boolean awareness);

public void setValidating(boolean validating);

public boolean isNamespaceAware();

public boolean isValidating();

}

JDOM 1.0

JDOM 1.0, opisany w rozdziale 8., oferuje pełny wgląd w strukturę drzewiastą dokumentu XML. Model dokumentu jest podobny do tego w standardzie DOM, ale zasady, według których jest budowany, nie są aż tak ścisłe. Np. możliwe jest, bezpośrednie wpisanie zawartości obiektu Ele­ment (a nie poprzez wartość elementu potomnego). JDOM zawiera ponadto konkretne klasy, a nie interfejsy, dzięki czemu możliwe jest bezpośrednie tworzenie obiektów (nie poprzez klasę producenta). SAX i DOM są wykorzystywane w interfejsie JDOM jedynie do utworzenia obiektu JDOM Document na podstawie istniejących danych XML. Zostały zdefiniowane w pakiecie org.jdom.input.

Pakiet org.jdom

Pakiet ten zawiera podstawowe klasy JDOM 1.0. Składają się na nie obiekty XML odwzorowane na język Java oraz zestaw wyjątków zgłaszanych w razie wystąpienia błędów.

Attribute

W klasie Attribute zdefiniowano zachowanie atrybutu XML, odwzorowując je na język Java. Udostępniono tutaj metody pozwalające na uzyskanie wartości atrybutu oraz związanych z nim informacji o przestrzeni nazw. Możliwe jest utworzenie egzemplarza klasy poprzez podanie nazwy atrybutu i jego wartości lub poprzez obiekt Namespace, nazwę lokalną atrybutu i jego wartość. Udo­stępniono także metody pomocnicze, służące do automatycznej konwersji typu danych stano­wiących wartość atrybutu.

public class Attribute {

public Attribute(String name, String value);

public Attribute(String name, String prefix, String uri, String value);

public Attribute(String name, Namespace ns, String value);

public String getName();

public String getQualifiedName();

public String getNamespacePrefix();

public Namespace getNamespaceURI();

public String getValue();

public void setValue(String value);

// Metody pomocnicze do przeprowadzania konwersji

public String get StringValue(String default Value);

public int getIntValue(int defaultValue);

public int getIntValue() throws DataConversionException;

public log getLongValue (long defaultValue);

public long getLongValue() throws DataConversionException;

public float getFloatValue(float defaultValue);

public float getFloatValue() throws DataConversionException;

public double getDoubleValue(double defaultValue);

public double getDoubleValue() throws DataConversionException;

public boolean getBooleanValue(boolean defaultValue);

public boolean getBooleanValue() throws DataConversionException;

public char getCharValue(char defaultValue);

public char getCharValue() throws DataConversionException;

public byte getByteValue(byte defaultValue);

public byte getByteValue() throws DataConversionException;

}

Comment

Comment to prosta reprezentacja komentarza XML. Zawiera tekst znajdujący się wewnątrz ko­mentarza XML.

public class Comment {

public Comment(String text);

public String getText();

public void setText(String text);

public String toString();

}

DataConversionException

Ten wyjątek zgłaszany jest w przypadku konwersji wartości elementu Attribute lub Element na określony typ. W zgłaszanym komunikacie zawarta jest nazwa przetwarzanego atrybutu oraz typ danych, na który następuje konwersja. Wyjątek ten stanowi podklasę JDOMException, a więc aplikacja wykorzystująca interfejs DOM może przechwycić ten jeden wyjątek i otrzymać wszy­stkie informacje o błędach.

public class DataConversionException extends JDOMException {

public DataConversionException(String name, String dataType);

}

DocType

DocType reprezentuje deklarację DOCTYPE znajdującą się w dokumencie XML. Udostępnia nazwę zawężanego elementu oraz identyfikatory — publiczny i systemowy — zewnętrznej defi­ni­cji DTD (jeśli taka istnieje).

public class DocType {

public DocType(String elementName, String publicID, String systemID);

public DocType(String elementName, String systemID);

public DocType(String elementName);

public String getElementName();

public String getPublicID();

public DocType setPublicID(String publicID);

public String getSystemID();

public DocType setSystemID(String systemID);

}

Document

Document stanowi odwzorowanie dokumentu XML w języku Java. Jest tworzony tylko poprzez główny element Element, ale zamiast klasy Element można tutaj wykorzystać metodę set­Root­Element(). Pozwala również na ustawienie (lub pobranie) wartości DocType oraz listy List instrukcji ProcessingInstruction. Są tutaj także metody pomocnicze, umoż­li­wia­ją­ce dodanie instrukcji przetwarzania do obiektu Document. Metoda getContent() zwraca całą zawartość obiektu Document, wraz z elementem głównym oraz komentarzami.

public class Document {

public Document(Element rootElement, DocType docType);

public Document(Element rootElement);

public Element getRootElement() throws NoSuchElementException;

public Document setRootElement(Element rootElement);

public DocType getDocType();

public Document setDocType(DocType docType);

public List getProcessingInstructions();

public List getProcessingInstructions(String target);

public ProcessingInstruction getProcessingInstruction(String target)

throws NoSuchProcessingInstructionException;

public Document addProcessingInstruction(ProcessingInstruction pi);

public Document addProcessingInstruction(String target, String data);

public Document addProcessingInstruction(String target, Map data);

public Document setProcessingInstructions(List processingInstructions);

public boolean removeProcessingInstruction(

ProcessingInstruction processingInstruction);

public boolean removeProcessingInstruction(String target);

public boolean removeProcessingInstructions(String target);

public Document addComment(Comment comment);

public List getMixedContent();

}

Element

Element stanowi reprezentację elementu XML w języku Java. W pełni obsługuje przestrzenie nazw, a więc wszystkie metody mogą jako argument przyjmować jedną nazwę elementu oraz op­cjonalną informację o przestrzeni nazw. Wynikiem wywołania getContent() jest zawsze String, pusty albo zawierający tekst elementu. Zawartość elementu uważa się za mieszaną (ang. mixed), gdy składają się na nią dane tekstowe i elementy zagnieżdżone, a także opcjonalne ko­men­tarze, encje i instrukcje przetwarzania. Taką kompletną listę List zawartości elementu można uzyskać poprzez wywołanie metody getMixedContent(). Zawartość tak uzyskanej listy prze­twa­rza się instrukcją instanceof wykonywaną na obiektach String, Element lub Comment.

Metody addXXX() zostały tak stworzone, aby programista łączył je ze sobą, a więc wszystkie zwracają zmodyfikowany Element:

Element element = new Element(„rodzic”);

element.addChild(new Element(„syn”)

.addChild(new Element(„wnuk”)

.addAttribute(„nazwa”, „wartosc”)

.setContent(„Witaj świecie!”))

.addChild(new Element(„drugiSyn”))

);

Taki kod spowodowałby utworzenie następującego fragmentu dokumentu XML:

<rodzic>

<syn>

<wnuk nazwa=„wartosc”>

Witaj świecie!

</wnuk>

</syn>

<drugiSyn />

</rodzic>

Istnieją także metody pomocnicze pozwalające na dodawanie w trybie „inline” atrybutów do ele­mentów (setAttribute(String name, String value)). Podobnie działają metody usu­wające obiekty; są również dostępne odpowiedniki tych metod obsługujące przestrzenie nazw.

public class Element {

public Element(String name, Namespace namespace);

public Element(String name);

public Element(String name, String uri);

public Element(String name, String prefix, String uri);

public String getName();

public String getNamespacePrefix();

public String getNamespaceURI();

public String getQualifiedName();

public String getContent();

public Element setContent(String textContent);

public boolean hasMixedContent();

public List getMixedContent();

public Element setMixedContent(List mixedContent);

public List getChildren();

public Element setChildren(List children);

public List getChildren(String name);

public List getChildren(String name, Namespace ns);

public Element getChild(String name, Namespace ns)

throws NoSuchElementException;

public Element addChild(Element element);

public Element addChild(ProcessingInstruction pi);

public Element addChild(Comment comment);

public Element addChild(String s);

public boolean removeChild(Element element);

public boolean removeChild(Comment comment);

public boolean removeChild(String name);

public boolean removeChild(String name, Namespace ns);

public boolean removeChildren(String name);

public boolean removeChildren(String name, Namespace ns);

public boolean removeChildren();

public List getAttributes();

public Attribute getAttribute(String name)

throws NoSuchAttributeException;

public Attribute getAttribute(String name, Namespace ns)

throws NoSuchAttributeException;

public Element addAttribute(List attributes);

public Element addAttribute(Attribute attribute);

public Element addAttribute(String name, String value);

public boolean removeAttribute(String name, Namespace ns, String value);

public boolean removeAttribute(String name);

public boolean removeAttribute(String name, Namespace ns);

}

JDOMException

Jest to podstawowy wyjątek JDOM, stanowiący podklasę wszystkich innych wyjątków. Dostarcza komunikatów o błędach oraz stanowi interfejs do wyjątków niższego poziomu, jeśli zachodzi po­trzeba ich obsłużenia.

public class JDOMException extends Exception {

public JDOMException();

public JDOMException(String message);

public JDOMException(String message, Throwable rootCause);

public Throwable getRootCause();

}

Namespace

Klasa Namespace obsługuje odwzorowania przestrzeni nazw w obiektach JDOM Document.

public class Namespace {

public static Namespace getNamespaceURI(String uri);

public static Namespace getNamespaceURI(String prefix, String uri);

public String getProcessingInstruction();

public String getURI();

public boolean isDefault();

}

NoSuchAttributeException

Wyjątek zgłaszany w przypadku, gdy określony atrybut nie został znaleziony. Zwracany komu­ni­kat zawiera nazwę atrybutu, którego poszukiwano.

public class NoSuchAttributeException extends JDOMException {

public NoSuchAttributeException(String elementName);

}

NoSuchElementException

Wyjątek zgłaszany w przypadku, gdy określony element nie został znaleziony. Zwracany komu­ni­kat zawiera nazwę elementu, którego poszukiwano.

public class NoSuchElementException extends JDOMException {

public NoSuchElementException(String elementName);

}

NoSuchProcessingInstructionException

Wyjątek zgłaszany w przypadku, gdy określona instrukcja przetwarzania nie została znaleziona. Zwra­cany komunikat zawiera nazwę obiektu docelowego instrukcji, której poszukiwano.

public class NoSuchProcessingInstructionException extends JDOMException {

public class NoSuchProcessingInstructionException(String target);

}

ProcessingInstruction

W klasie ProcessingInstruction zdefiniowano zachowanie instrukcji przetwarzania XML, odwzorowane na język Java. Klasa ta umożliwia obsługę zarówno obiektu docelowego jako ca­łości, jak i „surowych” danych związanych z tym obiektem. Ponadto, ponieważ wiele instrukcji PI zawiera dane w postaci par nazwa-wartość (podobnie jak atrybuty), możliwe jest dodawanie i po­bieranie takich par. Na przykład, w przypadku instrukcji przetwarzania <?cocoon-process type=„xslt”?> wywołanie getValue(„type”) na obiekcie ProcessingInstruc­tion reprezentującym tę instrukcję XML spowodowałoby zwrócenie xslt.

public class ProcessingInstruction {

public ProcessingInstruction(String target, Map data);

public ProcessingInstruction(String target, String data);

public String getTarget();

public String getData();

public ProcessingInstruction setData(String data);

public ProcessingInstruction setData(Map data);

public String getValue(String name);

public ProcessingInstruction setValue(String name, String value);

public boolean removeValue(String name);

}

Pakiet org.jdom.adapters

Pakiet ten zawiera „adaptery” tworzące standardowy interfejs pozwalający na uzyskanie obiektu DOM Document z dowolnego parsera DOM (w tym z parserów DOM Level 1). Możliwe jest proste dodanie adaptera dla dowolnego parsera, w którym zachodzi potrzeba uzyskania obsługi interfejsu JDOM.

AbstractDOMAdapter

Klasa opisująca domyślne zachowanie określonej wersji metody getDocument(); domyślnie me­toda ta pobiera zawartość pliku poprzez „zapuszkowanie” go w obiekcie FileOutput­Stream i oddelegowanie do getDocument(InputStream).

public abstract class AbstractDOMAdapter implements DOMAdapter {

public Document getDocument(String filename, boolean validate)

throws IOException;

public abstract Document getDocument(InputStream in, boolean validate)

throws IOException;

public abstract Document createDocument() throws IOException;

}

DOMAdapter

W tej klasie zdefiniowano interfejs, który musi zostać zaimplementowany przez klasy pełniące rolę „adapterów”. Określono tutaj sposób utworzenia obiektu DOM Document po podaniu naz­wy pliku lub obiektu InputStream, a także sposób uzyskania nowego, pustego obiektu Document.

public interface DOMAdapter {

public Document getDocument(String filename, boolean validate)

throws IOException;

public Document getDocument(InputStream in, boolean validate)

throws IOException;

public Document createDocument() throws IOException;

}

Nie opisano tutaj specyficznych klas „adapterów”, ponieważ mogą one ulec zmianie w czasie przy­gotowywania tej książki do publikacji. W czasie pisania książki dostępne były następujące dzia­łające „adaptery” dla następujących parserów:

• Oracle Version 1 XML Parser

• Oracle Version 2 XML Parser

• Sun Project X Parser
  (teraz także dla powstałego na jego bazie parsera Crimson — przyp. tłum.)

• Apache Xerces Parser

• IBM XML4J Parser

Pakiet org.jdom.input

W tym pakiecie zdefiniowano interfejs służący do budowania obiektu JDOM Document. Moż­liwe jest dodawanie nowych implementacji Builder dla innych interfejsów XML API lub dla nowych implementacji parserów (np. takich, w których odczyt całego dokumentu będzie odbywał się dopiero wtedy, gdy zażąda tego użytkownik).

AbstractBuilder

Ta podstawowa implementacja klasy Builder służy do obsługi metod build(), które po­bie­rają obiekt File lub URL i konwertują je na strumienie przekazywane do innej metody build(), wymagającej jako parametru obiektu InputStream.

public abstract class AbstractBuilder implements Builder {

public abstract Document build(InputStream in) throws JDOMException;

public Document build(File file) throws JDOMException;

public Document build(URL url) throws JDOMException;

}

Builder

Jest to podstawowy interfejs, w którym zdefiniowano zachowanie wszystkich metod tworzących obiekt Document. Każda implementacja Builder musi udostępniać mechanizm pozwalający na utworzenie obiektu JDOM Document z obiektów InputStream, File lub URL. Wszystkie te implementacje zgłaszają wyjątki JDOMException, w których zawarte są informacje o błę­dach związanych z formatowaniem lub poprawnością (odpowiednio do sytuacji) i występujących w czasie budowania obiektu Document.

public interface Builder {

public Document build(InputStream in) throws JDOMException;

public Document build(File file) throws JDOMException;

public Document build(URL url) throws JDOMException;

}

DOMBuilder

Ta klasa umożliwia utworzenie obiektu JDOM Document z wejściowych danych XML, za po­mo­cą parsera obsługującego DOM (obiektowy model dokumentu). Wykorzystuje w tym celu róż­ne „adaptery” z pakietu org.jdom.adapters, a więc jeśli chcemy użyć parsera, dla którego nie istnieje odpowiedni „adapter”, wystąpią błędy. W klasie tej jest także metoda pozwalająca na zbudowanie obiektu JDOM Document na podstawie istniejącego drzewa DOM (org.w3c.­dom.­Do­cument). Klasa DOMBuilder umożliwia włączenie sprawdzania poprawności, można także jawnie określić klasę adaptera do wykorzystania. Jeśli użytkownik nie poda żadnego z tych parametrów, sprawdzanie poprawności nie odbywa się i zostanie wykorzystany parser Apache Xerces.

public class DOMBuilder extends AbstractBuilder {

public DOMBuilder(String adapterClass, boolean validate);

public DOMBuilder(String adapterClass);

public DOMBuilder(boolean validate);

public DOMBuilder();

public Document build(InputStream in) throws JDOMException;

public Document build(org.w3c.dom.Document domDocument);

}

SAXBuilder

Klasa umożliwiająca utworzenie obiektu JDOM Document z wejściowych danych XML za po­mocą parsera obsługującego SAX (Simple API for XML). Możliwe jest wykorzystanie dowolnej implementacji parsera zgodnej z SAX 2. W czasie korzystania z SAXBuilder można zażądać włączenia sprawdzania poprawności oraz określić nazwę klasy sterownika SAX, jaki ma zostać użyty. Jeśli żaden z tych parametrów nie zostanie podany, wykorzystuje się ustawienia domyślne — brak sprawdzania poprawności i parser Apache Xerces.

public class SAXBuilder extends AbstractBuilder {

public SAXBuilder(String saxDriverClass, boolean validate);

public SAXBuilder(String saxDriverClass);

public SAXBuilder(boolean validate);

public SAXBuilder();

public Document build(InputStream in) throws JDOMException;

}

Pakiet org.jdom.output

W tym pakiecie określono, jak mają być zwracane obiekty JDOM Document. Obecnie jedyną klasą jest tutaj XMLOutputter, za pomocą którego można uzyskać wyjściowy obiekt JDOM Document w postaci strumienia. Możliwe jest jednak dodawanie dalszych klas. Oczekuje się, że w finalnej wersji JDOM 1.0 pojawi się kilka dodatkowych klas. Szczególną uwagę warto zwrócić na klasę SAXOutputter, która umożliwia uruchamianie zdarzeń SAX poprzez JDOM Do­cu­ment w aplikacji, która obsługuje SAX.

XMLOutputter

Ta klasa obsługuje wyjściowy obiekt Document, wysyłany w formacie XML do strumienia Out­putStream. Dostępne są konstruktory umożliwiajace ustawienie głębokości wcięć oraz określenie, czy do danych wynikowych mają być dopisywane znaki nowego wiersza. Domyślnie dane wynikowe są „elegancko sformatowane” (ang. pretty-printing) — czyli dwie spacje dla każ­dego poziomu wcięć oraz obecne znaki nowego wiersza. Po stworzeniu egzemplarza klasy metoda output() spowoduje wysłanie podanego obiektu Document do określonego strumienia Out­putStream.

public class XMLOutputter {

public XMLOutputter();

public XMLOutputter(String indent);

public XMLOutputter(String indent, boolean newlines);

public void output(Document doc, OutputStream out)

throws IOException;

}

W tej oraz innych metodach z rodziny DOM setXXX() w wyniku próby modyfikacji węzła tylko do odczytu zostaje zgłoszony wyjątek DOMException.

Niestety, aby uzyskać egzemplarz DOMImplementation, trzeba posiadać obiekt Document i wykonać metodę get­DOMImplementation(), ewentualnie bezpośrednio załadować klasy danego producenta. Powstaje więc często problem „jajka i kury”; alternatywny sposób wykonania tego zadania znaleźć można w opisach interfejsu JDOM (w rozdziale 8. oraz w dalszej części tego dodatku).

Należy pamiętać, że choć interfejs API JDOM jest raczej stabilny, to wciąż jest to wersja beta. W czasie przy­go­to­wy­wania tej książki do druku w interfejsie tym mogą zostać wprowadzone drobne zmiany. Najnowsze klasy JDOM można znaleźć pod adresem http://www.jdom.org.

Jeśli będzie takie zapotrzebowanie, być może w późniejszych wersjach JDOM zostanie dodana obsługa SAX 1.0.

390 Dodatek A Interfejs API — materiał referencyjny

SAX 2.0 371

H:\Książki\!Kudlaty\Java i XML\92 po poprawkach korektora\A-08.doc — strona 390

H:\Książki\!Kudlaty\Java i XML\92 po poprawkach korektora\A-08.doc — strona 371

H:\Książki\!Kudlaty\Java i XML\92 po poprawkach korektora\A-08.doc — strona 361

W.D.: Powinien być: public interface Attributes{ ... Oryginał str 430. (tłumacz: tak, powinno być Attributes)

---