Element

(Auszug aus "XML in a Nutshell" von Elliotte Rusty Harold & W. Scott Means)

Das Interface Element bietet Zugriff auf Struktur und Daten eines XML-Dokuments. Jedes XML-Element wird genau auf einen Element-Knoten abgebildet. Dies gilt auch für das Dokumentelement, das über das Attribut documentElement des Document-Objekts zugänglich ist. Ausgehend von diesem Knoten kann man die komplette Struktur bearbeiten, indem man sich den Knotenbaum entlanghangelt.

Java-Beispiel

// Lies das Dokumentelement des Dokuments.
Element elem = doc.getDocumentElement(  );

Dieses Interface ist eine Erweiterung des Node-Interfaces um den Zugriff auf die XML-Attribute in einem Dokument. Dabei gibt es jeweils zwei Varianten; die eine arbeitet mit Attr-Objektbäumen, die andere mit einfachen DOMStrings.

Attribute

Das Objekt Element besitzt die folgenden Attribute:

schemaTypeInfo: TypeInfo ⁽³⁾

Dieses Property bietet einen Link zu allen Typinformationen, die für dieses Dokument anhand einer DTD oder eines Schemas, die mit dem Elterndokument verknüpft sind, verfügbar sein können. Nur-lesbar.

Java-Bindung
public TypeInfo getSchemaTypeInfo( );

tagName: DOMString

Der Name des XML-Tags aus dem ursprünglichen Dokument.

Java-Bindung
public String getTagName( );

Java-Beispiel

// Gib den Namen des Dokumentelements aus.
Element elem = doc.getDocumentElement(  );
System.out.println("Das ist ein " + elem.getTagName(  ) + " Dokument.");

Methoden

Die folgenden Methoden sind für dieses Objekt definiert:

getAttribute: name

Liefert als Ergebnis den Wert des Attributs mit dem angegebenen Namen. Das Ergebnis ist ein DOMString. Eine ausführliche Erklärung darüber, wie der Wert des Attributs festgestellt wird, finden Sie im Abschnitt »getAttributeNode: name«. Wenn das Attribut nicht explizit gesetzt wurde und die DTD keinen Default-Wert definiert, ist das Ergebnis ein Leer-String.

Java-Bindung
public String getAttribute(String name);

Java-Beispiel

// Prüfe, ob das Attribut name gesetzt ist.
Element elem = doc.getDocumentElement(  );

if (elem.getAttribute("name") == "") {
    System.out.println("warning: " + elem.getTagName(  ) +
                   " element: no name attribute");
}

getAttributeNS: namespaceURI, localName ⁽²⁾

Liefert als Ergebnis einen Attributwert als DOMString. Sie unterstützt aber Namensräume und erhält deshalb den URI sowie den lokalen Teil des qualifizierten Namens.

Argumente

namespaceURI: DOMString

Der URI des Namensraums, in dem das zu lesende Attribut liegt.
localName: DOMString

Der lokale Teil des zu lesenden qualifizierten Attributnamens.

Rückgabewert

Ein Leer-String wird übergeben, wenn das Attribut weder explizit gesetzt war noch in der DTD mit einem Default-Wert spezifiziert wurde.

Java-Bindung
public String getAttributeNS(String namespaceURI, String localName);

getAttributeNode: name

Das Ergebnis dieser Methode ist ein Attr-Objekt, dessen Attribut name den angegebenen Wert hat. Falls kein entsprechendes Objekt existiert, ist das Ergebnis null.

Argument

name: DOMString

Der Name des zu lesenden Attributs.

Java-Bindung
public Attr getAttributeNode(String name);

Java-Beispiel

// Benutze das id-Attribut.
Attr attr;
if ((attr = elem.getAttributeNode("id")) == null) {
    System.out.println("Warnung: Das Element " + elem.getTagName(  ) +
                       ": enthält kein id-Attribut.");
}

getAttributeNodeNS: namespaceURI, localName ⁽²⁾

Das Ergebnis dieser Methode ist ein Attr-Objekt, dessen Attribut den angegebenen Namensraum-URI und den angebenenen lokalen Namen hat. Falls kein entsprechendes Objekt existiert, ist das Ergebnis null.

Argumente

namespaceURI: DOMString

URI des Namensraums, in dem das gesuchte Attribut liegen soll.
localName: DOMString

