XML-Technologien / XML / XML in a Nutshell / DOM-Referenz / Objekt-Referenz / CharacterData

CharacterData

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

Das Interface CharacterData ist eine Erweiterung des Interfaces Node um Methoden zur Manipulation von Textdaten. Alle Objekttypen von DOM, die Textdaten enthalten, sind direkt oder indirekt von diesem Interface abgeleitet.

Die Möglichkeiten, die dieses Interface zur Bearbeitung von Text bietet, entsprechen dem, was die meisten modernen Programmiersprachen bieten. Wie bei C/C++ oder Java wird stets die 0 als Basis für alle Routinen angenommen, die CharacterData verarbeiten.

Java-Beispiel

// Erzeuge einen neuen Textknoten
Text ndText = doc.createTextNode("Im Wein liegt Wahrheit.");
// Und wandle ihn durch einen Cast in ein CharacterData-Objekt um
CharacterData ndCD = (CharacterData)ndText;

Attribute

CharacterData-Objekte besitzen die folgenden Attribute:

data: DOMString

Dieses Attribut liefert die »rohen« Textdaten des CharacterData-Knotens. Obwohl eine konkrete DOM-Implementierung die Größe dieser Texte, die im CharacterData-Knoten gespeichert werden, limitiert, könnte es sein, dass Sie die Methode substringData benutzen müssen, um die Textdaten in kleine Teile zu zerlegen, die keine Implementierungsprobleme bereiten.

Exceptions

NO_MODIFICATION_ALLOWED_ERR

Wird ausgelöst, wenn das data-Attribut für diesen DOM-Objekttyp nur-lesbar ist und trotzdem modifiziert werden soll.
DOMSTRING_SIZE_ERR

Wird ausgelöst, wenn der zu lesende Wert zu lang ist, um in einem DOMString-Typ in dieser Implementierung enthalten zu sein.

Java-Bindungen
public String getData( ) throws DOMException;
public void setData(String data) throws DOMException;

Java-Beispiel

// Zitiere den Inhalt des CharacterData-Knotens
CharacterData ndCD =
doc.createTextNode("Unquoted text.");
...
ndCD.setData('\"' + ndCD.getData(  ) + '\"');

length: unsigned long

Die Länge des DOMString, der im data-Attribut gespeichert ist. Für alle Methoden dieses Interfaces, die einen index als Parameter erwarten, gilt 0 <= index < length für gültige Werte. 0 ist ein gültiger Wert, da leere CharacterData-Knoten erlaubt sind. Nur-lesbar.

Java-Bindung
public long getLength( );

Java-Beispiel

