DOM

	Mitemetes keeltes leiduvad vahendid XMLi andmepuu loomiseks, lugemiseks ja 
muutmiseks. Võrrelduna lihtsalt tekstikäskude abil töötlemisele saab siin 
programmeerija enam keskenduda andmete paiknemise loogikale. Samuti hoiab puu 
elementide loomine ja nende poole pöördumine ära teksti loomisel tekkida võivad 
trükivead. Abikäskudega õnnestub küsida sobivaid elemente. Kasutatavad avaldised 
pole küll veel nõnda paindlikud kui XSLi juurde kuuluva XPathi omad, kuid 
märgatavat kasu on neistki.
	Järgnevalt DOM-i tutvustus väikese Java näite abil. Keskseks klassiks on 
Document. Selle eksemplari kasutatakse nii uute elementide loomiseks kui 
elemendihierarhia algusena. Dokument võidakse luua kas tühjana tühjale kohale 

    Document 
d=DocumentBuilderFactory.newInstance().newDocumentBuilder().newDocument();

või siis lugeda sisse olemasolevast failist. 
    Document 
d=DocumentBuilderFactory.newInstance().newDocumentBuilder().parse("linnad.xml");

	Nagu näha, ei kasutata dokumendi loomisel mitte klassi konstruktorit, vaid 
selle asemel koostatakse vabriku (DocumentBuilderFactory) eksemplar, mille abil 
siis dokument kokku pannakse. Selline pikk lähenemine võimaldab mitmel pool 
seada parameetreid, samuti kasutada ilma koodi muutmata mitmete tootjate 
abitükke.
	Et dokumenti saaks elemente lisada, peab selles olema vähemasti 
juurelement. Failist lugedes tuleb see kaasa, tühja dokumendi loomisel tuleb aga 
ka juur luua ja määrata. Ning nagu XMLi spetsifikatsioonis öeldakse, peab igal 
failil või dokumendil olema üks ja ainult üks juur. Nii nagu hiljemgi elementide 
puhul, nii ka siin tuleb eraldi käskudena element luua ning siis sobivasse kohta 
lisada. 

    Element juur=d.createElement("linnad");
    d.appendChild(juur);

	Edasi siis dokumendile külge ka sisulised andmed, mis praegu lihtsuse 
mõttes võetakse massiivist.

    String[] linnanimed={"Tallinn", "Tartu", "Narva"};

	Tekstiliste andmete XML-i puusse kinnitamiseks tuleb kõigepealt luua 
teksti puusse kinnitatavaks tervikuks ühendav TextNode, mis siis omakorda nimega 
elemendi sisse paigutada. Et siin näites on juurelemendiks "linnad", selle all 
elemendid nimega "linn" ning edasi vastava elemendi sees omakorda linnanimi, 
näiteks "Tartu".


    for(int i=0; i<linnanimed.length; i++){
      Element e=d.createElement("linn");
      e.appendChild(d.createTextNode(linnanimed[i]));
      juur.appendChild(e);
    }

	Soovides valmisehitatud puud talletada, tuleb puu viia voo kujule. Seda 
aitab klassi Transformer eksemplar. Piisab vaid käsust transform, ning andmepuu 
muudetaksegi vooks. Kas voog suunatakse faili, ekraanile või võrku, see on juba 
programmeerija mure ning selleks piisab vastava voo ots transformeerija 
väljundisse pakkuda. Siin nagu näha viib System.out tulemuse ekraanile.

    Transformer t=TransformerFactory.newInstance().newTransformer();
    t.transform(new DOMSource(d), new StreamResult(System.out));

Järgnevalt programmi kood.


import javax.xml.parsers.*;
import javax.xml.transform.*;
import javax.xml.transform.dom.*;
import javax.xml.transform.stream.*;

import org.w3c.dom.*;

public class UusDokument{
  public static void main(String argumendid[]) throws Exception{
    String[] linnanimed={"Tallinn", "Tartu", "Narva"};
    Document 
d=DocumentBuilderFactory.newInstance().newDocumentBuilder().newDocument();
    Element juur=d.createElement("linnad");
    d.appendChild(juur);
    for(int i=0; i<linnanimed.length; i++){
      Element e=d.createElement("linn");
      e.appendChild(d.createTextNode(linnanimed[i]));
      juur.appendChild(e);
    }
    Transformer t=TransformerFactory.newInstance().newTransformer();
    t.transform(new DOMSource(d), new StreamResult(System.out));
  }
}

