API-Referenz
Dieser Anhang ist eine API-Referenz für die vier Java- und XML-APIs niedriger Abstraktionsebenen, die in diesem Buch vorgestellt wurden: SAX, DOM, JDOM und JAXP. Sie ist in Abschnitte entsprechend der jeweils behandelten API aufgeteilt.
SAX 2.0
SAX 2.0 liefert eine sequentielle Ansicht auf XML-Dokumente. Wie ausführlich in den Kapiteln SAX und SAX für Fortgeschrittene dargestellt wurde, definiert SAX eine Menge Interfaces, die implementiert werden können und dann als Callbacks während des Prozesses des Parsens aufgerufen werden. Die zu SAX gehörigen Packages werden hier detailliert erläutert, wobei Interfaces und Klassen alphabetisch sortiert werden. Die meisten Methoden in den Hilfsklassen in dem Package org.xml.sax.helpers sind Implementierungen von Interfaces, die im Kern von SAX – dem Package (org.xml.sax) – definiert wurden.
Package: org.xml.sax
Dieses Package beinhaltet die Kernklassen und -interfaces für SAX 2.0. Die meisten der Interfaces sind dazu bestimmt, von Ihnen, dem Java-Programmierer, implementiert zu werden. Ausnahmen bilden dabei die Implementierungen von XMLReader und Attributes. Diese Interfaces sollten vom Hersteller der benutzten Software zum Parsen von XML-Dokumenten implementiert werden. Zusätzlich ist hier noch eine Anzahl an Exceptions, die SAX-Methoden auslösen dürfen, definiert. Einige der Interfaces sind Teil von SAX 1.0 und 2.0 alpha und heute veraltet (deprecated).
AttributeList [deprecated]
Dieses Interface war in SAX 1.0 definiert und ist nun veraltet. Das Interface Attributes sollte statt AttributeList für SAX 2.0-Implementierungen verwendet werden.
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
Dieses Interface repräsentiert eine Liste von XML-Attributen. Sie wird an die Callbacks übergeben, die mit dem Beginn eines Elements (startElement( ) in ContentHandler) verbunden sind, und ähnelt ein wenig einem Java-Vector. Man kann die Anzahl an Attributen ebenso abfragen, wie man eine Anzahl an Views auf die Namen der Attribute und deren Werte erhalten kann (lokal, Namensraum-Präfix und URI und roh). Zusätzlich stehen Methoden zur Verfügung, die den Index eines Attributs ermitteln, dessen Name bekannt ist. Der Hauptunterschied zwischen diesem Interface und seinem Vorgänger AttributeList ist, daß jetzt Namensräume berücksichtigt werden.
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 localName);
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);
}
ContentHandler
Dieses Interface definiert die Callback-Methoden, die es der Anwendung erlauben, mit dem Inhalt des XML-Dokuments zu arbeiten, das gerade geparst wird. Das schließt die Benachrichtigung beim Start und Ende des Parsens (die jeweils allen anderen Handler-Callbacks vorangehen oder nachfolgen) genauso ein wie Verarbeitungsinstruktionen oder Entities, die von nicht-validierenden Parsern übersprungen werden. Ebenfalls verfügbar sind Element-Callbacks mit Namensraum-Mappings.
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
Dieses Interface wurde in SAX 1.0 definiert und ist nun veraltet. Statt DocumentHandler sollte das Interface ContentHandler für SAX 2.0-Implementierungen benutzt werden.
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
Dieses Interface definiert Callbacks, die während des Parsens von DTDs aufgerufen werden. Beachten Sie, daß dieses Interface zwar keine Informationen über die Beschränkungen in der DTD liefert, wohl aber über Referenzen zu nicht geparsten Entities und NOTATION-Deklarationen, womit Items gekennzeichnet werden, die generell nicht geparste Daten darstellen.
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
Dieses Interface erlaubt es Anwendungen, in den Prozeß der Auflösung externer Entities einzugreifen, wie zum Beispiel eine Referenz auf eine DTD oder ein Stylesheet innerhalb eines XML-Dokuments anzulegen. Durch das Implementieren dieses Interfaces ist es möglich, dem aufrufenden Programm eine modifizierte oder komplett andere SAX-InputSource zu übergeben. Zusätzlich ist es erlaubt, null zurückzugeben, was dem System anzeigt, daß eine normale URI-Connection für die angegebene ID geöffnet werden soll.
public interface EntityResolver {
public abstract InputSource resolveEntity(String publicId,
String systemId)
throws SAXException, IOException;
}
ErrorHandler
Dieses Interface erlaubt es, bestimmte Verhaltensweisen an die drei Fehlerbedingungen anzukoppeln, die während des Parsens eines XML-Dokuments auftreten können. Jede empfängt eine SAXParseException, die anzeigt, was für ein Problem den Callback auslöste. Die SAXException wird benutzt, um das Parsen insgesamt zu stoppen.
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
Diese Hilfsklasse stellt leere Implementierungen aller SAX 1.0-Kern-Interfaces zur Verfügung. Von dieser Klasse kann abgeleitet werden, um durch Überschreiben von Methoden mit applikationsspezifischer Funktionalität schnell neue Handler zu erzeugen. Diese Klasse wurde mit SAX 1.0 eingeführt, sie ist nun veraltet. Die Klasse org.xml.sax.helpers.DefaultHandler sollte statt HandlerBase für SAX 2.0-Implementierungen benutzt werden.
public class HandlerBase implements EntityResolver, DTDHandler,
DocumentHandler, ErrorHandler {
// EntityResolver-Implementierung
public InputSource resolveEntity(String publicId, String systemId);
// DTDHandler-Implementierung
public void notationDecl(String name, String publicId,
String systemId);
public void unparsedEntityDecl(String name, String publicId,
String systemId, String notationName);
// DocumentHandler-Implementierung
public 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;
// ErrorHandler-Implementierung
public abstract void warning(SAXParseException exception)
throws SAXException;
public abstract void error(SAXParseException exception)
throws SAXException;
public abstract void fatalError(SAXParseException exception)
throws SAXException;
}
InputSource
Diese Klasse kapselt alle Informationen über eine bei der XML-Verarbeitung benutzte Ressource. Das kann eine so kleine Ressource wie ein String oder InputStream zur Bestimmung des Inputs oder eine so komplexe Ressource wie eine Entity mit einer öffentlichen und einer System-ID oder auch eine URI-Referenz (zum Beispiel eine öffentlich definierte DTD) sein. Diese Klasse ist der bevorzugte Wrapper, um Input an einen SAX-Parser zu übergeben.
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 String getEncoding( );
public void setCharacterStream(Reader characterStream);
public Reader getCharacterStream( );
}
Locator
Diese Klasse ist eine Ergänzung zu einem XML-Dokument oder einem anderen geparsten Konstrukt. Sie bietet die öffentliche und die System-ID des Dokuments und Informationen über die momentane Position in der bearbeiteten Datei. Das ist besonders für die Integration in IDEs und generell zum Auffinden von Fehlerursachen beim Parsen hilfreich.
public interface Locator {
public abstract String getPublicId( );
public abstract String getSystemId( );
public abstract int getLineNumber( );
public abstract int getColumnNumber( );
}
Parser
Dieses Interface wurde für SAX 1.0 definiert und ist nun veraltet. Das Interface XMLReader sollte statt dessen für SAX 2.0-Implementierungen benutzt werden.
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
Das ist die Kern-Exception, die von SAX-Callbacks und -Parser-Implementierungen ausgelöst wird. Da sie oft als Resultat anderer Exceptions ausgelöst wird, hat sie einen Konstruktor, der es erlaubt, eine speziellere Exception zu übergeben, wie auch Zugriffsmethoden, um die auslösende Exception abzufragen. Sie ist außerdem die Basisklasse für alle anderen SAX-Exception-Klassen.
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
Diese Klasse stellt ein Werkzeug für eine XMLReader-Implementierung dar, um einen Fehler zu signalisieren, wenn sie über unbekannte Identifier stolpert. Das geschieht am häufigsten in den Methoden setProperty( ) und setFeature( ) (wie auch bei den entsprechenden Gettern), wenn eine URI angegeben wurde, über die der Reader keine Informationen besitzt.
public class SAXNotRecognizedException extends SAXException {
public SAXNotRecognizedException(String message);
}
SAXNotSupportedException
Diese Klasse stellt ein Werkzeug für eine XMLReader-Implementierung zur Verfügung, um einen Fehler zu signalisieren, wenn ein nicht unterstützter (aber bekannter) Identifier gelesen wird. Dies geschieht am häufigsten in den Methoden setProperty( ) und setFeature( ) (wie auch bei den entsprechenden Gettern), wenn eine URI angegeben wurde, für die dem Parser kein entsprechender Code zur Verfügung steht.
public class SAXNotSupportedException extends SAXException {
public SAXNotSupportedException(String message)
}
SAXParseException
Diese Klasse repräsentiert Exceptions, die während des Parsens auftreten können. Informationen über die Position des Fehlers innerhalb des XML-Dokuments können durch die entsprechenden Getter dieser Klasse abgefragt werden. Die bevorzugte Methode zur Angabe einer solchen Position ist ein Locator. Zeilen- und Spaltennummer des Fehlers können mittels entsprechender Konstruktoren jedoch ebenfalls verwendet werden. Außerdem können der Klasse auch die öffentliche und die System-ID des Dokuments, in dem der Fehler auftrat, über entsprechende Konstruktoraufrufe zur Verfügung gestellt werden.
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 getColumnNumber( );
}
XMLFilter
Diese Klasse ist analog zur Klasse XMLReader, erhält ihre Eingaben aber von einem anderen XMLReader statt von einem statischen Dokument oder einer Netzwerk-Ressource. Es ist möglich, mehrere solcher Filter zu verketten. Ihr Hauptnutzen liegt in der Modifikation der Ausgabe eines früheren XMLReaders in der Kette und damit im Filtern der an Callbacks übergebenen Daten, bevor die eigentliche Anwendung diese zu Gesicht bekommt.
public interface XMLFilter extends XMLReader {
public abstract void setParent(XMLReader parent);
public abstract XMLReader getParent( );
}
XMLReader
Dieses Interface ist das Kernstück, das das Verhalten beim Parsen mit SAX 2.0 bestimmt. Jedes Softwarepaket zum Parsen von XML muß mindestens eine Implementierung dieses Interfaces beinhalten. Es ersetzt das Interface Parser aus SAX 1.0. Neu ist die Unterstützung von Namensräumen in Dokumenten-Elementen und Attributen. Zusätzlich zu der Möglichkeit, ins Parsen einzugreifen (entweder durch eine System-ID oder eine InputSource als Input) erlaubt es die Registrierung der verschiedenen Handler-Interfaces von SAX 2.0. Die Eigenschaften und Features, die einer SAX-Parser-Implementierung zur Verfügung stehen, werden ebenfalls durch dieses Interface gesetzt. Anhang B enthält eine vollständige Liste der zentralen Features und Eigenschaften von SAX.
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;
}
Package: org.xml.sax.ext
Dieses Package stellt Erweiterungen zu den zentralen Klassen und Interfaces von SAX bereit. Insbesondere werden hier zusätzliche Handler für weniger verbreitete Verarbeitungsschritte während des Parsens definiert. Implementierungen des Interfaces XMLReader müssen diese Erweiterungen nicht unterstützen.
DeclHandler
Dieses Interface definiert Callbacks, die spezifische Informationen über DTD-Deklarationen liefern. Die Definitionen von Elementen und Attributen rufen den entsprechenden Callback mit ihren Namen (bei Attributen außerdem mit dem Elementnamen) wie auch mit Informationen über Beschränkungen auf. Obwohl das eine sehr starre Menge von Daten über Attribute darstellt, erhalten Elemente nur einen String mit dem Constrained-Modell als einfachen Text. Zusätzlich sind die Benachrichtigungen über interne und externe Entity-Referenzen definiert.
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
Dieses Interface definiert Callbacks für verschiedene Events, die bei der Verarbeitung auf Dokumentenebene auftreten, die aber die resultierenden Daten im XML-Dokument nicht beeinflussen. Zum Beispiel würde die Verarbeitung von DTD-Deklarationen, Kommentaren und Entity-Referenzen Callbacks in Implementierungen dieses Interfaces aufrufen. Zusätzlich ist ein Callback definiert, der eingreift, wenn eine CDATA-Sektion beginnt oder endet (obwohl die gelieferten Daten immer dieselben bleiben werden).
public interface LexicalHandler {
public abstract void startDTD(String name, String publicId,
String systemId)
throws SAXException;
public abstract void endDTD( )
throws SAXException;
public abstract void startEntity(String name)
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;
}
Package: org.xml.sax.helpers
Dieses Package stellt eine Erweiterung zu den Interfaces und Klassen des SAX-Kerns dar. Speziell zusätzliche Handler für weniger verbreitete Verarbeitungsschritte während des Parsens werden hier definiert. Implementierungen des Interfaces XMLReader müssen diese Erweiterungen nicht unterstützen.
In den Klassen dieses Packages, die Default-Implementierungen von Interfaces des Packages org.xml.sax darstellen, habe ich die wiederholten Methoden der Kürze halber weggelassen. Statt dessen habe ich einen Kommentar hinzugefügt, der aussagt, welche Methoden jeweils implementiert sind.
AttributeListImpl
Dies ist eine Default-Implementierung des Interfaces org.xml.sax.AttributeList und seit SAX 2.0 veraltet. Sie erlaubt das Hinzufügen und Löschen von Attributen und das Löschen der gesamten Liste.
public class AttributeListImpl implements AttributeList {
public AttributeListImpl( );
public AttributeListImpl(AttributeList atts);
// Implementierung des Interfaces AttributeList
// Zusätzliche Methoden
public void setAttributeList(AttributeList atts);
public void addAttribute(String name, String type, String value);
public void removeAttribute(String name);
public void clear( );
}
AttributesImpl
Diese Klasse ist eine Default-Implementierung des Interfaces org.xml.sax.Attributes. Es erlaubt das Hinzufügen und Entfernen von Attributen und das Löschen der gesamten Liste.
public class AttributesImpl implements Attributes {
public AttributesImpl( );
public AttributesImpl(Attributes atts);
// Implementierung des Interfaces Attributes
// Zusätzliche Methoden
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
Diese Hilfsklasse stellt leere Implementierungen aller Handler-Interfaces des SAX 2.0-Kerns zur Verfügung. Durch Ableitung davon kann man schnell Handler hinzufügen, indem man nur die Methoden überschreibt, die sich anwendungsspezifisch verhalten sollen. Diese Klasse ersetzt die Klasse org.xml.sax.HandlerBase aus SAX 1.0.
public class DefaultHandler implements EntityResolver, DTDHandler,
ContentHandler, ErrorHandler {
// (Leer) Implementierung des Interfaces EntityResolver
// (Leer) Implementierung des Interfaces DTDHandler
// (Leer) Implementierung des Interfaces ContentHandler
// (Leer) Implementierung des Interfaces ErrorHandler
}
LocatorImpl
Diese Klasse stellt eine Default-Implementierung des Interfaces org.xml.sax.Locator dar. Sie stellt außerdem Mittel zur Verfügung, um Zeilen- und Spaltennummern direkt anzugeben.
public class LocatorImpl implements Locator {
public LocatorImpl( );
public LocatorImpl(Locator locator);
// Implementierung des Interfaces Locator
// Zusätzliche Methoden
public void setPublicId(String publicId);
public void setSystemId(String systemId);
public void setLineNumber(int lineNumber);
public void setColumnNumber(int columnNumber);
}
NamespaceSupport
Diese Klasse stellt Namensraum-Erweiterungen zur Verfügung; damit müssen Anwendungen dieses Verhalten nur dann selbst implementieren, wenn es wegen der Performance unbedingt nötig ist. Sie wickelt die Behandlung von Namensraum-Kontexten über einen Stack ab und erlaubt es, auch Namen aus XML 1.0 zu verwenden, die durch ihre entsprechenden Namensraum-»belasteten« Gegenstücke ersetzt werden.
public class NamespaceSupport {
public NamespaceSuport( );
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( );
public Enumeration getDeclaredPrefixes( );
}
ParserAdapter
Diese Hilfsklasse packt die Implementierung eines SAX 1.0-Parsers ein und läßt sie nach außen hin als Implementierung des Interfaces XMLReader aus SAX 2.0 erscheinen (womit eine Namensraum-Unterstützung bereitgestellt wird). Der einzige Callback, der sich nicht normal verhält, ist skippedEntity( ) im Interface ContentHandler – er wird einfach nie aufgerufen.
public class ParserAdapter implements XMLReader, DocumentHandler {
public ParserAdapter( ) throws SAXException;
public ParserAdapter(Parser parser);
// Implementierung des Interfaces XMLReader
// Implementierung des Interfaces DocumentHandler
}
ParserFactory
Diese Klasse enthält Methoden, über die man eine Instanz einer Implementierung eines Parsers vom spezifizierten Klassennamen erzeugt. Wird keiner angegeben, wird der Wert der Systemeigenschaft »org.xml.sax.driver« benutzt.
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
Diese Klasse bietet eine Default-Implementierung des Interfaces org.xml.sax.XMLFilter.
public class XMLFilterImpl implements XMLFilter, EntityResolver,
DTDHandler, ContentHandler,
ErrorHandler {
public XMLFilterImpl( );
public XMLFilterImpl(XMLReader parent);
// Implementierung des Interfaces XMLFilter
// Implementierung des Interfaces XMLReader
// Implementierung des Interfaces EntityResolver
// Implementierung des Interfaces DTDHandler
// Implementierung des Interfaces ContentHandler
// Implementierung des Interfaces ErrorHandler
}
XMLReaderAdapter
Diese Hilfsklasse verpackt eine Implementierung eines SAX 2.0-XMLReaders und läßt sie wie eine Implementierung eines Parsers aus SAX 1.0 aussehen (damit ist die Namensraum-Unterstützung nicht mehr verfügbar). Das Namensraum-Feature (http://xml.org/sax/features/namespaces) muß unterstützt werden, sonst treten beim Parsen Fehler auf.
public class XMLReaderAdapter implements Parser, ContentHandler {
public XMLReaderAdapter ( ) throws SAXException;
public XMLReaderAdapter (XMLReader xmlReader);
// Implementierung des Interfaces Parser
// Implementierung des Interfaces ContentHandler
}
XMLReaderFactory
Diese Klasse enthält Methoden, die dynamisch Instanzen einer XMLReader-Implementierung einer spezifizierten Klasse erzeugen. Wird kein Klassenname angegeben, wird der Wert der Systemeigenschaft »org.xml.sax.driver« benutzt.
final public class XMLReaderFactory {
public static XMLReader createXMLReader( ) throws SAXException;
public static XMLReader createXMLReader(String className)
throws SAXException;
}
DOM Level 2
DOM bietet eine vollständige Repräsentation eines XML-Dokuments im Speicher. Entwickelt vom W3C, bietet DOM detaillierte Informationen über die Struktur eines Dokuments, nachdem es geparst wurde. Während DOM Level 3 eine API spezifizieren wird, über die man auf das DOM-Objekt Document zugreifen kann, gibt es im Augenblick in DOM nichts Vergleichbares. Wie in SAX besteht auch der Großteil des Kerns des DOM-Packages aus Interfaces, die Strukturen in einem XML-Dokument definieren und diese auf Strukturen der Sprache Java abbilden (dieselben Abbildungen oder Mappings passen auch für CORBA, JavaScript und andere Sprachen).
Package: org.w3c.dom
Dieses Package enthält die zum Kern von DOM Level 2 gehörenden Klassen und Interfaces. Typischerweise liefern die Hersteller entsprechender Parser-Software Implementierungen der Interfaces mit, die implizit von der Anwendungssoftware benutzt werden.
Attr
Dieses Interface repräsentiert ein XML-Attribut (eines Elements) innerhalb von Java. Es erlaubt Zugriff auf den Namen und den Wert des Attributs sowie die Änderung des Werts (wenn das Attribut mutable ist).1 Die Methode getSpecified( ) zeigt an, ob das Attribut (und sein Wert) explizit im XML-Dokument angegeben war oder ob der Wert nicht angegeben war, die DTD aber einen Standardwert eingesetzt hat. Letztlich kann noch das »Eigner«-Element abgefragt werden.
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
Dieses Interface definiert selbst keine Methoden; statt dessen erbt es alle Methoden des Interfaces Text. Durch die Tatsache begründet, daß es ein selbständiges Interface (und daher ein eigenständiger Node-Typ) ist, kann man Text innerhalb von XML-CDATA-Sektionen von ordinärem Text (der nicht in einer solchen Sektion vorkommt) innerhalb eines Elements unterscheiden.
public interface CDATASection extends Text {
}
CharacterData
Dieses Interface ist das »Ober«-Interface für alle Node-Typen in DOM, die etwas mit Text zu tun haben (Text, Comment und – indirekt – auch CDATASection). Es definiert Methoden für das Lesen und Schreiben der Daten in einem Text-Node. Außerdem enthält es Methoden, die es gestatten, den enthaltenen Text als Menge von Buchstaben zu betrachten. Darunter fallen das Bestimmen der Länge, das Anhängen, das Einfügen, das Löschen von Daten und schließlich das vollständige oder teilweise Ersetzen von Daten. All diese Methoden lösen DOMExceptions aus, wenn der Node nur lesbar ist.
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
Dieses Interface liefert eine Java-Entsprechung für einen XML-Kommentar. Ähnlich wie CDATASection definiert es selbst keine Methoden, erlaubt es aber (durch den Typ des Interfaces), zwischen normalem Text und Kommentaren in einem XML-Dokument zu unterscheiden.
public interface Comment extends CharacterData {
}
Document
Dieses Interface repräsentiert ein komplettes XML-Dokument in DOM. Es ist der Schlüssel zur Erzeugung neuer XML-Elemente, -Attribute, -PIs und anderer Konstrukte. Zusätzlich zur Möglichkeit, die DTD-Deklaration (getDocType( )) und das root-Element (getDo-cumentElement( )) zu extrahieren, ist es möglich, den Baum mittels Pre-order-Suche nach bestimmten Elementen zu durchsuchen (getElementsByTagName( )).
Da das DOM-Modell es erfordert, daß alle Node-Implementierungen an ein DOM-Document-Objekt gekoppelt sind, erlaubt dieses Interface es, die verschiedenen Node-Typen zu erzeugen. Jede Methode des Namens createXXX( ) hat ein Pendant, das Namensräume unterstützt und der Namenskonvention createXXXNS( ) folgt. Außerdem können Nodes mittels importNode( ) in das Document importiert werden – das boolean-Argument zeigt an, ob die Kinder dieses Node rekursiv ebenfalls importiert werden sollen.
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
Dieses Interface erlaubt es, einen Teil eines Documents zu bearbeiten. Dadurch kann man Teile des DOM-Baums im Speicher manipulieren, ohne den gesamten Baum in den Speicher laden zu müssen.
public interface DocumentFragment extends Node {
}
DocumentType
Dieses Interface repräsentiert die DOCTYPE-Deklaration eines XML-Dokuments. Der Name ist der Elementname unmittelbar hinter <!DOCTYPE – die System-ID und die öffentliche ID aller referenzierten DTDs sind ebenfalls verfügbar. Sind irgendwelche Inline-Entities oder Anmerkungen vorhanden, kann man mittels entsprechender Methoden des Namens getXXX( ) darauf zugreifen.
public interface DocumentType extends Node {
public String getName( );
public NamedNodeMap getEntities( );
public NamedNodeMap getNotations( );
public String getPublicId( );
public String getSystemId( );
public String getInternalSubset( );
}
DOMException
Diese Klasse stellt eine Exception dar, die von DOM-Interfaces ausgelöst wird, wenn Probleme auftauchen. Sie stellt auch eine Menge Fehlercodes bereit, die die verschiedenen Fehler repräsentieren, die bei der Benutzung von DOM auftreten können und eventuell eine Exception auslösen.
public class DOMException extends RuntimeException {
public DOMException(short code, String message);
// Exception-Codes
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
Dieses Interface versucht, einen Standard-Zugriffsmechanismus für herstellerspezifische DOM-Implementierungen und die Erzeugung von DocumentType- und Document- Instanzen in diesen Implementierungen bereitzustellen.2 Mittels der Methode hasFeature( ) kann kann man bestimmen, ob ein gewünschtes Feature, wie zum Beispiel die DOM-Level-2-Module Traversal oder Range, in der vorliegenden Implementierung enthalten ist.
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
Dieses Interface liefert eine Java-Repräsentation eines XML-Elements. Es enthält Methoden zum Lesen wie auch zum Schreiben des Namens und der Attribute. Außerdem stellt es Methoden zum Zugriff auf XML-Attribute zur Verfügung, einschließlich der Namensräume unterstützenden Varianten der Methoden getXXX( ) und setXXX( ).
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
Das ist eine Java-Repräsentation einer Entity (geparst oder ungeparst) in einem XML-Dokument. Der Zugriff auf die System- und die öffentliche ID wie auch auf die Notation der Entity (aus der DTD) wird über entsprechende Methoden realisiert.
public interface Entity extends Node {
public String getPublicId( );
public String getSystemId( );
public String getNotationName( );
}
EntityReference
Dieses Interface repräsentiert das Resultat einer Entity-Referenz nach deren Auflösung. Dieses Interface nimmt an, daß alle anderen Referenzen bereits aufgelöst wurden, wenn dieses Interface dem Client angeboten wird.
public interface EntityReference extends Node {
}
NamedNodeMap
Dieses Interface definiert eine Liste ähnlich NodeList, die aber zusätzlich fordert, daß jeder Node in der Liste ein benannter (engl. named) Node (wie zum Beispiel ein Element oder Attr) ist. Diese Forderung macht es möglich, Methoden zur Verfügung zu stellen, mit denen man über den Namen auf Elemente zugreifen kann (mit oder ohne Namensraum-Unterstützung). Die Liste erlaubt außerdem das Entfernen und Modifizieren einzelner Elemente. All diese Methoden lösen eine DOMException aus, wenn der entsprechende Node nur lesbar ist.
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
Dies ist das zentrale Interface für alle DOM-Objekte. Es liefert einen umfassenden Satz an Methoden zum Zugriff auf die Informationen innerhalb eines Node im DOM-Baum. Es ermöglicht ebenfalls Zugriff auf die Kinder des Node (wenn es welche gibt). Die meisten der Methoden sind selbsterklärend, auf einige soll hier jedoch gesondert eingegangen werden: getAttributes( ) gibt nur dann nicht null zurück, wenn der Node ein Element ist; cloneNode( ) liefert eine flache oder tiefe Kopie eines Node; normalize( ) bewegt den vollständigen Text in nicht benachbarte Text-Nodes (keine zwei Text-Nodes sind benachbart und alle aufgelösten Referenzen auf Text-Entities sind in Text-Nodes umgewandelt); isSupported( ) schließlich liefert Informationen über die Menge der Features des Node.
Weiterhin existieren Namensraum-unterstützende Methoden (getNamespaceURI( ), getPrefix( ) und getLocalName( )). Schließlich ist eine Menge Konstanten definiert, die es erlauben, den Typ des Node durch einen Vergleich mit dem Resultat getNodeType( ) zu ermitteln.
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 isSupported(String feature, String version);
public String getNamespaceURI( );
public String getPrefix( );
public void setPrefix(String prefix) throws DOMException;
public String getLocalName( );
public boolean hasAttributes( );
// Node-Typ-Konstanten
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
Dieses Interface ist eine DOM-Struktur ähnlich einem Vector oder einer List in Java. Es stellt den Rückgabewert jeder Methode dar, die eine Menge von Node-Implementierungen als Resultat liefert. Man kann durch die Nodes iterieren oder mittels ihres Index auf einen bestimmten Node zugreifen.
public interface NodeList {
public Node item(int index);
public int getLength( );
}
Notation
Dieses Interface repräsentiert das Konstrukt NOTATION in einer DTD, das benutzt wird, um das Format einer ungeparsten Entity oder eine PI zu deklarieren. Es sind Methoden vorhanden, mit denen man auf die öffentliche und die System-ID innerhalb der Deklaration zugreifen kann. Beide liefern null, wenn das entsprechende Konstrukt nicht vorhanden ist.
public interface Notation extends Node {
public String getPublicId( );
public String getSystemId( );
}
ProcessingInstruction
Dies repräsentiert eine XML-Verarbeitungsanweisung (engl. processing instruction – PI). Es liefert Methoden zum Zugriff auf die Daten und das Ziel der PI. Beachten Sie, daß es keine Möglichkeit gibt, die »Name/Wert«-Paare innerhalb der PI einzeln anzusprechen. Die Daten der PI können ebenfalls modifiziert werden.
public interface ProcessingInstruction extends Node {
public String getTarget( );
public String getData( );
public void setData(String data) throws DOMException;
}
Text
Dieses Interface bildet eine Java-Repräsentation der Text-Daten eines XML-Dokuments. Die einzige Methode, die es zu den bereits in CharacterData definierten Methoden hinzufügt, ist eine, die den Node in zwei aufspaltet. Der ursprüngliche Text-Node enthält den Text bis zum angegebenen Index. Diese Methode gibt einen neuen Text-Node mit dem Text ab dieser Stelle zurück. Wie andere Methoden zum Modifizieren löst auch diese Methode eine DOMException aus, wenn der Node nur lesbar ist.
public interface Text extends CharacterData {
public Text splitText(int offset) throws DOMException;
}
JAXP 1.1
JAXP bietet eine herstellerunabhängige Abstraktion für das Erzeugen einer Instanz eines SAX- oder DOM-Parsers und stellt Transformationen auf eine herstellerunabhängige Weise zur Verfügung. Damit hat man die Möglichkeit, verschiedene Implementierungen einfach gegeneinander auszutauschen.
Package: javax.xml.parsers
Dies ist das Package in JAXP, das die JAXP-Klassen enthält, die die angesprochene Abstraktionsschicht bilden.
DocumentBuilder
Diese Klasse kapselt eine zugrundeliegende Klasse zur Implementierung eines Parsers ein. Sie gestattet es, den Prozeß des Parsens hersteller- und implementierungsunabhängig zu machen.
public abstract class DocumentBuilder {
public Document parse(InputStream stream)
throws SAXException, IOException, IllegalArgumentException;
public Document parse(InputStream stream, String systemID)
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 source)
throws SAXException, IOException, IllegalArgumentException;
public abstract Document newDocument( );
public abstract boolean isNamespaceAware( );
public abstract boolean isValidating( );
public abstract void setEntityResolver(EntityResolver er);
public abstract void setErrorHandler(ErrorHandler eh);
public DOMmplementation getDOMImplementation( );
}
DocumentBuilderFactory
Diese Klasse ist die Factory zur Erzeugung von Instanzen der Klasse DocumentBuilder. Sie erlaubt es, die Eigenschaften der Instanzen bezüglich Namensraum-Unterstützung und Validierung zu bestimmen.
public abstract class DocumentBuilderFactory {
public static DocumentBuilderFactory newInstance( );
public abstract DocumentBuilder newDocumentBuilder( )
throws ParserConfigurationException;
public void setAttribute(String name, Object value);
public void setCoalescing(boolean coalescing);
public void setExpandEntityReferences(boolean expand);
public void setIgnoringComments(boolean ignoreComments);
public void setIgnoringElementContentWhitespace(boolean ignoreWhitespace);
public void setNamespaceAware(boolean aware);
public void setValidating(boolean validating);
public boolean isCoalescing( );
public boolean isExapandEntityReferences( );
public boolean isIgnoringComments( );
public boolean isIgnoreingElementContentWhitespace( );
public boolean isNamespaceAware( );
public boolean isValidating( );
public Object getAttribute(String name);
}
FactoryConfigurationError
Diese Klasse definiert einen Fehler, der ausgelöst wird, wenn eine Factory-Instanz nicht erzeugt werden kann.
public class FactoryConfigurationException extends Error {
public FactoryConfigurationError( );
public FactoryConfigurationError(String msg);
public FactoryConfigurationError(Exception e);
public FactoryConfigurationError(Exception e, String msg);
}
ParserConfigurationException
Dies definiert eine Exception, die ausgelöst wird, wenn ein Parser angefordert wird, der aber mit den angegebenen Einstellungen für Namensraum-Unterstützung und Validierung nicht erzeugt werden kann.
public class ParserConfigurationException extends Exception {
public ParserConfigurationException( );
public ParserConfigurationException(String msg);
}
SAXParser
Diese Klasse kapselt eine zugrundeliegende Klasse, die eine SAX 1.0/2.0-Parser-Implementierung darstellt. Sie erlaubt es, den Prozeß des Parsens herstellerunabhängig zu gestalten. Sie verfügt über zwei Ausprägungen jeder Methode: eine für SAX 1.0 und eine für SAX 2.0.
public abstract class SAXParser {
public void parse(InputStream stream, HandlerBase base)
throws SAXException, IOException, IllegalArgumentException;
public void parse(InputStream stream, HandlerBase base, String systemID)
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 void parse(InputStream stream, DefaultHandler dh)
throws SAXException, IOException, IllegalArgumentException;
public void parse(InputStream stream, DefaultHandler dh, String systemID)
throws SAXException, IOException, IllegalArgumentException;
public void parse(String uri, DefaultHandler dh)
throws SAXException, IOException, IllegalArgumentException;
public void parse(File file, DefaultHandler dh)
throws SAXException, IOException, IllegalArgumentException;
public void parse(InputSource source, DefaultHandler dh)
throws SAXException, IOException, IllegalArgumentException;
public Parser getParser( ) throws SAXException;
public XMLReader getXMLReader( ) throws SAXException;
public Object getProperty(String name);
public void setProperty(String name, Object value);
public boolean isNamespaceAware( );
public boolean isValidating( );
}
SAXParserFactory
Diese Klasse ist die Factory zur Erzeugung von Instanzen der Klasse SAXParser. Sie erlaubt es, die Eigenschaften der Instanzen bezüglich Namensraum-Unterstützung und Validierung zu bestimmen.
public abstract class SAXParserFactory {
public static SAXParserFactory newInstance( );
public SAXParser newSAXParser( )
throws ParserConfigurationException, SAXException;
public void setNamespaceAware(boolean aware);
public void setValidating(boolean validating);
public void setFeature(String name, boolean value);
public boolean isNamespaceAware( );
public boolean isValidating( );
public boolean getFeature(String name);
}
Package: javax.xml.transform
Dies ist das Package, das innerhalb von JAXP zur Transformation von XML-Dokumenten benutzt wird. Es erlaubt es, diese Transformationen herstellerunabhängig und auswechselbar zu gestalten, vorausgesetzt, daß die einzelnen Implementierungen die hier definierten TrAX-Interfaces (Transformations-API für XML) verwenden.
ErrorListener
Dieses Interface entspricht ErrorHandler in SAX und benachrichtigt die Transformationen über aufgetretene Fehler. Sie müssen es in eigenen Applikationen implementieren, die TrAX benutzen.
public interface ErrorListener {
public void warning(TransformerException exception);
public void error(TransformerException exception);
public void fatalError(TransformerException exception);
}
OutputKeys
Diese Klasse enthält lediglich einige static-Konstanten, die in der übrigen TrAX-API benutzt werden.
public class OutputKeys {
public static final String CDATA_SECTION_ELEMENTS;
public static final String DOCTYPE_PUBLIC;
public static final String DOCTYPE_SYSTEM;
public static final String ENCODING;
public static final String INDENT;
public static final String MEDIA_TYPE;
public static final String METHOD;
public static final String OMIT_XML_DECLARATION;
public static final String STANDALONE;
public static final String VERSION;
}
Result
Dieses Interface liefert die Ausgabe von XML-Transformationen. Default-Implementierungen dieses Interfaces sind in den JAXP-Packages javax.xml.transform.* enthalten.
public interface Result {
public static final String PI_DISABLE_OUTPUT_ESCAPING;
public static final String PI_ENABLE_OUTPUT_ESCAPING;
public String getSystemId( );
public void setSystemId( );
}
Source
Dieses Interface liefert die Eingaben für XML-Transformationen. Default-Implementierungen dieses Interfaces finden Sie in den JAXP-Packages javax.xml.transform.*.
public interface Source {
public String getSystemId( );
public void setSystemId( );
}
SourceLocator
Dieses Interface ist ein Analogon zum SAX-Interface Locator und stellt TrAX Informationen über den Standort von Eingaben zur Verfügung. Wie auch ErrorListener ist es bei der Fehlerbehandlung und beim Reporting am nützlichsten.
public interface SourceLocator {
public int getColumnNumber( );
public int getLineNumber( );
public String getPublicId( );
public String getSystemId( );
}
Templates
Dieses Interface erlaubt es, optimale Transformationen unter Benutzung desselben Stylesheets durchzuführen. Es enthält lediglich Methoden, die es erlauben, Instanzen der Klasse Transformer zu erzeugen und die aktuellen Output-Eigenschaften einzusehen.
public interface Tempaltes {
public Properties getOutputProperties( );
public Transformer newTransformer( );
}
Transformer
Dies ist die zentrale (abstrakte) Klasse bei der Durchführung von XML-Transformationen mittels TrAX und JAXP. Sie haben nicht nur die Möglichkeit, verschiedene Eigenschaften und Objekte des Interfaces zu setzen, sondern können durch Aufrufen der Methode transform( ) auch die eigentliche Transformation starten.
public class Transformer {
public void setErrorListener(ErrorListener errorListener);
public ErrorListener getErrorListener( );
public void setURIResolver(URIResolver resolver);
public URIResolver getURIResolver( );
public void setOutputProperties(Properties properties);
public Properties getOutputProperties( );
public void setOutputProperty(String name, String value);
public String getOutputProperty(String name);
public void clearParmaters( );
public void setParameter(String name, String value);
public Object getParameter(String name);
public void transform(Source xmlSource, Result outputTarget);
}
TransformerFactory
Das ist die andere »Hälfte« der Transformations-Engine in JAXP. Sie können das Stylesheet angeben, das für die Transformation benutzt werden soll, und dann neue Instanzen der Klasse Transformer erzeugen. Sie können damit auch neue Instanzen der Klasse Templates erzeugen, wenn Sie mehrere Transformationen mit dem gleichen Stylesheet durchführen möchten.
public class TransformerFactory {
public TransformerFactory newInstance( );
public Transformer newTemplates(Source stylesheet);
public Transformer newTransformer(Source stylesheet);
public Transformer newTransformer( );
public Source getAssociatedStylesheet(Source source, String media,
String title, String charset);
public ErrorListener getErrorListener( );
public void setErrorListener(ErrorListener errorListener);
public URIResolver getURIResolver( );
public void setURIResolver(URIResolver uriResolver);
public Object getAttribute(String name);
public void setAttribute(String name, String value);
public boolean getFeature(String name);
}
URIResolver
Dieses Interface ist für die URI-Auflösung verantwortlich und entspricht dem SAX-Interface EntityResolver.
public interface URIResolver {
public Source resolve(String href, String base);
}
Package: javax.xml.transform.dom
Dieses Package beinhaltet zwei Klassen: DOMResult und DOMSource. Dies sind Implementierungen der Interfaces Result und Source. Sie werden dann genutzt, wenn die Eingabe und Ausgabe von Transformationen durch DOM-Bäume repräsentiert werden soll. Da dies einfache Implementierungsklassen sind, wird hier auf die Methoden nicht ausführlich eingegangen; das Kapitel JAXP erläutert ihre Benutzung.
Package: javax.xml.transform.sax
Dieses Package enthält zwei Klassen: SAXResult und SAXSource. Dies sind Implementierungen der Interfaces Result und Source. Sie werden benutzt, wenn die Eingabe und Ausgabe von Transformationen durch SAX-Events repräsentiert werden soll. Da dies einfache Implementierungsklassen sind, wird hier auf die Methoden nicht näher eingegangen; das Kapitel JAXP erläutert ihre Benutzung.
Package: javax.xml.transform.stream
Dieses Package stellt die zwei Klassen StreamResult und StreamSource zur Verfügung. Sie sind Implementierungen der Interfaces Result und Source. Sie werden benutzt, wenn die Eingabe und Ausgabe von Transformationen durch I/O-Streams repräsentiert werden soll. Da dies einfache Implementierungsklassen sind, wird hier auf die Methoden nicht näher eingegangen; das Kapitel JAXP erläutert ihre Benutzung.
JDOM 1.0 (Beta 7)
JDOM 1.0 (Beta 7), auf das bereits in den Kapiteln JDOM und JDOM für Fortgeschrittene eingegangen wurde, liefert eine vollständige Ansicht eines XML-Dokuments in Baumform. Es ähnelt zwar DOM sehr, stellt aber eine weniger starre Repräsentation dar. JDOM erlaubt es beispielsweise, den Inhalt eines Elements direkt zu setzen, anstatt den Wert des Kindes dieses Elements. Zusätzlich enthält JDOM konkrete Klassen und nicht lediglich Interfaces. Dadurch ist es möglich, Objekte direkt, ohne den Zwang zur Benutzung von Factories, zu instantiieren. SAX und DOM werden lediglich benutzt, um ein JDOM-Document aus XML-Daten zu erzeugen – die Klassen dafür sind in dem Package org.jdom.input enthalten.
Package: org.jdom
Die in diesem Package enthaltenen Klassen bilden den Kern von JDOM 1.0.3 Einige dieser Klassen modellieren XML-Objekte, der Rest stellt Exceptions dar, die ausgelöst werden, wenn Fehler auftreten.4
Attribute
Attribute modelliert ein XML-Attribut in Java. Sie enthält Methoden, die es erlauben, Informationen über den Wert des Attributs wie auch seinen Namensraum zu erhalten. Eine Instanz kann unter Angabe des Namens und seines Wertes oder des Namespaces und seines lokalen Namens zusammen mit seinem Wert erzeugt werden. Außerdem werden einige Methoden zur automatischen Konvertierung des Wertes zur Verfügung gestellt.
public class Attribute {
public Attribute(String name, String value);
public Attribute(String name, String value, Namespace ns);
public Element getParent( );
public String getName( );
public Namespace getNamespace( );
public void setNamespace(Namespace ns);
public String getQualifiedName( );
public String getNamespacePrefix( );
public String getNamespaceURI( );
public String getValue( );
public void setValue(String value);
public Object clone( );
public boolean equals(Object obj);
public int hashCode( );
public String toString( );
// Methoden zur bequemen Datenumwandlung
public String get StringValue(String default Value);
public int getIntValue( ) throws DataConversionException;
public long getLongValue( ) throws DataConversionException;
public float getFloatValue( ) throws DataConversionException;
public double getDoubleValue( ) throws DataConversionException;
public boolean getBooleanValue( ) throws DataConversionException;
}
CDATA
Die Klasse CDATA definiert das Verhalten von XML-CDATA-Abschnitten.
public class CDATA {
public CDATA(String text);
public String getText( );
public Object clone( );
public boolean equals(Object obj);
public int hashCode( );
public String toString( );
}
Comment
Comment ist eine einfache Repräsentation von XML-Kommentaren und enthält den Text des Kommentars.
public class Comment {
public Comment(String text);
public Document getDocument( );
public Element getParent( );
public String getText( );
public void setText(String text);
public Object clone( );
public boolean equals(Object obj);
public int hashCode( );
public String toString( );
}
DocType
DocType repräsentiert eine DOCTYPE-Deklaration innerhalb eines XML-Dokuments. Es enthält Informationen über den Namen des betroffenen Elements wie auch die öffentliche und System-ID der externen DTD-Referenz, wenn eine angegeben wurde.
public class DocType {
public DocType(String elementName, String publicID, String systemID);
public DocType(String elementName, String systemID);
public DocType(String elementName);
public Document getDocument( );
public String getElementName( );
public String getPublicID( );
public DocType setPublicID(String publicID);
public String getSystemID( );
public DocType setSystemID(String systemID);
public Object clone( );
public boolean equals(Object obj);
public int hashCode( );
public String toString( );
}
Document
Document modelliert ein XML-Dokument in Java. Document erfordert ein root-Element zur Erzeugung, obwohl dieses durch die Methode setRootElement( ) ersetzt werden kann. Die Methode getContent( ) liefert den Inhalt des gesamten Dokuments Document, einschließlich des root-Elements und jeglicher Comments (Kommentare), die eventuell auf Dokumentebene vorhanden sind.
public class Document {
public Document(Element rootElement, DocType docType);
public Document(Element rootElement);
public Document(List content);
public Document(List content, DocType docType);
public Document addContent(Comment comment);
public Document removeContent(Comment comment);
public Document addContent(ProcessingInstruction pi);
public Document removeContent(ProcessingInstruction pi);
public Element getRootElement( ) throws NoSuchElementException;
public Document setRootElement(Element rootElement);
public DocType getDocType( );
public Document setDocType(DocType docType);
public List getContent( );
public void setMixedContent(List content);
public Object clone( );
public boolean equals(Object obj);
public int hashCode( );
public String toString( );
}
Element
Element ist die Java-Repräsentation eines XML-Elements. Es unterstützt Namensräume, daher akzeptiert jede Methode einen aus einem Element bestehenden Namen, wie auch optionale Informationen über den Namensraum als Argument. Das Resultat des Aufrufs von getText( ) ist immer ein String, und zwar entweder der Text-Inhalt des Elements oder ein leerer String. Ein Element hat dann gemischten Inhalt, wenn es einerseits Textdaten und eingebettete Elemente und andererseits auch optionale Kommentare, Entities und Verarbeitungsinstruktionen enthält. Diese komplette List des Inhalts kann mittels getContent( ) abgefragt werden. Der Typ kann dann mittels instanceof zu String, Element oder Comment verfeinert werden.
Die Methoden addXXX( ) sind so gestaltet, daß man sie verketten kann, und liefern daher jeweils das modifizierte Element zurück:
Element element = new Element("root");
element.addChild(new Element("child")
.addChild(new Element("grandchild")
.addAttribute("name", "value")
.setContent("Hello World!"))
.addChild(new Element("anotherChild"))
);
Das würde folgendes Fragment eines XML-Dokuments ergeben:
<root>
<child>
<grandchild name="value">
Hello World!
</grandchild>
</child>
<anotherChild />
</root>
Hier folgt nun das API-Listing:
public class Element {
public Element(String name);
public Element(String name, String uri);
public Element(String name, String prefix, String uri);
public Element(String name, Namespace ns);
public Document getDocument( );
public Element getParent( );
public Element detach( );
public String getName( );
public void setName(String name);
public Namespace getNamespace( );
public Namespace getNamespace(String prefix);
public void setNamespace(Namespace ns);
public String getNamespacePrefix( );
public String getNamespaceURI( );
public String getQualifiedName( );
public void addNamespaceDeclaration(Namespace additionalNS);
public void removeNamespaceDeclaration(Namespace additionalNS);
public List getAdditionalNamespaces( );
public List getContent( );
public Element setMixedContent(List mixedContent);
public Element addContent(CDATA cdata);
public Element addContent(Comment comment);
public Element addContent(Element element);
public Element addContent(EntityRef entityRef);
public Element addContent(ProcessingInstruction pi);
public Element addContent(String text);
public boolean removeContent(CDATA cdata);
public boolean removeContent(Comment comment);
public boolean removeContent(Element element);
public boolean removeContent(EntityRef entityRef);
public boolean removeContent(ProcessingInstruction pi);
public boolean hasChildren( );
public Element getChild(String name);
public Element getChild(String name, Namespace ns);
public List getChildren( );
public List getChildren(String name);
public List getChildren(String name, Namespace ns);
public boolean removeChild(String name);
public boolean removeChild(String name, Namespace ns);
public boolean removeChildren( );
public boolean removeChildren(String name);
public boolean removeChildren(String name, Namespace ns);
public Element setChildren(List children);
public Attribute getAttribute(String name);
public Attribute getAttribute(String name, Namespace ns);
public List getAttributes( );
public String getAttributeValue(String name);
public String getAttributeValue(String name, Namespace ns);
public boolean removeAttribute(String name);
public boolean removeAttribute(String name, Namespace ns);
public Element setAttribute(Attribute attribute);
public Element setAttributes(List attributes);
public String getChildText(String name);
public String getChildText(String name, Namespace ns);
public String getChildTextTrim(String name);
public String getChildTextTrim(String name, Namespace ns);
public String getText( );
public String getTextNormalize( );
public String getTextTrim( );
public Element setText(String text);
public boolean isRootElement( );
public Object clone( );
public boolean equals(Object obj);
public int hashCode( );
public String toString( );
}
EntityRef
Diese Klasse definiert ein JDOM-Modell für Entity-Referenzen in XML-Dokumenten. Sie erlaubt es, den Namen, die öffentliche und die System-ID der Referenz zu lesen und zu setzen.
public class EntityRef {
public EntityRef(String name);
public EntityRef(String name, String publicID, String systemID);
public Document getDocument( );
public Element getParent( );
public String getName( );
public EntityRef setName(String name);
public String getPublicID( );
public void setPublicID(String publicID);
public String getSystemID( );
public void setSystemID(String systemID);
public EntityRef detach( );
public Object clone( );
public boolean equals(Object obj);
public int hashCode( );
public String toString( );
}
JDOMException
Dies ist die zentrale Exception in JDOM, von der jede andere JDOM-Exception abgeleitet ist. Sie liefert eine Fehlermeldung. Es ist möglich, eine andere Exception zu kapseln, sollte eine JDOMException durch eine andere Exception ausgelöst worden sein.
public class JDOMException extends Exception {
public JDOMException( );
public JDOMException(String message);
public JDOMException(String message, Throwable rootCause);
public Throwable getCause( );
public String getMessage( );
}
Namespace
Die Klasse Namespace bearbeitet in JDOM-Objekten benutzte Namensraum-Mappings.
public class Namespace {
public static Namespace getNamespace(String uri);
public static Namespace getNamespace(String prefix, String uri);
public String getPrefix( );
public String getURI( );
public boolean equals(Object obj);
public int hashCode( );
public String toString( );
}
ProcessingInstruction
ProcessingInstruction stellt eine in Java modellierte XML-Verarbeitungsanweisung dar. Sie erlaubt eine spezielle Bahandlung des Ziels und der Rohdaten. Da viele PIs Daten in der Form von Name/Wert-Paaren benutzen (wie Attribute), erlaubt diese Klasse das Auslesen und Hinzufügen solcher Paare. Zum Beispiel würde der Aufruf getValue("type") für eine Instanz der Klasse ProcessingInstruction, die die PI <?cocoon-process type="xslt"?> repräsentiert, »xslt« als Ergebnis liefern.
public class ProcessingInstruction {
public ProcessingInstruction(String target, Map data);
public ProcessingInstruction(String target, String data);
public ProcessingInstruction detach( );
public Document getDocument( );
public Element getParent( );
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);
public Object clone( );
public boolean equals(Object obj);
public int hashCode( );
public String toString( );
}
Text
Diese Klasse repräsentiert Textdaten, die »Eigentum« eines JDOM-Elements sind. Sie ist für den Benutzer meist unsichtbar, da die Klasse Element diese Daten in einen simplen String umwandelt, wenn der Wert abgefragt wird. Sie wird nur durch die getContent( )-Methode der Klasse Element nach außen gegeben.
public class Text {
public Text(String stringValue);
public Element getParent( );
public void append(String stringValue);
public String getValue( );
public void setValue(String stringValue);
public Object clone( );
public boolean equals(Object obj);
public int hashCode( );
public String toString( );
}
Package: org.jdom.adapters
Dieses Package enthält Adapter, die ein Standard-Interface für die Erzeugung eines DOM-Documents von beliebigen DOM-Parsern aus darstellt (einschließlich DOM-Level-1-Parsern). Adapter können für beliebige Parser, für die JDOM-Unterstützung gewünscht wird, einfach hinzugefügt werden.
AbstractDOMAdapter
Diese Klasse stellt eine rudimentäre Implementierung der Methode getDocument( ) dar, die mittels des übergebenen Dateinamens einen FileOutputStream konstruiert und anschließend getDocument(InputStream) aufruft.
public abstract class AbstractDOMAdapter implements DOMAdapter {
public abstract Document getDocument(InputStream in, boolean validate)
throws IOException;
public abstract Document getDocument(File filename, boolean validate)
throws IOException;
public abstract Document createDocument(DocType docType)
throws IOException;
}
DOMAdapter
Dieses Interface müssen Adapter implementieren. Es beinhaltet Methoden zur Erzeugung eines DOM-Documents aus einem Dateinamen oder aus einem InputStream, wie auch die Erzeugung eines neuen leeren DOM-Document-Objekts.
public interface DOMAdapter {
public abstract Document getDocument(InputStream in, boolean validate)
throws IOException;
public abstract Document getDocument(File filename, boolean validate)
throws IOException;
public abstract Document createDocument(DocType docType)
throws IOException;
}
Spezielle Adapter werden hier nicht genauer beleuchtet, da sich ständig Änderungen ergeben können. Zu dem Zeitpunkt, da diese Zeilen geschrieben werden, sind Adapter für folgende Parser verfügbar:
- Oracle Version 1 XML Parser
- Oracle Version 2 XML Parser
- Sun Project X Parser
- Sun/Apache Crimson Parser
- Apache Xerces Parser
- IBM XML4J Parser
Package: org.jdom.input
Dieses Package definiert Klassen, die aus verschiedensten Datenquellen JDOM-Document-Objekte erzeugen. Dazu gehören unter anderem auch SAX-Streams und bereits vorhandene DOM-Bäume. Es stellt außerdem Interfaces zum Gebrauch benutzerdefinierter Varianten der JDOM-Klassen, wie zum Beispiel Kindklassen von Element und Attribute, zur Verfügung.
BuilderErrorHandler
Dies ist der Default-Error-Handler, der bei der Erstellung von JDOM-Dokumenten benutzt wird.
public class BuilderErrorHandler
implements org.xml.sax.ErrorHandler {
public void warning(SAXParserException exception);
public void error(SAXParserException exception);
public void fatalError(SAXParserException exception);
}
DOMBuilder
Diese Klasse kann mittels eines Parsers, der DOM (das Document Object Model) unterstützt, JDOM-Document-Objekte aus einer XML-Quelle erzeugen. Sie benutzt die verschiedenen Adapter in org.jdom.adapters. Wird also ein dort nicht unterstützter Parser benutzt, werden Fehler gemeldet werden. Zusätzlich wird eine Methode definiert, die ein JDOM-Document-Objekt aus einem bestehenden DOM-Baum (org.w3c.dom.Document) erzeugt. Wenn der DOMBuilder konstruiert ist, können Sie seine Validierung beantragen. Genauso ist es möglich, den Klassennamen des Adapters anzugeben, der benutzt werden soll. Wird keiner angegeben, wird keine Validierung durchgeführt und der Apache Xerces-Parser benutzt.
Man kann auch die Factory angeben (siehe den Eintrag JDOMFactory), die benutzt wird, um während des Aufbaus des Dokuments die JDOM-Klassen zu generieren.
public class DOMBuilder {
public DOMBuilder(String adapterClass, boolean validate);
public DOMBuilder(String adapterClass);
public DOMBuilder(boolean validate);
public DOMBuilder( );
public Document build(InputStream in);
public Document build(File file);
public Document build(URL url);
public Document build(org.w3c.dom.Document domDocument);
public Element build(org.w3c.dom.Element domElement);
public void setValidation(boolean validate);
public void setFactory(JDOMFactory factory);
}
JDOMFactory
Dieses Interface erlaubt es Benutzern, ihre eigene Factory zur Erzeugung von JDOM-Konstrukten (Element, Attribute etc.) zu nutzen. Wenn eine Factory-Implementierung mit der Methode setFactory( ) an den Builder übergeben wird, wird diese zur Erzeugung von JDOM-Konstrukten benutzt. Das erlaubt die vollständige Anpassung des Prozesses der Erzeugung von JDOM-Objekten.
Um das Ganze abzukürzen und überschaubar zu halten, führe ich hier nicht die sehr lange Liste von Methoden dieser Factory auf. Ich möchte Sie statt dessen auf das entsprechende Javadoc-Dokument verweisen. Jedes mögliche Konstrukt jeder JDOM-Klasse wird in dieser Klasse abgedeckt, und all diese Methoden liefern als Ergebnis den Typ des Objekts, das konstruiert wurde.
SAXBuilder
Diese Klasse stellt eine Funktionalität zur Verfügung, die es erlaubt, ein JDOM-Dokument mittels eines SAX-Parsers (SAX: Simple API for XML) aus einer XML-Quelle zu erzeugen. Sie kann jede SAX 2.0-kompatible Parser-Implementierung nutzen. Wenn der SAXBuilder konstruiert wird, kann man seine Validierung beantragen und auch den Namen des zu verwendenden Parsers angeben. Wird nichts angegeben, wird keine Validierung durchgeführt und der Apache Xerces-Parser benutzt.
Sie können außerdem die Factory angeben (siehe den Eintrag JDOMFactory), die zur Generierung von JDOM-Klassen während des Prozesses der Dokumenterzeugung benutzt werden soll.
public class SAXBuilder {
public SAXBuilder(String saxDriverClass, boolean validate);
public SAXBuilder(String saxDriverClass);
public SAXBuilder(boolean validate);
public SAXBuilder( );
public Document build(InputStream in);
public Document build(InputStream in, String systemID);
public Document build(InputSource inputSource);
public Document build(Reader characterStream);
public Document build(Reader characterStream, String systemID);
public Document build(File file);
public Document build(URL url);
public Document build(org.w3c.dom.Document domDocument);
public Element build(org.w3c.dom.Element domElement);
public void setDTDHandler(DTDHandler dtdHandler);
public void setEntityResolver(EntityResolver entityResolver);
public void setErrorHandler(ErrorHandler errorHandler);
public void setExpandEntities(boolean expandEntities);
public void setXMLFilter(XMLFilter xmlFilter);
public void setIgnoringElementContentWhitespace(boolean ignore);
public void setValidation(boolean validate);
public void setFactory(JDOMFactory factory);
}
Package: org.jdom.output
Dieses Package definiert das Verhalten für die Ausgabe von JDOM-Dokument-Objekten. Besondere Beachtung verdienen hier die Klassen SAXOutputter, die es einem JDOM-Dokument erlaubt, SAX-Events an eine Anwendung zu schicken, die SAX-Verhalten erwartet, sowie DOMOutputter, die JDOM- in DOM-Strukturen umwandelt. Natürlich ist die Klasse XMLOutputter die bei weitem am meisten benutzte Ausgabe-Klasse für JDOM-Objekte. Wie einige Klassen in dem Package org.jdom.input haben diese drei Hunderte von Methoden. Anstatt zehn Seiten mit diesen eher langweiligen Informationen zu füllen, verweise ich an dieser Stelle wieder auf die Javadoc-Dokumente unter http://www.jdom.org. Dort können Sie sich die aktuellsten Informationen zur Benutzung jeder der JDOM-Ausgabe-Klassen beschaffen.
- 1)
- In dieser und anderen Methoden des Typs setXXX( ) in DOM wird eine DOMException ausgelöst, wenn versucht wird, ein Konstrukt zu ändern, das als nur lesbar deklariert ist.
- 2)
- Unglücklicherweise muß man, um eine Instanz von DOMImplementation zu erhalten, bereits über ein Document-Objekt verfügen und getDOMImplementation( ) aufrufen oder die Klassen des Herstellers direkt laden. Das ist fast ein Henne-Ei-Problem; die Kapitel DOM und DOM für Fortgeschrittene gehen weiter darauf ein.
- 3)
- Beachten Sie, daß die JDOM-API trotz ihrer relativen Stabilität immer noch im Beta-Stadium ist. Es könnten sich kleinere Änderungen nach dem Erscheinen des Buches ergeben. Daher sollten Sie unter http://www.jdom.org einen Blick auf die neuesten JDOM-Klassen werfen.
- 4)
- Um Sie nicht zu Tode zu langweilen, habe ich alle Exceptions außer der zentralen – JDOMException – in diesem Abschnitt ausgelassen. Ich konzentriere mich statt dessen auf die Klassen.