Lokaler Name des gesuchten Attributs, d.h. der auf den : folgende Teil des vollqualifizierten Attributnamens.

Java-Bindung
public Attr getAttributeNodeNS(String namespaceURI, String localName);

getElementsByTagName: name

Das Ergebnis dieser Methode ist eine NodeList, die alle Element-Knoten enthält, deren Attribut tagName mit dem angegebenen Parameter name übereinstimmt. Die Knoten werden in der gleichen Reihenfolge zurückgegeben, in der sie beim rekursiven Durchlauf durch den Objektbaum gefunden werden, d.h., für jeden Knoten sucht man zuerst seine Kinder und dann seine nachfolgenden Geschwister.

Argument

name: DOMString

Der Name des zu suchenden Tags. Der spezielle Name * steht für beliebige Tags.

Java-Bindung
public NodeList getElementsByTagName(String name);

Java-Beispiel

// Generiere eine Liste aller Adresseinträge im aktuellen Dokument.
Element elem = doc.getDocumentElement(  );
NodeList nlAddrs = elem.getElementsByTagName("adresse");

getElementsByTagNameNS: namespaceURI, localName ⁽²⁾

Entspricht der Methode getElementsByTagName. Das Ergebnis dieser Methode ist eine Liste aller Element-Knoten sowie ihrer Nachkommen, die den in den Parametern namespaceURI und localName angegebenen Kriterien entsprechen. Die Ergebnisliste enthält alle den Kriterien entsprechenden Elemente in der Reihenfolge, in der man die Elemente findet, wenn man rekursiv für jeden Knoten erst dessen Kinder und dann dessen Geschwister durchläuft.

Argumente

namespaceURI: DOMString

Der URI des Namensraums, in dem die gesuchten Elemente liegen sollen. Der spezielle Wert * steht für beliebige Namensräume.
localName: DOMString

Der lokale Name der zu suchenden Elemente. Der spezielle Wert * steht für beliebige lokale Namen.

Java-Bindung
public NodeList getElementsByTagNameNS(String namespaceURI,
String localName);

hasAttribute: name ⁽²⁾

Diese Methode liefert den Wert true, wenn ein Attribut mit dem angegebenen Namen explizit oder als Default-Wert in der DTD definiert war. Das Ergebnis ist false, wenn das nicht der Fall ist.

Argument

name: DOMString

Der Name des gesuchten Attributs.

Java-Bindung
public boolean hasAttribute(String name);

hasAttributeNS: namespaceURI, localName ⁽²⁾

Das Ergebnis ist true, wenn das Element ein XML-Attribut im Namensraum mit dem URI namespaceURI und dem lokalen Namen localName hat, und sonst false. Dabei spielt es keine Rolle, ob das Attribut explizit im XML-Dokument oder implizit in der DTD als Default-Wert angegeben war.

Argumente

namespaceURI: DOMString

Der URI des Namensraums, in dem das gesuchte Attribut liegen soll.
localName: DOMString

Der lokale Name des gesuchten Attributs.

Java-Bindung
public boolean hasAttribute(String namespaceURI, String localName);

normalize

Diese Methode durchläuft den Kindknoten des aktuellen Element-Objekts und verschmilzt aufeinander folgende Text-Knoten zu einem einzigen.

Anmerkung: In DOM Level 2 wurde diese Methode vom Interface Element in das Interface Node übernommen. Da Elemente insbesondere Knoten sind, kann man sie natürlich weiter auf Elemente anwenden, so dass diese Änderung aufwärtskompatibel ist.

Java-Bindung
public void normalize( );

Java-Beispiel

// Alle aufeinander folgenden Textknoten werden verschmolzen.
elem.normalize(  );

removeAttribute: name

^

Löscht das Attribut mit dem angegebenen Namen aus der Attributliste des Elements. Falls für das Attribut, das entfernt werden soll, ein Default-Wert in der DTD angegeben ist, wird von jetzt an der Default-Wert ausgegeben, wenn das Attribut gelesen werden soll.

Argument

name: DOMString

Der Name des zu löschenden Attributs.

Exception

NO_MODIFICATION_ALLOWED_ERR

Wird ausgelöst, wenn das Element nur-lesbar ist.

Java-Bindung
public void removeAttribute(String name) throws DOMException;

Java-Beispiel

// Lösche die eindeutige id.
...
elem.removeAttribute("id");
...