Ning väljund.

E:\kasutaja\jaagup\xml>java UusDokument
<?xml version="1.0" encoding="UTF-8"?>
<linnad><linn>Tallinn</linn><linn>Tartu</linn><linn>Narva</linn></linnad>

	Lihtsalt tekstiekraanile kirjutatuna võib linnade rida olla halvasti 
loetav. Kui aga sama XMLi lõik salvestada faili ja avada seiluriga, siis 
õnnestub hulga selgemini lugeda.


Ülesandeid

* Väljasta DOMi abil XML-loeteluna kolme inimese eesnimed.
* Küsi nimed kasutajalt ja väljasta DOMi abil XML-loeteluna.
* Võimalda kasutajal valida, kas luuakse uus fail või lisatakse nimesid 
olemasolevasse faili juurde.
* Salvesta DOMi abil faili ühe inimese eesnimi, perekonnanimi ja sünniaasta.
* Küsi kasutajalt mitme inimese eesnimi, perekonnanimi ja sünniaasta ning 
salvesta nad DOMi abil faili.
* Koosta rakendusele graafiline liides. Võimalda inimeste andmeid lisada ning 
olemasolevaid muuta ja kustutada.


 Joonistusvahend
	Järgnevalt veidi pikem näide, kus pildi andmete salvestamisel kasutatakse 
XMLi andmepuud. Puu loomise käsud samad kui lühemagi näite puhul. Juures 
käsklused puust andmete lugemiseks ning joonistuspool. Tähtsamad nupud avamise 
ja salvestamise jaoks. Iga hiire vedamisega tekib joon, joone juures jäetakse 
meelde koordinaadid, mida hiir läbinud. Nii nagu eelmises näites oli 
juurelemendiks "linnad" ning selle all hulk elemente "linn", nii siin on 
juurelemendiks "koordinaadid" ning juure küljes elemendid "joon". Iga joone sees 
omakorda hulk elemente nimega "punkt", milles koordinaate tähistavad "x" ja "y". 
	Algus nagu eelmiselgi korral. Nii alustuse kui kustutuse puhul luuakse uus 
tühi dokument ning sinna sisse juurelement.

d=DocumentBuilderFactory.newInstance().newDocumentBuilder().newDocument();
juur=d.createElement("koordinaadid");
d.appendChild(juur);

	Iga hiirevajutuse puhul luuakse uus element nimega "joon" ning jäetakse 
vastava nimega muutujasse meelde. Nii vajutuse kui lohistuse puhul lisatakse 
joone külge punkt. 

  public void mousePressed(MouseEvent e) {
    joon=d.createElement("joon");
    juur.appendChild(joon);
    lisaPunkt(e.getX(), e.getY());    
  }
  
  public void mouseDragged(MouseEvent e){
     lisaPunkt(e.getX(), e.getY());
  }

	Selle suhteliselt tervikliku tegevuse tarbeks loodi omaette alamprogramm. 
Isendi piires kättesaadava muutuja joon külge lisatakse element punkt, mille 
juurde omakorda x ja y oma koordinaatide tekstilise väärtusega.

  void lisaPunkt(int x, int y){
    Element punkt=d.createElement("punkt");
    Element px=d.createElement("x");
    px.appendChild(d.createTextNode(x+""));
    punkt.appendChild(px);
    Element py=d.createElement("y");
    py.appendChild(d.createTextNode(y+""));
    punkt.appendChild(py);
    joon.appendChild(punkt);  
  }

	Joonistamine näeb välja mõnevõrra keerukam. Graafikakomponentide puhul 