// Inhalt des CharacterData-Knotens ausgeben
CharacterData ndCD = (CharacterData)doc.createTextNode("Dieser String besteht aus
 32 Zeichen.");

System.out.println("Der String \'" + ndCD.getData(  ) + "\' enthält "
            + Long.toString(ndCD.getLength(  )) + " Zeichen.");

Methoden

Die folgenden Methoden sind für CharacterData-Objekte definiert:

appendData: arg

Der im Parameter arg übergebene String wird an den Wert des data-Attributs angehängt.

Argument

arg: DOMString

Der anzuhängende String.

Exception

NO_MODIFICATION_ALLOWED_ERR

Wird ausgelöst, wenn der Knoten nur-lesbar ist.

Java-Bindung
public void appendData(String arg) throws DOMException;

Java-Beispiel

// Ein String wird erweitert.
// Erzeuge einen Textknoten und behandle ihn als CharacterData-Objekt.

CharacterData ndCD = (CharacterData)doc.createTextNode("Die Wahrheit ist ");
// Werfen wir eine Münze

ndCD.appendData((Math.random(  ) &lt; 0.5) ? "da draußen." : "hier drin.");
System.out.println(ndCD.getData(  ));

deleteData: offset, count

Entfernt einen Abschnitt aus dem DOMString des data-Attributs. Diese Methode entfernt count-Zeichen, beginnend beim Zeichen mit dem Index offset.

Argumente

offset: unsigned long

Die Position im data-Attribut, ab der count-Zeichen entfernt werden.
count: unsigned long

Die Anzahl zu entfernender Zeichen; falls offset + count größer oder gleich dem Wert des length-Attributs ist, wird einfach der Rest des Strings ab der Position offset entfernt.

Exceptions

INDEX_SIZE_ERR

Wird ausgelöst, wenn der offset-Parameter zu hoch ist, d.h. größer oder gleich der Länge des DOMString.
NO_MODIFICATION_ALLOWED_ERR

Wird ausgelöst, wenn der Knoten nur-lesbar ist.

Java-Bindung
public void deleteData(long offset, long count)
throws DOMException;

Java-Beispiel

// Erzeuge ein neues Textobjekt, und behandle es als CharacterData-Objekt.
CharacterData ndCD = doc.createTextNode("Die Wahrheit ist nicht da draußen.");

// Meinungsänderung ...
ndCD.deleteData(15, 6);

System.out.println(ndCD.getData(  ));

insertData: offset, arg

Diese Methode nimmt einen String, splittet den aktuellen Inhalt des data-Attributs an der Position offset und fügt den String aus dem arg-Argument zwischen die beiden String-Teile ein.

Argumente

offset: unsigned long

Die Position, an der der String in das data-Attribut einzufügen ist. 0 steht für den Anfang.
arg: DOMString

Der einzufügende String.

Exceptions

INDEX_SIZE_ERR

Wird ausgelöst, falls der Parameter offset kein erlaubter, an der Position 0 eingefügter data DOMString ist.
NO_MODIFICATION_ALLOWED_ERR

Wird ausgelöst, wenn der Knoten nur-lesbar ist.

Java-Bindung
public void insertData(long offset, String arg) throws
DOMException;

Java-Beispiel

// Daten werden in einen String eingeführt.
boolean fZynisch = true;

// Ein neues Text-Objekt wird in ein CharacterData-Objekt umgewandelt.
CharacterData ndCD = doc.createTextNode("Die Wahrheit ist
                      da draußen.");

...

// Ist das zynisch?
if (fZynisch) {
    ndCD.insertData(15, " nicht");
}

System.out.println(ndCD.getData(  ));

replaceData: offset, count, arg

Ersetzt einen Teil-String im data-Attribut durch das Argument arg unter Berücksichtigung der angegebenen offset- und count-Parameter.

Argumente

offset: long

Die Anfangsposition des zu ersetzenden Strings.
count: long

Die Anzahl der zu ersetzenden Zeichen. Falls offset + count größer oder gleich dem Wert des length-Attributs sind, wird einfach der Substring ab der Position des offset ersetzt.
arg: DOMString

Der String, der als Ersatz einzufügen ist.

Die Operation replaceData entspricht dem folgenden Code-Fragment:

cdNode.deleteData(offset, count);
cdNode.insertData(offset, arg);

Exceptions

INDEX_SIZE_ERR

Der Parameter offset ist ungültig, d.h., es ist kein erlaubter, an der Position 0 eingefügter data DOMString.
NO_MODIFICATION_ALLOWED_ERR

Wird ausgelöst, wenn der Knoten nur-lesbar ist.

Java-Bindung
public void replaceData(long offset, long count,
String arg) throws DOMException;

Java-Beispiel

//Ein neues Text-Objekt wird in ein CharacterData-Objekt umgewandelt.
CharacterData ndCD = doc.createTextNode("Die Wahrheit ist
                     nicht da draußen.");

// Ersetzen wir die Wahrheit
String strFind = "Wahrheit";
String strReplace = "Katze";

ndCD.replaceData(ndCD.getData().indexOf(strFind), strFind.length(  ),
                 strReplace);

System.out.println(ndCD.getData(  ));

substringData: offset, count

Liefert als Ergebnis einen DOMString, der eine Teilmenge des Strings aus dem data-Attribut ist. Die Argumente offset und count definieren diesen Substring. Das Argument offset muss zwar eine gültige Position innerhalb der Knotendaten angeben, trotzdem könnte sich aber das Ende des Substrings über das Ende des data-Attributs hinaus erstrecken. Wenn das geschieht, gibt die Methodes alles aus, was sich zwischen der offset-Position und dem Ende des data-Strings befindet.

Argumente

offset: unsigned long

Die Position, an der der zu lesende Substring beginnt. Diese Position wird durch 0 gekennzeichnet. Ein gültiger offset muss daher >= 0 und < das length-Attribut des Knotens sein.
count: unsigned long

Zeichenzahl des zu lesenden Strings.

Exceptions

INDEX_SIZE_ERR

Wird ausgelöst, wenn der angegebene Parameter offset kleiner als 0 oder größer oder gleich dem Wert des length-Attributs ist oder wenn der count-Parameter negativ ist.
DOMSTRING_SIZE_ERR

Wird ausgelöst, wenn der Ergebnis-String zu groß ist; je nach System und der konkreten Implementierung ist die Größe eines DOMString beschränkt.

Java-Bindung
public String substringData(unsigned long offset, unsigned long count)
throws DOMException;

Java-Beispiel

// Baue eine Referenz auf das CharacterData-Interface auf.
CharacterData ndCD = doc.createTextNode("Die Wahrheit ist da draußen.");

// Uns interessiert nur die "Wahrheit".
String strWahrheit = ndCD.substringData(4, 8);

System.out.println("Der Substring ist '" + strWahrheit + '\'');

<< zurück

vor >>

Tipp der data2type-Redaktion:
Zum Thema XML bieten wir auch folgende Schulungen zur Vertiefung und professionellen Fortbildung an:

Copyright © 2005 O'Reilly Verlag GmbH & Co. KG
Für Ihren privaten Gebrauch dürfen Sie die Online-Version ausdrucken.
Ansonsten unterliegt dieses Kapitel aus dem Buch "XML in a Nutshell" denselben Bestimmungen, wie die gebundene Ausgabe: Das Werk einschließlich aller seiner Teile ist urheberrechtlich geschützt. Alle Rechte vorbehalten einschließlich der Vervielfältigung, Übersetzung, Mikroverfilmung sowie Einspeicherung und Verarbeitung in elektronischen Systemen.

O’Reilly Verlag GmbH & Co. KG, Balthasarstraße 81, 50670 Köln, kommentar(at)oreilly.de