removeAttributeNS: namespaceURI, localName ⁽²⁾

Löscht das Attribut mit dem angegebenen Namensraum-URI und dem lokalen Namen aus der Attributliste des Elements.

Argumente

namespaceURI: DOMString

Der URI des Namensraums, in dem das zu löschende Attribut liegen soll.
localName: DOMString

Lokaler Name des zu löschenden Attributs, d.h. der rechts vom : stehende Teil in einem vollqualifizierten Namen.

Exception

NO_MODIFICATION_ALLOWED_ERR

Wird ausgelöst, wenn das Element nur-lesbar ist.

Java-Bindung
public void removeAttributeNS(String namespaceURI, String localName)
throws DOMException;

removeAttributeNode: oldAttr

Entfernt den angegebenen Attributknoten aus der attributes-Liste des Elements. Falls für das Attribut, das entfernt werden soll, ein Default-Wert in der DTD angegeben ist, wird von jetzt an der Default-Wert zurückgegeben, wenn das Attribut gelesen werden soll.

Argument

oldAttr: Attr

Der zu löschende Attributknoten.

Exceptions

NO_MODIFICATION_ALLOWED_ERR

Wird ausgelöst, wenn das Element nur-lesbar ist.
NOT_FOUND_ERR

Wird ausgelöst, wenn kein mit dem oldAttr-Parameter übereinstimmendes Attribut in der Liste der Attribute des Elements enthalten ist.

Java-Bindung
public Attr removeAttributeNode(Attr oldAttr) throws DOMException;

Java-Beispiel

// Finde und lösche temporäre Attribute.
Attr attr;

if ((attr = elem.getAttributeNode("temp")) != null) {
    // Lösche das Attribut.
    elem.removeAttributeNode(attr);
}

setAttribute: name, value

Diese Methode setzt das Attribut mit dem im Parameter name angegebenen Namen auf den als DOMString im Argument value übergebenen Wert. Der String wird nicht auf Entity-Referenzen überprüft. Es wird einfach ein Text-Kindknoten mit dem angegebenen Wert dem entsprechenden Element der attributes-Liste hinzugefügt. Falls ein gleichnamiger Knoten bereits existiert, wird einfach dessen value-Argument modifiziert.

Argumente

name: DOMString

Der Name des zu setzenden oder zu ändernden Attributs.
value: DOMString

Der neue Attributwert.

Exceptions

INVALID_CHARACTER_ERR

Gibt an, dass der übergebene Name kein gültiger Name für ein XML-Attribut ist.
NO_MODIFICATION_ALLOWED_ERR

Wird ausgelöst, wenn das Element nur-lesbar ist.

Java-Bindung
public void setAttribute(String name, String value) throws DOMException;

Java-Beispiel

// Prüfe, ob ein Attribut name vorhanden ist.
if (elem.getAttribute("name") == "") {
    // Lege einen sinnvollen Default-Wert fest.
    elem.setAttribute("name", elem.getTagName(  ));
}

setAttributeNS: namespaceURI, qualifiedName, value ⁽²⁾

Diese Methode entspricht der Methode setAttribute, berücksichtigt aber Namensräume. Namensraum-URI und qualifizierter Name werden in der attributes-Liste des ausgewählten Elements aktualisiert.

Argumente

namespaceURI: DOMString

Der URI des Namensraums, in dem das gesuchte oder zu erzeugende Attribut liegen soll.
qualifiedName: DOMString

Der voll qualifizierte Name (einschließlich Präfix) des gesuchten oder zu erzeugenden Attributs.
value: DOMString

Der neue Attributwert.

Exceptions

INVALID_CHARACTER_ERR

Gibt an, dass der übergebene Name kein zulässiger Name für ein XML-Attribut ist.
NO_MODIFICATION_ALLOWED_ERR

Wird ausgelöst, wenn das Element nur-lesbar ist.
NAMESPACE_ERR

Wird ausgelöst, wenn die Parameter namespaceURI und qualifiedName gegen die Regeln für Namensräume verstoßen. Enthält der qualifizierte Name ein Präfix, darf der Namensraum-URI nicht null oder ein Leer-String sein. Wenn die reservierten Präfixe xml oder xmlns verwendet werden, muss der Namensraum-URI mit dem angegebenen, entsprechenden System-URI übereinstimmen. Weitere Informationen über Namensräume und Präfixe finden Sie unter Namensräume.

