A-08.pdf

(346 KB) Pobierz
Interfejs API
—
materiał referencyjny
A
Niniejszy dodatek zawiera krótki materiał referencyjny. Przedstawione są stutaj najważniejsze inter-
fejsy API Javy: SAX, DOM, a także JDOM, omówiony w rozdziale 8. oraz wspomniany w innych
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 podstawo-
wym pakiecie SAX (org.xml.sax). W celu zachowania zwięzłości te zdublowane definicje
metod 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 interfej-
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ć implemen-
towane 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.
C:\Users\a_czajka\Dropbox\Informatyka\książki
informatyczne\Java i
XML\A-08.DOC —
strona
361
362
public interface AttributeList {
public
public
public
public
public
public
}
abstract
abstract
abstract
abstract
abstract
abstract
Dodatek A Interfejs API
—
materiał referencyjny
int getLength ();
String getName (int i);
String getType (int i);
String getValue (int i);
String getType (String name);
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 przypo-
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);
}
ContentH anlder
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;
C:\Users\a_czajka\Dropbox\Informatyka\książki
informatyczne\Java i XML\A-08.DOC
—
strona
362
SAX 2.0
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;
}
363
DocumentH andler
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
nieprzetworzonych encji i deklaracji
NOTATION,
czyli wskazuje na obiekty stanowiące nieprze-
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
C:\Users\a_czajka\Dropbox\Informatyka\książki
informatyczne\Java i XML\A-08.DOC
—
strona
363
364
Dodatek A Interfejs API
—
materiał referencyjny
interfejsu możliwe jest zwrócenie do programu wywołującego zmodyfikowanego lub nawet całko-
wicie innego obiektu SAX
InputSource.
Ponadto, jeśli dla określonego identyfikatora syste-
mowego 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;
}
H andlerBase
Ta klasa pomocnicza udostępnia puste implementacje wszystkich podstawowych interfejsów pro-
cedur 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 implementa-
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;
C:\Users\a_czajka\Dropbox\Informatyka\książki
informatyczne\Java i XML\A-08.DOC
—
strona
364
SAX 2.0
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;
}
365
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 syste-
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.
C:\Users\a_czajka\Dropbox\Informatyka\książki
informatyczne\Java i XML\A-08.DOC
—
strona
365

Plik z chomika:

Inne pliki z tego folderu:

Inne foldery tego chomika:

Zgłoś jeśli naruszono regulamin