soovitatakse kogu joonistus ette võtta paint-meetodis ning meetodit sobival ajal 
välja kutsuda. Ka pole lihtsuse mõttes siin näites puhvrit vahele loodud, nii et 
iga ülejoonistuskäsu peale koostatakse kogu pilt uuesti. 

  public void paint(Graphics g){

	Alustuseks küsitakse massiivina välja kõik dokumendis paiknevad jooned. Et 
elementide paiknemine on teada, siis piisab küsimisest asukoha ning mitte nime 
järgi. Dokumendi d käsk getFirstChild() väljastab juurelemendi "koordinaadid", 
sealt käsk getChildNodes() väljastab joonte kogumi. 

    NodeList jooned=d.getFirstChild().getChildNodes();

	Edasises tsüklis käiakse jooned ükshaaval läbi ning palutakse nad kõik 
ekraanile joonistada.

    for(int i=0; i<jooned.getLength(); i++){
	Iga joon määratakse punktikogumiga, mis jooneelemendist samuti välja 
küsitakse nagu jooned juurelemendi küljest. Ning näiliselt vabakäejoon koosneb 
üksikute punktide vahele tõmmatud sirglõikudest. 

      NodeList punktid=jooned.item(i).getChildNodes();
      for(int j=1; j<punktid.getLength(); j++){
	Sirglõigu tõmbamiseks läheb vaja kahte punkti. Nõnda käiaksegi tsükkel 
läbi ühe korra vähem kui punkte kokku. Ning igal korral küsitakse punkt nii 
loenduri juurest kui ka ühe võrra eelnevast kohast.

        Node p1=punktid.item(j-1);
        Node p2=punktid.item(j);

	Edasiseks joonistamiseks on vaja kätte saada punktide sees paiknevate 
koordinaatide arvulised väärtused. Näidatakse mitut võimalust selle välja 
küsimiseks. Klassi Element eksemplaril leidub käsklus getElementsByTagName, mis 
väljastab kogumi soovitud nimega elementidega. Et iga punkti juures leidub 
täpselt üks x, siis item(0) peaks just selle väljastama. Koordinaadi väärtuse 
saamiseks tuleb aga elemendi seest küsida "nähtamatu" TextNode ning selle seest 
omakorda sõnena väärtus ehk getNodeValue(). Integer.parseInt annab arvulise 
väärtuse.

        int x1=Integer.parseInt(((Element)p1).getElementsByTagName("x").item(0).
                                                        getFirstChild().getNodeV
alue());

	Väärtuse võib välja küsida ka vaid asukoha järgi. Lahti seletatult: 
p1.getFirstChild annab punkti esimese alamelemendi ehk x-i. Käsk getNextSibling 
küsib järgmise sama taseme elemendi ehk y-i. Sealt juba TextNode ning selle 
väärtus.

        int y1=Integer.parseInt(p1.getFirstChild().getNextSibling().
getFirstChild().getNodeValue());
        int 
x2=Integer.parseInt(p2.getFirstChild().getFirstChild().getNodeValue());
        int y2=Integer.parseInt(p2.getFirstChild().getNextSibling().
                                               getFirstChild().getNodeValue());

	Kui kõik neli koordinaati nõnda käes, võib tõmmata joone.

        g.drawLine(x1, y1, x2, y2);
      }
    }
  }
	
	Salvestamise juures mõistavad valmiskäsud suurema osa tööst ära teha. 
Transformeerijale tuleb vaid öelda, kust andmed võtta ja kuhu panna. Praegusel 
juhul siis mälus paiknevast DOMi puust faili suunduvasse väljundvoogu. 
Süntaktiliselt oleks saanud failivoo loomise ka otse transform-käsu parameetri 
sisse paigutada, kuid sellisel juhul pole kindel, et fail ka suletakse ning kõik 
baidid faili jõuavad. Eraldi close-käskluse puhul seda muret pole.

    if(e.getSource()==salvesta){
      try{
          Transformer t=TransformerFactory.newInstance().
                      newTransformer();
          FileOutputStream valja=
                     new FileOutputStream(failinimi);
          t.transform(new DOMSource(d), 
                     new StreamResult(valja));
          valja.close();
      } catch(Exception viga){ viga.printStackTrace();   }
    } 

Ekraanile testiks trükkimine veelgi lihtsam. Kui soovida XML-i  koodi 
väljastada, siis piisab Node/sõlme väljatrükist. Meetod toString hoolitseb juba 
ise vajaliku väljundi kuju eest.
    if(e.getSource()==tryki){
       System.out.println(d.getFirstChild());}

 


Ning rakenduse kood tervikuna.

import javax.xml.parsers.*;
import javax.xml.transform.*;
import javax.xml.transform.dom.*;
import javax.xml.transform.stream.*;
import java.io.*;
import java.awt.*;
import java.awt.event.*;

import org.w3c.dom.*;