Java-Bindung
public void setAttributeNS(String namespaceURI, String qualifiedName,
String value) throws DOMException;

setAttributeNode: newAttr

Setzt oder ersetzt ein Attribut in der attributes-Liste des Node durch das angegebene Attr-Objekt. Der Name des Attributs wird aus dem Attribut name des neuen Attribut-Objekts gelesen. Wenn ein Attr-Objekt mit dem angegebenen Namen bereits in der attributes-Liste existiert, wird es ersetzt, und diese Methode liefert eine Referenz auf das alte Attr-Objekt. Andernfalls gibt sie null zurück.

Argument

newAttr: Attr

Das neu zu setzende Attr-Objekt.

Exceptions

WRONG_DOCUMENT_ERR

Wird ausgelöst, wenn der newAttr-Knoten bereits zu einem anderen Dokument als dem Elternknoten gehört.
NO_MODIFICATION_ALLOWED_ERR

Wird ausgelöst, wenn der neue Elternknoten nur-lesbar ist.
INUSE_ATTRIBUTE_ERR

Wird ausgelöst, wenn ein anderes Element den neuen Attr-Knoten bereits verwendet. Jedes Element muss sein eigenes Attr-Objekt haben.

Java-Bindung
public Attr setAttributeNode(Attr newAttr) throws DOMException;

Java-Beispiel

// Stelle sicher, dass ein id-Attribut vorhanden ist.
Attr attr;

if ((attr = elem.getAttributeNode("id")) == null) {
    // Generiere eine neue, eindeutige id.
    attr = doc.createAttribute("id");

    elem.setAttributeNode(attr);

    // Setze die Verarbeitung fort.
}

setAttributeNodeNS: newAttr ⁽²⁾

Setzt oder ersetzt die Attribute in der attributes-Liste des Elements. Dabei werden der Namensraum-URI und der lokale Name des angegebenen Attr-Objekts für die Suche verwendet. Diese Methode entspricht der Methode setAttributeNode, berücksichtigt aber die Namensräume der Attribute.Wenn ein Attr-Objekt mit dem angegebenen Namen bereits in der attributes-Liste existiert, wird es ersetzt, und diese Methode liefert eine Referenz auf das alte Attr-Objekt. Andernfalls gibt sie null zurück.

Argument

newAttr: Attr

Das neu zu setzende Attr-Objekt.

Exceptions

WRONG_DOCUMENT_ERR

Wird ausgelöst, wenn der newAttr-Knoten bereits zu einem anderen Dokument als dem Elternknoten gehört.
NO_MODIFICATION_ALLOWED_ERR

Wird ausgelöst, wenn der neue Elternknoten nur-lesbar ist.
INUSE_ATTRIBUTE_ERR

Wird ausgelöst, wenn ein anderes Element den neuen Attr-Knoten bereits verwendet. Jedes Element muss sein eigenes Attr-Objekt haben.

Java-Bindung
public Attr setAttributeNodeNS(Attr newAttr) throws DOMException;

setIdAttribute: name, isId ⁽³⁾

Diese Methode bietet eine Möglichkeit, ein Attribut als ein vom Benutzer festgelegtes ID-Attribut zu markieren. Obwohl Attribute, die mit dieser Methode als ID-Attribute markiert werden, in Suchen auftauchen, die mit der Methode Document.getElementById( ) durchgeführt werden, werden die Typinformationen, die vom Attribut Attr.schemaTypeInfo geliefert werden, dadurch nicht betroffen. Verwenden Sie die Methode setIdAttributeNS( ), um Attribute mit Namensräumen zu markieren.

Argumente

name: DOMString

Der Name des zu modifizierenden Attributs.
isId: boolean

Dieses Argument muss auf true gesetzt werden, wenn dieses Attribut ein ID-Attribut sein soll. Andernfalls muss es auf false gesetzt werden.

Exceptions

NO_MODIFICATION_ALLOWED_ERR

Wird ausgelöst, wenn das Element nur-lesbar ist.
NOT_FOUND_ERR

Wird ausgelöst, wenn in der Attribut-Collection kein Attribut gefunden wird, das dem Parameter name entspricht.

Java-Bindung
public void setIdAttribute(String name, boolean isId)
throws DOMException;

