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().getNodeValue());

	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.