public class XMLJoonis extends Frame implements ActionListener, 
   MouseListener, MouseMotionListener{
  
  Button nupp = new Button("Lae");
  Button salvesta=new Button("Salvesta");
  Button tryki=new Button("Trüki");
  Button kustuta=new Button("Kustuta");
  String failinimi="joonistusandmed.xml";
  Document d;
  Node juur, joon;
 
  public XMLJoonis(){
      setLayout(new FlowLayout());
      add(nupp);    add(salvesta);
      add(tryki);   add(kustuta);
      nupp.addActionListener(this);
      salvesta.addActionListener(this);
      tryki.addActionListener(this);
      kustuta.addActionListener(this);
      addMouseListener(this);
      addMouseMotionListener(this);
      addWindowListener(new WindowAdapter(){
        public void windowClosing(WindowEvent evt){          
         System.exit(0);
        }
      });
      alusta();
      setSize(400,300);
      setVisible(true);  
  }
  
  public void actionPerformed(ActionEvent e){
    if(e.getSource()==nupp){
     try{
         d=DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(failinimi);
         juur=(Element)d.getFirstChild();
         repaint();
     } catch(Exception viga){System.out.println("Probleem lugemisel: "+viga);   }
    }
    if(e.getSource()==salvesta){
      try{
             Transformer t=TransformerFactory.newInstance().newTransformer();
             FileOutputStream valja=new FileOutputStream(failinimi);
             t.transform(new DOMSource(d), new StreamResult(valja));
             valja.close();
      } catch(Exception viga){ viga.printStackTrace();   }
    } 
    if(e.getSource()==tryki){System.out.println(d.getFirstChild());}
    if(e.getSource()==kustuta){alusta();}
  }
  
  
  public void paint(Graphics g){
    NodeList jooned=d.getFirstChild().getChildNodes();
    for(int i=0; i<jooned.getLength(); i++){
      NodeList punktid=jooned.item(i).getChildNodes();
      for(int j=1; j<punktid.getLength(); j++){
        Node p1=punktid.item(j-1);
        Node p2=punktid.item(j);
        int x1=Integer.parseInt(
              ((Element)p1).getElementsByTagName("x").item(0).
                 getFirstChild().getNodeValue());
        int y1=Integer.parseInt(
               p1.getFirstChild().getNextSibling().getFirstChild().
                     getNodeValue());
        int x2=Integer.parseInt(
               p2.getFirstChild().getFirstChild().getNodeValue());
        int y2=Integer.parseInt(
               p2.getFirstChild().getNextSibling().getFirstChild().
                     getNodeValue());
        g.drawLine(x1, y1, x2, y2);
      }
    }
  } 
  
  public void mousePressed(MouseEvent e) {
    joon=d.createElement("joon");
    juur.appendChild(joon);
    lisaPunkt(e.getX(), e.getY());    
  }
  
  public void mouseDragged(MouseEvent e){
     lisaPunkt(e.getX(), e.getY());
  }

  void lisaPunkt(int x, int y){
    Element punkt=d.createElement("punkt");
    Element px=d.createElement("x");
    px.appendChild(d.createTextNode(x+""));
    punkt.appendChild(px);
    Element py=d.createElement("y");
    py.appendChild(d.createTextNode(y+""));
    punkt.appendChild(py);
    joon.appendChild(punkt);  
  }

  
  public void alusta(){
      try{
         d=DocumentBuilderFactory.newInstance().newDocumentBuilder().newDocument();
         juur=d.createElement("koordinaadid");
         d.appendChild(juur);
         repaint();
      } catch(Exception viga){System.out.println("Viga dokumendi loomisel: "+viga);}           
  }

  public void mouseClicked(MouseEvent e) { }
  public void mouseReleased(MouseEvent e) { repaint(); }
  public void mouseEntered(MouseEvent e) {}
  public void mouseExited(MouseEvent e) {}
  public void mouseMoved(MouseEvent e){}
  
  
  public static void main(String argumendid[]) throws Exception{
    new XMLJoonis();
  }
}


Ülesandeid

* Tutvu joonistusrakendusega. Muuda tekstiredaktori abil koordinaatide väärtusi. 
Veendu tulemuse muutuses.
* Võimalda ühte joont märgistada. Märgistatuks osutub esimene joontest, mille 
kasvõi üks salvestatud punkt on hiirevajutusele lähemal kui kolm ekraanipunkti. 
Märgistatud joon tähistatakse punaselt. 
* Märgistatud joont saab kustutada.
* Märgistatud joont saab soovitud suunas nihutada.
* Lisa kujunditena valikusse ning salvestusfaili ristkülik ja ring. 
* Võimalda ka neid kustutada ning nihutada.