setIdAttributeNS: namespaceURI, localName, isId ⁽³⁾

Diese Methode bietet eine Möglichkeit, ein Attribut, das in einen Namensraum gehört, als ein vom Benutzer festgelegtes ID-Attribut zu markieren. Obwohl Attribute, die mit dieser Methode als ID-Attribut markiert werden, in Suchen auftauchen, die mit der Methode Document.getElementById( ) durchgeführt werden, werden die Typinformationen, die vom Attribut Attr.schemaTypeInfo geliefert werden, dadurch nicht betroffen.

Argumente

namespaceURI: DOMString

Der Namensraum-URI des zu modifizierenden Attributs.
localName: DOMString

Der lokale Teil des Namens des zu modifizierenden Attributs.
isId: boolean

Dieses Argument muss auf true gesetzt werden, wenn dieses Attribut ein ID-Attribut sein soll. Andernfalls muss es auf false gesetzt werden.

Exceptions

NO_MODIFICATION_ALLOWED_ERR

Wird ausgelöst, wenn das Element nur-lesbar ist.
NOT_FOUND_ERR

Wird ausgelöst, wenn in der Attribut-Collection kein Attribut gefunden wird, das dem Parameter name entspricht.

Java-Bindung
public void setIdAttributeNS(String namespaceURI, String localName,
boolean isId) throws DOMException;

setIdAttributeNode: idAttr, isId ⁽³⁾

Diese Methode bietet eine Möglichkeit, ein Attribut als ein vom Benutzer festgelegtes ID-Attribut zu markieren. Obwohl Attribute, die mit dieser Methode als ID-Attribute markiert werden, in Suchen auftauchen, die mit der Methode Document.getElementById( ) durchgeführt werden, werden die Typinformationen, die vom Attribut Attr.schemaTypeInfo geliefert werden, dadurch nicht betroffen. Verwenden Sie die Methode setIdAttributeNS( ), um Attribute mit Namensräumen zu markieren.

Argumente

idAttr: Attr

Das zu modifizierende Attribut.
isId: boolean

Dieses Argument muss auf true gesetzt werden, wenn dieses Attribut ein ID-Attribut sein soll. Andernfalls muss es auf false gesetzt werden.

Exceptions

NO_MODIFICATION_ALLOWED_ERR

Wird ausgelöst, wenn das Element nur-lesbar ist.
NOT_FOUND_ERR

Wird ausgelöst, wenn in der Attribut-Collection kein Attribut gefunden wird, das dem Parameter name entspricht.

Java-Bindung
public void setIdAttributeNode(Attr idAttr, boolean isId)
throws DOMException;

<< zurück

vor >>

Element

Attribute

schemaTypeInfo: TypeInfo (3)

tagName: DOMString

Methoden

getAttribute: name

getAttributeNS: namespaceURI, localName (2)

getAttributeNode: name

getAttributeNodeNS: namespaceURI, localName (2)

getElementsByTagName: name

getElementsByTagNameNS: namespaceURI, localName (2)

hasAttribute: name (2)

hasAttributeNS: namespaceURI, localName (2)

normalize

removeAttribute: name

removeAttributeNS: namespaceURI, localName (2)

removeAttributeNode: oldAttr

setAttribute: name, value

setAttributeNS: namespaceURI, qualifiedName, value (2)

setAttributeNode: newAttr

setAttributeNodeNS: newAttr (2)

setIdAttribute: name, isId (3)

setIdAttributeNS: namespaceURI, localName, isId (3)

setIdAttributeNode: idAttr, isId (3)

schemaTypeInfo: TypeInfo ⁽³⁾

getAttributeNS: namespaceURI, localName ⁽²⁾

getAttributeNodeNS: namespaceURI, localName ⁽²⁾

getElementsByTagNameNS: namespaceURI, localName ⁽²⁾

hasAttribute: name ⁽²⁾

hasAttributeNS: namespaceURI, localName ⁽²⁾

removeAttributeNS: namespaceURI, localName ⁽²⁾

setAttributeNS: namespaceURI, qualifiedName, value ⁽²⁾

setAttributeNodeNS: newAttr ⁽²⁾

setIdAttribute: name, isId ⁽³⁾

setIdAttributeNS: namespaceURI, localName, isId ⁽³⁾

setIdAttributeNode: idAttr, isId ⁽³⁾