diff --git a/Doc/Makefile b/Doc/Makefile
index d837a1a281ba2d458cc3dcf38585c8589583041c..5788834df775cc8d6f137452fc8c3223bb3908a9 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -1,4 +1,4 @@
-SCRIPTBASENAME=course
+SCRIPTBASENAME=sda1
PLUGINID=de.hdm_stuttgart.mi.sda1
WWWBASE=www.mi.hdm-stuttgart.de:/home/infocenter2/doc
M2HOME=/ma/goik/.m2/repository
diff --git a/Doc/Ref/Fig/Makefile b/Doc/Ref/Fig/Makefile
index 400fb0c6bd839fd592403459479891a2c868d5e1..c2df99bb7c7063fc6baca0f2248f9c0ecfaffbea 100644
--- a/Doc/Ref/Fig/Makefile
+++ b/Doc/Ref/Fig/Makefile
@@ -3,17 +3,17 @@
#
-FIGFILES=attribInElement attributes billingData billing billingMapJoined \
-billingSql booknavigate classUser clientserv contentmixed cpp \
+FIGFILES=attribInElement attributes \
+booknavigate clientserv contentmixed cpp \
crossmedia dictionaryStack domtree entityresolve externalize \
-figureInherit filtering headfoot heartland impropernest invoicedata \
+filtering headfoot heartland impropernest invoicedata \
invoicedataimplement jdbcarch jdbcFourTier \
jdbcObjectRelation jdbcread jdbcReadWrite jdbcSniffing jdbcThreeTier \
-jdbcurl mapUser mapUserIntegrity mavenIntro memofour memorelativexpath \
+jdbcurl memofour memorelativexpath \
memotree memoxpath overlay pagerefhyperStack pagerefStack pageStack \
-persistence persistentStates persistHandlerStates persistProvider preceding propernest \
+persistence persistentStates persistHandlerStates preceding propernest \
regions saxxmlrdbms sqlinject sqlTransport sqlTransportPrepare sqrtree \
-sqrtrender transitiveDep updateinfo wellformedandvalid xhtmlexample \
+sqrtrender updateinfo wellformedandvalid xhtmlexample \
xhtml xml2fo2pdf xml2html xmlattribandjava xmlbase xpath xslconvert xsl_id
# For reasons ... invoicewellformed
diff --git a/Doc/course.xml b/Doc/course.xml
deleted file mode 100644
index a70e7a4b5ef814c0dbc747755f102232becf337f..0000000000000000000000000000000000000000
--- a/Doc/course.xml
+++ /dev/null
@@ -1,13987 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<book version="5.0" xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xmlns:xi="http://www.w3.org/2001/XInclude"
- xmlns:svg="http://www.w3.org/2000/svg"
- xmlns:m="http://www.w3.org/1998/Math/MathML"
- xmlns:html="http://www.w3.org/1999/xhtml"
- xmlns:db="http://docbook.org/ns/docbook">
- <info>
- <title>Lecture notes of Martin Goik</title>
-
- <author>
- <personname><firstname>Martin</firstname>
- <surname>Goik</surname></personname>
-
- <affiliation>
- <orgname>http://medieninformatik.hdm-stuttgart.de</orgname>
- </affiliation>
- </author>
-
- <legalnotice>
- <para>Source code available at <uri
- xlink:href="https://version.mi.hdm-stuttgart.de/git/GoikLectures">https://version.mi.hdm-stuttgart.de/git/GoikLectures</uri></para>
- </legalnotice>
- </info>
-
- <part xml:id="sda1">
- <title>Structured Data and Applications 1</title>
-
- <chapter xml:id="prerequisites">
- <title>Prerequisites</title>
-
- <section xml:id="resources">
- <title>Lecture resources</title>
-
- <glosslist>
- <glossentry>
- <glossterm>Recommended book</glossterm>
-
- <glossdef>
- <para><link linkend="fawcett2012">Beginning XML</link></para>
-
- <caution>
- <para>Some figures including videos are left blank.</para>
- </caution>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>Lecture notes as PDF</glossterm>
-
- <glossdef>
- <para><uri
- xlink:href="http://www.mi.hdm-stuttgart.de/freedocs/topic/de.hdm_stuttgart.mi.sda1/printversion.pdf">http://www.mi.hdm-stuttgart.de/freedocs/topic/de.hdm_stuttgart.mi.sda1/printversion.pdf</uri></para>
-
- <caution>
- <para>Some figures including videos are left blank.</para>
- </caution>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>Live lecture additions</glossterm>
-
- <glossdef>
- <para><link
- xlink:href="https://cloud.mi.hdm-stuttgart.de/owncloud/public.php?service=files&t=dae5c53f0a05d6661209527cee45d323">https://cloud.mi.hdm-stuttgart.de/owncloud/public.php?service=files&t=dae5c53f0a05d6661209527cee45d323</link></para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>List of exercises</glossterm>
-
- <glossdef>
- <para>The lecture notes contain exercises to be solved by you! A
- complete list is available at <uri
- xlink:href="http://www.mi.hdm-stuttgart.de/freedocs/topic/de.hdm_stuttgart.mi.sda1/apb.html">http://www.mi.hdm-stuttgart.de/freedocs/topic/de.hdm_stuttgart.mi.sda1/apb.html</uri>.
- You may also use the corresponding PDF version within <filename
- xlink:href="http://www.mi.hdm-stuttgart.de/freedocs/topic/de.hdm_stuttgart.mi.sda1/printversion.pdf">printversion.pdf</filename>
- to keep track of your personal advance by filling in your
- completion status.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm><link
- linkend="gloss_Javadoc"><trademark>Javadoc</trademark></link>
- references and source code</glossterm>
-
- <glossdef>
- <para>The lecture notes contain a lot of <link
- linkend="gloss_Javadoc"><trademark>Javadoc</trademark></link>
- references. Most classes appearing within these lecture notes
- have <link
- linkend="gloss_Javadoc"><trademark>Javadoc</trademark></link>
- generated links to the source code as well. For example when
- clicking on the class name in
- <classname>sda.jdbc.intro.v1.SimpleInsert</classname> you will
- see the complete implementation.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>Links to animated figures</glossterm>
-
- <glossdef>
- <para>The lecture notes' online version contains links to <uri
- xlink:href="http://www.mi.hdm-stuttgart.de/freedocs/topic/de.hdm_stuttgart.mi.sda1/jdbcWrite.html">PDF
- images</uri>. Clicking on <quote>Animated PDF Version</quote>
- takes you to a referenced PDF which in full screen mode of
- Acrobat Reader or <trademark>google-chrome</trademark> provides
- a slide like animation.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm><trademark>Virtualbox</trademark> image</glossterm>
-
- <glossdef>
- <para>A <productname
- xlink:href="https://www.virtualbox.org">Virtualbox</productname>
- image is available at <uri
- xlink:href="ftp://mirror.mi.hdm-stuttgart.de/ubuntu/VirtualBox/lubuntu.rar">ftp://mirror.mi.hdm-stuttgart.de/ubuntu/VirtualBox/lubuntu.rar</uri>
- <link
- xlink:href="ftp://mirror.mi.hdm-stuttgart.de/ubuntu/VirtualBox/lubuntu.vdi">ftp://mirror.mi.hdm-stuttgart.de/ubuntu/VirtualBox/lubuntu.vdi</link>.</para>
-
- <caution>
- <para>Access from networks being external to
- <uri>hdm-stuttgart.de</uri> requires <acronym>VPN</acronym>
- access.</para>
- </caution>
-
- <para>It contains (hopefully) all related tools from the <link
- xlink:href="http://www.mi.hdm-stuttgart.de">CSM</link>
- department's lecture room Linux installation:</para>
-
- <itemizedlist>
- <listitem>
- <para>Eclipse J2EE version with <productname
- xlink:href="http://www.eclipse.org/datatools">Database
- developer tools</productname>, <productname
- xlink:href="http://git-scm.com">git</productname>,
- <trademark
- xlink:href="http://oxygenxml.com">Oxygenxml</trademark>,
- <productname
- xlink:href="http://testng.org/doc/eclipse.html">TestNG</productname>
- and <productname
- xlink:href="http://subversion.apache.org/">svn</productname>
- plugins installed.</para>
- </listitem>
-
- <listitem>
- <para>A running <productname
- xlink:href="http://www.mysql.com/">Mysql</productname>
- server preconfigured with user
- <quote><code>hdmuser</code></quote>, password
- <quote><code>XYZ</code></quote> (<emphasis
- role="bold">capital letters!</emphasis>) and database
- <quote><code>hdm</code></quote>.</para>
- </listitem>
-
- <listitem>
- <para><productname
- xlink:href="http://www.xmlmind.com/xmleditor">Xmlmind XML
- editor</productname> for visually editing technical
- documents based on <productname
- xlink:href="http://docbook.org/tdg5/index.html">docbook</productname>
- or <productname
- xlink:href="http://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture">DITA</productname>.</para>
- </listitem>
- </itemizedlist>
-
- <caution>
- <para>This VM is only accessible from within the <orgname
- xlink:href="http://www.hdm-stuttgart.de">HdM</orgname>
- network. External downloads require <productname
- xlink:href="https://wiki.mi.hdm-stuttgart.de/wiki/VPN">OpenVPN</productname>.</para>
- </caution>
-
- <para>The virtual machine is based on the <productname
- xlink:href="http://lubuntu.net">Lubuntu</productname> fork of
- the <productname
- xlink:href="http://www.ubuntu.com">Ubuntu</productname> Linux
- distribution for resource saving reasons.</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="oxygenLicenseKey">
- <glossterm><uri>Oxygen Xml Editor</uri> license key</glossterm>
-
- <glossdef>
- <para>This is the only software component in this lecture
- requiring a license. Your <orgname>HdM</orgname> affiliation
- entitles you to use the <productname
- xlink:href="http://oxygenxml.com/">Oxygenxml</productname>
- software for educational (non-commercial) purposes. The
- corresponding key is available at <uri
- xlink:href="ftp://mirror.mi.hdm-stuttgart.de/Firmen/Oxygen/Keys">ftp://mirror.mi.hdm-stuttgart.de/Firmen/Oxygen/Keys</uri>.</para>
-
- <para>This license key is compatible both with the standalone
- and the eclipse plugin version of the product.</para>
-
- <caution>
- <para>The license key's <abbrev
- xlink:href="http://en.wikipedia.org/wiki/File_Transfer_Protocol">ftp</abbrev>
- URL is only accessible from within the <orgname
- xlink:href="http://www.hdm-stuttgart.de">HdM</orgname>
- network. External access requires <link
- xlink:href="https://wiki.mi.hdm-stuttgart.de/wiki/VPN">Vpn
- activation</link>.</para>
- </caution>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>Source code of lecture resources</glossterm>
-
- <glossdef>
- <para>The complete lecture sources are available from <link
- xlink:href="https://version.mi.hdm-stuttgart.de/git/GoikLectures">https://version.mi.hdm-stuttgart.de/git/GoikLectures</link>.</para>
-
- <para>You may simply execute <quote><command
- xlink:href="http://git-scm.com/">git</command>
- <option>clone</option>
- <option>https://version.mi.hdm-stuttgart.de/git/GoikLectures</option>
- <option>.</option></quote> to check out the master tree.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>Source code of exercises and examples</glossterm>
-
- <glossdef>
- <para>These sources contain a subdirectory
- <filename>ws/eclipse/Jdbc</filename> which can be imported as an
- eclipse project. This allows for browsing solutions to the
- exercises and executing sample applications. Import into eclipse
- works the following way:</para>
-
- <itemizedlist>
- <listitem>
- <para>When starting eclipse choose
- <filename>.../ws/eclipse</filename> as workspace</para>
- </listitem>
-
- <listitem>
- <para>In eclipse click <quote>File --> Import -->
- General --> Existing Projects into Workspace</quote>.
- After re-selecting the current workspace
- <filename>.../ws/eclipse</filename> the folder
- <filename>Jdbc</filename> should be on the list of
- importable projects.</para>
-
- <para>Depending on your eclipse installation you may have to
- adjust the <link
- linkend="gloss_Java"><trademark>Java</trademark></link>
- system libraries. Right click on your project root in the
- package explorer and choose <quote>Build Path -->
- Configure Buildpath</quote>. The <quote>JRE System
- Library</quote> entry in the <quote>Libraries</quote> tab
- may have to be changed to suit your eclipse's installation
- needs. You may want to create a dummy <link
- linkend="gloss_Java"><trademark>Java</trademark></link>
- project to find the correct setting.</para>
- </listitem>
- </itemizedlist>
- </glossdef>
- </glossentry>
- </glosslist>
- </section>
-
- <section xml:id="tools">
- <title>Tools</title>
-
- <para>The subsequent sections describe tools being helpful to
- successfully carry out the exercises. These descriptions are suitable
- for current Linux/Ubuntu systems. However these tool are available for
- <trademark>Windows</trademark> or <trademark>Apple</trademark> systems
- as well. For the latter some command line hints may have to be
- replaced by using GUI based tools.</para>
-
- <para>You may want to use the <link
- xlink:href="ftp://mirror.mi.hdm-stuttgart.de/ubuntu/VirtualBox/lubuntu.vdi">corresponding</link>
- <link xlink:href="https://www.virtualbox.org">Virtualbox image</link>
- containing a complete system avoiding installation hassles. This
- should work well one reasonable current hardware systems.</para>
-
- <section xml:id="eclipse">
- <title><productname
- xlink:href="http://www.oracle.com/technetwork/java/javase/jdk-7-readme-429198.html">JDK</productname>
- and Eclipse</title>
-
- <para>So you like to take the hard way rather than using <link
- xlink:href="ftp://mirror.mi.hdm-stuttgart.de/ubuntu/VirtualBox/lubuntu.vdi">the
- virtualbox image</link>? Good! Real programmers tend to complicate
- things!</para>
-
- <para>The Eclipse IDE will be used as the primary coding tool
- especially for <link
- linkend="gloss_Java"><trademark>Java</trademark></link> and XML.
- Users may use different tools like e.g. <productname
- xlink:href="http://netbeans.org">Netbeans</productname> or
- <productname
- xlink:href="http://www.altova.com/de/xmlspy.html">XML-Spy</productname>.
- There are however some caveats:</para>
-
- <itemizedlist>
- <listitem>
- <para>Certain functionalities may not be provided</para>
- </listitem>
-
- <listitem>
- <para><orgname>HdM</orgname> staff support in case of troubles
- will be limited to coding excluding tool support. In other
- words: You are on your own!</para>
- </listitem>
- </itemizedlist>
-
- <para>Installation of eclipse requires a suitable <link
- linkend="gloss_Java"><trademark>Java</trademark></link> Development
- Kit.</para>
-
- <caution>
- <para>Your<productname
- xlink:href="http://www.oracle.com/technetwork/java/javase/jdk-7-readme-429198.html">JDK</productname>
- selection may be affected by your system's hardware. On a 64 bit
- system you may install either a 32 bit or a 64 bit <productname
- xlink:href="http://www.oracle.com/technetwork/java/javase/jdk-7-readme-429198.html">JDK</productname>.
- If you subsequently install eclipse you must select the
- appropriate 32 or 64 Bit version matching your <productname
- xlink:href="http://www.oracle.com/technetwork/java/javase/jdk-7-readme-429198.html">JDK</productname>
- choice.</para>
- </caution>
-
- <para>Due to Oracle's (end-user unfriendly) licensing policy you may
- have to install this component manually. For <productname
- xlink:href="http://www.ubuntu.com">Ubuntu</productname> and
- <productname xlink:href="http://www.debian.org">Debian</productname>
- systems a standard (package manager compatible) procedure is being
- described at <uri
- xlink:href="http://www.webupd8.org/2012/01/install-oracle-java-jdk-7-in-ubuntu-via.html">http://www.webupd8.org/2012/01/install-oracle-java-jdk-7-in-ubuntu-via.html</uri>.
- This boils down to (being executed as user root or preceded by
- <command>sudo</command> <option>...</option>):</para>
-
- <programlisting language="none">add-apt-repository ppa:webupd8team/java
-apt-get update
-apt-get install oracle-jdk7-installer</programlisting>
-
- <para>During the installation process you will have to accept
- Oracle's license terms. If you do so this information will be cached
- and not be asked again for when updating via <command>aptitude
- </command><option>update</option>;<command>aptitude</command>
- <option>safe-upgrade</option>. After successful installation when
- executing <command
- xlink:href="http://www.oracle.com/us/technologies/java">java</command>
- <option>-version</option> in a shell you should see something
- similar to:</para>
-
- <programlisting language="none">goik@goiki:~$ <emphasis role="bold">java -version</emphasis>
-java version "1.7.0_07"
-Java(TM) SE Runtime Environment (build 1.7.0_07-b10)
-Java HotSpot(TM) Server VM (build 23.3-b01, mixed mode)</programlisting>
-
- <para>The Eclipse IDE comes <link
- xlink:href="http://www.eclipse.org/downloads">with various
- flavours</link> depending on which plugins are already being
- shipped. For our purposes the <quote><productname>Eclipse
- Classic</productname></quote> <link
- linkend="gloss_Java"><trademark>Java</trademark></link> edition is
- sufficient. You may however want to install other flavours like
- <quote><productname>Eclipse IDE for Java EE
- Developers</productname></quote> if you require features beyond this
- course's needs. Remember to download the correct 32 or 64 bit
- version corresponding to your<productname
- xlink:href="http://www.oracle.com/technetwork/java/javase/jdk-7-readme-429198.html">JDK</productname>.</para>
-
- <para>Follow <uri
- xlink:href="http://askubuntu.com/questions/26632/how-to-install-eclipse#answer-145018">http://askubuntu.com/questions/26632/how-to-install-eclipse#answer-145018</uri>
- to install eclipse on your system.</para>
- </section>
-
- <section xml:id="oxygenxmlInstall">
- <title><productname
- xlink:href="http://oxygenxml.com">Oxygenxml</productname>
- plugin</title>
-
- <para>Go to <uri
- xlink:href="http://www.oxygenxml.com/download_oxygenxml_developer.html?os=Eclipse">http://www.oxygenxml.com/download_oxygenxml_developer.html?os=Eclipse</uri>.
- You may choose between the <quote>Plugin Update site</quote> and
- <quote>Plugin zip distribution</quote> installation method. The
- latter allows for better long term eclipse plugin management and is
- being described at</para>
-
- <para>There are two different ways to install Eclipse
- plugins:</para>
-
- <itemizedlist>
- <listitem>
- <para>Use Eclipse's built in Update manager by <link
- xlink:href="http://www.oxygenxml.com/download_oxygenxml_developer.html?os=Eclipse#eclipse_install_instructions">defining
- a corresponding update site</link>.</para>
- </listitem>
-
- <listitem>
- <para>Unzip <filename>com.oxygenxml.developer_XYZ.zip</filename>
- in a subfolder of <filename>.../eclipse/dropins</filename> and
- restart eclipse (as root).</para>
- </listitem>
- </itemizedlist>
-
- <para>See <xref linkend="oxygenLicenseKey"/> for obtaining a license
- key. You may as well install the standalone version of the Oxygen
- XML Editor.</para>
- </section>
-
- <section xml:id="erMaster">
- <title>ERMaster</title>
-
- <para>Visual editing of physical entity relationship diagrams. See
- <link xlink:href="http://ermaster.sourceforge.net">installation
- instructions</link> on top of an existing eclipse
- installation.</para>
- </section>
-
- <section xml:id="testngInstall">
- <title><foreignphrase>TestNG</foreignphrase> plugin</title>
-
- <para>Some exercises require the TestNG plugin to be installed in
- the Eclipse IDE. You may proceed in a similar way as in <uri
- linkend="oxygenxmlInstall">Oxygenxml</uri>. According to <uri
- xlink:href="http://testng.org/doc/eclipse.html#eclipse-installation">http://testng.org/doc/eclipse.html#eclipse-installation</uri>
- the Eclipse URL being needed is
- <quote>http://beust.com/eclipse</quote>.</para>
- </section>
-
- <section xml:id="mysql">
- <title><productname
- xlink:href="http://www.mysql.com">Mysql</productname> Database
- components</title>
-
- <para>We start by installing the <productname
- xlink:href="http://www.mysql.com">Mysql</productname> server:</para>
-
- <programlisting language="none">root@goiki:~# aptitude install mysql-server
-The following NEW packages will be installed:
- libdbd-mysql-perl{a} libdbi-perl{a} libnet-daemon-perl{a} libplrpc-perl{a}
- mysql-client-5.5{a} mysql-server-5.5
-0 packages upgraded, 6 newly installed, 0 to remove and 0 not upgraded.
-Need to get 0 B/17.8 MB of archives. After unpacking 63.2 MB will be used.
-Do you want to continue? [Y/n/?]</programlisting>
-
- <para>Hit <keycap>Y - return</keycap> to start. During the
- installation you will be asked for the <productname
- xlink:href="http://www.mysql.com">Mysql</productname> servers
- <quote>root</quote> (Administrator) password:</para>
-
- <programlisting language="none">Package configuration
-
-
- ┌───────────────────────────┤ Configuring mysql-server-5.5 ├────────────────────────────â”
- │ While not mandatory, it is highly recommended that you set a password for the MySQL │
- │ administrative "root" user. │
- │ │
- │ If this field is left blank, the password will not be changed. │
- │ │
- │ New password for the MySQL "root" user: │
- │ │
- │ ********_____________________________________________________________________________ │
- │ │
- │ <Ok> │
- │ │
- └───────────────────────────────────────────────────────────────────────────────────────┘
-
-
- </programlisting>
-
- <para>This has to be entered twice. Keep a <emphasis
- role="bold">permanent</emphasis> record of this entry. Alternatively
- set a bookmark to <uri
- xlink:href="https://help.ubuntu.com/community/MysqlPasswordReset">https://help.ubuntu.com/community/MysqlPasswordReset</uri>
- for later reference *** and don't blame me! ***.</para>
-
- <para>At this point we should be able to connect to our newly
- installed Server. We create a database <quote>hdm</quote> to be used
- for our exercises:</para>
-
- <programlisting language="none">goik@goiki:~$ mysql -u root -p
-Enter password:
-Welcome to the MySQL monitor. Commands end with ; or \g.
-Your MySQL connection id is 42
-Server version: 5.5.24-0ubuntu0.12.04.1 (Ubuntu)
-
-Copyright (c) 2000, 2011, Oracle and/or its affiliates. All rights reserved.
-
-Oracle is a registered trademark of Oracle Corporation and/or its
-affiliates. Other names may be trademarks of their respective
-owners.
-
-Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
-
-mysql> <emphasis role="bold">create database hdm;</emphasis>
-Query OK, 1 row affected (0.00 sec)</programlisting>
-
- <para>Following <uri
- xlink:href="https://dev.mysql.com/doc/refman/5.5/en/adding-users.html">https://dev.mysql.com/doc/refman/5.5/en/adding-users.html</uri>
- we add a new user and grant full access to the newly created
- database:</para>
-
- <programlisting language="none">goik@goiki:~$ mysql -u root -p
-Enter password:
- ...
-mysql> CREATE USER 'hdmuser'@'localhost' IDENTIFIED BY 'XYZ';
-mysql> use hdm;
-mysql> GRANT ALL PRIVILEGES ON *.* TO 'hdmuser'@'localhost' WITH GRANT OPTION;
-mysql> FLUSH PRIVILEGES;</programlisting>
-
- <para>The next step is optional. The <productname
- xlink:href="http://www.ubuntu.com">Ubuntu</productname> <productname
- xlink:href="http://www.mysql.com">Mysql</productname> server default
- configuration allows connections only via
- <varname>loopback</varname> interface i.e.
- <varname>localhost</varname>. If you want your <productname
- xlink:href="http://www.mysql.com">Mysql</productname> server to
- listen to the external network interface comment out the
- bind-address parameter in
- <filename>/etc/mysql/my.cnf</filename>:</para>
-
- <programlisting language="none"># Instead of skip-networking the default is now to listen only on
-# localhost which is more compatible and is not less secure.
-# <emphasis role="bold">bind-address = 127.0.0.1</emphasis></programlisting>
-
- <para>Since we are dealing with <link
- linkend="gloss_Java"><trademark>Java</trademark></link> a <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- driver is needed to connect Applications to our <productname
- xlink:href="http://www.mysql.com">Mysql</productname> server:</para>
-
- <programlisting language="none">root@goiki:~# aptitude install libmysql-java</programlisting>
-
- <para>This provides the file
- /usr/share/java/mysql-connector-java-5.1.16.jar and two symbolic
- links:</para>
-
- <programlisting language="none">goik@goiki:~$ cd /usr/share/java
-goik@goiki:/usr/share/java$ ls -al mysql*
--rw-r--r-- 1 ... 2011 <emphasis role="bold">mysql-connector-java-5.1.16.jar</emphasis>
-lrwxrwxrwx 1 ... 2011 <emphasis role="bold">mysql-connector-java.jar -> mysql-connector-java-5.1.16.jar</emphasis>
-lrwxrwxrwx 1 ... 2011 <emphasis role="bold">mysql.jar -> mysql-connector-java.jar</emphasis></programlisting>
- </section>
- </section>
-
- <section xml:id="lectureNotes">
- <title>Lecture related resources</title>
-
- <para>The sources for lecture notes and exercises are available from
- the <orgname xlink:href="http://www.mi.hdm-stuttgart.de">MIB</orgname>
- <productname xlink:href="http://git-scm.com">git</productname>
- repository:</para>
-
- <para><uri
- xlink:href="https://version.mi.hdm-stuttgart.de/git/GoikLectures">https://version.mi.hdm-stuttgart.de/git/GoikLectures</uri></para>
-
- <para>Check-out is straightforward:</para>
-
- <programlisting language="none">goik@goiki:~$ mkdir StructuredData;cd StructuredData
-
-goik@goiki:~/StructuredData$ git clone https://version.mi.hdm-stuttgart.de/git/GoikLectures .
-Cloning into '.'...
-remote: Counting objects: 694, done
-...
-Resolving deltas: 100% (296/296), done.</programlisting>
-
- <para>After checkout an eclipse workspace holding the complete example
- source code becomes visible:</para>
-
- <programlisting language="none">goik@goiki:~/StructuredData$ cd ws/eclipse
-goik@goiki:~/StructuredData/ws/eclipse$ ls -al
-insgesamt 16
-drwxr-xr-x 3 goik fb1prof 4096 Nov 8 22:04 .
-drwxr-xr-x 4 goik fb1prof 4096 Nov 8 22:04 ..
--rw-r--r-- 1 goik fb1prof 11 Nov 8 22:04 .gitignore
-<emphasis role="bold">drwxr-xr-x 6 goik fb1prof 4096 Nov 8 22:04 Jdbc</emphasis></programlisting>
-
- <para>The subdirectory <filename>Jdbc</filename> can be imported as an
- eclipse project via File --> import --> General --> Existing
- Projects into workspace. This should enable each participant to browse
- and execute the examples being provided in the lecture notes. It also
- contains the a <productname
- xlink:href="http://www.mysql.com">Mysql</productname> driver in
- Jdbc/lib/mysql-connector-java-5.1.16.jar being required to set up a
- <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- connection.</para>
- </section>
-
- <section xml:id="repeatRelational">
- <title>Some notes on relational databases</title>
-
- <qandaset defaultlabel="qanda" xml:id="airlineRelationalSchema">
- <title>Airlines, airports and flights</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>Implement a relational schema describing airlines,
- flights, airports and their respective relationships:</para>
-
- <itemizedlist>
- <listitem>
- <para>Airline:</para>
-
- <itemizedlist>
- <listitem>
- <para>An informal unique name like e.g.
- <quote>Lufthansa</quote>.</para>
- </listitem>
-
- <listitem>
- <para>A unique <link
- xlink:href="http://en.wikipedia.org/wiki/List_of_airline_codes">ICAO
- abbreviation</link>.</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>Destination</para>
-
- <itemizedlist>
- <listitem>
- <para>Full name like <quote>Frankfurt am Main
- International</quote></para>
- </listitem>
-
- <listitem>
- <para>World airport code like
- <quote>FRA</quote>.</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>Flight</para>
-
- <itemizedlist>
- <listitem>
- <para>A unique flight number e.g. LH 4234</para>
- </listitem>
-
- <listitem>
- <para>The <quote>owning</quote> airline.</para>
- </listitem>
-
- <listitem>
- <para>originating airport</para>
- </listitem>
-
- <listitem>
- <para>destination airport</para>
- </listitem>
-
- <listitem>
- <para>Constraint: origin and destination must differ.
- Hint: Mysql provides a syntactical means to implement
- this constraint. It will however not be enforced at
- runtime. Database vendors like Oracle, IBM/DB2 support
- this type of runtime integrity constraint
- enforcement.</para>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
-
- <para>Provide surrogate keys for all entities.</para>
- </question>
-
- <answer>
- <programlisting language="sql">DROP TABLE IF EXISTS Flight;
-DROP TABLE IF EXISTS Destination;
-DROP TABLE IF EXISTS Airline;
-
-
-CREATE Table Airline (
- id INT NOT NULL PRIMARY KEY
- ,name CHAR(20) NOT NULL UNIQUE
- ,airlineCode CHAR(5)NOT NULL UNIQUE
-);
-
-CREATE TABLE Destination (
- id INT NOT NULL PRIMARY KEY
- ,fullName CHAR(20) NOT NULL
- ,airportCode CHAR(20) NOT NULL UNIQUE
-);
-
-
-CREATE TABLE Flight (
- id INT NOT NULL PRIMARY KEY
- ,flightNumber CHAR(10) NOT NULL UNIQUE
- ,airline INT NOT NULL REFERENCES Airline
- ,origin int NOT NULL REFERENCES Destination
- ,destination int NOT NULL REFERENCES Destination
- ,CHECK(NOT(origin = destination))
-);</programlisting>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
-
- <section xml:id="toolingConfigJdbc">
- <title>Tooling: Configuring and using the <link
- xlink:href="http://www.eclipse.org/datatools">Eclipse database
- development</link> plugin</title>
-
- <para>For some basic SQL communications the Eclipse environment offers
- a standard plugin (Database development). Establishing connections to
- a specific database server generally requires prior installation of a
- <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- driver on the client side as being shown in the following
- video:</para>
-
- <figure xml:id="figureConfigJdbcDriver">
- <title>Adding a <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- Driver for <productname
- xlink:href="http://www.mysql.com">Mysql</productname> to the
- database plugin.</title>
-
- <mediaobject>
- <videoobject>
- <videodata fileref="Ref/Video/jdbcDriverConfig.mp4"/>
- </videoobject>
- </mediaobject>
- </figure>
-
- <para>During the exercises the eclipse database development
- perspective may be used to browse and structure SQL tables and data.
- The following video demonstrates the configuration of a <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- connection to a local (<varname>localhost</varname> network interface)
- database server. With respect to the introduction given in <xref
- linkend="mysql"/> we assume the existence of a database
- <code>hdm</code> and a corresponding account <quote>hdmuser</quote>
- and password <quote><code>XYZ</code></quote> (<emphasis
- role="bold">capital letters!</emphasis>) on our database
- server.</para>
-
- <figure xml:id="figureConfigJdbcConnection">
- <title>Configuring a <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- connection to a (local) <productname
- xlink:href="http://www.mysql.com">Mysql</productname> database
- server.</title>
-
- <mediaobject>
- <videoobject>
- <videodata fileref="Ref/Video/jdbcConnection.mp4"/>
- </videoobject>
- </mediaobject>
- </figure>
-
- <para>We are now ready to communicate with our database server. The
- last video in this section shows some basic SQL tasks:</para>
-
- <figure xml:id="figureEclipseBasicSql">
- <title>Executing SQL statements, browsing schema and retrieving
- data</title>
-
- <mediaobject>
- <videoobject>
- <videodata fileref="Ref/Video/eclipseBasicSql.mp4"/>
- </videoobject>
- </mediaobject>
- </figure>
- </section>
- </chapter>
-
- <chapter xml:id="xmlIntro">
- <title>Introduction to XML</title>
-
- <section xml:id="xmlBasic">
- <title>The XML industry standard</title>
-
- <para>A short question might be: <quote>What is XML?</quote> An answer
- might be: The acronym XML stands for
- <quote>E<emphasis>x</emphasis>tensible <emphasis>M</emphasis>arkup
- <emphasis>L</emphasis><foreignphrase>anguage</foreignphrase></quote>
- and is an industry standard being published by the W3C standardization
- organization. Like other industry software standards talking about XML
- leads to talk about XML based software: Applications and frameworks
- supplying added values to software implementors and enhancing data
- exchange between applications.</para>
-
- <para>Many readers are already familiar with XML without explicitly
- referring to the standard itself: The world wide web's
- <foreignphrase>lingua franca</foreignphrase> HTML has been ported to
- an XML dialect forming the <link
- xlink:href="http://www.w3.org/MarkUp">XHTML</link> Standard. The idea
- behind this standard is to distinguish between an abstract markup
- language and rendered results being generated from so called document
- instances by a browser:</para>
-
- <figure xml:id="renderXhtmlMarkup">
- <title>Rendering XHTML markup</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/xhtml.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>Xhtml is actually a good example to illustrate the tree like,
- hierarchical structure of XML documents:</para>
-
- <figure xml:id="xhtmlTree">
- <title>Xhtml tree structure</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/xhtmlexample.fig" scale="65"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>We may extend this example by representing a mathematical
- formula via a standard called <link
- xlink:href="http://www.w3.org/Math">Mathml</link>:</para>
-
- <figure xml:id="mathmlExample">
- <title>A formula in <link
- xlink:href="http://www.w3.org/Math">MathML</link>
- representation.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/sqrtrender.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>Again we observe a similar situation: A database like
- <emphasis>representation</emphasis> of a formula on the left and a
- <emphasis>rendered</emphasis> version on the right. Regarding XML we
- have:</para>
-
- <itemizedlist>
- <listitem>
- <para>The <link xlink:href="http://www.w3.org/Math">MathML</link>
- standard intended to describe mathematical formulas. The standard
- defines a set of <emphasis>tags</emphasis> like e.g. <tag
- class="starttag">math:msqrt</tag> with well-defined semantics
- regarding permitted attribute values and nesting rules.</para>
- </listitem>
-
- <listitem>
- <para>Informal descriptions of formatting expectations.</para>
- </listitem>
-
- <listitem>
- <para>Software transforming an XML formula representation into
- visible or printable output. In other words: A rendering
- engine.</para>
- </listitem>
- </itemizedlist>
-
- <para>XML documents may also be regarded as a persistence mechanism to
- represent and store data. Similarities to Relational Database Systems
- exist. A RDBMS
- (<emphasis>R</emphasis><foreignphrase>elational</foreignphrase>
- <emphasis>D</emphasis><foreignphrase>atabase</foreignphrase>
- <emphasis>M</emphasis><foreignphrase>anagement</foreignphrase>
- <emphasis>S</emphasis><foreignphrase>ystem</foreignphrase>) is
- typically capable to hold Tera bytes of data being organized in
- tables. The arrangement of data may be subject to various constraints
- like candidate- or foreign key rules. With respect to both end users
- and software developers a RDBMS itself is a building block in a
- complete solution. We need an application on top of it acting as a
- user interface to the data being contained.</para>
-
- <para>In contrast to a RDBMS XML allows data to be organized
- hierarchically. The <link
- xlink:href="http://www.w3.org/Math">MathML</link> representation given
- in <xref linkend="mathmlExample"/> may be graphically
- visualized:</para>
-
- <figure xml:id="mathmltree">
- <title>A tree graph representation of the <link
- xlink:href="http://www.w3.org/Math">MathML</link> example given
- before.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/sqrtree.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>CAD applications may user XML documents as a representation of
- graphical primitives:</para>
-
- <informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/attributes.fig" scale="65"/>
- </imageobject>
- </mediaobject>
- </informalfigure>
-
- <para>Of course RDBMS also allow the representation of tree like
- structures or arbitrary graphs. But these have to be modelled by using
- foreign key constraints since relational tables themselves have a
- <quote>flat</quote> structure. Some RDBMS vendors provide extensions
- to the SQL standard which allow <quote>native</quote> representations
- of <link linkend="gloss_XML"><abbrev>XML</abbrev></link>
- documents.</para>
- </section>
-
- <section xml:id="xmlHtml">
- <title>Well formed XML documents</title>
-
- <para>The general structure of an <link
- linkend="gloss_XML"><abbrev>XML</abbrev></link> document is as
- follows:</para>
-
- <figure xml:id="xmlbase">
- <title><link linkend="gloss_XML"><abbrev>XML</abbrev></link> basic
- structure</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/xmlbase.fig" scale="65"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>We explore a simple XML document representing messages like
- E-mails:</para>
-
- <figure xml:id="memoWellFormed">
- <title>The representation of a short message.</title>
-
- <programlisting language="none"><?xml<co
- xml:id="first_xml_code_magic"/> version="1.0"<co
- xml:id="first_xml_code_version"/> encoding="UTF-8"<co
- xml:id="first_xml_code_encoding"/>?>
-<memo><co xml:id="first_xml_code_topelement"/>
- <from>M. Goik</from><co xml:id="first_xml_code_from"/>
- <to>B. King</to>
- <to>A. June</to>
- <subject>Best whishes</subject>
- <content>Hi all, congratulations to your splendid party</content>
-</memo></programlisting>
- </figure>
-
- <calloutlist>
- <callout arearefs="first_xml_code_magic">
- <para>The very first characters <code><?xml</code> may be
- regarded as a <link
- xlink:href="http://en.wikipedia.org/wiki/Magic_number_(programming)">magic
- number string</link> being used as a format indicator which allows
- to distinguish between different file types i.e. GIF, JPEG, HTML
- and so on.</para>
- </callout>
-
- <callout arearefs="first_xml_code_version">
- <para>The <code>version="1.0"</code> attribute tells us that all
- subsequent lines will conform to the <link
- xlink:href="http://www.w3.org/TR/xml">XML</link> standard of
- version 1.0. This way a document can express its conformance to
- the version 1.0 standard even if in the future this standard
- evolves to a higher version e.g.
- <code>version="2.1"</code>.</para>
- </callout>
-
- <callout arearefs="first_xml_code_encoding">
- <para>The attribute <code>encoding="UTF-8"</code> tells us that
- all text in the current document uses <link
- xlink:href="http://unicode.org">Unicode</link> encoding. <link
- xlink:href="http://unicode.org">Unicode</link> is a widely
- accepted industry standard for font encoding. Thus European,
- Cyrillic and most Asian font codes are allowed to be used in
- documents <emphasis>simultaneously</emphasis>. Other encodings may
- limit the set of allowed characters, e.g.
- <code>encoding="ISO-8859-1"</code> will only allow characters
- belonging to western European languages. However a system also
- needs to have the corresponding fonts (e.g. TrueType) being
- installed in order to render the document appropriately. A
- document containing Chinese characters is of no use if the
- underlying rendering system lacks e.g. a set of Chinese True Type
- fonts.</para>
- </callout>
-
- <callout arearefs="first_xml_code_topelement">
- <para>An XML document has exactly one top level
- <emphasis>node</emphasis>. In contrast to the HTML standard these
- nodes are commonly called elements rather than tags. In this
- example the top level (root) element is <tag
- class="starttag">memo</tag>.</para>
- </callout>
-
- <callout arearefs="first_xml_code_from">
- <para>Each XML element like <tag class="starttag">from</tag> has a
- corresponding counterpart <tag class="endtag">from</tag>. In terms
- of XML we say each element being opened has to be closed. In
- conjunction with the precedent point this is equivalent to the
- fact that each XML document represents a tree structure as being
- shown in the <link linkend="mathmltree">tree graph</link>
- representation.</para>
- </callout>
- </calloutlist>
-
- <para>As with the introductory formula example this representation
- itself is of limited usefulness: In an office environment we need a
- rendered version being given either as print or as some online format
- like E-Mail or HTML.</para>
-
- <para>From a software developer's point of view we may use a piece of
- software called a <emphasis>parser</emphasis> to test the document's
- standard conformance. At the MI department we may simply invoke
- <userinput><command>xmlparse</command> message.xml</userinput> to
- start a check:</para>
-
- <programlisting language="none"><errortext>goik>xmlparse wellformed.xml
-Parsing was successful</errortext></programlisting>
-
- <para>Various XML related plugins are supplied for the <productname
- xlink:href="http://eclipse.org">eclipse platform</productname> like
- the <productname xlink:href="http://oxygenxml.com">Oxygen
- software</productname> supplying <quote>life</quote> conformance
- checking while editing XML documents. Now we test our assumptions by
- violating some of the rules stated before. We deliberately omit the
- closing element <tag class="endtag">from</tag>:</para>
-
- <figure xml:id="omitFrom">
- <title>An invalid XML document due to the omission of <tag
- class="endtag">from</tag>.</title>
-
- <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
-<memo>
- <from>M. Goik <co xml:id="omitFromMissingElement"/>
- <to>B. King</to>
- <to>A. June</to>
- <subject>Best whishes</subject>
- <content>Hi all, congratulations to your splendid party</content>
-</memo></programlisting>
-
- <calloutlist>
- <callout arearefs="omitFromMissingElement">
- <para>The opening element <tag class="starttag">from</tag> is
- not terminated by <tag class="endtag">from</tag>.</para>
- </callout>
- </calloutlist>
- </figure>
-
- <para>Consequently the parser's output reads:</para>
-
- <programlisting language="none"><errortext>goik>xmlparse omitfrom.xml
-file:///ma/goik/workspace/Vorlesungen/Input/Memo/omitfrom.xml:8:3:
-fatal error org.xml.sax.SAXParseException: The element type "from"
-must be terminated by the matching end-tag "</from>". parsing error</errortext></programlisting>
-
- <para>Experienced HTML authors may be confused: In fact HTML is not an
- XML standard. Instead HTML belongs to the set of SGML applications.
- SGML is a much older standard namely the <emphasis>Standard
- Generalized Markup Language</emphasis>.</para>
-
- <para>Even if every XML element has a closing counterpart the
- resulting XML may be invalid:</para>
-
- <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
-<memo>
- <from>M. Goik<to>B. King</from></to>
- <to>A. June</to>
- <subject>Best whishes</subject>
- <content>Hi all, congratulations to your splendid party</content>
-</memo></programlisting>
-
- <para>The parser echoes:</para>
-
- <programlisting language="none"><computeroutput>file:///ma/goik/workspace/Vorlesungen/Input/Memo/nonest.xml:3:29:
-fatal error org.xml.sax.SAXParseException: The element type "to" must be
-terminated by the matching end-tag "</to>". parsing error</computeroutput></programlisting>
-
- <para>This type of error is caused by so called improper nesting of
- elements: The element <tag class="starttag">from</tag>is closed before
- the <quote>inner</quote> element <tag class="starttag">to</tag> has
- been closed. Actually this violates the expressibility of XML
- documents as a tree like structure. The situation may be resolved by
- choosing:</para>
-
- <programlisting language="none">...<from>M. Goik<to>B. King</to></from>...</programlisting>
-
- <para>We provide two examples illustrating proper and improper nesting
- of XML documents:</para>
-
- <figure xml:id="fig_nestingProper">
- <title>Proper nesting of XML elements</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/propernest.fig" scale="65"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>The following example violates proper nesting constraint and
- thus does not provide an XML document:</para>
-
- <figure xml:id="fig_improperNest">
- <title>Improperly nested elements</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/impropernest.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <!-- goik:later
- <para>An animation showing the usage of the Oxygen plug in for the
- examples given above can be found <uri
- xlink:href="src/viewlet/wellformed/wellformed_viewlet_swf.html">here</uri>.</para>
--->
-
- <para>XML elements may have so called attributes like <tag
- class="attribute">date</tag> in the following example:</para>
-
- <figure xml:id="memoWellAttrib">
- <title>An XML document with attributes.</title>
-
- <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
-<memo date="10.02.2006" priority="high">
- <from>M. Goik</from>
- <to>B. King</to>
- <to>A. June</to>
- <subject>Best whishes</subject>
- <content>Hi all, congratulations to your splendid party</content>
-</memo></programlisting>
- </figure>
-
- <para>The conformance of a XML document with the following rules may
- be verified by invoking a parser:</para>
-
- <itemizedlist>
- <listitem>
- <para>Within the <emphasis>scope</emphasis> of a given element an
- attribute name must be unique. In the example above one may not
- define a second attribute <varname>date="..."</varname> within the
- same element <memo ... >. This reflects the usual
- programming language semantics of attributes: In a <link
- linkend="gloss_Java"><trademark>Java</trademark></link> class an
- attribute is represented by an unique identifier and thus cannot
- appear twice.</para>
- </listitem>
-
- <listitem>
- <para>An attribute value must be enclosed either in single (') or
- double (") quotes. This is different from the HTML standard which
- allows attribute values without quotes provided the given
- attribute value does not give rise to ambiguities. For example
- <tag class="starttag">td align=left</tag> is allowed since the
- attribute value <tag class="attvalue">left</tag> does not contain
- any spaces thus allowing a parser to recognize the end of the
- value's definition.</para>
- </listitem>
- </itemizedlist>
-
- <qandaset defaultlabel="qanda" xml:id="example_memoAttribTree">
- <title>A graphical representation of a memo.</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>Draw a graphical representation similar as in <xref
- linkend="mathmltree"/> of the memo document being given in
- <xref linkend="memoWellAttrib"/>.</para>
- </question>
-
- <answer>
- <para>The <link linkend="memoWellAttrib">memo
- document's</link> structure may be visualized as:</para>
-
- <informalfigure xml:id="memotreeFigure">
- <para>A graphical representation of <xref
- linkend="memoWellAttrib"/>:</para>
-
- <informalfigure xml:id="memotreeFigureFalse">
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/memotree.fig"/>
- </imageobject>
- </mediaobject>
- </informalfigure>
-
- <para>The sequence of <emphasis>element</emphasis> child
- nodes is important in XML and has to be preserved. Only the
- order of the two attributes <tag
- class="attribute">date</tag> and <tag
- class="attribute">priority</tag> is undefined: They actually
- belong to the <tag class="starttag">memo</tag> node serving
- as a dictionary with the attribute names being the keys and
- the attribute values being the values of the
- dictionary.</para>
- </informalfigure>
- </answer>
- </qandaentry>
-
- <qandaentry xml:id="example_attribInQuotes">
- <question>
- <label>Attributes and quotes</label>
-
- <para>As stated before XML attributes have to be enclosed in
- single or double quotes. Construct an XML document with mixed
- quotes like <code><date day="monday'></code>. How does
- the parser react? Find the corresponding syntax definition of
- legal attribute values in the <link
- xlink:href="http://www.w3.org/TR/xml">XML standard W3C
- Recommendation</link>.</para>
- </question>
-
- <answer>
- <para>The parser flags a mixture of single and double quotes
- for a given attribute as an error. The XML standard <link
- xlink:href="http://www.w3.org/TR/xml#NT-AttValue">defines</link>
- the syntax of attribute values: An attribute value has to be
- enclosed <emphasis>either</emphasis> in two single
- <emphasis>or</emphasis> in two double quotes as being defined
- in <uri
- xlink:href="http://www.w3.org/TR/xml/#NT-AttValue">http://www.w3.org/TR/xml/#NT-AttValue</uri>.</para>
- </answer>
- </qandaentry>
-
- <qandaentry xml:id="quoteInAttributValue">
- <question>
- <label>Quotes as part of an attributes value?</label>
-
- <para>Single and double quote are used to delimit an attribute
- value. May quotes appear themselves as part of an at tribute's
- value, e.g. like in a person's name <code>Gary "King"
- Mandelson</code>?</para>
- </question>
-
- <answer>
- <para>Attribute values may contain double quotes if the
- attributes value is enclosed in single quotes and vice versa.
- As a limitation the value of an an attribute may not contain
- single quotes and double quotes at the same time:</para>
-
- <informalfigure xml:id="exampleSingleDoubleQuotes">
- <para>Quotes as part of attribute values.</para>
-
- <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
-<test>
- <person name='Gary "King" Mandelson'/> <!-- o.k. -->
- <person name="Gary 'King' Mandelson"/> <!-- o.k. -->
- <person name="Gary 'King 'S.' "Mandelson"'/> <!-- oops! -->
-</test></programlisting>
- </informalfigure>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
-
- <para>Some constraints being imposed on XML documents by the standard
- defined so far may be summarized as:</para>
-
- <itemizedlist>
- <listitem>
- <para>A XML documents requires to have exactly one top level
- element.</para>
- </listitem>
-
- <listitem>
- <para>Elements have to be properly nested. An element must not be
- closed if an <quote>inner</quote> Element is still open.</para>
- </listitem>
-
- <listitem>
- <para>Attribute names within a given Element must be
- unique.</para>
- </listitem>
-
- <listitem>
- <para>Attribute values <emphasis>must</emphasis> be quoted
- correctly.</para>
- </listitem>
- </itemizedlist>
-
- <para>The very last rule shows one of several differences to the HTML
- Standard: In HTML a lot of elements don't have to be closed. For
- example paragraphs (<tag class="starttag">p</tag>) or images (<tag
- class="starttag">img src='foo.gif'</tag>) don't have to be closed
- explicitly. This is due to the fact that HTML used to be defined in
- accordance with the older <emphasis><emphasis
- role="bold">S</emphasis>tandard <emphasis
- role="bold">G</emphasis>eneralized <emphasis
- role="bold">M</emphasis>arkup <emphasis
- role="bold">L</emphasis>anguage</emphasis> (SGML) Standard.</para>
-
- <para>These constraints are part of the definition of a <link
- xlink:href="http://www.w3.org/TR/xml#sec-well-formed">well formed
- document</link>. The specification imposes additional constraints for
- a document to be well-formed.</para>
- </section>
- </chapter>
-
- <chapter xml:id="dtd">
- <title>Beyond well- formedness</title>
-
- <section xml:id="motivationDdt">
- <title>Motivation</title>
-
- <para>So far we are able to create XML documents containing
- hierarchically structured data. We may nest elements and thus create
- tree structures of arbitrary depth. The only restrictions being
- imposed by the XML standard are the constraints of well - formedness.
- For many purposes in software development this is not
- sufficient.</para>
-
- <para>A company named <productname>Softmail</productname> might
- implement an email system which uses <link
- linkend="memoWellAttrib">memo</link> document files as low level data
- representation serving as a persistence layer. Now a second company
- named <productname>Hardmail</productname> wants to integrate mails
- generated by <productname>Softmail</productname>'s system into its own
- business product. The <productname>Hardmail</productname> software
- developers might <emphasis>infer</emphasis> the logical structure of
- <productname>Softmail</productname>'s email representation but the
- following problems arise:</para>
-
- <itemizedlist>
- <listitem>
- <para>The logical structure will in practice become more complex:
- E-mails may contain attachments leading to multi part messages.
- Additional header information is required for standard Internet
- mail compliance. This adds additional complexity to the XML
- structure being mandatory for data representation. Relying only on
- well-formedness the specification of an internal E-mail format can
- only be achieved <emphasis>informally</emphasis>. Thus a rule like
- <quote>Each E-mail must have a subject</quote> may be written down
- in the specification. A software developer will code these rules
- but probably make mistakes as the set of rules grows.</para>
-
- <para>In contrast a RDBMS based solution offers to solve such
- problems in a declarative manner: A developer may use a <code>NOT
- NULL</code> constraint on a subject attribute of type
- <code>VARCHAR</code> thus inhibiting empty subjects.</para>
- </listitem>
-
- <listitem>
- <para>As <productname>Softmail</productname>'s product evolves its
- internal E-mail XML format is subject to change due to functional
- extensions and possibly bug fixes both giving rise to
- interoperability problems.</para>
- </listitem>
- </itemizedlist>
-
- <para>Generally speaking well formed XML documents lack grammar
- constraints as being available for programming languages. In case of
- RDBMS developers can impose primary-, foreign and <code>CHECK</code>
- constraints in a <emphasis>declarative</emphasis> manner rather than
- hard coding them into their applications (A solution bad programmers
- are in favour of though...). Various XML standards exist for
- declarative constraint definitions namely:</para>
-
- <itemizedlist>
- <listitem>
- <para>DTDs</para>
- </listitem>
-
- <listitem>
- <para><link xlink:href="http://www.w3.org/XML/Schema">XML
- Schema</link></para>
- </listitem>
-
- <listitem>
- <para><link
- xlink:href="http://www.relaxng.org">RelaxNG</link></para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section xml:id="dtdBasic">
- <title>XML Schema</title>
-
- <section xml:id="dtdFirstExample">
- <title>Structural descriptions for documents</title>
-
- <para>As an example we choose documents of type
- <emphasis>memo</emphasis> as a starting point. Documents like the
- example from <xref linkend="memoWellAttrib"/> may be
- <emphasis>informally</emphasis> described to be a sequence of the
- following mandatory items:</para>
-
- <figure xml:id="figure_memo_informalconstraints">
- <title>Informal constraints on <tag class="element">memo</tag>
- document instances</title>
-
- <itemizedlist>
- <listitem>
- <para><emphasis>Exactly one</emphasis> sender.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>One or more</emphasis> recipients.</para>
- </listitem>
-
- <listitem>
- <para>Subject</para>
- </listitem>
-
- <listitem>
- <para>Content</para>
- </listitem>
- </itemizedlist>
-
- <para>In addition we have:</para>
-
- <itemizedlist>
- <listitem>
- <para>A date string <emphasis>must</emphasis> be
- supplied</para>
- </listitem>
-
- <listitem>
- <para>A priority <emphasis>may</emphasis> be supplied with
- allowed values to be chosen from the set of values <tag
- class="attvalue">low</tag>, <tag class="attvalue">medium</tag>
- or <tag class="attvalue">high</tag>.</para>
- </listitem>
- </itemizedlist>
- </figure>
-
- <para>All these fields contain ordinary text to be filled in by a
- user and shall appear exactly in the defined order. For simplicity
- we do not care about email address syntax rules being described in
- <link xlink:href="http://www.w3.org/Protocols/rfc822">RFC based
- address schemes</link>. We will see how the
- <emphasis>constraints</emphasis> mentioned above can be modelled in
- XML by an extension to the concept of well formed documents.</para>
- </section>
-
- <section xml:id="section_memo_machinereadable">
- <title>A machine readable description</title>
-
- <para>We now introduce an example of an XML schema. It allows for
- the specification of additional constraints to both element nodes
- and their attributes. Our set of <link
- linkend="figure_memo_informalconstraints" revision="">informal
- constraints</link> on memo documents may be expressed as:</para>
-
- <figure xml:id="figure_memo_dtd">
- <title>A schema to describe memo documents.</title>
-
- <programlisting language="none"><xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
- xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning" elementFormDefault="qualified"
- vc:minVersion="1.0" vc:maxVersion="1.1">
-
- <xs:element name="memo">
- <xs:complexType>
- <xs:sequence> <co xml:id="memodtd_memodef"/>
- <xs:element name="from" type="xs:string"/> <co
- xml:id="memodtd_elem_from"/>
- <xs:element name="to" minOccurs="1" maxOccurs="unbounded" type="xs:string"/>
- <xs:element name="subject" type="xs:string"/>
- <xs:element name="content" type="xs:string"/>
- </xs:sequence>
- <xs:attribute name="date" type="xs:date" use="required"/> <co
- xml:id="memodtd_memo_attribs"/>
- <xs:attribute name="priority" type="Priority" use="optional"/>
- </xs:complexType>
-
- </xs:element>
-
- <xs:simpleType name="Priority">
- <xs:restriction base="xs:string">
- <xs:enumeration value="low"/>
- <xs:enumeration value="medium"/>
- <xs:enumeration value="high"/>
- </xs:restriction>
- </xs:simpleType>
-
-</xs:schema></programlisting>
-
- <calloutlist>
- <callout arearefs="memodtd_memodef">
- <para>A <tag class="element">memo</tag> consists of a sender,
- at least one recipient, a subject and content.</para>
- </callout>
-
- <callout arearefs="memodtd_memo_attribs">
- <para>A <tag class="element">memo</tag> has got one required
- attribute <varname>date</varname> and an optional attribute
- <varname>priority</varname> being restricted to the three
- allowed values <tag class="attvalue">low</tag>, <tag
- class="attvalue">medium</tag> and <tag
- class="attvalue">high</tag> being defined by a separate <tag
- class="starttag">xs:simpleType</tag> directive.</para>
- </callout>
-
- <callout arearefs="memodtd_elem_from">
- <para>A <tag class="starttag">from</tag> element consists of
- ordinary text. This disallows XML markup. For example
- <code><from>Smith & partner</from></code> is
- disallowed since XML uses the ampersand (&) to denote the
- beginning of an entity like <tag class="genentity">auml</tag>
- for the German a-umlaut (ä). The correct form is
- <code><from>Smith &amp; partner</from></code>
- using the predefined entity <tag class="genentity">amp</tag>
- as an escape sequence for the ampersand.</para>
-
- <para><code>type="xs:string"</code> is a built in XML Schema
- type representing a restricted version of ordinary strings.
- Without digging into details a <code>xs:string</code> string
- must not contain any markup code like e.g. <tag
- class="starttag">msqrt</tag>. This ensures that a string does
- not interfere with the document's XML markup.</para>
- </callout>
- </calloutlist>
- </figure>
-
- <para>We notice our schema's syntax itself is an XML
- document.</para>
-
- <para>From the viewpoint of software modeling an XML Schema instance
- is a <emphasis>schema</emphasis> describing the syntax of a class of
- XML document instances adhering to it. In the context of XML
- technologies <link xlink:href="http://www.w3.org/XML/Schema">XML
- Schema</link> is one of several language alternatives which allow
- for XML document structure descriptions.</para>
-
- <para>Readers being familiar with <abbrev
- xlink:href="http://en.wikipedia.org/wiki/Backus-Naur_form">BNF</abbrev>
- or <abbrev
- xlink:href="http://en.wikipedia.org/wiki/Extended_Backus_Naur_form">EBNF</abbrev>
- will be able to understand the grammatical rules being expressed
- here.</para>
-
- <productionset>
- <title>A message of type <tag class="starttag">memo</tag></title>
-
- <production xml:id="memo.ebnf.memo">
- <lhs>Memo Message</lhs>
-
- <rhs>'<memo>' <nonterminal
- def="#memo.ebnf.sender">Sender</nonterminal> [<nonterminal
- def="#memo.ebnf.recipient">Recipient</nonterminal>]+
- <nonterminal def="#memo.ebnf.subject">Subject</nonterminal>
- <nonterminal def="#memo.ebnf.content">Content</nonterminal>
- '</memo>'</rhs>
- </production>
-
- <production xml:id="memo.ebnf.sender">
- <lhs>Sender</lhs>
-
- <rhs>'<from>' <nonterminal def="#memo.ebnf.text"> Text
- </nonterminal> '</from>'</rhs>
- </production>
-
- <production xml:id="memo.ebnf.recipient">
- <lhs>Recipient</lhs>
-
- <rhs>'<to>' <nonterminal def="#memo.ebnf.text"> Text
- </nonterminal> '</to>'</rhs>
- </production>
-
- <production xml:id="memo.ebnf.subject">
- <lhs>Subject</lhs>
-
- <rhs>'<subject>' <nonterminal def="#memo.ebnf.text"> Text
- </nonterminal> '</subject>'</rhs>
- </production>
-
- <production xml:id="memo.ebnf.content">
- <lhs>Content</lhs>
-
- <rhs>'<content>' <nonterminal def="#memo.ebnf.text"> Text
- </nonterminal> '</content>'</rhs>
- </production>
-
- <production xml:id="memo.ebnf.text">
- <lhs>Text</lhs>
-
- <rhs>[a-zA-Z0-9]* <lineannotation>In real documents this is too
- restrictive!</lineannotation></rhs>
- </production>
- </productionset>
-
- <para>We may as well supply a graphical representation:</para>
-
- <figure xml:id="extendContModelGraph">
- <title>Graphical representation of the extended
- <code>content</code> model.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/contentmixed.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>In comparison to our informal description of memo documents a
- schema offers an added value: The grammar is machine readable and
- may thus become input to a parser which in turn gets enabled to
- check whether an XML document obeys the constraints being imposed.
- So the parser must be instructed to use a schema in addition to the
- XML document in question. For this purpose an XML document may
- define a reference to a schema:</para>
-
- <figure xml:id="memo_external_dtd">
- <title>A memo document instance holding a reference to a document
- external schema.</title>
-
- <programlisting language="none"><memo <co
- xml:id="memo_external_dtd_top_element"/> xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:noNamespaceSchemaLocation="memo.xsd" <co
- xml:id="memo_external_dtd_url"/>
- date="2014-09-24" priority="high">
- <from>M. Goik</from>
- <to>B. King</to>
- <to>A. June</to>
- <subject>Best whishes</subject>
- <content>Hi all, congratulations to your splendid party</content>
-</memo></programlisting>
-
- <calloutlist>
- <callout arearefs="memo_external_dtd_top_element">
- <para>The element <tag class="starttag">memo</tag> is chosen
- to be the top (root) element of the document's tree. It must
- be defined in our schema <filename>memo.xsd</filename>. This
- is really a choice since an XML schema defines a
- <emphasis>set</emphasis> of elements in
- <emphasis>arbitrary</emphasis> order. There is no such rule as
- <quote>define before use</quote>. So an XML schema does not
- tell us which element has to appear on top of a
- document.</para>
-
- <para>Suppose a given XML schema offers both <tag
- class="starttag">book</tag> and <tag
- class="starttag">report</tag> elements. An XML author writing
- a complex document will choose <tag
- class="starttag">book</tag> as top level element rather than
- <tag class="starttag">report</tag> being more appropriate for
- a small piece of documentation. Consequently it is an XML
- authors <emphasis>choice</emphasis> which of the elements
- being defined in a schema shall appear as
- <emphasis>the</emphasis> top level element</para>
- </callout>
-
- <callout arearefs="memo_external_dtd_url">
- <para>The address of the schema's rule set. In the given
- example it is just a filename but it may as well be an <link
- xlink:href="http://www.w3.org/Addressing">URL</link> of type
- <abbrev
- xlink:href="http://en.wikipedia.org/wiki/File_Transfer_Protocol">ftp</abbrev>,
- <abbrev xlink:href="http://www.w3.org/Protocols">http</abbrev>
- and so on, see <xref linkend="memoDtdOnFtp"/>.</para>
- </callout>
- </calloutlist>
- </figure>
-
- <para>In presence of a schema parsing a document is actually a two
- step process: First the parser will check the document for well
- -formedness. Then the parser will read the referenced schema
- <filename>memo.xsd</filename> and check the document for the
- additional constraints being defined within.</para>
-
- <para>In the current example both the schema and the XML memo
- document reside as text files in a common file system folder. For
- general use a schema is usually kept at a centralized location. The
- attribute <varname>xsi:noNamespaceSchemaLocation</varname> value is
- actually a
- <emphasis>U</emphasis><foreignphrase>niform</foreignphrase>
- <emphasis>R</emphasis><foreignphrase>esource</foreignphrase>
- <emphasis>L</emphasis><foreignphrase>ocator</foreignphrase> <link
- xlink:href="http://www.w3.org/Addressing">(URL)</link>. Thus our
- <filename>memo.xsd</filename> may also be supplied as a <abbrev
- xlink:href="http://www.w3.org/Protocols">http</abbrev> or <abbrev
- xlink:href="http://en.wikipedia.org/wiki/File_Transfer_Protocol">ftp</abbrev>
- <link xlink:href="http://www.w3.org/Addressing">URL</link>:</para>
-
- <figure xml:id="memoDtdOnFtp">
- <title>A schema reference to a FTP server.</title>
-
- <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
-<memo ... xsi:noNamespaceSchemaLocation="https://someserver.org/memo.xsd">
- <from>M. Goik</from>
- ...
-</memo></programlisting>
- </figure>
-
- <para>Some terms are helpful in the context of schemas:</para>
-
- <variablelist>
- <varlistentry>
- <term>Validating / non-validating:</term>
-
- <listitem>
- <para>A non-validating parser only checks a document for well-
- formedness. If it also checks XML documents for conformance to
- schema it is a <emphasis>validating</emphasis> parser.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Valid / invalid documents:</term>
-
- <listitem>
- <para>An XML document referencing a schema may either be valid
- or invalid depending on its conformance to the schema in
- question.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Document instance:</term>
-
- <listitem>
- <para>An XML memo document may conform to the <link
- linkend="figure_memo_dtd">memo schema</link>. In this case we
- call it a <emphasis>document instance</emphasis> of the memo
- schema.</para>
-
- <para>This situation is quite similar as in typed programming
- languages: A <link
- linkend="gloss_Java"><trademark>Java</trademark></link>
- <code>class</code> declaration is a blueprint for the <link
- linkend="gloss_Java"><trademark>Java</trademark></link>
- runtime system to construct <link
- linkend="gloss_Java"><trademark>Java</trademark></link>
- objects in memory. This is done by e.g. a statement<code>
- String name = new String();</code>. The identifier
- <code>name</code> will hold a reference to an
- <emphasis>instance of class String</emphasis>. So in a <link
- linkend="gloss_Java"><trademark>Java</trademark></link>
- runtime environment a class declaration plays the same role as
- a schema declaration in XML. See also <xref
- linkend="example_memoJavaClass"/>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>For further discussions it is very useful to clearly
- distinguish element definitions in a schema from their
- <emphasis>realizations</emphasis> in a corresponding document
- instance: Our memo schema defines an element <tag
- class="starttag">from</tag> to be of content <type>xs:string</type>.
- According to the schema at least one <tag
- class="starttag">from</tag> clause must appear in a valid
- (conforming) document instance . If we were talking about HTML
- document instances we would prefer to talk about a <tag
- class="starttag">from</tag> <emphasis>tag</emphasis> rather than a
- <tag class="starttag">from</tag>
- <emphasis>element</emphasis>.</para>
-
- <para>In this document we will use the term <emphasis>element
- type</emphasis> to denote an <code><!ELEMENT ...</code>
- definition in a DTD. Thus we will talk about an element type <tag
- class="element">subject</tag> being defined in
- <filename>memo.dtd</filename>.</para>
-
- <para>An element type being defined in a <abbrev
- xlink:href="http://en.wikipedia.org/wiki/Document_Type_Declaration">schema</abbrev>
- may have document instances as realizations. For example the
- document instance shown in <xref linkend="memo_external_dtd"/> has
- two <emphasis>nodes</emphasis> of element type <tag
- class="element">to</tag>. Thus we say that the document instance
- contains two <emphasis>element nodes</emphasis> of type <tag
- class="element">to</tag>. We will frequently abbreviate this by
- saying the instance contains to <tag class="starttag">from</tag>
- element nodes. And we may even omit the term
- <emphasis>nodes</emphasis> and simply talk about two <tag
- class="starttag">from</tag> elements. But the careful reader should
- always distinguish between a single type <code>foo</code> being
- defined in a <abbrev
- xlink:href="http://en.wikipedia.org/wiki/Document_Type_Declaration">schema</abbrev>
- and the possibly empty set of <tag class="starttag">foo</tag> nodes
- appearing in valid document instances.</para>
-
- <para><abbrev
- xlink:href="http://en.wikipedia.org/wiki/Document_Type_Declaration">Schema</abbrev>'s
- appear on top of well-formed XML documents:</para>
-
- <figure xml:id="wellformedandvalid">
- <title>Well-formed and valid documents</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/wellformedandvalid.fig" scale="65"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <qandaset defaultlabel="qanda" xml:id="example_memoTestValid">
- <title>Validation of memo document instances.</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>Copy the two files <link
- xlink:href="Ref/src/Memo.1/message.xml">message.xml</link>
- and <link
- xlink:href="Ref/src/Memo.1/memo.dtd">memo.xsd</link> into
- your eclipse project. Use the Oxygen XML plug in to check if
- the document is valid. Then subsequently do and undo the
- following changes each time checking the document for
- validity:</para>
-
- <itemizedlist>
- <listitem>
- <para>Omit the <tag class="starttag">from</tag>
- element.</para>
- </listitem>
-
- <listitem>
- <para>Change the order of the two sub elements <tag
- class="starttag">subject</tag> and <tag
- class="starttag">content</tag>.</para>
- </listitem>
-
- <listitem>
- <para>Erase the <varname>date</varname> attribute and
- its value.</para>
- </listitem>
-
- <listitem>
- <para>Erase the <varname>priority</varname> attribute
- and its value.</para>
- </listitem>
- </itemizedlist>
-
- <para>What do you observe?</para>
- </question>
-
- <answer>
- <para>The <tag class="attribute">priority</tag> attribute is
- declared as <code>optional</code> and may thus be omitted.
- Erasing the <tag class="attribute">priority</tag> attribute
- thus leaves the document in a valid state. The remaining
- three edit actions yield an invalid document
- instance.</para>
- </answer>
- </qandaentry>
-
- <qandaentry xml:id="example_memoJavaClass">
- <question>
- <label>A memo implementation sketch in Java</label>
-
- <para>The aim of this exercise is to clarify the (abstract)
- relation between XML <abbrev
- xlink:href="http://en.wikipedia.org/wiki/Document_Type_Declaration">schema</abbrev>'s
- and sets of <link
- linkend="gloss_Java"><trademark>Java</trademark></link>
- classes rather then building a running application. We want
- to model the <link xlink:href="Ref/src/Memo.1/memo.dtd">memo
- schema</link> as a set of <link
- linkend="gloss_Java"><trademark>Java</trademark></link>
- classes.</para>
- </question>
-
- <answer>
- <para>The XML attributes <tag class="attribute">date</tag>
- and <tag class="attribute">priority</tag> can be mapped as
- <link
- linkend="gloss_Java"><trademark>Java</trademark></link>
- attributes. The same applies for the Memo elements <tag
- class="element">from</tag>, <tag
- class="element">subject</tag> and <tag
- class="element">content</tag> which may be implemented as
- simple Strings or alternatively as separate Classes wrapping
- the String content. The latter method of implementation
- should be preferred if the Memo schema is expected to grow
- in complexity. A simple sketch reads:</para>
-
- <programlisting language="none">import java.util.Date;
-import java.util.SortedSet;
-
-public class Memo {
- private Date date;
- Priority priority = Priority.standard;
- private String from, subject,content;
- private SortedSet<String> to;
- // Accessors not yet implemented
-}</programlisting>
-
- <para>The only thing to note here is the implementation of
- the <tag class="element">to</tag> element: We want to be
- able to address a <emphasis>set</emphasis> of recipients.
- Thus we have to disallow duplicates. Note that this is an
- <emphasis>informal</emphasis> constraint not being handled
- by our schema: A Memo document instance
- <emphasis>may</emphasis> have duplicate content in <tag
- class="starttag">to</tag> nodes. This is a weakness of
- <abbrev
- xlink:href="http://en.wikipedia.org/wiki/Document_Type_Declaration">schema</abbrev>s:
- We are unable to impose uniqueness constraints on the
- content of partial sets of document nodes.</para>
-
- <para>On the other hand our set of recipients has to be
- ordered: In a XML document instance the order of <tag
- class="starttag">to</tag> nodes is important and has to be
- preserved in a <link
- linkend="gloss_Java"><trademark>Java</trademark></link>
- representation. Thus we choose an
- <classname>java.util.SortedSet</classname> parametrized with
- String type to fulfill both requirements.</para>
-
- <para>Our schema defines:</para>
-
- <programlisting language="none"><!ATTLIST memo ... priority (low|medium|high) #IMPLIED></programlisting>
-
- <para>Starting from <link
- linkend="gloss_Java"><trademark>Java</trademark></link> 1.5
- we may implement this constraint by a type safe enumeration
- in a file <filename>Priority.java</filename>:</para>
-
- <programlisting language="none">public enum Priority{low, standard, high};</programlisting>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
-
- <para>In the following chapters we will extend the memo document
- type (<code><!DOCTYPE memo ... ></code>) to demonstrate
- various concepts of <abbrev
- xlink:href="http://en.wikipedia.org/wiki/Document_Type_Declaration">schema</abbrev>'s
- and other XML related standards. In parallel a series of exercises
- deals with building a schema usable to edit books. This schema gets
- extended as our knowledge about XML advances. We start with an
- initial exercise:</para>
-
- <qandaset defaultlabel="qanda" xml:id="example_bookDtd">
- <title>A schema for editing books</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>Write a schema describing book document instances with
- the following features:</para>
-
- <itemizedlist>
- <listitem>
- <para>A book shall have a title to describe the book
- itself.</para>
- </listitem>
-
- <listitem>
- <para>A book shall have at least one but possibly a
- sequence of chapters.</para>
- </listitem>
-
- <listitem>
- <para>Each chapter shall have a title and at least one
- paragraph.</para>
- </listitem>
-
- <listitem>
- <para>The titles and paragraphs shall consist of
- ordinary text.</para>
- </listitem>
- </itemizedlist>
- </question>
-
- <answer>
- <para>A possible schema looks like:</para>
-
- <figure xml:id="figure_book.dtd_v1">
- <title>A first schema version for book documents</title>
-
- <programlisting language="none"><xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
- xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning" elementFormDefault="qualified"
- vc:minVersion="1.0" vc:maxVersion="1.1">
-
- <xs:element name="book">
- <xs:complexType>
- <xs:sequence>
- <xs:element ref="title"/>
- <xs:element ref="chapter" minOccurs="1" maxOccurs="unbounded"/>
- </xs:sequence>
- </xs:complexType>
- </xs:element>
-
- <xs:element name="title" type="xs:string"/>
- <xs:element name="chapter">
- <xs:complexType>
- <xs:sequence>
- <xs:element ref="title"/>
- <xs:element ref="para" minOccurs="1" maxOccurs="unbounded"/>
- </xs:sequence>
- </xs:complexType>
- </xs:element>
-
- <xs:element name="para" type="xs:string"/>
-
-</xs:schema></programlisting>
- </figure>
-
- <para>We supply a valid document instance:</para>
-
- <informalfigure xml:id="bookInitialInstance">
- <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book SYSTEM "book.dtd">
-<book>
- <title>Introduction to Java</title>
- <chapter>
- <title>Introduction</title>
- <para>Java is a programming language</para>
- </chapter>
- <chapter>
- <title>The virtual machine</title>
- <para>We also call it the runtime system.</para>
- </chapter>
- <chapter>
- <title>Annotations</title>
- <para>Annotations provide a means to add meta information.</para>
- <para>This is especially useful for framework authors.</para>
- </chapter>
-</book></programlisting>
- </informalfigure>
-
- <para>.</para>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
-
- <section xml:id="dtdVsSqlDdl">
- <title>Relating <abbrev
- xlink:href="http://en.wikipedia.org/wiki/Document_Type_Declaration">schema</abbrev>'s
- and <acronym
- xlink:href="http://en.wikipedia.org/wiki/Sql">SQL</acronym> -
- <abbrev
- xlink:href="http://en.wikipedia.org/wiki/Data_definition_language">DDL</abbrev></title>
-
- <para>XML <abbrev
- xlink:href="http://en.wikipedia.org/wiki/Document_Type_Declaration">schema</abbrev>'s
- and <acronym
- xlink:href="http://en.wikipedia.org/wiki/Sql">SQL</acronym> -
- <abbrev
- xlink:href="http://en.wikipedia.org/wiki/Data_definition_language">DDL</abbrev>
- are related: They both describe data models and thus integrity
- constraints. We consider a simple invoice example:</para>
-
- <figure xml:id="invoiceIntegrity">
- <title>Invoice integrity constraints</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/invoicedata.fig" scale="65"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>A relational implementation may look like:</para>
-
- <figure xml:id="invoiceSqlDdl">
- <title>Relational implementation</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/invoicedataimplement.fig"
- scale="65"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <qandaset defaultlabel="qanda" xml:id="qandaInvoiceSchema">
- <title>An XML schema representing invoices</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>Represent the relational schema being described in
- <xref linkend="invoiceSqlDdl"/> by an XML Schema and provide
- an appropriate instance example.</para>
- </question>
-
- <answer>
- <para>A possible schema implementation:</para>
-
- <programlisting language="none"><xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
- xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning" elementFormDefault="qualified"
- vc:minVersion="1.0" vc:maxVersion="1.1">
-
- <xs:simpleType name="money">
- <xs:restriction base="xs:decimal">
- <xs:fractionDigits value="2"/>
- </xs:restriction>
- </xs:simpleType>
-
- <xs:element name="data">
- <xs:complexType>
- <xs:sequence>
- <xs:element ref="customer" maxOccurs="unbounded"/>
- <xs:element ref="invoice" maxOccurs="unbounded"/>
- </xs:sequence>
- </xs:complexType>
- <xs:key name="customerId">
- <xs:selector xpath="customer"/>
- <xs:field xpath="@id"/>
- </xs:key>
-
- <xs:keyref refer="customerId" name="customerToInvoice">
- <xs:selector xpath="invoice"/>
- <xs:field xpath="@customer"></xs:field>
- </xs:keyref>
- </xs:element>
-
- <xs:element name="customer">
- <xs:complexType>
- <xs:sequence>
- <xs:element name="name" type="xs:string"/>
- <xs:element name="phoneNumber" type="xs:string" minOccurs="0"/>
- </xs:sequence>
- <xs:attribute name="id" type="xs:int" use="required"/>
- </xs:complexType>
- </xs:element>
-
- <xs:element name="invoice">
- <xs:complexType>
- <xs:sequence>
- <xs:element name="amount" type="money"/>
- <xs:element name="status">
- <xs:simpleType>
- <xs:restriction base="xs:token">
- <xs:enumeration value="open"/>
- <xs:enumeration value="due"/>
- <xs:enumeration value="cleared"/>
- </xs:restriction>
- </xs:simpleType>
- </xs:element>
- </xs:sequence>
- <xs:attribute name="customer" type="xs:int" use="required"/>
- </xs:complexType>
- </xs:element>
-
-</xs:schema></programlisting>
-
- <para>An example data set:</para>
-
- <programlisting language="none"><data xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:noNamespaceSchemaLocation="invoice.xsd">
- <customer id="5">
- <name>Clarke Jefferson</name>
- </customer>
-
- <invoice customer="5">
- <amount>33.12</amount>
- <status>due</status>
- </invoice>
-</data></programlisting>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
-
- <section xml:id="xmlAndJava">
- <title>Relating <abbrev
- xlink:href="http://en.wikipedia.org/wiki/Document_Type_Declaration">schema</abbrev>'s
- and <link linkend="gloss_Java"><trademark>Java</trademark></link>
- class descriptions.</title>
-
- <para>We may also compare XML data constraints to <link
- linkend="gloss_Java"><trademark>Java</trademark></link>. A <link
- linkend="gloss_Java"><trademark>Java</trademark></link> class
- declaration is actually a blueprint for a <trademark
- xlink:href="http://www.oracle.com/technetwork/java/javase">JRE</trademark>
- to instantiate compatible objects. Likewise an XML schema restricts
- well-formed documents:</para>
-
- <figure xml:id="fig_XmlAndJava">
- <title>XML <abbrev
- xlink:href="http://en.wikipedia.org/wiki/Document_Type_Declaration">schema</abbrev>'s
- and <link linkend="gloss_Java"><trademark>Java</trademark></link>
- class declarations.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/xmlattribandjava.fig" scale="65"/>
- </imageobject>
- </mediaobject>
- </figure>
- </section>
-
- <section xml:id="xmlSchemaExercise">
- <title>XML schema exercises</title>
-
- <section xml:id="sectSchemaProductCatalog">
- <title>A product catalog</title>
-
- <qandaset defaultlabel="qanda" xml:id="quandaProductCatalog">
- <title>Product catalog schema</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>Consider the following product catalog
- example:</para>
-
- <programlisting language="none"><catalog xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:noNamespaceSchemaLocation="catalog.xsd">
- <title>Outdoor products</title>
- <introduction>
- <para>We offer a great variety of basic stuff for mountaineering
- such as ropes, harnesses and tents.</para>
- <para>Our shop is proud for its large number of available
- sleeping bags.</para>
- </introduction>
- <product id="x-223">
- <title>Multi freezing bag Nightmare camper</title>
- <description>
- <para>You will feel comfortable till minus 20 degrees - At
- least if you are a penguin or a polar bear.</para>
- </description>
- </product>
- <product id="r-334">
- <title>Rope 40m</title>
- <description>
- <para>Excellent for indoor climbing.</para>
- </description>
- </product>
-</catalog></programlisting>
-
- <para>As you may have inferred the following rules shall
- apply for arbitrary catalog documents:</para>
-
- <itemizedlist>
- <listitem>
- <para>Each <tag class="starttag">catalog</tag> shall
- have exactly one <tag class="starttag">title</tag> and
- <tag class="starttag">introduction</tag>
- element.</para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">introduction</tag> and
- <tag class="starttag">description</tag> shall have at
- least one <tag class="starttag">para</tag>
- child.</para>
- </listitem>
-
- <listitem>
- <para>Each <tag class="starttag">catalog</tag> shall
- have at least one <tag
- class="starttag">product</tag>.</para>
- </listitem>
-
- <listitem>
- <para>Each <tag class="starttag">product</tag> shall
- have exactly one <tag class="starttag">title</tag> and
- at least one <tag class="starttag">para</tag> child
- element.</para>
- </listitem>
-
- <listitem>
- <para>The required <code>id</code> attribute shall not
- contain whitespace and be unique with respect to all
- <tag class="starttag">product</tag> elements.</para>
- </listitem>
-
- <listitem>
- <para>The attribute price shall represent money
- amounts and be optional.</para>
- </listitem>
- </itemizedlist>
-
- <para>Provide a suitable <filename>catalog.xsd</filename>
- schema.</para>
- </question>
-
- <answer>
- <programlisting language="none"><xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
- xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning" elementFormDefault="qualified"
- vc:minVersion="1.0" vc:maxVersion="1.1">
-
- <xs:simpleType name="money">
- <xs:restriction base="xs:decimal">
- <xs:fractionDigits value="2"/>
- </xs:restriction>
- </xs:simpleType>
-
- <xs:element name="title" type="xs:string"/>
- <xs:element name="para" type="xs:string"/>
-
- <xs:element name="description" type="paraSequence"/>
- <xs:element name="introduction" type="paraSequence"/>
-
- <xs:complexType name="paraSequence">
- <xs:sequence>
- <xs:element ref="para" minOccurs="1" maxOccurs="unbounded"/>
- </xs:sequence>
- </xs:complexType>
-
- <xs:element name="product">
- <xs:complexType>
- <xs:sequence>
- <xs:element ref="title"/>
- <xs:element ref="description"/>
- </xs:sequence>
- <xs:attribute name="id" type="xs:token" use="required"/>
- <xs:attribute name="price" type="money" use="optional"/>
- </xs:complexType>
- </xs:element>
-
- <xs:element name="catalog">
- <xs:complexType>
- <xs:sequence>
- <xs:element ref="title"/>
- <xs:element ref="introduction"/>
- <xs:element ref="product" minOccurs="1" maxOccurs="unbounded"/>
- </xs:sequence>
- </xs:complexType>
-
- <xs:key name="uniqueProductId">
- <xs:selector xpath="product"></xs:selector>
- <xs:field xpath="@id"/>
- </xs:key>
- </xs:element>
-
-</xs:schema></programlisting>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
-
- <section xml:id="sectQandaBookV1">
- <title>Book like documents</title>
-
- <qandaset defaultlabel="qanda" xml:id="example_operatorprecedence">
- <title>Book documents with mixed content and itemized
- lists</title>
-
- <qandadiv>
- <qandaentry xml:id="example_book_v2">
- <question>
- <para>Extend the first version of <link
- linkend="example_bookDtd">book.xsd</link> to support the
- following features:</para>
-
- <itemizedlist>
- <listitem>
- <para>Within a <tag class="starttag">chapter</tag>
- node <tag class="starttag">para</tag> and <tag
- class="starttag">itemizedlist</tag> elements in
- arbitrary order shall be allowed.</para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">itemizedlist</tag> nodes
- shall contain at least one <tag
- class="starttag">listitem</tag>.</para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">listitem</tag> nodes shall
- be composed of one or more para or nested list item
- elements.</para>
- </listitem>
-
- <listitem>
- <para>Within a <tag class="starttag">para</tag> we
- want to be able to emphasize text passages.</para>
- </listitem>
- </itemizedlist>
-
- <para>The following sample document instance shall be
- valid:</para>
-
- <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book SYSTEM "book.dtd">
-<book>
- <title>Introduction to Java</title>
- <chapter>
- <title>Introduction</title>
- <para>Java supports <emphasis>lots</emphasis> of concepts:</para>
- <itemizedlist>
- <listitem>
- <para>Single <emphasis>implementation</emphasis> inheritance.</para>
- </listitem>
- <listitem>
- <para>Multiple <emphasis>interface</emphasis> inheritance.</para>
- <itemizedlist>
- <listitem><para>Built in types</para></listitem>
- <listitem><para>User defined types</para></listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- </chapter>
-</book></programlisting>
- </question>
-
- <answer>
- <para>An extended DTD looks like:</para>
-
- <figure xml:id="paraListEmphasize">
- <title>Version 2 of book.dtd</title>
-
- <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
-<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
- xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning" elementFormDefault="qualified"
- vc:minVersion="1.0" vc:maxVersion="1.1">
-
- <xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="http://www.w3.org/2001/03/xml.xsd" />
-
-
- <xs:include schemaLocation="table.xsd"/>
-
- <!-- Type definitions -->
- <xs:simpleType name="languageType">
- <xs:restriction base="xs:string">
- <xs:enumeration value="en"/>
- <xs:enumeration value="fr"/>
- <xs:enumeration value="de"/>
- <xs:enumeration value="it"/>
- <xs:enumeration value="es"/>
- </xs:restriction>
- </xs:simpleType>
-
-
- <!-- Elements having no inner structure -->
- <xs:element name="emphasis" type="xs:string"/>
- <xs:element name="title" type="xs:string"/>
- <xs:element name="link">
- <xs:complexType mixed="true">
- <xs:attribute name="linkend" type="xs:IDREF" use="required"/>
- </xs:complexType>
- </xs:element>
-
- <!-- Starting the game ... -->
- <xs:element name="book">
- <xs:complexType>
- <xs:sequence>
- <xs:element ref="title"/>
- <xs:element ref="chapter" minOccurs="1" maxOccurs="unbounded"/>
- </xs:sequence>
- <xs:attribute name="lang" type="languageType" use="optional"/>
- </xs:complexType>
- </xs:element>
-
- <xs:element name="chapter">
- <xs:complexType>
- <xs:sequence> <co xml:id="figure_book.dtd_v2_chapter"/>
- <xs:element ref="title"/>
- <xs:choice minOccurs="1" maxOccurs="unbounded">
- <xs:element ref="para"/>
- <xs:element ref="itemizedlist"/>
- <xs:element ref="table"/>
- </xs:choice>
- </xs:sequence>
- <xs:attribute name="id" type="xs:ID" use="optional"/>
- <xs:attribute ref="xml:base"/> <!-- This allows for <xi:include ...> -->
- </xs:complexType>
- </xs:element>
-
- <xs:element name="para">
- <xs:complexType mixed="true"> <co
- xml:id="figure_book.dtd_v2_para"/>
- <xs:choice minOccurs="0" maxOccurs="unbounded">
- <xs:element ref="emphasis"/>
- <xs:element ref="link"/>
- </xs:choice>
- <xs:attribute name="id" type="xs:ID" use="optional"/>
- </xs:complexType>
- </xs:element>
-
- <xs:element name="itemizedlist">
- <xs:complexType>
- <xs:sequence>
- <xs:element ref="listitem" minOccurs="1" <co
- xml:id="figure_book.dtd_v2_itemizedlist"/> maxOccurs="unbounded"/>
- </xs:sequence>
- <xs:attribute name="id" type="xs:ID" use="optional"/>
- </xs:complexType>
- </xs:element>
-
- <xs:element name="listitem">
- <xs:complexType>
- <xs:choice minOccurs="1" maxOccurs="unbounded"> <co
- xml:id="figure_book.dtd_v2_listitem"/>
- <xs:element ref="para"/>
- <xs:element ref="itemizedlist"/>
- </xs:choice>
- </xs:complexType>
- </xs:element>
-
-</xs:schema></programlisting>
-
- <caption>
- <para>This allows emphasized text in <tag
- class="starttag">para</tag> nodes and <tag
- class="starttag">itemizedlists</tag>.</para>
- </caption>
- </figure>
-
- <calloutlist>
- <callout arearefs="figure_book.dtd_v2_chapter">
- <para>We hook into <tag class="starttag">chapter</tag>
- to allow arbitrary sequences of at least one <tag
- class="starttag">para</tag> or <tag
- class="starttag">itemizedlist</tag> element
- node.</para>
- </callout>
-
- <callout arearefs="figure_book.dtd_v2_para">
- <para><tag class="starttag">para</tag> nodes now allow
- mixed content.</para>
- </callout>
-
- <callout arearefs="figure_book.dtd_v2_itemizedlist">
- <para>An <tag class="starttag">itemizedlist</tag>
- contains at least one list item.</para>
- </callout>
-
- <callout arearefs="figure_book.dtd_v2_listitem">
- <para>A <tag class="starttag">listitem</tag> contains
- a sequence of at least one <tag
- class="starttag">para</tag> or <tag
- class="starttag">itemizedlist</tag> child node. The
- latter gives rise to nested lists. We find a similar
- construct in HTML namely unnumbered lists defined by
- <code><UL><LI>...
- </code>constructs.</para>
- </callout>
- </calloutlist>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
-
- <section xml:id="sectQandaBookLang">
- <title>Allow different languages</title>
-
- <qandaset defaultlabel="qanda" xml:id="example_book.dtd_v3">
- <title>book.dtd and languages</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>We want to extend our schema from <xref
- linkend="example_book_v2"/> by allowing an author to
- define the language to be used within the whole or parts
- of the document in question. Add an attribute
- <code>lang</code> to all relevant elements like e.g. <tag
- class="starttag">para lang="es"</tag>. An XML editor may
- use this attribute to activate corresponding dictionaries
- for spell checking.</para>
-
- <para>The <code>lang</code> attribute shall be restricted
- to the following values:</para>
-
- <itemizedlist>
- <listitem>
- <para><token>en</token></para>
- </listitem>
-
- <listitem>
- <para><token>fr</token></para>
- </listitem>
-
- <listitem>
- <para><token>de</token></para>
- </listitem>
-
- <listitem>
- <para><token>it</token></para>
- </listitem>
-
- <listitem>
- <para><token>es</token></para>
- </listitem>
- </itemizedlist>
- </question>
-
- <answer>
- <para>We define a suitable <tag
- class="starttag">xs:attribute</tag> type:</para>
-
- <programlisting language="none"><xs:attribute <emphasis
- role="bold">name="lang"</emphasis>>
- <xs:simpleType>
- <xs:restriction base="xs:string">
- <xs:enumeration value="en"/>
- <xs:enumeration value="fr"/>
- <xs:enumeration value="de"/>
- <xs:enumeration value="it"/>
- <xs:enumeration value="es"/>
- </xs:restriction>
- </xs:simpleType>
-</xs:attribute></programlisting>
-
- <para>Than we add this attribute to our elements like <tag
- class="starttag">chapter</tag> and others:</para>
-
- <programlisting language="none"> <xs:element name="chapter">
- <xs:complexType>
- <xs:sequence> ... </xs:sequence>
- <xs:attribute <emphasis role="bold">ref="lang"</emphasis> use="optional"/>
- ...
- </xs:complexType>
- </xs:element></programlisting>
-
- <para>This allows us to set a language on arbitrary
- hierarchy level. But of course we may define it on top
- level as well:</para>
-
- <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
-<book ... lang="english">
- <title>Introduction to Java</title>
-...</programlisting>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
-
- <section xml:id="sectMixQuotes">
- <title>Mixing attribute quotes</title>
-
- <qandaset defaultlabel="qanda" xml:id="example_quotes">
- <title>Single and double quotes reconsidered</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>We recall the problem of nested quotes yielding
- non-well formed XML code:</para>
-
- <programlisting language="none"><img src="bold.gif" alt="We may use "quotes" here" /></programlisting>
-
- <para>The XML specification defines legal attribute value
- definitions as:</para>
-
- <productionset>
- <title><link
- xlink:href="http://www.w3.org/TR/2008/REC-xml-20081126/#d0e888">Literals</link></title>
-
- <production xml:id="w3RecXml_NT-EntityValue">
- <lhs>EntityValue</lhs>
-
- <rhs>'"' ([^%&"] | <nonterminal
- def="#w3RecXml_NT-PEReference">PEReference</nonterminal>
- | <nonterminal
- def="#w3RecXml_NT-Reference">Reference</nonterminal>)*
- '"' |Â "'" ([^%&'] | <nonterminal
- def="#w3RecXml_NT-PEReference">PEReference</nonterminal>
- | <nonterminal
- def="#w3RecXml_NT-Reference">Reference</nonterminal>)*
- "'"</rhs>
- </production>
-
- <production xml:id="w3RecXml_NT-AttValue">
- <lhs>AttValue</lhs>
-
- <rhs>'"' ([^<&"] | <nonterminal
- def="#w3RecXml_NT-Reference">Reference</nonterminal>)*
- '"' |Â "'" ([^<&'] | <nonterminal
- def="#w3RecXml_NT-Reference">Reference</nonterminal>)*
- "'"</rhs>
- </production>
-
- <production xml:id="w3RecXml_NT-SystemLiteral">
- <lhs>SystemLiteral</lhs>
-
- <rhs>('"' [^"]* '"') |Â ("'" [^']* "'")</rhs>
- </production>
-
- <production xml:id="w3RecXml_NT-PubidLiteral">
- <lhs>PubidLiteral</lhs>
-
- <rhs>'"' <nonterminal
- def="#w3RecXml_NT-PubidChar">PubidChar</nonterminal>*
- '"' | "'" (<nonterminal
- def="#w3RecXml_NT-PubidChar">PubidChar</nonterminal> -
- "'")* "'"</rhs>
- </production>
-
- <production xml:id="w3RecXml_NT-PubidChar">
- <lhs>PubidChar</lhs>
-
- <rhs>#x20 | #xD | #xA |Â [a-zA-Z0-9]
- |Â [-'()+,./:=?;!*#@$_%]</rhs>
- </production>
- </productionset>
-
- <para>Find out how it is possible to set the attribute
- <tag class="attribute">alt</tag>'s value to the string
- <code>We may use "quotes" here</code>.</para>
- </question>
-
- <answer>
- <para>The production rule for attribute values
- reads:</para>
-
- <productionset>
- <productionrecap linkend="w3RecXml_NT-AttValue"/>
- </productionset>
-
- <para>This allows us to use either of two alternatives to
- delimit attribute values:</para>
-
- <glosslist>
- <glossentry>
- <glossterm><tag class="starttag">img ...
- alt="..."/</tag></glossterm>
-
- <glossdef>
- <para><emphasis>Validity constraint:</emphasis> do
- not use <code>"</code> inside the value
- string.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm><tag class="starttag">img ...
- alt='...'/</tag></glossterm>
-
- <glossdef>
- <para><emphasis>Validity constraint:</emphasis> do
- not use <code>'</code> inside the value
- string.</para>
- </glossdef>
- </glossentry>
- </glosslist>
-
- <para>We may take advantage of the second rule:</para>
-
- <programlisting language="none"><img src="bold.gif" alt='We may use "quotes" here' /></programlisting>
-
- <para>Notice that according to <xref
- linkend="w3RecXml_NT-AttValue"/> the delimiting quotes
- must not be mixed. The following code is thus not well
- formed:</para>
-
- <programlisting language="none"><img src="bold.gif'/></programlisting>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
-
- <section xml:id="qandasetInternalRef">
- <title>Internal references</title>
-
- <qandaset defaultlabel="qanda" xml:id="example_book.dtd_v5">
- <title>book.dtd and internal references</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>We want to extend our DTD from <xref
- linkend="example_book.dtd_v3"/> to allow document internal
- references by:</para>
-
- <itemizedlist>
- <listitem>
- <para>Allowing each <tag
- class="starttag">chapter</tag>, <tag
- class="starttag">para</tag> and <tag
- class="starttag">itemizedlist</tag> to become
- reference targets.</para>
- </listitem>
-
- <listitem>
- <para>Extending the element <tag
- class="element">para</tag>'s mixed content model by a
- new element <tag class="element">link</tag> with an
- attribute <tag class="attribute">linkend</tag> being a
- reference to a target.</para>
- </listitem>
- </itemizedlist>
- </question>
-
- <answer>
- <para>We extend our DTD:</para>
-
- <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
-<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
- xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning" elementFormDefault="qualified"
- vc:minVersion="1.0" vc:maxVersion="1.1">
-
- <xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="http://www.w3.org/2001/03/xml.xsd" />
-
-
- <xs:include schemaLocation="table.xsd"/>
-
- <!-- Type definitions -->
-
- <xs:attribute name="lang">
- <xs:simpleType>
- <xs:restriction base="xs:string">
- <xs:enumeration value="en"/>
- <xs:enumeration value="fr"/>
- <xs:enumeration value="de"/>
- <xs:enumeration value="it"/>
- <xs:enumeration value="es"/>
- </xs:restriction>
- </xs:simpleType>
- </xs:attribute>
-
- <!-- Elements having no inner structure -->
- <xs:element name="emphasis" type="xs:string"/>
- <xs:element name="title" type="xs:string"/>
- <xs:element name="link">
- <xs:complexType mixed="true"> <co
- xml:id="progamlisting_book_v5_link"/>
- <xs:attribute name="linkend" <co
- xml:id="progamlisting_book_v5_link_linkend"/> type="xs:IDREF" use="required"/>
- </xs:complexType>
- </xs:element>
-
- <!-- Starting the game ... -->
- <xs:element name="book">
- <xs:complexType>
- <xs:sequence>
- <xs:element ref="title"/>
- <xs:element ref="chapter" minOccurs="1" maxOccurs="unbounded"/>
- </xs:sequence>
- <xs:attribute ref="lang" use="optional"/>
- </xs:complexType>
- </xs:element>
-
- <xs:element name="chapter">
- <xs:complexType>
- <xs:sequence>
- <xs:element ref="title"/>
- <xs:choice minOccurs="1" maxOccurs="unbounded">
- <xs:element ref="para"/>
- <xs:element ref="itemizedlist"/>
- <xs:element ref="table"/>
- </xs:choice>
- </xs:sequence>
- <xs:attribute ref="lang" use="optional"/>
- <xs:attribute name="id" <co
- xml:id="progamlisting_book_v5_chapter_id"/> type="xs:ID" use="optional"/>
- <xs:attribute ref="xml:base"/> <!-- This allows for <xi:include ...> -->
- </xs:complexType>
- </xs:element>
-
- <xs:element name="para">
- <xs:complexType mixed="true"> <co
- xml:id="progamlisting_book_v5_mixed_link"/>
- <xs:choice minOccurs="0" maxOccurs="unbounded">
- <xs:element ref="emphasis"/>
- <xs:element ref="link"/>
- </xs:choice>
- <xs:attribute ref="lang" use="optional"/>
- <xs:attribute name="id" <co
- xml:id="progamlisting_book_v5_para_id"/> type="xs:ID" use="optional"/>
- </xs:complexType>
- </xs:element>
-
- <xs:element name="itemizedlist">
- <xs:complexType>
- <xs:sequence>
- <xs:element ref="listitem" minOccurs="1" maxOccurs="unbounded"/>
- </xs:sequence>
- <xs:attribute ref="lang" use="optional"/>
- <xs:attribute name="id" type="xs:ID" use="optional"/>
- </xs:complexType>
- </xs:element>
-
- <xs:element name="listitem">
- <xs:complexType>
- <xs:choice minOccurs="1" maxOccurs="unbounded">
- <xs:element ref="para"/>
- <xs:element ref="itemizedlist"/>
- </xs:choice>
- <xs:attribute ref="lang" use="optional"/>
- </xs:complexType>
- </xs:element>
-
-</xs:schema></programlisting>
-
- <calloutlist>
- <callout arearefs="progamlisting_book_v5_chapter_id">
- <para>Defining an attribute <tag
- class="attribute">id</tag> of type <code>ID</code> for
- the elements <tag class="element">chapter</tag>, <tag
- class="element">para</tag> and <tag
- class="element">itemizedList</tag>. This enables an
- author to define internal reference targets.</para>
- </callout>
-
- <callout arearefs="progamlisting_book_v5_mixed_link">
- <para>A link is part of the element <tag
- class="element">para</tag>'s mixed content model. Thus
- an author may define internal references along with
- ordinary text.</para>
- </callout>
-
- <callout arearefs="progamlisting_book_v5_link">
- <para>Like in HTML a link may contain text. If
- converted to HTML the formatting expectation is a
- hypertext link.</para>
- </callout>
-
- <callout arearefs="progamlisting_book_v5_link_linkend">
- <para>The attribute <tag
- class="attribute">linkend</tag> holds the reference to
- an internal target being either a <tag
- class="element">chapter</tag>, a <tag
- class="element">para</tag> or an <tag
- class="element">itemizedList</tag>.</para>
- </callout>
- </calloutlist>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
- </section>
- </section>
- </chapter>
-
- <chapter xml:id="xsl">
- <title>The Extensible Stylesheet Language XSL</title>
-
- <para>XSL is a <link xlink:href="http://www.w3.org/Style/XSL">W3C
- standard</link> which defines a language to transform XML documents into
- the following output formats:</para>
-
- <itemizedlist>
- <listitem>
- <para>Ordinary text e.g in <link
- xlink:href="http://unicode.org">Unicode</link> encoding.</para>
- </listitem>
-
- <listitem>
- <para>XML.</para>
- </listitem>
-
- <listitem>
- <para>HTML</para>
- </listitem>
-
- <listitem>
- <para>XHTML</para>
- </listitem>
- </itemizedlist>
-
- <para>Transforming a source XML document into a target XML document may
- be required if:</para>
-
- <itemizedlist>
- <listitem>
- <para>The target document expresses similar semantics but uses a
- different XML dialect i.e. different tag names.</para>
- </listitem>
-
- <listitem>
- <para>The target document is only a view on the source document. We
- may for example extract the chapter names from a <tag
- class="starttag">book</tag> document to create a table of
- contents.</para>
- </listitem>
- </itemizedlist>
-
- <section xml:id="xsl_helloworld">
- <title>A <quote>Hello, world</quote> <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> example</title>
-
- <para>We start from an extended version of our
- <filename>memo.dtd</filename>:</para>
-
- <programlisting language="none"><!ELEMENT memo (from, to+, subject, content)>
-<!ATTLIST memo date CDATA #REQUIRED
- priority (low|medium|high) #IMPLIED>
-<!ELEMENT from (#PCDATA)>
-<!ATTLIST from id ID #IMPLIED >
-<!ELEMENT to (#PCDATA)>
-<!ATTLIST to id ID #IMPLIED >
-
-<!ELEMENT subject (#PCDATA)>
-<!ELEMENT content (para)+>
-<!ELEMENT para (#PCDATA|link)*>
-<!ELEMENT link (#PCDATA) >
-<!ATTLIST link linkend IDREF #REQUIRED ></programlisting>
-
- <para>This DTD allows a memo's document content to be structured into
- paragraphs. A paragraph may contain links either to the sender or to
- one of the memo's recipients.</para>
-
- <figure xml:id="figure_memoref_instance">
- <title>A memo document instance with an internal reference.</title>
-
- <programlisting language="none"><?xml version="1.0" ?>
-<!DOCTYPE memo SYSTEM "memo.dtd">
-<memo date="9.9.2099" priority="high">
- <from id="goik">Martin Goik</from>
- <to>Adam Hacker</to>
- <to id="eve">Eve Intruder</to>
- <subject>Firewall problems</subject>
- <content>
- <para>Thanks for your excellent work.</para>
- <para>Our firewall is definitely broken! This bug has been reported by
- the <link linkend="goik">sender</link>.</para>
- </content>
-</memo></programlisting>
- </figure>
-
- <para>We want to extract the sender's name from an arbitrary <tag
- class="element">memo</tag> document instance. Using <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> this task can be
- accomplished by a script <filename>memo2sender.xsl</filename>:</para>
-
- <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
- version="2.0">
-
- <xsl:output method="text"/>
-
- <xsl:template match="/memo">
- <xsl:value-of select="from"/>
- </xsl:template>
-
-</xsl:stylesheet></programlisting>
-
- <para>Before closer examining this code we first show its effect. We
- need a piece of software called a <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> processor. It
- reads both a <tag>memo</tag> document instance and a style sheet and
- produces the following output:</para>
-
- <programlisting language="none"><computeroutput>[goik@mupter Memoref]$ xml2xml message.xml memo2sender.xsl
-Martin Goik</computeroutput></programlisting>
-
- <para>The result is the sender's name <computeroutput>Martin
- Goik</computeroutput>. We may sketch the transformation
- principle:</para>
-
- <figure xml:id="figure_xsl_principle">
- <title>An <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> processor
- transforming a XML document into a result using a stylesheet</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/xslconvert.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>The executable <filename>xml2xml</filename> defined at the MI
- department is actually a script wrapping the <productname
- xlink:href="http://saxon.sourceforge.net">Saxon XSLT
- processor</productname>. We may also use the Eclipse/Oxygen plugin
- replacing the shell command by a GUI <link
- xlink:href="http://www.oxygenxml.com/doc/ug-editorEclipse/#topics/defining-new-transformation-scenario.html">as
- being described in the corresponding documentation</link>. Next we
- closer examine the <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> example
- code:</para>
-
- <programlisting language="none"><xsl:stylesheet <co
- xml:id="programlisting_helloxsl_stylesheet"/> xmlns:xsl <co
- xml:id="programlisting_helloxsl_namespace_abbv"/> ="http://www.w3.org/1999/XSL/Transform"
- version="2.0" <co xml:id="programlisting_helloxsl_xsl_version"/> >
-
- <xsl:output method="text" <co
- xml:id="programlisting_helloxsl_method_text"/>/>
-
- <xsl:template <co xml:id="programlisting_helloxsl_template"/> match <co
- xml:id="programlisting_helloxsl_match"/> ="/memo">
- <xsl:value-of <co xml:id="programlisting_helloxsl_value-of"/> select <co
- xml:base="" xml:id="programlisting_helloxsl_valueof_select_att"/> ="from" />
- </xsl:template>
-
-</xsl:stylesheet></programlisting>
-
- <calloutlist>
- <callout arearefs="programlisting_helloxsl_stylesheet">
- <para>The element stylesheet belongs the the namespace
- <code>http://www.w3.org/1999/XSL/Transform</code>. This namespace
- is <emphasis>represented</emphasis> by the literal
- <literal>xsl</literal>. As an alternative we might also use <tag
- class="starttag">stylesheet
- xmlns="http://www.w3.org/1999/XSL/Transform"</tag> instead of <tag
- class="starttag">xsl:stylesheet ...</tag>. The value of the
- namespace itself gets defined next.</para>
- </callout>
-
- <callout arearefs="programlisting_helloxsl_namespace_abbv">
- <para>The keyword <code>xmlns</code> is reserved by the <link
- xlink:href="http://www.w3.org/TR/REC-xml-names/">Namespaces in
- XML</link> specification. In <quote>pure</quote> XML the whole
- term <code>xmlns:xsl</code> would simply define an attribute. In
- presence of a namespace aware XML parser however the literal
- <literal>xsl</literal> represents the attribute value <tag
- class="attvalue">http://www.w3.org/1999/XSL/Transform</tag>. This
- value <emphasis>must not</emphasis> be changed! Otherwise a XSL
- converter will fail since it cannot distinguish processing
- instructions from other XML elements. An element <tag
- class="starttag">stylesheet</tag> belonging to a different
- namespace <code>http//someserver.org/SomeNamespace</code> may have
- to be generated.</para>
- </callout>
-
- <callout arearefs="programlisting_helloxsl_xsl_version">
- <para>The <link xlink:href="http://www.w3.org/TR/xslt20">XSL
- standard</link> is still evolving. The version number identifies
- the conformance level for the subsequent code.</para>
- </callout>
-
- <callout arearefs="programlisting_helloxsl_method_text">
- <para>The <tag class="attribute">method</tag> attribute in the
- <link
- xlink:href="http://www.w3.org/TR/xslt20/#element-output"><xsl:output></link>
- element specifies the type of output to be generated. Depending on
- this type we may also define indentation depths and/or encoding.
- Allowed <tag class="attvalue">method</tag> values are:</para>
-
- <glosslist>
- <glossentry>
- <glossterm>text</glossterm>
-
- <glossdef>
- <para>Ordinary text.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>html</glossterm>
-
- <glossdef>
- <para><link
- xlink:href="http://www.w3.org/TR/html4">HTML</link>
- markup.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>xhtml</glossterm>
-
- <glossdef>
- <para><link
- xlink:href="http://www.w3.org/TR/xhtml1">Xhtml</link> markup
- differing from the former by e.g. the closing
- <quote>/></quote> in <tag><img
- src="..."/></tag>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>xml</glossterm>
-
- <glossdef>
- <para>XML code. This is most commonly used to create views
- on or different dialects of a XML document instance.</para>
- </glossdef>
- </glossentry>
- </glosslist>
- </callout>
-
- <callout arearefs="programlisting_helloxsl_template">
- <para>A <tag class="starttag">xsl:template</tag> defines the
- output that will be created for document nodes being defined by a
- selector.</para>
- </callout>
-
- <callout arearefs="programlisting_helloxsl_match">
- <para>The attribute <tag class="attribute">match</tag> tells us
- for which nodes of a document instance the given <tag
- class="starttag">xsl:template</tag> is appropriate. In the given
- example the value <code>/memo</code> tells us that the template is
- only responsible for <tag class="element">memo</tag> nodes
- appearing at top level i.e. being the root element of the document
- instance.</para>
- </callout>
-
- <callout arch=""
- arearefs="programlisting_helloxsl_value-of programlisting_helloxsl_valueof_select_att">
- <para>A <tag class="element">value-of</tag> element writes content
- to the <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> process'
- output. In this example the <code>#PCDATA</code> content from the
- element <tag class="element">from</tag> will be written to the
- output.</para>
- </callout>
- </calloutlist>
- </section>
-
- <section xml:id="xpath">
- <title><link xlink:href="http://www.w3.org/TR/xpath">XPath</link> and
- node sets</title>
-
- <para>The <acronym
- xlink:href="http://www.w3.org/TR/xpath">XPath</acronym> standard
- allows us to retrieve node sets from XML documents by predicate based
- queries. Thus its role may be compared to <acronym
- xlink:href="http://en.wikipedia.org/wiki/Sql">SQL</acronym>
- <code>SELECT</code> ... <code>FROM</code> ...<code>WHERE</code>
- queries. Some simple examples:</para>
-
- <figure xml:id="fig_Xpath">
- <title>Simple <acronym
- xlink:href="http://www.w3.org/TR/xpath">XPath</acronym>
- queries</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/xpath.fig" scale="65"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>We are now interested in a list of all recipients being defined
- in a <tag class="element">memo</tag> element. We introduce the element
- <tag class="element">xsl:for-each</tag> which iterates over a result
- set of nodes:</para>
-
- <figure xml:id="programlisting_tolist_xpath">
- <title>Iterating over the list of recipient nodes.</title>
-
- <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
-
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
- version="2.0">
-
- <xsl:output method="text"/>
-
- <xsl:template match="/" <co xml:id="programlisting_tolist_match_root"/>>
- <xsl:for-each select="memo/to" <co
- xml:id="programlisting_tolist_xpath_memo_to"/> >
- <xsl:value-of select="." <co xml:id="programlisting_tolist_value_of"/> />
- <xsl:text>,</xsl:text> <co
- xml:id="programlisting_tolist_xsl_text"/>
- </xsl:for-each>
- </xsl:template>
-
-</xsl:stylesheet></programlisting>
- </figure>
-
- <calloutlist>
- <callout arearefs="programlisting_tolist_match_root">
- <para>This template matches the XML document instance,
- <emphasis>not</emphasis> the visible <tag
- class="element"><memo></tag> node.</para>
- </callout>
-
- <callout arearefs="programlisting_tolist_xpath_memo_to">
- <para>The <link
- xlink:href="http://www.w3.org/TR/xpath">XPath</link> expression
- <tag class="attvalue">memo/to</tag> gets evaluated starting from
- the invisible top level document node being the context node. For
- the given document instance this will define a result set
- containing both <tag class="element"><to></tag> recipient
- nodes, see <xref linkend="figure_memo_xpath_memo_to"/>.</para>
- </callout>
-
- <callout arearefs="programlisting_tolist_value_of">
- <para>The dot <quote>.</quote> represents the <code>#PCDATA</code>
- content of the current <tag class="element">to</tag>
- element.</para>
- </callout>
-
- <callout arearefs="programlisting_tolist_xsl_text">
- <para>A comma is appended. This is not quite correct since it
- should be absent for the last element.</para>
- </callout>
- </calloutlist>
-
- <figure xml:id="figure_recipientlist_trailing_comma">
- <title>A list of recipients.</title>
-
- <para>The <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> presented
- before yields:</para>
-
- <programlisting language="none"><computeroutput>Adam Hacker,Eve Intruder</computeroutput><emphasis
- role="bold">,</emphasis></programlisting>
- </figure>
-
- <para>Right now we do not bother about the trailing <quote>,</quote>
- after the last recipient. The surrounding
- <code><xsl:text></code>,<code></xsl:text></code> elements
- <emphasis>may</emphasis> be omitted. We encourage the reader to leave
- them in place since they increase readability when a template's body
- gets more complex. The element <tag class="starttag">xsl:text</tag> is
- used to append static text to the output. This way we append a
- separator after each recipient. We now discuss the role of the two
- attributes <tag class="attribute">match="/"</tag> and <tag
- class="attribute">select=memo/to</tag>. Both are examples of so called
- <link xlink:href="http://www.w3.org/TR/xpath">XPath</link>
- expressions. They allow to define <emphasis>node sets</emphasis> being
- subsets from the set of all nodes from a given document
- instance.</para>
-
- <para>Conceptually <link
- xlink:href="http://www.w3.org/TR/xpath">XPath</link> expressions may
- be compared to the <acronym
- xlink:href="http://en.wikipedia.org/wiki/Sql">SQL</acronym> language
- the latter allowing the retrieval of data<emphasis>sets</emphasis>
- from a relational database. We illustrate the current example by a
- figure:</para>
-
- <figure xml:id="figure_memo_xpath_memo_to">
- <title>Selecting node sets from <tag class="element">memo</tag>
- document instances</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/memoxpath.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>This figure needs some explanation. We observe an additional
- node <quote>above</quote> <tag class="starttag">memo</tag> being
- represented as <quote>filled</quote>. This node represents the
- document instance as a whole and has got <tag>memo</tag> as its only
- child. We will rediscover this additional root node when we discuss
- the <abbrev
- xlink:href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407">DOM</abbrev>
- application programming interface.</para>
-
- <para>As already mentioned the expression <code>memo/to</code>
- evaluates to a <emphasis>set</emphasis> of nodes. In our example this
- set consists of two nodes of type <tag class="starttag">to</tag> each
- of them representing a recipient of the memo. We observe a subtle
- difference between the two <abbrev
- xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev>
- expressions:</para>
-
- <glosslist>
- <glossentry>
- <glossterm><code>match="/"</code></glossterm>
-
- <glossdef>
- <para>The expression starts and actually consists of the string
- <quote>/</quote>. Thus it can be called an
- <emphasis>absolute</emphasis> <abbrev
- xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev>
- expression. Like a file specification
- <filename>C:\dos\myprog.exe</filename> it starts on top level
- and needs no further context information to get
- evaluated.</para>
-
- <para>A <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> style
- sheet <emphasis>must</emphasis> have an <link
- xlink:href="http://www.w3.org/TR/xslt20/#initiating">initial
- context node</link> to start the transformation. This is
- achieved by providing exactly one <tag
- class="starttag">xsl:template</tag> with an absolute <abbrev
- xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev> value for
- its <tag class="attribute">match</tag> attribute like <tag
- class="attvalue">/memo</tag>.<emphasis/></para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm><code>select="memo/to"</code></glossterm>
-
- <glossdef>
- <para>This expression can be compared to a
- <emphasis>relative</emphasis> file path specification like e.g.
- <filename>../images/hdm.gif</filename>. We need to add the base
- (context) directory in order for a relative file specification
- to become meaningful. If the base directory is
- <filename>/home/goik/xml</filename> than this
- <emphasis>relative</emphasis> file specification will address
- the file <filename>/home/goik/images/hdm.gif</filename>.</para>
-
- <para>Likewise we have to define a <emphasis>context</emphasis>
- node if we want to evaluate a relative <abbrev
- xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev>
- expression. In our example this is the root node. The XSL
- specification introduces the term <link
- xlink:href="http://www.w3.org/TR/xslt20/#context">evaluation
- context</link> for this purpose.</para>
- </glossdef>
- </glossentry>
- </glosslist>
-
- <para>In order to explain relative <abbrev
- xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev> expressions we
- consider <code>content/para</code> starting from the (unique!) <tag
- class="element">memo</tag> node:</para>
-
- <figure xml:id="memoXpathPara">
- <title>The node set represented by <code>content/para</code>
- starting at the context node <tag
- class="starttag">memo</tag>.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/memorelativexpath.fig"/>
- </imageobject>
-
- <caption>
- <para>The dashed lines represent the relative <abbrev
- xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev>
- expressions starting from the context node to each of the nodes
- in the result set.</para>
- </caption>
- </mediaobject>
- </figure>
- </section>
-
- <section xml:id="xsl_important_elements">
- <title>Some important <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> elements</title>
-
- <section xml:id="xsl_if">
- <title><tag class="starttag">xsl:if</tag></title>
-
- <para>Sometimes we need conditional processing rules. We might want
- create a list of sender and recipients with a defined value for the
- attribute <tag class="attribute">id</tag>. In the <link
- linkend="figure_memoref_instance">given example</link> this is only
- valid for the (unique) sender and the recipient <code><to
- id="eve">Eve Intruder</to></code>. We assume this set of
- persons shall be inserted into a relational database table
- <code>Customer</code> consisting of two <code>NOT NULL</code>
- columns <code>id</code> an <code>name</code>. Thus both attributes
- <emphasis>must</emphasis> be specified and we must exclude <tag
- class="starttag">from</tag> or <tag class="starttag">to</tag> nodes
- with undefined <tag class="attribute">id</tag> attributes:</para>
-
- <figure xml:id="programlisting_memo_export_sql">
- <title>Exporting SQL statements.</title>
-
- <programlisting language="none">...
-<xsl:variable name="newline" <co xml:id="programlisting_xsl_if_definevar"/>> <!-- A newline \n -->
- <xsl:text>
-</xsl:text>
-</xsl:variable>
-
-<xsl:template match="/memo">
- <xsl:for-each select="from|to" <co xml:id="programlisting_xsl_if_foreach"/>>
- <xsl:if <emphasis role="bold">test="@id"</emphasis> <co
- xml:id="programlisting_xsl_if_test"/>>
- <xsl:text>INSERT INTO Customer (id, name) VALUES ('</xsl:text>
- <xsl:value-of select="@id" <co
- xml:id="programlisting_xsl_if_select_idattrib"/>/>
- <xsl:text>', '</xsl:text>
- <xsl:value-of select="." <co
- xml:id="programlisting_xsl_if_selectcontent"/>/>
- <xsl:text>')</xsl:text>
- <xsl:value-of select="$newline" <co
- xml:id="programlisting_xsl_if_usevar"/>/>
- </xsl:if>
- </xsl:for-each>
-</xsl:template></programlisting>
-
- <caption>
- <para>We want to export data from XML documents to a database
- server. For this purpose INSERT statements are being crafted
- from a XML document containing relevant data.</para>
- </caption>
- </figure>
-
- <calloutlist>
- <callout arearefs="programlisting_xsl_if_definevar">
- <para>Define a file local variable <code>newline</code>. Dealing
- with text output frequently requires the insertion of newlines.
- Due to the syntax of the <tag class="element">xsl:text</tag>
- elements this tends to clutter the code.</para>
- </callout>
-
- <callout arearefs="programlisting_xsl_if_foreach">
- <para>Iterate over the set of the sender node and all recipient
- nodes.</para>
- </callout>
-
- <callout arearefs="programlisting_xsl_if_test">
- <para>The attribute value of <tag class="attribute">test</tag>
- will be <link
- xlink:href="http://www.w3.org/TR/xslt20/#xsl-if">evaluated</link>
- as a boolean. In this example it evaluates to <code>true</code>
- iff the attribute <tag class="attribute">id</tag> is defined for
- the context node. Since we are inside the <tag
- class="element">xsl:for-each</tag> block all context nodes are
- either of type <tag class="starttag">from</tag> or <tag
- class="starttag">to</tag> and thus <emphasis>may</emphasis> have
- an <tag class="attribute">id</tag> attribute.</para>
- </callout>
-
- <callout arearefs="programlisting_xsl_if_select_idattrib">
- <para>The <tag class="attribute">id</tag> attributes value is
- copied to the output. The <quote>@</quote> character in
- <code>select="@id"</code> tells the <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> processor
- to read the value of an <emphasis>attribute</emphasis> with name
- <tag class="attribute">id</tag> rather then the content of a
- nested sub<emphasis>element</emphasis> like in <code><to
- id="foo"><id>I am
- nested!</id></to></code>.</para>
- </callout>
-
- <callout arearefs="programlisting_xsl_if_selectcontent">
- <para>As stated earlier the dot <quote>.</quote> denotes the
- current context element. In this example simply the
- <code>#PCDATA</code> content is copied to the output.</para>
- </callout>
-
- <callout arearefs="programlisting_xsl_if_usevar">
- <para>The <quote>$</quote> sign in front of <code>newline</code>
- tells the <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> processor
- to access the variable <varname>newline</varname> previously
- defined in <coref linkend="programlisting_xsl_if_definevar"/>
- rather then interpreting it as the name of a sub element or an
- attribute.</para>
- </callout>
- </calloutlist>
-
- <para>As expected the recipient entry <quote>Adam Hacker</quote>
- does not appear due to the fact that no <tag
- class="attribute">id</tag> attribute is defined in its <tag
- class="starttag">to</tag> element:</para>
-
- <programlisting language="none"><computeroutput>INSERT INTO Customer (id, name) VALUES ('goik', 'Martin Goik')
-INSERT INTO Customer (id, name) VALUES ('eve', 'Eve intruder')</computeroutput></programlisting>
-
- <qandaset defaultlabel="qanda" xml:id="example_position_last">
- <title>The XPath functions position() and last()</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>We return to our recipient list in <xref
- linkend="figure_recipientlist_trailing_comma"/>. We are
- interested in a list of recipients avoiding the trailing
- comma:</para>
-
- <programlisting language="none"><computeroutput>Adam Hacker,Eve Intruder</computeroutput></programlisting>
-
- <para>We may use a <tag class="element">xsl:if</tag> to
- insert a comma for all but the very last recipient node.
- This can be achieved by using the <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev>
- functions <link
- xlink:href="http://www.w3.org/TR/xpath#function-position">position()</link>
- and <link
- xlink:href="http://www.w3.org/TR/xpath#function-last">last()</link>.
- Hint: The arithmetic operator <quote><</quote> may be
- used in <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> to
- compare two integer numbers. However it must be escaped as
- <code>&lt;</code> in order to be XML compatible.</para>
- </question>
-
- <answer>
- <para>We have to exclude the comma for the last node of the
- recipient list. If we have e.g. 10 recipients the function
- <code>position()</code> will return values integer values
- starting at 1 and ending with 10. So for the last node the
- comparison <code>10 < 10</code> will evaluate to
- false:</para>
-
- <programlisting language="none"><xsl:for-each select="memo/to">
- <xsl:value-of select="."/>
- <xsl:if test="position() &lt; last()">
- <xsl:text>,</xsl:text>
- </xsl:if>
-</xsl:for-each></programlisting>
- </answer>
- </qandaentry>
-
- <qandaentry xml:id="example_avoid_xsl_if">
- <question>
- <label>Avoiding xsl:if</label>
-
- <para>In <xref linkend="programlisting_memo_export_sql"/> we
- used the <abbrev
- xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev> value
- <quote>from|to</quote> to select the desired sender and
- recipient nodes. Inside the <tag
- class="element">xsl:for-each</tag> block we permitted only
- those nodes which have an <tag class="attribute">id</tag>
- attribute. These two steps may be combined into a single
- <abbrev
- xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev>
- expression obsoleting the <tag
- class="element">xsl:if</tag>.</para>
- </question>
-
- <answer>
- <para>We simply need a modified <abbrev
- xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev> in
- the <tag class="element">for-each</tag>:</para>
-
- <programlisting language="none"><xsl:for-each select="<emphasis
- role="bold">from[@id]|to[@id]</emphasis>">
- <xsl:text>INSERT INTO Customer (id, name) VALUES ('</xsl:text>
- <xsl:value-of select="@id"/>
- <xsl:text>', '</xsl:text>
- <xsl:value-of select="."/>
- <xsl:text>')</xsl:text>
- <xsl:value-of select="$newline"/>
-</xsl:for-each></programlisting>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
-
- <section xml:id="xsl_apply_templates">
- <title><tag class="starttag">xsl:apply-templates</tag></title>
-
- <para>We already used <tag class="element">xsl:for-each</tag> to
- iterate over a list of element nodes. <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> offers a
- different possibility for this purpose. The idea is to define the
- formatting rules at a centralized location. So the solution to <xref
- linkend="example_position_last"/> in an equivalent way:</para>
-
- <programlisting language="none"><xsl:template match="/">
- <xsl:apply-templates select="memo/to" <co
- xml:id="programlisting_apply_templates_apply"/>/>
-</xsl:template>
-
-<xsl:template match="to" <co xml:id="programlisting_apply_templates_match"/>>
- <xsl:value-of select="."/>
- <xsl:if test="<emphasis role="bold">position()</emphasis> &lt; <emphasis
- role="bold">last()</emphasis>">
- <xsl:text>,</xsl:text>
- </xsl:if>
-</xsl:template></programlisting>
-
- <calloutlist>
- <callout arearefs="programlisting_apply_templates_apply">
- <para>Definition of the recipient node list. Each element of
- this list shall be processed further.</para>
- </callout>
-
- <callout arearefs="programlisting_apply_templates_match">
- <para>This template <emphasis>may</emphasis> be used by a XSL
- processor to format nodes of type <tag
- class="starttag">to</tag>. Since the processor is asked to do
- exactly this in <xref
- linkend="programlisting_apply_templates_apply"/> the current
- template will <emphasis>really</emphasis> be used in this
- example.</para>
- </callout>
- </calloutlist>
-
- <para>The procedure outlined above may have the following
- advantages:</para>
-
- <itemizedlist>
- <listitem>
- <para>Some elements being central for a DTD may appear at
- different places. For example a <tag
- class="starttag">title</tag> element is likely to appear as a
- child of chapters, sections, tables figures and so on. It may be
- sufficient to define a single template with a
- <code>match="title"</code> attribute which contains all rules
- being required.</para>
- </listitem>
-
- <listitem>
- <para>Sometimes the body of a <tag
- class="starttag">xsl:for-each</tag> ... <tag
- class="endtag">xsl:for-each</tag> spans multiple screens thus
- limiting code readability. Factoring out the body into a
- template may avoid this obstacle.</para>
- </listitem>
- </itemizedlist>
-
- <para>This method is well known from programming languages: If the
- code inside a loop is needed multiple times or reaches a painful
- line count <emphasis>good</emphasis> programmers tend to define a
- separate method. For example:</para>
-
- <programlisting language="none">for (int i = 0; i < 10; i++){
- if (a[i] < b[i]){
- max[i] = b;
- } else {
- max[i] = a;
- }
- ...
-}</programlisting>
-
- <para>Inside the loop's body the relative maximum value of two
- variables gets computed. This may be needed at several locations and
- thus it is convenient to centralize this code into a method:</para>
-
- <programlisting language="none">// cf. <xsl:template match="...">
-static int maximum(int a, int b){
- if (a < b){
- return b;
- } else {
- return a;
- }
-}
-...
-// cf. <xsl:apply-templates select="..."/>
-for (int i = 0; i < 10; i++){
- max[i] = maximum(a[i], b[i]);
-}</programlisting>
-
- <para>So far calling a static method in <link
- linkend="gloss_Java"><trademark>Java</trademark></link> may be
- compared to a <tag class="starttag">xsl:apply-templates</tag>. There
- is however one big difference. In <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> the
- <quote>method</quote> being called may not exist at all. A <tag
- class="starttag">xsl:apply-templates</tag> instructs a processor to
- format a set of nodes. It does not contain information about any
- rules being defined to do this job:</para>
-
- <programlisting language="none"><xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
- version="2.0">
-
- <xsl:output method="text"/>
-
- <xsl:template match="/memo">
- <xsl:apply-templates <emphasis role="bold">select="content"</emphasis>/>
- </xsl:template>
-
-</xsl:stylesheet></programlisting>
-
- <para>Since no suitable template supplying rules for <tag
- class="starttag">content</tag> nodes exists a <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> processor uses
- a default formatting rule instead:</para>
-
- <programlisting language="none"><computeroutput>Thanks for your excellent work.Our firewall is definitely
-broken! This bug has been reported by the sender.</computeroutput></programlisting>
-
- <para>We observe that the <code>#PCDATA</code> content strings of
- the element itself and all (recursive) sub elements get glued
- together into one string. In most cases this is definitely not
- intended. Omitting a necessary template is usually a programming
- error. It is thus good programming practice during style sheet
- development to define a special template catching forgotten
- rules:</para>
-
- <programlisting language="none"><xsl:template match="/memo">
- <xsl:apply-templates select="content"/>
-</xsl:template>
-
-<xsl:template match="*">
- <xsl:message>
- <xsl:text>Error: No template defined matching element '</xsl:text>
- <xsl:value-of select="name(.)"/>
- <xsl:text>'</xsl:text>
- </xsl:message>
-</xsl:template></programlisting>
-
- <para>The <quote>*</quote> matches any element if there is no <link
- xlink:href="http://www.w3.org/TR/xslt20/#conflict">better
- matching</link> rule defined. Since we did not supply any template
- for <tag class="starttag">content</tag> nodes at all this default
- template will match nodes of type <tag
- class="starttag">content</tag>. The function <code>name()</code> is
- predefined in <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> and returns
- the element type name of a node. During the formatting process we
- will now see the following warning message:</para>
-
- <programlisting language="none"><computeroutput>Error: No template defined matching element 'content'</computeroutput></programlisting>
-
- <para>We note that for document nodes <tag
- class="starttag">xyz</tag><code>foo</code><tag
- class="endtag">xyz</tag> containing only <code>#PCDATA</code> a
- simple <tag class="emptytag">xsl:apply-templates select="xyz"</tag>
- is sufficient: A <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> processor uses
- its default rule and copies the node's content <code>foo</code> to
- its output.</para>
-
- <qandaset defaultlabel="qanda" xml:id="example_rdbms_person">
- <title>Extending the export to a RDBMS</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>We assume that our RDBMS table <code>Customer</code>
- from <xref linkend="programlisting_memo_export_sql"/> shall
- be replaced by a table <code>Person</code>. We expect the
- senders of memo documents to be employees of a given
- company. Conversely the recipients of memos are expected to
- be customers. Our <code>Person</code> table shall have a
- <quote>tag</quote> like column named <code>type</code>
- having exactly two allowed values <code>customer</code> or
- <code>employee</code> being controlled by a
- <code>CHECK</code> constraint, see <xref
- linkend="table_person"/>. Create a style sheet generating
- the necessary SQL statements from a memo document instance.
- Hint: Define two different templates for <tag
- class="starttag">from</tag> and <tag
- class="starttag">to</tag> nodes.</para>
- </question>
-
- <answer>
- <para>We define two templates differing only in the static
- string value for a person's type. The relevant <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev>
- portion reads:<programlisting language="none"><xsl:template match="/memo">
- <xsl:apply-templates select="from|to"/>
-</xsl:template>
-
-<xsl:template match="from">
- <xsl:text>INSERT INTO Person (name, type) VALUES('</xsl:text>
- <xsl:value-of select="."/>
- <xsl:text>', <emphasis role="bold">'employee'</emphasis>)</xsl:text>
- <xsl:value-of select="$newline"/>
-</xsl:template>
-
- <xsl:template match="to">
- <xsl:text>INSERT INTO Person (name, type) VALUES('</xsl:text>
- <xsl:value-of select="."/>
- <xsl:text>', <emphasis role="bold">'customer'</emphasis>)</xsl:text>
- <xsl:value-of select="$newline"/>
-</xsl:template></programlisting></para>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
-
- <table xml:id="table_person">
- <title>The Person table</title>
-
- <?dbhtml table-width="30%" ?>
-
- <?dbfo table-width="40%" ?>
-
- <tgroup cols="2">
- <colspec colwidth="3*"/>
-
- <colspec colwidth="2*"/>
-
- <thead>
- <row>
- <entry>name</entry>
-
- <entry>type</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>Martin Goik</entry>
-
- <entry>employee</entry>
- </row>
-
- <row>
- <entry>Adam Hacker</entry>
-
- <entry>customer</entry>
- </row>
-
- <row>
- <entry>Eve intruder</entry>
-
- <entry>customer</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section xml:id="xsl_choose">
- <title><tag class="starttag">xsl:choose</tag></title>
-
- <para>We already described the <tag class="starttag">xsl:if</tag>
- which can be compared to an <code>if(..){...}</code> statement in
- many programming languages. The <tag
- class="starttag">xsl:choose</tag> element can be compared to
- multiple <code>else</code> conditions including an optional final
- <code>else</code> block being reached if all boolean tests
- fail:</para>
-
- <programlisting language="none">if (condition a){
-...//block 1
-} else if (condition b){
-... //block b
-} ...
-...
-else {
- ... //code being reached whan all conditions evaluate to false
-}</programlisting>
-
- <para>We want to generate a list of memo recipient names with roman
- type numeration up to 10. Higher numbers shall be displayed in
- ordinary decimal notation:</para>
-
- <programlisting language="none"><computeroutput>I:Adam Hacker
-II:Eve intruder
-III: ...
-IV: ...
-...</computeroutput></programlisting>
-
- <para>Though <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> offers <link
- xlink:href="http://www.w3.org/TR/xslt20/#convert">a better
- way</link> we may generate these number literals by:</para>
-
- <programlisting language="none"><xsl:template match="/memo">
- <xsl:apply-templates select="to"/>
-</xsl:template>
-
-<xsl:template match="to">
- <xsl:choose>
- <xsl:when test="1 = position()">I</xsl:when>
- <xsl:when test="2 = position()">II</xsl:when>
- <xsl:when test="3 = position()">III</xsl:when>
- <xsl:when test="4 = position()">IV</xsl:when>
- <xsl:when test="5 = position()">V</xsl:when>
- <xsl:when test="6 = position()">VI</xsl:when>
- <xsl:when test="7 = position()">VII</xsl:when>
- <xsl:when test="8 = position()">VIII</xsl:when>
- <xsl:when test="9 = position()">IX</xsl:when>
- <xsl:when test="10 = position()">X</xsl:when>
- <xsl:otherwise>
- <xsl:value-of select="position()"/>
- </xsl:otherwise>
- </xsl:choose>
-
- <xsl:text>:</xsl:text>
- <xsl:value-of select="."/>
- <xsl:value-of select="$newline"/>
-</xsl:template></programlisting>
-
- <para>Note that this conversion is incomplete: If the number in
- question is larger than 10 it will be formatted in ordinary decimal
- style according to the <tag class="starttag">xsl:otherwise</tag>
- clause.</para>
- </section>
-
- <section xml:id="section_html_book">
- <title>A complete HTML formatting example</title>
-
- <para>We now present a series of exercises showing how to format
- <tag class="starttag">book</tag> document instances to XHTML. This
- is done in a step by step manner each time showing correspondent
- code snippets for our <filename>memo.dtd</filename>.</para>
-
- <section xml:id="section_memo_to_list">
- <title>Listing the recipients of a memo</title>
-
- <para>In order to generate a XHTML <link
- xlink:href="http://www.w3.org/TR/html401/struct/lists.html#h-10.2">list</link>
- of all <tag class="starttag">memo</tag> recipients of a memo we
- have to use <tag class="starttag">xsl:output method="xhtml"</tag>
- and embed the required HTML tags in our <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> style
- sheet:</para>
-
- <programlisting language="none"><xsl:output method="xhtml" indent="yes"/>
-
-<xsl:template match="/memo">
- <html>
- <head>
- <title>Recipient list</title>
- </head>
- <body>
- <ul>
- <xsl:apply-templates select="to"/>
- </ul>
- </body>
- </html>
-</xsl:template>
-
-<xsl:template match="to">
- <li>
- <xsl:value-of select="."/>
- </li>
-</xsl:template></programlisting>
-
- <para>Processing this style sheet for a <tag
- class="starttag">memo</tag> document instance yields:</para>
-
- <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
-<html>
- <head>
- <title>Recipient list</title>
- </head>
- <body>
- <ul>
- <li>Adam Hacker</li>
- <li>Eve intruder</li>
- </ul>
- </body>
-</html></programlisting>
-
- <para>The generated Xhtml code does not contain a reference to a
- DTD. We may supply this reference by modifying our <tag
- class="emptytag">xsl:output</tag> directive:</para>
-
- <programlisting language="none"><xsl:output method="xhtml" indent="yes"
- <emphasis role="bold">doctype-public</emphasis>="-//W3C//DTD XHTML 1.0 Strict//EN"
- <emphasis role="bold">doctype-system</emphasis>="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"/></programlisting>
-
- <para>This adds a corresponding header which allows to validate
- the generated HTML:</para>
-
- <programlisting language="none"><!DOCTYPE html
- PUBLIC "<emphasis role="bold">-//W3C//DTD XHTML 1.0 Strict//EN</emphasis>"
- "<emphasis role="bold">http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</emphasis>">
-<html><head> ...</programlisting>
-
- <para>This may be improved further by instructing the XSL
- formatter to use <uri
- xlink:href="http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</uri>
- as default namespace:</para>
-
- <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
-<xsl:stylesheet <emphasis role="bold">xmlns="http://www.w3.org/1999/xhtml"</emphasis>
- xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0">
-
-<xsl:output method="xhtml" indent="yes"
- doctype-public="-//W3C//DTD XHTML 1.0 Strict//EN"
- doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"/>
-
- <xsl:template match="/">
- <html><head> ...
- </xsl:template>
-...
-</xsl:stylesheet></programlisting>
-
- <para>This yields the following output::</para>
-
- <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html
- PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-
-<html <emphasis role="bold">xmlns="http://www.w3.org/1999/xhtml"</emphasis>>
- <head> ...
-</html></programlisting>
-
- <para>The top level element <tag class="element">html</tag> is now
- declared to belong to the namespace
- <code>xmlns="http://www.w3.org/1999/xhtml</code>. This will be
- inherited by all inner Xhtml elements.</para>
-
- <qandaset defaultlabel="qanda" xml:id="example_xsl_book_1_dtd">
- <title>Transforming book instances to Xhtml</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>Create a <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev>
- style sheet to transform instances of the first version of
- <link endterm="example_bookDtd"
- linkend="example_bookDtd">book.dtd</link> (<xref
- linkend="example_bookDtd"/>) into <uri
- xlink:href="http://www.w3.org/TR/xhtml1/#a_dtd_XHTML-1.0-Strict">Xhtml
- 1.0 strict</uri>.</para>
-
- <para>You should first construct a Xhtml document
- <emphasis>manually</emphasis> before coding the XSL. After
- you have a <quote>working</quote> Xhtml example document
- create a <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev>
- style sheet which transforms arbitrary
- <filename>book.dtd</filename> document instances into a
- corresponding Xhtml file.</para>
- </question>
-
- <answer>
- <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0">
-
- <xsl:output indent="yes" method="xhtml"/>
-
- <xsl:template match="/book">
- <html>
- <head>
- <title><xsl:value-of select="title"/></title>
- </head>
- <body>
- <h1><xsl:value-of select="title"/></h1>
- <xsl:apply-templates select="chapter"/>
- </body>
- </html>
- </xsl:template>
-
- <xsl:template match="chapter">
- <h2><xsl:value-of select="title"/></h2>
- <xsl:apply-templates select="para"/>
- </xsl:template>
-
- <xsl:template match="para">
- <p><xsl:value-of select="."/></p>
- </xsl:template>
-
-</xsl:stylesheet></programlisting>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
-
- <section xml:id="section_xsl_attribute">
- <title><tag class="starttag">xsl:attribute</tag></title>
-
- <para>Sometimes we want to set attribute values in a generated XML
- document. For example we might want to set the background color
- <quote>red</quote> if a memo has a priority value of <tag
- class="attvalue">high</tag>:</para>
-
- <programlisting language="none"><h1 style="background:red">Firewall problems</h1></programlisting>
-
- <para>Regarding our memo example this may be achieved by:</para>
-
- <programlisting language="none"><xsl:template match="/memo">
- <html>
- ...
- <body>
- <xsl:variable name="<emphasis role="bold">messageColor</emphasis>" <co
- xml:id="programlisting_priority_lolor_vardef"/>>
- <xsl:choose>
- <xsl:when test="@priority = 'low'">green</xsl:when>
- <xsl:when test="@priority = 'medium'">yellow</xsl:when>
- <xsl:when test="@priority = 'high'">red</xsl:when>
- </xsl:choose>
- </xsl:variable>
- <h1 style="background:{<emphasis role="bold">$messageColor</emphasis>};" <co
- xml:id="programlisting_priority_lolor_usevar"/>>
- <xsl:value-of select="subject"/>
- </h1>
- </body>
- </html>
-</xsl:template></programlisting>
-
- <calloutlist>
- <callout arearefs="programlisting_priority_lolor_vardef">
- <para>Definition of a color name depending on the attribute
- <tag class="attvalue">priority</tag>'s value. The set off
- possible attribute values (low,medium,high) is mapped to the
- color names (green, yellow,red).</para>
- </callout>
-
- <callout arearefs="programlisting_priority_lolor_usevar">
- <para>The color variable is used to compose the attribute <tag
- class="attribute">style</tag>'s value. The curly
- <code>{...}</code> braces are part of the <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev>
- standard's syntax. They are required here to instruct the
- <abbrev xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev>
- processor to substitute the local variable
- <code>messageColor</code>'s value instead of simply copying
- the literal string <quote><code>$messageColor</code></quote>
- itself to the output document e.g. generating <tag
- class="starttag">h1 style =
- "background:$messageColor;"</tag>.</para>
- </callout>
- </calloutlist>
-
- <para>Instead of constructing an extra variable <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> offers a
- slightly more compact way for the same purpose. The <tag
- class="starttag">xsl:attribute</tag> element allows us to define
- the name of an attribute to be added together with an attribute
- value specification:</para>
-
- <programlisting language="none"><xsl:template match="/memo">
- <html>
- ...
- <h1>
- <xsl:attribute name="<emphasis role="bold">style</emphasis>">
- <xsl:text>background:</xsl:text>
- <xsl:choose>
- <xsl:when test="@priority = 'low'">green</xsl:when>
- <xsl:when test="@priority = 'medium'">yellow</xsl:when>
- <xsl:when test="@priority = 'high'">red</xsl:when>
- </xsl:choose>
- </xsl:attribute>
- <xsl:value-of select="subject"/>
- </h1>
- </body>
- </html>
-</xsl:template></programlisting>
-
- <qandaset defaultlabel="qanda" xml:id="example_book_toc">
- <title>Adding a table of contents (toc)</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>For larger document instances it is convenient to
- add a table of contents to the generated Xhtml document.
- <!-- We
- demonstrate the desired result as an <uri
- xlink:href="src/viewlet/bookhtmltoc/bookhtmltoc_viewlet_swf.html">animation</uri>.--></para>
-
- <para>For this exercise you need a unique string value for
- each <tag class="starttag">chapter</tag> node. If a <tag
- class="starttag">chapter</tag>'s <tag
- class="attribute">id</tag> attribute had been declared as
- <code>#REQUIRED</code> its value would do this job
- perfectly. Unfortunately you cannot rely on its existence
- since it is declared to be <code>#IMPLIED</code> and may
- thus be absent.</para>
-
- <para>XSL offers a standard function for this purpose
- namely <link
- xlink:href="http://www.w3.org/TR/xslt20/#generate-id">generate-id(...)</link>.
- In a nutshell this function takes a XML node as an
- argument (or being called without arguments it uses the
- context node) and creates a string value being unique with
- respect to <emphasis>all</emphasis> other nodes in the
- document. For a given node the function may be called
- repeatedly and is guaranteed to always return the same
- value during the <emphasis>same</emphasis> transformation
- run. So it suffices to add something like <tag
- class="starttag">a href="#{generate-id(...)}"</tag> or use
- it in conjunction with <tag
- class="starttag">xsl:attribute</tag>.</para>
- </question>
-
- <answer>
- <para>We use the <code>generate-id()</code> function to
- create a unique identity string for each chapter node.
- Since we also want to define links to the table of
- contents we need another unique string value. It is
- tempting to simply use a static value like
- <quote>__toc__</quote> for this purpose. However we can
- not be sure that this value coincides with one of the
- <code>generate-id()</code> function return values.</para>
-
- <para>A cleaner solution uses the <tag
- class="starttag">book</tag> node's generated identity
- string for this purpose. As stated before this value is
- definitively unique:</para>
-
- <programlisting language="none"><xsl:template match="/book">
-...
- <body>
- <h1><xsl:value-of select="title"/></h1>
- <h2 id="{generate-id(.)}" <co xml:base=""
- xml:id="programlisting_book_toc_def_toc"/>>Table of contents</h2>
- <ul>
- <xsl:for-each select="chapter">
- <li>
- <a href="#{generate-id(.)}" <co xml:base=""
- xml:id="programlisting_book_toc_ref_chap"/>><xsl:value-of select="title"></xsl:value-of></a>
- </li>
- </xsl:for-each>
- </ul>
- <xsl:apply-templates select="chapter"/>
- </body>
- </html>
-</xsl:template>
-
-<xsl:template match="chapter">
- <h2 id="{generate-id(.)}" <co xml:base=""
- xml:id="programlisting_book_toc_def_chap"/>>
- <a href="#{generate-id(/book)}" <co xml:base=""
- xml:id="programlisting_book_toc_ref_toc"/>>
- <xsl:value-of select="title"/>
- </a>
- </h2>
- <xsl:apply-templates select="para"/>
-</xsl:template>
-...</programlisting>
-
- <calloutlist>
- <callout arearefs="programlisting_book_toc_def_toc">
- <para>The current context node is <tag
- class="starttag">book</tag>. We use it as argument to
- <code>generate-id()</code> to create a unique identity
- string.</para>
- </callout>
-
- <callout arearefs="programlisting_book_toc_ref_chap">
- <para>The <tag class="starttag">xsl:for-each</tag>
- iterates over all <tag class="starttag">chapter</tag>
- nodes. We reference the corresponding target nodes
- being created in <xref
- linkend="programlisting_book_toc_def_chap"/>.</para>
- </callout>
-
- <callout arearefs="programlisting_book_toc_def_chap">
- <para>Each <tag class="starttag">chapter</tag>'s
- heading is supplied with a unique identity string
- being referenced from <xref
- linkend="programlisting_book_toc_ref_chap"/>.</para>
- </callout>
-
- <callout arearefs="programlisting_book_toc_ref_toc">
- <para>Clicking on a chapter's title shall take us back
- to the table of contents (toc). So we create a
- hypertext link referencing our toc heading's identity
- string being defined in <xref
- linkend="programlisting_book_toc_def_toc"/>.</para>
- </callout>
- </calloutlist>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
-
- <section xml:id="section_xsl_mixed">
- <title>XSL and mixed content</title>
-
- <para>The subsequent example shows an element <tag
- class="starttag">content</tag> having a mixed content model
- possibly containing <tag class="starttag">url</tag> and <tag
- class="starttag">emphasis</tag> child nodes:</para>
-
- <programlisting language="none"><content>The <emphasis
- role="bold"><url href="http://w3.org/XML">XML</url></emphasis> language
- is <emphasis role="bold"><emphasis>easy</emphasis></emphasis> to learn. However you need
- some <emphasis role="bold"><emphasis>time</emphasis></emphasis>.</content></programlisting>
-
- <para>Embedded element nodes have been set to bold style in order
- to distinguish them from <code>xs:text</code> nodes. A possible
- <acronym>XHtml</acronym> output might look like:</para>
-
- <programlisting language="none"><p>The <emphasis role="bold"><a href="http://w3.org/XML">XML</a>language is<em>easy</em></emphasis> to learn. However you
-need some <emphasis role="bold"><em>time</em></emphasis>.</p></programlisting>
-
- <para>We start with a first version of an <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev>
- template:</para>
-
- <programlisting language="none"> <xsl:template match="content">
- <p>
- <xsl:value-of select="."/>
- </p>
- </xsl:template></programlisting>
-
- <para>As mentioned earlier all <code>#PCDATA</code> text nodes of
- the whole subtree are glued together leading to:</para>
-
- <programlisting language="none"><p>The XML language is easy to learn. However you need some time.</p></programlisting>
-
- <para>Our next attempt is to define templates to format the
- elements <tag class="starttag">url</tag> and <tag
- class="starttag">emphasis</tag>:</para>
-
- <programlisting language="none">...
-<xsl:template match="content">
- <p>
- <xsl:apply-templates select="emphasis|url"/>
- </p>
-</xsl:template>
-
-<xsl:template match="url">
- <a href="{@href}"><xsl:value-of select="."/></a>
-</xsl:template>
-
-<xsl:template match="emphasis">
- <em><xsl:value-of select="."/></em>
-</xsl:template>
-...</programlisting>
-
- <para>As expected the sub elements are formatted correctly.
- Unfortunately the <code>#PCDATA</code> text nodes between the
- element nodes are lost:</para>
-
- <programlisting language="none"><p>
- <a href="http://w3.org/XML">XML</a>
- <em>easy</em>
- <em>time</em>
-</p></programlisting>
-
- <para>To correct this transformation script we have to tell the
- formatting processor to include bare text nodes into the output.
- The <abbrev xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev>
- standard defines a function <link
- xlink:href="http://www.w3.org/TR/xpath#path-abbrev">text()</link>
- for this purpose. It returns the boolean value <code>true</code>
- for an argument node of type text:</para>
-
- <programlisting language="none">...
-<xsl:template match="content">
- <p>
- <xsl:apply-templates select="<emphasis role="bold">text()</emphasis>|emphasis|url"/>
- </p>
-</xsl:template>
-...</programlisting>
-
- <para>The yields the desired output. The text node result elements
- are shown in bold style</para>
-
- <programlisting language="none"><p><emphasis role="bold">The</emphasis> <a href="http://w3.org/XML">XML</a><emphasis
- role="bold"> language is </emphasis><em>easy</em><emphasis
- role="bold"> to learn. However
-you need some </emphasis><em>time</em><emphasis role="bold">.</emphasis></p></programlisting>
-
- <para>Some remarks:</para>
-
- <orderedlist>
- <listitem>
- <para>The <abbrev
- xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev>
- expression <code>select="text()|emphasis|url"</code>
- corresponds nicely to the content model definition in the
- DTD:</para>
-
- <programlisting language="none"><!ELEMENT content (#PCDATA|emphasis|url)*></programlisting>
- </listitem>
-
- <listitem>
- <para>In most mixed content models <emphasis>all</emphasis>
- sub elements of e.g. <tag class="starttag"
- role="">content</tag> have to be formatted. During development
- some of the elements defined in a DTD are likely to be omitted
- by accidence. For this reason the <quote>typical</quote>
- <abbrev xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev>
- expression acting on mixed content models is defined to match
- <emphasis>any</emphasis> sub element nodes:</para>
-
- <programlisting language="none">select="text()|<emphasis
- role="bold">*</emphasis>"</programlisting>
- </listitem>
-
- <listitem>
- <para>Regarding <code>select="text()|emphasis|url"</code> we
- have defined two templates for element nodes <tag
- class="starttag">emphasis</tag> and <tag
- class="starttag">url</tag>. What happens to those text nodes
- being matched by <code>text()</code>? These are subject to a
- default rule: The content of bare text nodes is written to the
- output. We may however redefine this default rule by adding a
- template:</para>
-
- <programlisting language="none"><xsl:template match="text()">
- <emphasis role="bold"><span style="color:red">
- <xsl:value-of select="."/>
- </span></emphasis>
-</xsl:template></programlisting>
-
- <para>This yields:</para>
-
- <programlisting language="none"><p>
- <emphasis role="bold"><span style="color:red">The </span></emphasis>
- <a href="http://w3.org/XML">XML</a>
- <emphasis role="bold"><span style="color:red"> language is </span></emphasis>
- <em>easy</em>
- <emphasis role="bold"><span style="color:red"> to learn. However you need some </span></emphasis>
- <em>time</em>
- <emphasis role="bold"><span style="color:red">.</span></emphasis>
-</p></programlisting>
-
- <para>In most cases it is not desired to replace all text
- nodes throughout the whole document. In the current example we
- might only format text nodes being
- <emphasis>immediate</emphasis> children of <tag
- class="starttag">content</tag>. This may be achieved by
- restricting the <abbrev
- xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev>
- expression to <tag class="starttag">xsl:template
- match="content/text()"</tag>.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section xml:id="section_xsl_functionid">
- <title>The function <code>id()</code></title>
-
- <para>In <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> we sometimes
- want to lookup nodes by an attribute value of type <link
- xlink:href="???">ID</link>. We consider our product catalog from
- <xref linkend="sectSchemaProductCatalog"/>. The following <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> may be used
- to create <acronym>XHtml</acronym>l documents from <tag
- class="starttag">catalog</tag> instances:</para>
-
- <programlisting language="none" xml:lang=""><xsl:template match="/catalog">
- <html>
- <head><title>Product catalog</title></head>
- <body>
- <h1>List of Products</h1>
- <xsl:apply-templates select="product"/>
- </body>
- </html>
-</xsl:template>
-
-<xsl:template match="product">
- <h2 id="{@id}" <co xml:base=""
- xml:id="programlisting_catalog2html_v1_defid"/>><xsl:value-of select="title"/></h2>
- <xsl:apply-templates select="para"/>
-</xsl:template>
-
-<xsl:template match="para">
- <p><xsl:apply-templates select="text()|*" <co
- xml:id="programlisting_catalog2html_v1_mixed"/>/></p>
-</xsl:template>
-
-<xsl:template match="link">
- <a href="#{@ref}" <co xml:id="programlisting_catalog2html_v1_refid"/>><xsl:value-of select="."/></a>
-</xsl:template></programlisting>
-
- <calloutlist>
- <callout arearefs="programlisting_catalog2html_v1_defid">
- <para>The <code>ID</code> attribute <tag
- class="starttag">product id="foo"</tag> is unique within the
- document instance. We may thus use it as an unique string
- value in the generated Xhtml, too.</para>
- </callout>
-
- <callout arearefs="programlisting_catalog2html_v1_mixed">
- <para>Mixed content consisting of text and <tag
- class="starttag">link</tag> nodes.</para>
- </callout>
-
- <callout arearefs="programlisting_catalog2html_v1_refid">
- <para>We define a file local Xhtml reference to a
- product.</para>
- </callout>
- </calloutlist>
-
- <para>The <tag class="starttag">para</tag> element from the
- example document instance containing a <tag class="starttag">link
- ref="homeTrainer"</tag> reference will be formatted as:</para>
-
- <programlisting language="none"><p>If you hate rain look <a href="#homeTrainer">here</a>.</p></programlisting>
-
- <para>Now suppose we want to add the product's title
- <emphasis>Home trainer</emphasis> here to give the reader an idea
- about the product without clicking the hypertext link:</para>
-
- <programlisting language="none"><p>If you hate rain look <a href="#homeTrainer">here</a> <emphasis
- role="bold">(Home trainer)</emphasis>.</p></programlisting>
-
- <para>This title text node is part of the <tag
- class="starttag">product</tag>node being referenced from the
- current <tag class="starttag">para</tag>:</para>
-
- <figure xml:id="linkIdrefProduct">
- <title>A graphical representation of our <tag
- class="starttag">catalog</tag>.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/xsl_id.fig"/>
- </imageobject>
-
- <caption>
- <para>The dashed line shows the <code>IDREF</code> based
- reference from the <tag class="starttag">link</tag> to the
- <tag class="starttag">product</tag> node.</para>
- </caption>
- </mediaobject>
- </figure>
-
- <para>In <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> we may
- follow <code>ID</code> reference by means of the built in function
- <link
- xlink:href="http://www.w3.org/TR/xpath#function-id">id(...)</link>:</para>
-
- <programlisting language="none"><xsl:template match="link">
- <a href="#{@ref}"><xsl:value-of select="."/></a>
- <xsl:text> (</xsl:text>
- <xsl:value-of select="<emphasis role="bold">id(@ref)</emphasis>/title" <co
- xml:id="programlisting_xsl_id_follow"/>/>
- <xsl:text>)</xsl:text>
-</xsl:template></programlisting>
-
- <para>Evaluating <code>id(@ref)</code> at <xref
- linkend="programlisting_xsl_id_follow"/> returns the first <tag
- class="starttag">product</tag> <emphasis>node</emphasis>. We
- simply take its <tag class="starttag">title</tag> value and embed
- it into a pair of braces. This way the desired text portion
- <emphasis role="bold">(Home trainer)</emphasis> gets added after
- the hypertext link.</para>
-
- <qandaset defaultlabel="qanda" xml:id="example_book_xsl_mixed">
- <title>Extending the memo style sheet by mixed content and
- itemized lists</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>In <xref linkend="example_book.dtd_v5"/> we
- constructed a DTD allowing itemized lists an mixed content
- for <tag class="starttag">book</tag> instances. This DTD
- also allowed to define <tag
- class="starttag">emphasis</tag>, <tag
- class="starttag">table</tag> and <tag
- class="starttag">link</tag> elements being part of a mixed
- content definition. Extend the current book2html.xsl to
- account for these extensions.</para>
-
- <para
- xlink:href="http://www.w3.org/TR/xslt20/#element-copy-of">As
- we already saw in our memo example itemized lists in Xhtml
- are represented by the element <tag
- class="starttag">ul</tag> containing <tag
- class="starttag">li</tag> elements. Since <tag
- class="starttag">p</tag> elements are also allowed to
- appear as children our itemized lists can be easily mapped
- to Xhtml tags. A<tag class="starttag">link</tag> node may
- be transformed into <tag class="starttag">a
- href="..."</tag> Xhtml node.</para>
-
- <para>The table model is a simplified version of the Xhtml
- table model. Read the <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev>
- documentation of the element <tag
- class="emptytag">xsl:copy-of</tag> at <link
- xlink:href="http://www.w3.org/TR/xslt20/#element-copy-of">copy-of</link>
- for processing tables.</para>
- </question>
-
- <answer>
- <para>The full source code of the solution is available at
- <link
- xlink:href="Ref/src/Dtd/book/v5/book2html.1.xsl">(Online
- HTML version) ... book2html.1.xsl</link>. We discuss some
- important aspects. The following table provides mapping
- rules from <filename>book.dtd</filename> to Xhtml:</para>
-
- <table xml:id="table_book2xhtml_element_mappings">
- <title>Mapping elements from
- <filename>book.dtd</filename> to Xhtml</title>
-
- <?dbhtml table-width="50%" ?>
-
- <?dbfo table-width="50%" ?>
-
- <tgroup cols="2">
- <colspec colwidth="3*"/>
-
- <colspec colwidth="2*"/>
-
- <thead>
- <row>
- <entry>book.dtd</entry>
-
- <entry>Xhtml</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><tag class="starttag">book</tag>/<tag
- class="starttag">title</tag></entry>
-
- <entry><tag class="starttag">h1</tag></entry>
- </row>
-
- <row>
- <entry><tag class="starttag">chapter</tag>/<tag
- class="starttag">title</tag></entry>
-
- <entry><tag class="starttag">h2</tag></entry>
- </row>
-
- <row>
- <entry><tag class="starttag">para</tag> (mixed
- content)</entry>
-
- <entry><tag class="starttag">p</tag></entry>
- </row>
-
- <row>
- <entry><tag class="starttag">link
- href="foo"</tag></entry>
-
- <entry><tag class="starttag">a
- href="foo"</tag></entry>
- </row>
-
- <row>
- <entry><tag class="starttag">emphasis</tag></entry>
-
- <entry><tag class="starttag">em</tag></entry>
- </row>
-
- <row>
- <entry><tag
- class="starttag">itemizedlist</tag></entry>
-
- <entry><tag class="starttag">ul</tag></entry>
- </row>
-
- <row>
- <entry><tag class="starttag">listitem</tag></entry>
-
- <entry><tag class="starttag">li</tag></entry>
- </row>
-
- <row>
- <entry><tag class="starttag">table</tag>, <tag
- class="starttag">caption</tag>,<tag
- class="starttag">tr</tag>, <tag
- class="starttag">td</tag> along with all
- attributes</entry>
-
- <entry>Identity copy</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>Since our table model is a subset of the HTML table
- model we may simply copy corresponding nodes to the
- output:</para>
-
- <programlisting language="none"><xsl:template match="table">
- <xsl:copy-of select="."/>
-</xsl:template></programlisting>
-
- <para>Next we need rules for itemized lists and
- paragraphs. Our model already implements lists in a way
- that closely resembles XHTML lists. Since the structure
- are compatible we only have to provide a mapping:</para>
-
- <programlisting language="none"><xsl:template match="para">
- <p id="{generate-id(.)}"><xsl:apply-templates select="text()|*" /></p>
-</xsl:template>
-
-<xsl:template match="itemizedlist">
- <ul><xsl:apply-templates select="listitem"/></ul>
-</xsl:template>
-
-<xsl:template match="listitem">
- <li><xsl:apply-templates select="*"/></li>
-</xsl:template></programlisting>
-
- <para>Since <emphasis>all</emphasis> chapters are
- reachable via hypertext links from the table of contents
- we <emphasis>must</emphasis> supply a unique
- <code>id</code> value <xref
- linkend="programlisting_book2html_single_chapterid"/> for
- <emphasis>all</emphasis> of them. Chapters and paragraphs
- may be referenced by <tag class="starttag">link</tag>
- elements and thus <emphasis>both</emphasis> need a unique
- identity value. For simplicity we create both of them via
- <code>generate-id()</code>. In a more sophisticated
- solution the strategy would be slightly different:</para>
-
- <itemizedlist>
- <listitem>
- <para>If a <tag class="starttag">chapter</tag> node
- does have an <code>id</code> attribute defined then
- take its value.</para>
- </listitem>
-
- <listitem>
- <para>If a <tag class="starttag">chapter</tag> node
- does <emphasis>not</emphasis> have an <code>id</code>
- attribute defined then use
- <code>generate-id()</code>.</para>
- </listitem>
-
- <listitem>
- <para><tag class="starttag">para</tag> nodes only get
- values in XHTML if they do have an <code>id</code>
- attribute defined. This is consistent since these
- nodes are never referenced from the table of contents.
- Thus an identity is only required if the <tag
- class="starttag">para</tag> node is referenced by a
- <tag class="starttag">link</tag>. If that is a case
- the <tag class="starttag">para</tag> surely does have
- a defined identity value.</para>
- </listitem>
- </itemizedlist>
-
- <para>We also have to provide a hypertext link <xref
- linkend="programlisting_book2html_single_toclink"/> to the
- table of contents:</para>
-
- <programlisting language="none"><xsl:template match="chapter">
- <h2 id="{<emphasis role="bold">generate-id(.)</emphasis>}" <co
- xml:base=""
- xml:id="programlisting_book2html_single_chapterid"/>>
- <a href="#{<emphasis role="bold">generate-id(/book)</emphasis>}" <co
- xml:base=""
- xml:id="programlisting_book2html_single_toclink"/>><xsl:value-of select="title"/></a>
- </h2>
- <xsl:apply-templates select="para|itemizedlist|table"/>
-</xsl:template></programlisting>
-
- <para>Implementing the <tag class="starttag">link</tag>
- element is somewhat more complicated. We cannot use the
- <code>@ref</code> attribute values itself as <tag
- class="starttag">a href="..."</tag> attribute values since
- the target's identity string is generated via
- <code>generate-id()</code>. But we may follow the
- reference via the <abbrev
- xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev>
- <link linkend="section_xsl_functionid">id()</link>
- function and then use the target's identity value:</para>
-
- <programlisting language="none"><xsl:template match="link">
- <a href="#{generate-id(id(@linkend))}">
- <xsl:value-of select="."/>
- </a>
-</xsl:template></programlisting>
-
- <para>The call to <code>id(@linkend)</code> returns either
- a <tag class="starttag">chapter</tag> or a <tag
- class="starttag">para</tag> node since according to the
- DTD attributes of type <code>ID</code> are only defined
- for these two elements. Using this node as input to
- <code>generate-id()</code> returns the desired identity
- value for the generated Xhtml.</para>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
-
- <section xml:id="xslAxis">
- <title>XSL axis definitions</title>
-
- <para>XSL allows us to traverse a document instance's graph in
- different directions. We start with a memo document
- instance:</para>
-
- <programlisting language="none"><!DOCTYPE memo SYSTEM "memo.dtd">
-<memo date="9.9.2099">
- <from>Joe</from>
- <to>Jack</to>
- <to>Eve</to>
- <to>Jude</to>
- <to>Tolstoi</to>
- <subject>Ignore me!</subject>
- <content>
- <para>Dumb text.</para>
- </content>
-</memo></programlisting>
-
- <para>This instance defines four nodes of type <tag
- class="starttag">to</tag>. For each of these we want to create a
- line of text showing also the preceding and the following
- recipients:</para>
-
- <programlisting language="none"> <----Jack----> Eve Jude Tolstoi <co
- xml:id="programlisting_axis_jack"/>
-Jack <----Eve----> Jude Tolstoi <co xml:id="programlisting_axis_eve"/>
-Jack Eve <----Jude----> Tolstoi <co xml:id="programlisting_axis_jude"/>
-Jack Eve Jude <----Tolstoi----> <co
- xml:id="programlisting_axis_tolstoi"/></programlisting>
-
- <calloutlist>
- <callout arearefs="programlisting_axis_jack">
- <para>Jack has no predecessor and 3 successors</para>
- </callout>
-
- <callout arearefs="programlisting_axis_eve">
- <para>Eve has 1 predecessor and 2 successors</para>
- </callout>
-
- <callout arearefs="programlisting_axis_jude">
- <para>Jude has 2 predecessors and 1 successor</para>
- </callout>
-
- <callout arearefs="programlisting_axis_tolstoi">
- <para><personname>Tolstoi</personname> has 3 predecessors and
- no successor</para>
- </callout>
- </calloutlist>
-
- <para>XSL supports this type of transformation by supplying
- <acronym xlink:href="http://www.w3.org/TR/xpath">XPath</acronym>
- axis definitions. We consider a memo document with 9 <tag
- class="starttag">to</tag> nodes:</para>
-
- <figure xml:id="memo9recipients">
- <title>A memo with 9 recipients</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/memofour.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>We marked the 4-th recipient to represent the context node.
- All three <tag class="starttag">to</tag> nodes to the
- <quote>left</quote> belong to the <emphasis>set</emphasis> of
- preceding siblings with respect to the context node. Likewise the
- 5 neighbours to the right are called following siblings. Returning
- to our <quote>four recipient</quote> example we may create the
- desired output by:</para>
-
- <programlisting language="none"><xsl:template match="/">
- <xsl:apply-templates select="memo/to"/>
-</xsl:template>
-
-<xsl:template match="to">
-
- <xsl:for-each select="preceding-sibling::to" <co
- xml:id="programlisting_memo_four_xsl_preceding"/>>
- <xsl:value-of select="."/>
- <xsl:text> </xsl:text>
- </xsl:for-each>
-
- <xsl:text> &lt;----</xsl:text>
- <xsl:value-of select="."/> <co
- xml:id="programlisting_memo_four_xsl_context"/>
- <xsl:text>----&gt; </xsl:text>
-
- <xsl:for-each select="following-sibling::to"> <co
- xml:id="programlisting_memo_four_xsl_following"/>
- <xsl:value-of select="."/>
- <xsl:text> </xsl:text>
- </xsl:for-each>
- <xsl:value-of select="$newline"/>
-</xsl:template></programlisting>
-
- <calloutlist>
- <callout arearefs="programlisting_memo_four_xsl_preceding">
- <para>Iterate on the set of recipients <quote>left</quote> of
- the context node.</para>
- </callout>
-
- <callout arearefs="programlisting_memo_four_xsl_context">
- <para>Taking the context node's value embedded in
- <code><---- ... ----></code>.</para>
- </callout>
-
- <callout arearefs="programlisting_memo_four_xsl_following">
- <para>Iterate on the set of recipients <quote>right</quote> of
- the context node.</para>
- </callout>
- </calloutlist>
-
- <para>More formally the set of preceding siblings is defined to be
- the set of all nodes having the same parent as the context node
- and appearing <quote>before</quote> the context node. The notion
- <quote>before</quote> is meant in the sense of a <link
- xlink:href="http://en.wikipedia.org/wiki/Depth-first_search">depth-first</link>
- traversal of the document tree. <abbrev
- xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev> provides
- different axis definitions, see <uri
- xlink:href="http://www.w3.org/TR/xpath#axes">http://www.w3.org/TR/xpath#axes</uri>
- for details. We provide an illustration here:</para>
-
- <figure xml:id="disjointAxeSets">
- <title>Disjoint <acronym
- xlink:href="http://www.w3.org/TR/xpath">XPath</acronym> axis
- definitions.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/preceding.fig"/>
- </imageobject>
-
- <caption>
- <para>The sets defined by ancestor, descendant, following,
- preceding and self are disjoint. Their union forms the set
- of all document nodes.</para>
- </caption>
- </mediaobject>
- </figure>
-
- <para>Some remarks:<itemizedlist>
- <listitem>
- <para>If the context node is already the topmost node i.e.
- the root node then the sets defined by <code>ancestor</code>
- and <code>parent</code> are empty.</para>
- </listitem>
-
- <listitem>
- <para>The <code>parent</code> set
- <emphasis>always</emphasis> contains zero or one
- node.</para>
- </listitem>
- </itemizedlist></para>
- </section>
-
- <section xml:id="xslChunking">
- <title>Splitting documents into chunks</title>
-
- <para>Sometimes we want to generate multiple output documents from
- a single XML source. It may for example be a bad idea to transform
- a book of 200 printed pages into a <emphasis>single</emphasis>
- online HTML page. Instead we may split each chapter into a
- separate HTML file and create navigation links between
- them.</para>
-
- <para>We consider a memo document instance. We want to generate
- one text file for each memo recipient containing just the
- recipient's name using the <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> element
- <link
- xlink:href="http://www.w3.org/TR/xslt20/#element-result-document"><xsl:result-document></link>:</para>
-
- <programlisting language="none"><xsl:template match="/memo">
- <xsl:apply-templates select="to"/>
-</xsl:template>
-
-<xsl:template match="to">
- <emphasis role="bold"><xsl:result-document</emphasis>
- <co xml:id="programlisting_xsl_result_document_main"/>
- <emphasis role="bold">href="file_{position()}.txt"</emphasis>
- <co xml:id="programlisting_xsl_result_document_href"/>
- <emphasis role="bold">method="text"</emphasis>
- <co xml:id="programlisting_xsl_result_document_method"/>>
- <xsl:value-of select="."/> <co
- xml:id="programlisting_xsl_result_document_content"/>
-
- <emphasis role="bold"></xsl:result-document></emphasis>
-</xsl:template></programlisting>
-
- <calloutlist>
- <callout arearefs="programlisting_xsl_result_document_main">
- <para>The output from all generating <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev>
- directives will be redirected from standard output to another
- output channel.</para>
- </callout>
-
- <callout arearefs="programlisting_xsl_result_document_href">
- <para>The output will be written to a file named
- <filename>file_i.txt</filename> with decimal number
- <code>i</code> ranging from value 1 up to the number of
- recipients.</para>
- </callout>
-
- <callout arearefs="programlisting_xsl_result_document_method">
- <para>The <code>method</code> attribute possibly overrides a
- value being given in the <tag
- class="starttag">xsl:output</tag> element. We may also
- redefine <link
- xlink:href="http://www.w3.org/TR/xslt20/#element-result-document">other
- attributes</link> from <tag class="starttag">xsl:output</tag>
- like <code>doctype-{public.system}</code> and the generated
- file's <code>encoding</code>.</para>
- </callout>
-
- <callout arearefs="programlisting_xsl_result_document_content">
- <para>All output being generated in this region gets
- redirected to the channel specified in <xref
- linkend="programlisting_xsl_result_document_href"/>.</para>
- </callout>
- </calloutlist>
-
- <qandaset defaultlabel="qanda" xml:id="example_book_chunk">
- <title>Splitting book into chapter files</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>Extend your solution of <xref
- linkend="example_book_xsl_mixed"/> by writing each <tag
- class="starttag">chapter</tag>'s content into a separate
- Xhtml file. In addition create a file
- <filename>index.html</filename> which contains references
- to the corresponding <tag class="starttag">chapter</tag>
- documents. Thus for a document instance with two chapters
- the overall navigation structure is illustrated by <xref
- linkend="figure_book_navigation"/>.</para>
-
- <para>Implementing the <tag class="starttag">link</tag>
- tag may cause a problem: An internal link may reference a
- <tag class="starttag">para</tag>. You need to identify the
- <tag class="starttag">chapter</tag> node embedding this
- para. This may be done by using a suitable <abbrev
- xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev>
- axis direction.</para>
- </question>
-
- <answer>
- <para>The full source code of the solution is available at
- <link
- xlink:href="Ref/src/Dtd/book/v5/book2chunks.1.xsl">(Online
- HTML version) ... book2chunks.1.xsl</link>. First we
- generate the table of contents file
- <filename>index.html</filename>:</para>
-
- <programlisting language="none"><xsl:template match="/">
- <xsl:result-document href="index.html">
- <xsl:apply-templates select="book"/>
- </xsl:result-document>
-
- <xsl:for-each select="book/chapter">
- <xsl:result-document href="{generate-id(.)}.html">
- <xsl:apply-templates select="."/>
- </xsl:result-document>
- </xsl:for-each>
-</xsl:template>
-
-<xsl:template match="book">
- <html>
- <head><title><xsl:value-of select="title"/></title></head>
- <body>
- <h1><xsl:value-of select="title"/></h1>
- <h2>Table of contents</h2>
- <ul>
- <xsl:for-each select="<emphasis role="bold">chapter</emphasis>">
- <li><a href="{<emphasis role="bold">generate-id(.)</emphasis>}.html"><xsl:value-of select="title"/></a></li>
- </xsl:for-each>
- </ul>
- </body>
- </html>
-</xsl:template></programlisting>
-
- <para>The <tag class="starttag">link ref="..."</tag> may
- reference a <tag class="starttag">chapter</tag> or a <tag
- class="starttag">para</tag>. So we may need to <quote>step
- up</quote> from a paragraph to the corresponding chapter
- node:</para>
-
- <programlisting language="none"><xsl:template match="link">
- <xsl:variable name="reftargetNode" select="id(@linkend)"/>
- <xsl:variable name="reftargetParentChapter"
- select="$reftargetNode/ancestor-or-self::chapter"/>
-
- <a href="{generate-id($reftargetParentChapter)}.html#{
- generate-id($reftargetNode)}">
- <xsl:value-of select="."/>
- </a>
-</xsl:template></programlisting>
-
- <para>This is consistent since <emphasis>all</emphasis>
- <tag class="starttag">p</tag> nodes in the generated Xhtml
- receive a unique <code>id</code> value regardless whether
- the originating <tag class="starttag">para</tag> node does
- have one.</para>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
-
- <figure xml:id="figure_book_navigation">
- <title>A <tag class="starttag">book</tag> document with two
- chapters</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/booknavigate.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
- </section>
- </section>
- </section>
- </chapter>
-
- <chapter xml:id="xmlApis">
- <title><abbrev
- xlink:href="http://en.wikipedia.org/wiki/Api">API</abbrev>s for XML
- document processing</title>
-
- <section xml:id="sax">
- <title>The Simple API for XML</title>
-
- <section xml:id="saxPrinciple">
- <title>The principle of a <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym>
- application</title>
-
- <para>We are already familiar with transformations of XML document
- instances to other formats. Sometimes the capabilities being offered
- by a given transformation approach do not suffice for a given
- problem. Obviously a general purpose programming language like <link
- linkend="gloss_Java"><trademark>Java</trademark></link> offers
- superior means to perform advanced manipulations of XML document
- trees.</para>
-
- <para>Before diving into technical details we present an example
- exceeding the limits of our present transformation capabilities. We
- want to format an XML catalog document with article descriptions to
- HTML. The price information however shall resides in a XML document
- external database namely a RDBMS:</para>
-
- <figure xml:id="saxRdbmsAccessPrinciple">
- <title>Generating HTML from a XML document and an RDBMS.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/saxxmlrdbms.fig" scale="65"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>Our catalog might look like:</para>
-
- <figure xml:id="simpleCatalog">
- <title>A <link linkend="gloss_XML"><abbrev>XML</abbrev></link>
- based catalog.</title>
-
- <programlisting language="none"><catalog>
- <item orderNo="<emphasis role="bold">3218</emphasis>">Swinging headset</item>
- <item orderNo="<emphasis role="bold">9921</emphasis>">200W Stereo Amplifier</item>
-</catalog></programlisting>
- </figure>
-
- <para>The RDBMS may hold some relation with a field
- <code>orderNo</code> as primary key and a corresponding attribute
- like <code>price</code>. In a real world application
- <code>orderNo</code> should probably be an integer typed
- <code>IDENTITY</code> attribute.</para>
-
- <figure xml:id="saxRdbmsSchema">
- <title>A Relation containing price information.</title>
-
- <programlisting language="none">CREATE TABLE Product (
- orderNo CHAR(10) PRIMARY KEY
- ,price Money
-)
-
-INSERT INTO Product VALUES('<emphasis role="bold">3218</emphasis>', 42.57)
-INSERT INTO Product VALUES('<emphasis role="bold">9921</emphasis>', 121.50)</programlisting>
-
- <caption>
- <para>Prices are depending on article numbers.</para>
- </caption>
- </figure>
-
- <para>The intended HTML output with order numbers being highlighted
- looks like:</para>
-
- <figure xml:id="saxPriceOut">
- <title>HTML generated output.</title>
-
- <programlisting language="none"><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
- <html>
- <head><title>Available products</title></head>
- <body>
- <table border="1">
- <tbody>
- <tr>
- <th><emphasis role="bold">Order number</emphasis></th>
- <th>Price</th>
- <th>Product</th>
- </tr>
- <tr>
- <td><emphasis role="bold">3218</emphasis></td>
- <td>42,57</td>
- <td>Swinging headset</td>
- </tr>
- <tr>
- <td><emphasis role="bold">9921</emphasis></td>
- <td>121,50</td>
- <td>200W Stereo Amplifier</td>
- </tr>
- </tbody>
- </table>
- </body>
- </html></programlisting>
-
- <caption>
- <para>This result HTML document contains content both from our
- XML document an from the database table
- <code>Product</code>.</para>
- </caption>
- </figure>
-
- <para>The intended transformation is beyond the XSLT standard's
- processing capabilities: XSLT does not enable us to RDBMS content.
- However some XSLT processors provide extensions for this
- task.</para>
-
- <para>It is tempting to write a <link
- linkend="gloss_Java"><trademark>Java</trademark></link> application
- which might use e.g. <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- for database access. But how do we actually read and parse a XML
- file? Sticking to the <link
- linkend="gloss_Java"><trademark>Java</trademark></link> standard we
- might use a <link
- xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/java/io/FileInputStream.html">FileInputStream</link>
- instance to read from <code>catalog.xml</code> and write a XML
- parser by ourself. Fortunately <orgname>SUN</orgname>'s <trademark
- xlink:href="http://www.oracle.com/technetwork/java/javase">JDK</trademark>
- already includes an API denoted <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym>, the
- <emphasis>S</emphasis>imple <emphasis>A</emphasis>pi for
- <emphasis>X</emphasis>ml. The<productname
- xlink:href="http://www.oracle.com/technetwork/java/javase/jdk-7-readme-429198.html">JDK</productname>
- also includes a corresponding parser implementation. In addition
- there are third party <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> parser
- implementations available like <productname
- xlink:href="http://xerces.apache.org">Xerces</productname> from the
- <orgname xlink:href="http://www.apache.org">Apache
- Foundation</orgname>.</para>
-
- <para>The <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> API is event
- based and will be illustrated by the relationship between customers
- and a software vendor company:</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/updateinfo.fig"/>
- </imageobject>
- </mediaobject>
-
- <para>After purchasing software customers are asked to register
- their software. This way the vendor receives the customer's address.
- Each time a new release is being completed all registered customers
- will receive a notification typically including a <quote>special
- offer</quote> to upgrade their software. From an abstract point of
- view the following two actions take place:</para>
-
- <variablelist>
- <varlistentry>
- <term>Registration</term>
-
- <listitem>
- <para>The customer registers itself at the company's site
- indicating it's interest in updated versions.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notification</term>
-
- <listitem>
- <para>Upon completion of each new software release (considered
- to be an <emphasis>event</emphasis>) a message is sent to all
- registered customers.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>The same principle applies to GUI applications in software
- development. A key press <emphasis>event</emphasis> for example will
- be forwarded by an application's <emphasis>event handler</emphasis>
- to a callback function (sometimes called a
- <emphasis>handler</emphasis> method) being implemented by an
- application developer. The <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> API works the
- same way: A parser reads a XML document generating events which
- <emphasis>may</emphasis> be handled by an application. During
- document parsing the XML tree structure gets
- <quote>flattened</quote> to a sequence of events:</para>
-
- <figure xml:id="saxFlattenEvent">
- <title>Parsing a XML document creates a corresponding sequence of
- events.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/saxmodel.pdf"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>An application may register components to the parser:</para>
-
- <figure xml:id="figureSax">
- <title><acronym
- xlink:href="http://www.saxproject.org">SAX</acronym>
- Principle</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/saxapparch.pdf"/>
- </imageobject>
-
- <caption>
- <para>A <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym>
- application consists of a <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> parser
- and an implementation of event handlers being specific to the
- application. The application is developed by implementing the
- two handlers.</para>
- </caption>
- </mediaobject>
- </figure>
-
- <para>An Error Handler is required since the XML stream may contain
- errors. In order to implement a <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> application we
- have to:</para>
-
- <orderedlist>
- <listitem>
- <para>Instantiate required objects:</para>
-
- <itemizedlist>
- <listitem>
- <para>Parser</para>
- </listitem>
-
- <listitem>
- <para>Event Handler</para>
- </listitem>
-
- <listitem>
- <para>Error Handler</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>Register handler instances</para>
-
- <itemizedlist>
- <listitem>
- <para>register Event Handler to Parser</para>
- </listitem>
-
- <listitem>
- <para>register Error Handler to Parser</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>Start the parsing process by calling the parser's
- appropriate method.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section xml:id="saxIntroExample">
- <title>First steps</title>
-
- <para>Our first <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> toy application
- <classname>sax.stat.v1.ElementCount</classname> shall simply count
- the number of elements it finds in an arbitrary XML document. In
- addition the <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> events shall be
- written to standard output generating output sketched in <xref
- linkend="saxFlattenEvent"/>. The application's central
- implementation reads:</para>
-
- <figure xml:id="saxElementCount">
- <title>Counting XML elements.</title>
-
- <programlisting language="none">package sax.stat.v1;
-...
-
-public class ElementCount {
-
- public void parse(final String uri) {
- try {
- final SAXParserFactory saxPf = SAXParserFactory.newInstance();
- final SAXParser saxParser = saxPf.newSAXParser();
- saxParser.parse(uri, eventHandler);
- } catch (ParserConfigurationException e){
- e.printStackTrace(System.err);
- } catch (org.xml.sax.SAXException e) {
- e.printStackTrace(System.err);
- } catch (IOException e){
- e.printStackTrace(System.err);
- }
- }
-
- public int getElementCount() {
- return eventHandler.getElementCount();
- }
- private final MyEventHandler eventHandler = new MyEventHandler();
-}</programlisting>
-
- <caption>
- <para>This application works for arbitrary well-formed XML
- documents.</para>
- </caption>
- </figure>
-
- <para>We now explain this application in detail. The first part
- deals with the instantiation of a parser:</para>
-
- <programlisting language="none">try {
- final SAXParserFactory saxPf = <emphasis role="bold">SAXParserFactory</emphasis>.newInstance();
- final SAXParser saxParser = saxPf.newSAXParser();
- saxParser.parse(uri, eventHandler);
-} catch (ParserConfigurationException e){
- e.printStackTrace(System.err);
-} ...</programlisting>
-
- <para>In order to keep an application independent from a specific
- parser implementation the <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> uses the so
- called <link
- xlink:href="http://www.dofactory.com/Patterns/PatternAbstract.aspx">Abstract
- Factory Pattern</link> instead of simply calling a constructor from
- a vendor specific parser class.</para>
-
- <para>In order to be useful the parser has to be instructed to do
- something meaningful when a XML document gets parsed. For this
- purpose our application supplies an event handler instance:</para>
-
- <programlisting language="none">public void parse(final String uri) {
- try {
- final SAXParserFactory saxPf = SAXParserFactory.newInstance();
- final SAXParser saxParser = saxPf.newSAXParser();
- saxParser.parse(uri, <emphasis role="bold">eventHandler</emphasis>);
- } catch (org.xml.sax.SAXException e) {
- ...
- private final MyEventHandler <emphasis role="bold">eventHandler = new MyEventHandler()</emphasis>;
-}</programlisting>
-
- <para>What does the event handler actually do? It offers methods to
- the parser being callable during the parsing process:</para>
-
- <programlisting language="none">package sax.stat.v1;
-...
-public class MyEventHandler extends <classname>org.xml.sax.helpers.DefaultHandler</classname> {
-
- public void <emphasis role="bold"><emphasis role="bold">startDocument()</emphasis></emphasis><co
- xml:id="programlisting_eventhandler_startDocument"/> {
- System.out.println("Opening Document");
- }
- public void <emphasis role="bold">endDocument()</emphasis><co
- xml:id="programlisting_eventhandler_endDocument"/> {
- System.out.println("Closing Document");
- }
- public void <emphasis role="bold">startElement(String namespaceUri, String localName, String rawName,
- Attributes attrs)</emphasis> <co
- xml:id="programlisting_eventhandler_startElement"/>{
- System.out.println("Opening \"" + rawName + "\"");
- elementCount++;
- }
- public void <emphasis role="bold">endElement(String namespaceUri, String localName,
- String rawName)</emphasis><co
- xml:id="programlisting_eventhandler_endElement"/>{
- System.out.println("Closing \"" + rawName + "\"");
- }
- public void <emphasis role="bold">characters(char[] ch, int start, int length)</emphasis><co
- xml:id="programlisting_eventhandler_characters"/>{
- System.out.println("Content \"" + new String(ch, start, length) + '"');
- }
- public int getElementCount() <co
- xml:id="programlisting_eventhandler_getElementCount"/>{
- return elementCount;
- }
- private int elementCount = 0;
-}</programlisting>
-
- <calloutlist>
- <callout arearefs="programlisting_eventhandler_startDocument">
- <para>This method gets called exactly once namely when opening
- the XML document as a whole.</para>
- </callout>
-
- <callout arearefs="programlisting_eventhandler_endDocument">
- <para>After successfully parsing the whole document instance
- this method will finally be called.</para>
- </callout>
-
- <callout arearefs="programlisting_eventhandler_startElement">
- <para>This method gets called each time a new element is parsed.
- In the given catalog.xml example it will be called three times:
- First when the <tag class="starttag">catalog</tag> appears and
- then two times upon each <item ... >. The supplied
- parameters depend whether or not name space processing is
- enabled.</para>
- </callout>
-
- <callout arearefs="programlisting_eventhandler_endElement">
- <para>Called each time an element like <tag
- class="starttag">item ...</tag> gets closed by its counterpart
- <tag class="endtag">item</tag>.</para>
- </callout>
-
- <callout arearefs="programlisting_eventhandler_characters">
- <para>This method is responsible for the treatment of textual
- content i.e. handling <code>#PCDATA</code> element content. We
- will explain its uncommon signature a little bit later.</para>
- </callout>
-
- <callout arearefs="programlisting_eventhandler_getElementCount">
- <para><function>getElementCount()</function> is a getter method
- to read only access the private field
- <varname>elementCount</varname> which gets incremented in <coref
- linkend="programlisting_eventhandler_startElement"/> each time
- an XML element opens.</para>
- </callout>
- </calloutlist>
-
- <para>The call <code>saxParser.parse(uri, eventHandler)</code>
- actually initiates the parsing process and tells the parser
- to:</para>
-
- <itemizedlist>
- <listitem>
- <para>Open the XML document being referenced by the URI
- argument.</para>
- </listitem>
-
- <listitem>
- <para>Forward XML events to the event handler instance supplied
- by the second argument.</para>
- </listitem>
- </itemizedlist>
-
- <para>A driver class containing a <code>main(...)</code> method may
- start the whole process and print out the desired number of elements
- upon completion of a parsing run:</para>
-
- <programlisting language="none">package sax.stat.v1;
-
-public class ElementCountDriver {
- public static void main(String argv[]) {
- ElementCount xmlStats = new ElementCount();
- xmlStats.parse("<emphasis role="bold">Input/Sax/catalog.xml</emphasis>");
- System.out.println("Document contains " + xmlStats.<emphasis role="bold">getElementCount()</emphasis> + " elements");
- }
-}</programlisting>
-
- <para>Processing the catalog example instance yields:</para>
-
- <programlisting language="none">Opening Document
-<emphasis role="bold">Opening "catalog"</emphasis> <co
- xml:id="programlisting_catalog_output"/>
-Content "
- "
-<emphasis role="bold">Opening "item"</emphasis> <co
- xml:id="programlisting_catalog_item1"/>
-Content "Swinging headset"
-Closing "item"
-Content "
- "
-<emphasis role="bold">Opening "item"</emphasis> <co
- xml:id="programlisting_catalog_item2"/>
-Content "200W Stereo Amplifier"
-Closing "item"
-Content "
-"
-Closing "catalog"
-Closing Document
-<emphasis role="bold">Document contains 3 elements</emphasis> <co
- xml:id="programlisting_catalog_elementcount"/></programlisting>
-
- <calloutlist>
- <callout arearefs="programlisting_catalog_output">
- <para>Start parsing element <tag
- class="starttag">catalog</tag>.</para>
- </callout>
-
- <callout arch="" arearefs="programlisting_catalog_item1">
- <para>Start parsing element <tag class="starttag">item
- orderNo="3218"</tag>Swinging headset<tag class="endtag"
- role="">item</tag>.</para>
- </callout>
-
- <callout arch="" arearefs="programlisting_catalog_item2">
- <para>Start parsing element <tag class="starttag">item
- orderNo="9921"</tag>200W Stereo Amplifier<tag class="endtag"
- role="">item</tag>.</para>
- </callout>
-
- <callout arearefs="programlisting_catalog_elementcount">
- <para>After the parsing process has completed the application
- outputs the number of elements being counted so far.</para>
- </callout>
- </calloutlist>
-
- <para>The output contains some lines of <quote>empty</quote>
- content. This content is due to whitespace being located between
- elements. For example a newline appears between the the <tag
- class="starttag">catalog</tag> and the first <tag
- class="starttag">item</tag> element. The parser encapsulates this
- whitespace in a call to the <link
- xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/org/xml/sax/ContentHandler.html#characters(char[],%20int,%20int)">characters</link>
- method. In an application this call will typically be ignored. XML
- document instances in a professional context will typically not
- contain any newline characters at all. Instead the whole document is
- represented as a single line. This inhibits human readability which
- is not required if the processing applications work well. In this
- case empty content as above will not appear.</para>
-
- <para>The <code>characters(char[] ch, int start, int length)</code>
- method's signature looks somewhat strange regarding <link
- linkend="gloss_Java"><trademark>Java</trademark></link> conventions.
- One might expect <code>characters(String s)</code>. But this way the
- <acronym xlink:href="http://www.saxproject.org">SAX</acronym> API
- allows efficient parser implementations: A parser may initially
- allocate a reasonable large <code>char</code> array of say 128 bytes
- sufficient to hold 64 (<link
- xlink:href="http://unicode.org">Unicode</link>) characters. If this
- buffer gets exhausted the parser might allocate a second buffer of
- double size thus implementing an <quote>amortized doubling</quote>
- algorithm:</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/saxcharacter.pdf"/>
- </imageobject>
- </mediaobject>
-
- <para>In this example the first element content fits in the first
- buffer. The second content <code>200W Stereo Amplifier</code> and
- the third content <code>Earphone</code> both fit in the second
- buffer. Subsequent content may require further buffer allocations.
- Such a strategy minimizes the number of time consuming <code>new
- </code> <link
- xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/String.html">String</link>
- <code>(...)</code> constructor calls being necessary for the more
- convenient API variant <code>characters(String s)</code>.</para>
- </section>
-
- <section xml:id="saxRegistry">
- <title>Event- and error handler registration</title>
-
- <para>Our first <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> application
- suffers from the following deficiencies:</para>
-
- <itemizedlist>
- <listitem>
- <para>The error handling is very sparse. It completely relies on
- exceptions being thrown by classes like <link
- xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/org/xml/sax/SAXException.html">SAXException</link>
- which frequently do not supply meaningful error
- information.</para>
- </listitem>
-
- <listitem>
- <para>The application is not aware of namespaces. Thus reading
- e.g. <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> document
- instances will not allow to distinguish between elements from
- different namespaces like HTML.</para>
- </listitem>
-
- <listitem>
- <para>The parser will not validate a document instance against a
- DTD being present.</para>
- </listitem>
- </itemizedlist>
-
- <para>We now incrementally add these features to the <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> parsing
- process. <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> offers an
- interface <link
- xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/org/xml/sax/XMLReader.html">XmlReader</link>
- to conveniently <emphasis>register</emphasis> event- and error
- handler instances instead of passing them as a separate argument to
- the <link
- xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/javax/xml/parsers/SAXParser.html#parse(java.lang.String,%20org.xml.sax.helpers.DefaultHandler)">parse</link>
- method. We first code an error handler class by implementing the
- interface <classname>org.xml.sax.ErrorHandler</classname> being part
- of the <acronym xlink:href="http://www.saxproject.org">SAX</acronym>
- API:</para>
-
- <programlisting language="none">package sax.stat.v2;
-...
-public class MyErrorHandler implements ErrorHandler {
-
- <emphasis role="bold">public void warning(SAXParseException e)</emphasis> {
- System.err.println("[Warning]" + getLocationString(e));
- }
- <emphasis role="bold">public void error(SAXParseException e)</emphasis> {
- System.err.println("[Error]" + getLocationString(e));
- }
- <emphasis role="bold">public void fatalError(SAXParseException e)</emphasis> throws SAXException{
- System.err.println("[Fatal Error]" + getLocationString(e));
- }
- private String getLocationString(SAXParseException e) {
- return " line " + e.getLineNumber() +
- ", column " + e.getColumnNumber()+ ":" + e.getMessage();
- }
-}</programlisting>
-
- <para>These three methods represent the
- <classname>org.xml.sax.ErrorHandler</classname> interface. The
- method <function>getLocationString</function> is used to supply
- precise parsing error locations by means of line- and column numbers
- within a document instance. If errors or warnings are encountered
- the parser will call one of the appropriate public methods:</para>
-
- <figure xml:id="saxMissItem">
- <title>A non well formed document.</title>
-
- <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
-<catalog>
- <item orderNo="3218">Swinging headset</item>
- <item orderNo="9921">200W Stereo Amplifier
-</catalog></programlisting>
-
- <caption>
- <para>This document is not well formed since due to a missing a
- closing <tag class="endtag">item</tag> tag is missing.</para>
- </caption>
- </figure>
-
- <para>Our error handler method gets called yielding an informative
- message:</para>
-
- <programlisting language="none">[Fatal Error] line 5, column -1:Expected "</item>" to terminate
-element starting on line 4.</programlisting>
-
- <para>This error output is achieved by
- <emphasis>registering</emphasis> an instance of
- <classname>sax.stat.v2.MyErrorHandler</classname> to the parser
- prior to starting the parsing process. In the following code snippet
- we also register a content handler instance to the parser and thus
- separate the parser's configuration from its invocation:</para>
-
- <programlisting language="none">package sax.stat.v2;
-...
-public class ElementCount {
- public ElementCount()
- throws SAXException, ParserConfigurationException{
- final SAXParserFactory saxPf = SAXParserFactory.newInstance();
- final SAXParser saxParser = saxPf.newSAXParser();
- xmlReader = saxParser.getXMLReader();
- xmlReader.setContentHandler(eventHandler); <co
- xml:id="programlisting_assemble_parser_setcontenthandler"/>
- xmlReader.setErrorHandler(errorHandler); <co
- xml:id="programlisting_assemble_parser_seterrorhandler"/>
- }
- public void parse(final String uri)
- throws IOException, SAXException{
- xmlReader.parse(uri); <co
- xml:id="programlisting_assemble_parser_invokeparse"/>
- }
- public int getElementCount() {
- return eventHandler.getElementCount(); <co
- xml:id="programlisting_assemble_parser_getelementcount"/>
- }
- private final XMLReader xmlReader;
- private final MyEventHandler eventHandler = new MyEventHandler(); <co
- xml:id="programlisting_assemble_parser_createeventhandler"/>
- private final MyErrorHandler errorHandler = new MyErrorHandler(); <co
- xml:id="programlisting_assemble_parser_createerrorhandler"/>
-}</programlisting>
-
- <calloutlist>
- <callout arearefs="programlisting_assemble_parser_setcontenthandler programlisting_assemble_parser_seterrorhandler">
- <para>Referring to <xref linkend="figureSax" os=""/> these two
- calls attach the event- and error handler objects to the parser
- thus implementing the two arrows from the parser to the
- application's implementation.</para>
- </callout>
-
- <callout arearefs="programlisting_assemble_parser_invokeparse">
- <para>The parser is invoked. Note that in this example we only
- pass a document's URI but no reference to a handler
- object.</para>
- </callout>
-
- <callout arearefs="programlisting_assemble_parser_getelementcount">
- <para>The method <function>getElementCount()</function> is
- needed to allow a calling object to access the private
- <varname>eventHandler</varname> object's
- <function>getElementCount()</function> method.</para>
- </callout>
-
- <callout arearefs="programlisting_assemble_parser_createeventhandler programlisting_assemble_parser_createerrorhandler">
- <para>An event handling and an error handling object are created
- to handle events during the parsing process.</para>
- </callout>
- </calloutlist>
-
- <para>The careful reader might notice a subtle difference between
- the content- and the error handler implementation: The class
- <classname>sax.stat.v2.MyErrorHandler</classname> implements the
- interface <classname>org.xml.sax.ErrorHandler</classname>. But
- <classname>sax.stat.v2.MyEventHandler</classname> is derived from
- <classname>org.xml.sax.helpers.DefaultHandler</classname> which
- itself implements the
- <classname>org.xml.sax.ContentHandler</classname> interface.
- Actually one might as well start from the latter interface requiring
- to implement all of it's 11 methods. In most circumstances this only
- complicates the application's code since it is unnecessary to react
- to events belonging for example to processing instructions. For this
- reason it is good coding practice to use the empty default
- implementations in
- <classname>org.xml.sax.helpers.DefaultHandler</classname> and to
- redefine only those methods corresponding to events actually being
- handled by the application in question.</para>
-
- <qandaset defaultlabel="qanda" xml:id="sda1SaxReadAttributes">
- <title>SAX and attribute values</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <label>Reading an element's set of attributes.</label>
-
- <para>The example document instance does include <tag
- class="attribute">orderNo</tag> attribute values for each
- <tag class="starttag">item</tag> element. The parser does
- not yet show these attribute keys and their corresponding
- values. Read the documentation for <classname
- xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/org/xml/sax/Attributes.html">org.xml.sax.Attributes</classname>
- and extend the given code to use it.</para>
- </question>
-
- <answer>
- <para>For the given example it would suffice to read the
- known <tag class="attribute">orderNo</tag> attributes value.
- A generic solution may ask for the set of all defined
- attributes and show their values:</para>
-
- <programlisting language="none">package sax;
-
-public class AttribEventHandler extends DefaultHandler {
-
- public void startElement(String namespaceUri, String localName,
- String rawName, Attributes attrs) {
- System.out.println("Opening Element " + rawName);
- for (int i = 0; i < attrs.getLength(); i++){
- System.out.println(attrs.getQName(i) + "=" + attrs.getValue(i) + "\n");
- }
- }
-}</programlisting>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
-
- <section xml:id="sda1SecElementLists">
- <title>The set of element names</title>
-
- <qandaset defaultlabel="qanda" xml:id="sda1QandaElementNames">
- <title>Element lists of arbitrary XML documents.</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>We reconsider the simple application reading
- arbitrary XML documents and providing a list of XML
- Elements being contained within:</para>
-
- <programlisting language="none">Opening Document
-<emphasis role="bold">Opening "catalog"</emphasis>
-Content "
- "
-<emphasis role="bold">Opening "item"</emphasis>
-Content "Swinging headset"
-Closing "item"
-Content " ...</programlisting>
-
- <para>If an element like e.g. <tag
- class="starttag">item</tag> appears multiple times it will
- also be written to standard output multiple times.</para>
-
- <para>We are now interested to get the list of all
- elements names being present in an arbitrary XML document.
- Consider the following example:</para>
-
- <programlisting language="none"><memo>
- <from>
- <name>Martin</name>
- <surname>Goik</surname>
- </from>
- <to>
- <name>Adam</name>
- <surname>Hacker</surname>
- </to>
- <to>
- <name>Eve</name>
- <surname>Intruder</surname>
- </to>
- <date year="2005" month="1" day="6"/>
- <subject>Firewall problems</subject>
- <content>
- <para>Thanks for your excellent work.</para>
- <para>Our firewall is definitely broken!</para>
- </content>
-</memo></programlisting>
-
- <para>The elements <tag class="starttag">to</tag> , <tag
- class="starttag">name</tag>, <tag
- class="starttag">surname</tag> and <tag
- class="starttag">para</tag> both appear multiple times.
- Write a SAX application which processes arbitrary XML
- documents and creates an alphabetically sorted list of
- elements being contained <emphasis role="bold">excluding
- duplicates</emphasis>. The intended output for the above
- example is:</para>
-
- <programlisting language="none">List of elements: {content date from memo name para subject surname to }</programlisting>
-
- <para>The corresponding handler should be implemented in a
- re-usable way. Thus if different XML documents are being
- handled in succession the list of elements should be
- erased prior to processing the current document.
- Hints:</para>
-
- <itemizedlist>
- <listitem>
- <para>Use a <classname>java.util.SortedSet</classname>
- instance to collect element names thereby excluding
- duplicates.</para>
- </listitem>
-
- <listitem>
- <para>The method
- <methodname>sax.count.ListTagNamesHandler.startDocument()</methodname>
- may be used to initialize your handler.</para>
- </listitem>
- </itemizedlist>
- </question>
-
- <answer>
- <para>A suitable handler reads:</para>
-
- <programlisting language="none">package sax.count;
-
-import java.util.SortedSet;
-import java.util.TreeSet;
-
-import org.xml.sax.Attributes;
-import org.xml.sax.SAXException;
-import org.xml.sax.helpers.DefaultHandler;
-
-/** Reading attributes from element events */
-public class ListTagNamesHandler extends DefaultHandler {
-
- // A SortedSet by definition does not contain any duplicates.
- private SortedSet<String> elementNames = new TreeSet<>();
-
- @Override
- public void startDocument() throws SAXException {
- elementNames.clear(); // May contain elements from a previous run.
- }
-
- public void startElement(String namespaceUri, String localName,
- String rawName, Attributes attrs) {
- // In case the current element name has already been inserted
- // this method call will be silently ignored.
- elementNames.add(rawName);
- }
-
- /**
- * @return A sorted list of element names of he currently processed XML
- * document without duplicates.
- */
- public String[] getTagNames() {
- return elementNames.toArray(new String[0]);
- }
-}</programlisting>
-
- <para>A complete application requires a driver:</para>
-
- <programlisting language="none">package sax.count;
-
-import javax.xml.parsers.SAXParser;
-import javax.xml.parsers.SAXParserFactory;
-
-import org.xml.sax.XMLReader;
-
-import sax.stat.v2.MyErrorHandler;
-
-public class Driver {
-
- public static void main(String argv[]) throws Exception {
-
- final SAXParserFactory saxPf = SAXParserFactory.newInstance();
- final SAXParser saxParser = saxPf.newSAXParser();
- final XMLReader xmlReader = saxParser.getXMLReader();
- final ListTagNamesHandler handler = new ListTagNamesHandler();
- xmlReader.setContentHandler(handler);
- xmlReader.setErrorHandler(new MyErrorHandler());
- xmlReader.parse("Input/Xml/Memo/message.xml");
-
- System.out.print("List of elements: {");
- for (String elementName : handler.getTagNames()) {
- System.out.print(elementName + " ");
- }
- System.out.println("}");
- }
-}</programlisting>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
-
- <section xml:id="sda1SaxView">
- <title>A limited view on a given XML document instance</title>
-
- <qandaset defaultlabel="qanda" xml:id="sda1QandamemoView">
- <title>A specific view on memo documents</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>We reconsider the following memo instance:</para>
-
- <programlisting language="none"><memo>
- <from>
- <name>Martin</name>
- <surname>Goik</surname>
- </from>
- <to>
- <name>Adam</name>
- <surname>Hacker</surname>
- </to>
- <to>
- <name>Eve</name>
- <surname>Intruder</surname>
- </to>
- <date year="2005" month="1" day="6"/>
- <subject>Firewall problems</subject>
- <content>
- <para>Thanks for your excellent work.</para>
- <para>Our firewall is definitely broken!</para>
- </content>
-</memo></programlisting>
-
- <para>Every memo instance does have exactly one sender and
- one subject. Write a SAX application to achieve the
- following output:</para>
-
- <programlisting language="none">Sender: Martin Goik
-Subject: Firewall problems</programlisting>
-
- <para>Hint: The callback implementation of
- <methodname>org.xml.sax.helpers.DefaultHandler.characters(char[],int,int)</methodname>
- may be used to filter the desired output. You have to
- limit its output to <tag class="starttag">from</tag> and
- <tag class="starttag">subject</tag> descendant content.
- Taking the <tag class="starttag">subject</tag>Firewall
- problems<tag class="endtag">subject</tag> element as an
- example the corresponding event sequence reads:</para>
-
- <informaltable border="1">
- <tr>
- <th>Event</th>
-
- <th>Corresponding callback</th>
- </tr>
-
- <tr>
- <td>...</td>
-
- <td>...</td>
- </tr>
-
- <tr>
- <td>Opening <tag class="starttag">subject</tag>
- element</td>
-
- <td>startElement(...)</td>
- </tr>
-
- <tr>
- <td>Firewall problems</td>
-
- <td>characters(...)</td>
- </tr>
-
- <tr>
- <td>Closing <tag class="endtag">subject</tag>
- element</td>
-
- <td>endElement(...)</td>
- </tr>
-
- <tr>
- <td>...</td>
-
- <td>...</td>
- </tr>
- </informaltable>
-
- <para>Limiting output of our
- <methodname>org.xml.sax.helpers.DefaultHandler.characters(char[],int,int)</methodname>
- callback method can be achieved by introducing instance
- scope boolean variables being set to true or false inside
- your
- <methodname>org.xml.sax.helpers.DefaultHandler.startElement(String
- uri,String localName,String qName,org.xml.sax.Attributes
- attributes)</methodname> and
- <methodname>org.xml.sax.helpers.DefaultHandler.endElement(String
- uri, String localName, String qName)</methodname>
- implementations accordingly to keep track of the current
- event state.</para>
- </question>
-
- <answer>
- <programlisting language="none">package sax.view;
-...
-/** A view on memo documents restricting to sender name an subject. */
-public class MemoViewHandler extends DefaultHandler {
-
- // These variables help us to keep track of the current event state spanning
- // each startElement(...) -- character(...) -- endElement(...) event sequence
- boolean inFromContext = false,
- inSubjectContext = false;
-
- public void startElement(String namespaceUri, String localName,
- String rawName, Attributes attrs) {
- switch(rawName) {
- case "from":
- inFromContext = true;
- System.out.print("Sender: ");
- break;
- case "subject":
- inSubjectContext = true;
- System.out.print("Subject: ");
- break;
- case "surname":
- if (inFromContext) {
- System.out.print(" "); // Adding additional space between <name> and <surname> content.
- }
- break;
- }
- }
-
- @Override
- public void endElement(String uri, String localName, String rawName)
- throws SAXException {
- switch(rawName) {
- case "from":
- inFromContext = false;
- System.out.println();
- break;
- case "subject":
- inSubjectContext = false;
- System.out.println();
- break;
- }
- }
-
- @Override
- public void characters(char[] ch, int start, int length) throws SAXException {
- if (inFromContext || inSubjectContext) {
- System.out.print(new String(ch, start, length));
- }
- }
-}</programlisting>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
- </section>
-
- <section xml:id="saxValidate">
- <title><acronym xlink:href="http://www.saxproject.org">SAX</acronym>
- validation</title>
-
- <para>So far we only parsed well formed document instances. Our
- current parser may operate on valid XML instances:</para>
-
- <figure xml:id="saxNotValid">
- <title>An invalid XML document.</title>
-
- <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE catalog [
- <!ELEMENT catalog (item) >
- <!ELEMENT item (#PCDATA) >
-<!ATTLIST item orderNo NMTOKEN #REQUIRED >
-]>
-<catalog>
- <item orderNo="3218">Swinging headset</item>
- <item orderNo="9921">200W Stereo Amplifier</item>
-</catalog></programlisting>
-
- <caption>
- <para>In contrast to <xref linkend="saxMissItem"/> this document
- is well formed. But it is not <emphasis
- role="bold">valid</emphasis> with respect to the DTD grammar
- since more than one <tag class="starttag">item</tag> elements
- are present.</para>
- </caption>
- </figure>
-
- <para>This document instance is well-formed but not valid. The
- parser will not report any error or warning. In order to enable
- validation we need to configure our parser:</para>
-
- <programlisting language="none">xmlReader.setFeature("http://xml.org/sax/features/validation", true);</programlisting>
-
- <para>The string <code>http://xml.org/sax/features/validation</code>
- serves as a key. Since this is an ordinary string value a parser may
- or may not implement it. The <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> standard
- defines two exception classes for dealing with feature related
- errors:</para>
-
- <variablelist>
- <varlistentry>
- <term><link
- xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/org/xml/sax/SAXNotRecognizedException.html">SAXNotRecognizedException</link></term>
-
- <listitem>
- <para>The feature is not known to the parser.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><link
- xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/org/xml/sax/SAXNotSupportedException.html">SAXNotSupportedException</link></term>
-
- <listitem>
- <para>The feature is known to the parser but the parser does
- not support it or it does not support a specific value being
- set as a value.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>Though not strictly required SAX validation may need DTD
- related (Entity) resolving. Having just SYSTEM identifier pointing
- to remote network addresses like <code>... SYSTEM
- "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd
- ..."</code> may take a long time for download or even fail
- completely. So XML catalog files are in order for validation being
- based on locally available schemes or DTDs.</para>
-
- <para>The <productname
- xlink:href="http://projects.apache.org/projects/xml_commons_resolver.html">xml-commons
- resolver project </productname>offers an implementation being able
- to process various catalog file formats. Maven based project allow
- the corresponding library import by adding the following
- dependency:</para>
-
- <programlisting language="none"><dependency>
- <groupId>xml-resolver</groupId>
- <artifactId>xml-resolver</artifactId>
- <version>1.2</version>
-</dependency></programlisting>
-
- <para>We need a properties file <link
- xlink:href="http://xerces.apache.org/xml-commons/components/resolver/tips.html">CatalogManager.properties</link>
- defining XML catalogs to be used and additional parameters:</para>
-
- <programlisting language="none"># Catalogs are relative to this properties file
-relative-catalogs=false
-# Catalog list
-
-catalogs=\
-/usr/share/eclipse/dropins/oxygenxml.oxygen_14.2/plugins/com.oxygenxml.editor_14.2.0.v2013021115/frameworks/xhtml/dtd/xhtmlcatalog.xml;\
-/usr/share/eclipse/dropins/oxygenxml.oxygen_14.2/plugins/com.oxygenxml.editor_14.2.0.v2013021115/frameworks/xhtml11/dtd/xhtmlcatalog.xml
-# PUBLIC in favour of SYSTEM
-prefer=public</programlisting>
-
- <para>This configuration uses some catalogs from the
- <trademark>Oxygen</trademark> <trademark>Eclipse</trademark> plugin.
- We may now add a resolver to our SAX application by referencing the
- above configuration file <coref linkend="resolverPropertyFile"/> and
- registering the resolver to our SAX parser instance <coref
- linkend="resolverRegister"/>:</para>
-
- <programlisting language="none">xmlReader = saxParser.getXMLReader();
-
- // Set up resolving PUBLIC identifier
- final CatalogManager cm = new CatalogManager("<emphasis role="bold">CatalogManager.properties</emphasis>" <co
- xml:id="resolverPropertyFile"/> );
- final CatalogResolver resolver = new CatalogResolver(cm);
- xmlReader.setEntityResolver(resolver) <co xml:id="resolverRegister"/>;</programlisting>
- </section>
-
- <section xml:id="saxNamespace">
- <title>Namespaces</title>
-
- <para>In order to make a <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> parser
- application namespace aware we have to activate two <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> parsing
- features:</para>
-
- <programlisting language="none">xmlReader = saxParser.getXMLReader();
-xmlReader.setFeature("http://xml.org/sax/features/namespaces", true);
-xmlReader.setFeature("http://xml.org/sax/features/namespace-prefixes", true);</programlisting>
-
- <para>This instructs the parser to pass the namespace's name for
- each element. Namespace prefixes like <code>xsl</code> in <tag
- class="starttag">xsl:for-each</tag> are also passed and may be used
- by an application:</para>
-
- <programlisting language="none">package sax;
-...
-public class NamespaceEventHandler extends DefaultHandler {
-...
- public void startElement(String <emphasis role="bold">namespaceUri</emphasis>, String localName,
- String rawName, Attributes attrs) {
- System.out.println("Opening Element rawName='" + rawName + "'\n"
- + "namespaceUri='" + <emphasis role="bold">namespaceUri</emphasis> + "'\n"
- + "localName='" + localName
- + "'\n--------------------------------------------");
-}</programlisting>
-
- <para>As an example we take a XSLT script:</para>
-
- <programlisting language="none"><?xml version="1.0" encoding="utf-8"?>
-<xsl:stylesheet version="1.0"
- xmlns:xsl='http://www.w3.org/1999/XSL/Transform'
- xmlns:fo='http://www.w3.org/1999/XSL/Format'>
-
- <xsl:template match="/">
- <fo:block>A block</fo:block>
- <HTML/>
- </xsl:template>
-
-</xsl:stylesheet></programlisting>
-
- <para>This XSLT script being conceived as a XML document instance
- contains elements belonging to two different namespaces namely
- <code>http://www.w3.org/1999/XSL/Transform</code> and
- <code>http://www.w3.org/1999/XSL/Format</code>. The script also
- contains a <quote>raw</quote> <tag audience=""
- class="emptytag">HTML</tag> element being introduced only for
- demonstration purposes belonging to the default namespace. The
- result reads:</para>
-
- <programlisting language="none">Opening Element rawName='xsl:stylesheet'
-namespaceUri='http://www.w3.org/1999/XSL/Transform'
-localName='stylesheet'
---------------------------------------------
-Opening Element rawName='xsl:template'
-namespaceUri='http://www.w3.org/1999/XSL/Transform'
-localName='template'
---------------------------------------------
-Opening Element rawName='fo:block'
-namespaceUri='http://www.w3.org/1999/XSL/Format'
-localName='block'
---------------------------------------------
-Opening Element rawName='HTML'
-namespaceUri=''
-localName='HTML'</programlisting>
-
- <para>Now the parser tells us to which namespace a given element
- node belongs to. A XSLT engine for example uses this information to
- build two classes of elements:</para>
-
- <itemizedlist>
- <listitem>
- <para>Elements belonging to the namespace
- <code>http://www.w3.org/1999/XSL/Transform</code> like <tag
- class="emptytag">xsl:value-of select="..."</tag> have to be
- interpreted as instructions by the processor.</para>
- </listitem>
-
- <listitem>
- <para>Elements <emphasis role="bold">not</emphasis> belonging to
- the namespace <code>http://www.w3.org/1999/XSL/Transform</code>
- like <tag class="emptytag">html</tag> or <tag
- class="starttag">fo:block</tag> are copied <quote>as is</quote>
- to the output.</para>
- </listitem>
- </itemizedlist>
-
- <qandaset defaultlabel="qanda" xml:id="quandaentry_SqlFromXml">
- <title>Generating SQL INSERT statements from XML data</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>Consider the following DTD + document instance
- example:</para>
-
- <figure xml:id="catalogProductDescriptionsExample">
- <title>A sample catalog containing products and
- corresponding descriptions.</title>
-
- <programlisting language="none"><!DOCTYPE catalog [
- <!ELEMENT catalog (product*)>
- <!ELEMENT product (name, description*, age?)>
- <!ATTLIST product id ID #REQUIRED>
- <!ELEMENT name (#PCDATA)>
- <!ELEMENT description (#PCDATA)>
- <!ELEMENT age (#PCDATA)>
-]>
-<catalog>
- <product id="mpt">
- <name>Monkey Picked Tea</name>
- <description>Rare wild Chinese tea</description>
- <description>Picked only by specially trained monkeys</description>
- </product>
- <product id="instantTent">
- <name>4-Person Instant Tent</name>
- <description>4-person, 1-room tent</description>
- <description>Pre-attached tent poles</description>
- <description>Exclusive WeatherTec system.</description>
- <age>15</age>
- </product>
-</catalog></programlisting>
- </figure>
-
- <para>Data being contained in catalog instances shall be
- transferred to a relational database system. Implement and
- test a <link linkend="gloss_SAX"><abbrev>SAX</abbrev></link>
- application by following the subsequently described
- steps:</para>
-
- <glosslist>
- <glossentry>
- <glossterm>Database schema</glossterm>
-
- <glossdef>
- <para>Create a database schema matching a product of
- your choice (<productname>Mysql</productname>,
- <productname>Oracle</productname>, ...). Your schema
- should map type and integrity constraints of the given
- DTD. In particular:</para>
-
- <itemizedlist>
- <listitem>
- <para>The element <tag class="starttag">age</tag> is
- optional and always expected to be of integer
- type.</para>
- </listitem>
-
- <listitem>
- <para>description elements are being composed in
- <product> elements and should thus be modeled
- as a 1:n relation. Thus you need a suitable foreign
- key.</para>
- </listitem>
- </itemizedlist>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>SAX Application</glossterm>
-
- <glossdef>
- <para>The order of appearance of the XML elements <tag
- class="starttag">product</tag>, <tag
- class="starttag">name</tag> and <tag
- class="starttag">age</tag> does not permit a linear
- generation of suitable SQL <code>INSERT</code>
- statements by a <link
- linkend="gloss_SAX"><abbrev>SAX</abbrev></link>
- content handler. Instead you will have to keep copies
- of local element values when implementing
- <methodname>org.xml.sax.ContentHandler.startElement(String,String,String,org.xml.sax.Attributes)</methodname>
- and related callback methods. The following sequence
- of insert statements corresponds to the XML data being
- contained in <xref
- linkend="catalogProductDescriptionsExample"/>. You may
- use these statements as a blueprint to be generated by
- your <link
- linkend="gloss_SAX"><abbrev>SAX</abbrev></link>
- application:</para>
-
- <programlisting language="none"><emphasis role="bold">INSERT INTO Product VALUES ('mpt', 'Monkey picked tea', NULL);</emphasis>
-INSERT INTO Description VALUES('mpt', 'Picked only by specially trained monkeys');
-INSERT INTO Description VALUES('mpt', 'Rare wild Chinese tea');
-
-<emphasis role="bold">INSERT INTO Product VALUES ('instantTent', '4-person instant tent', 15);</emphasis>
-INSERT INTO Description VALUES('instantTent', 'Exclusive WeatherTec system.');
-INSERT INTO Description VALUES('instantTent', '4-person, 1-room tent');
-INSERT INTO Description VALUES('instantTent', 'Pre-attached tent poles');</programlisting>
- </glossdef>
- </glossentry>
- </glosslist>
- </question>
-
- <answer>
- <itemizedlist>
- <listitem>
- <para><classname>sax.context.Catalog2SqlDriver</classname></para>
- </listitem>
-
- <listitem>
- <para><classname>sax.context.Catalog2Sql</classname></para>
- </listitem>
-
- <listitem>
- <para><classname>sax.context.ImportHandler</classname></para>
- </listitem>
- </itemizedlist>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
-
- <qandaset defaultlabel="qanda" xml:id="quandaentry_NumElemByNs">
- <title>Counting element names grouped by namespaces</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>We want to extend the SAX examples counting <link
- linkend="saxElementCount">elements</link> and <link
- linkend="exercise_saxAttrib">attributes</link> of arbitrary
- document instances. Consider the following <link
- linkend="gloss_XHTML">XHTML</link> + <link
- linkend="gloss_SVG">SVG</link> + <link
- linkend="gloss_MathML">MathML</link> sample document:</para>
-
- <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN"
- "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd" >
-<html xmlns="<emphasis role="bold">http://www.w3.org/1999/xhtml</emphasis>" <co
- xml:id="xhtmlCombinedNs_Xhtml"/>
- xmlns:svg="<emphasis role="bold">http://www.w3.org/2000/svg</emphasis>"> <co
- xml:id="xhtmlCombinedNs_Svg"/>
- <head>
- <title>Sample XHTML with Equations</title>
- </head>
- <body>
- <h1>Sample MathML:</h1>
- <math <emphasis role="bold">xmlns="http://www.w3.org/1998/Math/MathML</emphasis>"> <co
- xml:id="xhtmlCombinedNs_Mathml"/>
- <mstyle displaystyle="false" scriptlevel="0">
- <mrow>
- <mfrac>
- <mrow>
- <mi mathcolor="gray">sin</mi>
- <mo rspace="verythinmathspace">â¡</mo>
- <mi>θ</mi>
- </mrow>
- <mi>Ï€</mi>
- </mfrac>
- </mrow>
- </mstyle>
- </math>
- <h1>Sample SVG:</h1>
- <svg:svg version="1.1" baseProfile="full" width="300px" height="200px">
- <svg:circle cx="150px" cy="100px" r="50px" fill="#ff0000"
- stroke="#000000" stroke-width="5px"/>
- </svg:svg>
- </body>
-</html></programlisting>
-
- <para>This document does define three different namespaces
- <coref linkend="xhtmlCombinedNs_Xhtml"/>, <coref
- linkend="xhtmlCombinedNs_Svg"/> and <coref
- linkend="xhtmlCombinedNs_Mathml"/> corresponding to the
- three XML application components.</para>
-
- <para>Implement a <link linkend="gloss_SAX">SAX</link>
- application being able to group elements of arbitrary XML
- documents by namespaces along with their corresponding
- frequencies of occurrence. The intended output corresponding
- to the previous <link linkend="gloss_XHTML">XHTM</link>L
- example might look like:</para>
-
- <programlisting language="none">Namespace '<emphasis
- role="bold">http://www.w3.org/1998/Math/MathML</emphasis>' contains:
-<math> (1 occurrence)
-<mo> (1 occurrence)
-<mrow> (2 occurrences)
-<mfrac> (1 occurrence)
-<mi> (3 occurrences)
-<mstyle> (1 occurrence)
-
-Namespace '<emphasis role="bold">http://www.w3.org/1999/xhtml</emphasis>' contains:
-<body> (1 occurrence)
-<title> (1 occurrence)
-<html> (1 occurrence)
-<h1> (2 occurrences)
-<head> (1 occurrence)
-
-Namespace '<emphasis role="bold">http://www.w3.org/2000/svg</emphasis>' contains:
-<svg> (1 occurrence)
-<circle> (1 occurrence)</programlisting>
-
- <para>Hints:</para>
-
- <itemizedlist>
- <listitem>
- <para>Counting frequencies and grouping by namespaces
- may be achieved by using standard Java container
- implementations of <classname>java.util.Map</classname>.
- You may for example define sets of related XML elements
- and group them by their corresponding namespaces.</para>
- </listitem>
-
- <listitem>
- <para>Enabling validation may require an entity resolver
- as being described in <xref linkend="saxValidate"/>.
- Otherwise you may experience long parsing times due to
- downloading of referenced DTD components.</para>
- </listitem>
- </itemizedlist>
- </question>
-
- <answer>
- <itemizedlist>
- <listitem>
- <para><classname>sax.ns.stat.ElementFrequencyDriver</classname></para>
- </listitem>
-
- <listitem>
- <para><classname>sax.ns.stat.ElementFrequency</classname></para>
- </listitem>
-
- <listitem>
- <para><classname>sax.ns.stat.ElementcountByName</classname></para>
- </listitem>
-
- <listitem>
- <para><classname>sax.ns.stat.FrequencyGatherer</classname></para>
- </listitem>
- </itemizedlist>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
- </section>
-
- <section xml:id="dom">
- <title>The Document Object Model (<acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym>)</title>
-
- <titleabbrev><acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym></titleabbrev>
-
- <section xml:id="domBase">
- <title>Language independent specification</title>
-
- <titleabbrev>Language independence</titleabbrev>
-
- <para>XML documents allow for automated content processing. We
- already discussed the <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> API to access
- XML documents by <link
- linkend="gloss_Java"><trademark>Java</trademark></link>
- applications. There are however situations where <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> is not
- appropriate:</para>
-
- <itemizedlist>
- <listitem>
- <para>The <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> is event
- based. XML node elements are passed to handler methods.
- Sometimes we want to access neighbouring nodes from a context
- node in our handler methods for example a <tag
- class="starttag">title</tag> following a <tag
- class="starttag">chapter</tag> node. <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> does not
- offer any support for this. If we need references to
- neighbouring nodes we have to create them ourselves during a
- <acronym xlink:href="http://www.saxproject.org">SAX</acronym>
- parsing run. This is tedious and leads to code being hard to
- understand.</para>
- </listitem>
-
- <listitem>
- <para>Some applications may want to select node sets by <acronym
- xlink:href="http://www.w3.org/TR/xpath">XPath</acronym>
- expressions which is completely impossible in a <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym>
- application.</para>
- </listitem>
-
- <listitem>
- <para>We may want to move subtrees within a document itself (for
- example exchanging two <tag class="starttag">chapter</tag>
- nodes) or even transferring them to a different document.</para>
- </listitem>
- </itemizedlist>
-
- <para>The greatest deficiency of the <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> is the fact
- that an XML instance is not represented as a tree like structure but
- as a succession of events. The <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> allows us to
- represent XML document instances as tree like structures and thus
- enables navigational operations between nodes.</para>
-
- <para>In order to achieve language <emphasis>and</emphasis> software
- vendor independence the <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> approach uses two
- stages:</para>
-
- <itemizedlist>
- <listitem>
- <para>The <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> is formulated
- in an Interface Definition Language (<abbrev
- xlink:href="http://en.wikipedia.org/wiki/Interface_description_language">IDL</abbrev>)</para>
- </listitem>
-
- <listitem>
- <para>In order to use the <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> API by a
- concrete programming language a so called <emphasis>language
- binding</emphasis> is required. In languages like <link
- linkend="gloss_Java"><trademark>Java</trademark></link> the
- language binding will still be a set of (<link
- linkend="gloss_Java"><trademark>Java</trademark></link>)
- interfaces. Thus for actually coding an application an
- implementation of these interfaces is needed</para>
- </listitem>
- </itemizedlist>
-
- <para>So what exactly may an <abbrev
- xlink:href="http://en.wikipedia.org/wiki/Interface_description_language">IDL</abbrev>
- be? The programming language <link
- linkend="gloss_Java"><trademark>Java</trademark></link> already
- allows pure interface definitions without any implementation. In C++
- the same result can be achieved by so called <emphasis>pure virtual
- classes</emphasis>. An <abbrev
- xlink:href="http://en.wikipedia.org/wiki/Interface_description_language">IDL</abbrev>
- offers extended features to describe such interfaces. For <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> the <productname
- xlink:href="http://www.omg.org/gettingstarted/corbafaq.htm">CORBA
- 2.2</productname> <abbrev
- xlink:href="http://en.wikipedia.org/wiki/Interface_description_language">IDL</abbrev>
- had been chosen to describe an XML document programming interface.
- As a first example we take an excerpt from the <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym>'s <link
- xlink:href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#ID-1950641247">Node</link>
- interface definition:</para>
-
- <programlisting language="none">interface Node {
- // NodeType
- const unsigned short ELEMENT_NODE = 1;
- const unsigned short ATTRIBUTE_NODE = 2;
- const unsigned short TEXT_NODE = 3;
- ...
-
- readonly attribute DOMString nodeName;
- attribute DOMString nodeValue;
- // raises(DOMException) on setting
- // raises(DOMException) on retrieval
- readonly attribute unsigned short nodeType;
- readonly attribute Node parentNode;
- ...
- readonly attribute NodeList childNodes;
- readonly attribute Node firstChild;
- ...
- Node insertBefore(in Node newChild,
- in Node refChild)
- raises(DOMException);
- ...</programlisting>
-
- <para>If we want to implement the <abbrev
- xlink:href="http://en.wikipedia.org/wiki/Interface_description_language">IDL</abbrev>
- <classname>org.w3c.dom.Node</classname> specification in e.g. <link
- linkend="gloss_Java"><trademark>Java</trademark></link> a language
- binding has to be defined. This means writing <link
- linkend="gloss_Java"><trademark>Java</trademark></link> code which
- closely resembles the <abbrev
- xlink:href="http://en.wikipedia.org/wiki/Interface_description_language">IDL</abbrev>
- specification. Obviously this task depends on and is restricted by
- the constructs being offered by the target programming language. The
- W3C <link
- xlink:href="http://www.w3.org/TR/DOM-Level-3-Core/java-binding.html">defines</link>
- the <link linkend="gloss_Java"><trademark>Java</trademark></link>
- <classname>org.w3c.dom.Node</classname> interface by:</para>
-
- <programlisting language="none">package org.w3c.dom;
-
-public interface Node {
- public static final short ELEMENT_NODE = 1; // Node Types
- public static final short ATTRIBUTE_NODE = 2;
- public static final short TEXT_NODE = 3;
- ...
- 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 insertBefore(Node newChild,
- Node refChild)
- throws DOMException;
- ...
- }</programlisting>
-
- <para>We take
- <methodname>org.w3c.dom.Node.getChildNodes()</methodname> as an
- example:</para>
-
- <figure xml:id="domRetrieveChildren">
- <title>Retrieving child nodes of a given context node</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/domtree.fig" scale="65"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>The <classname>org.w3c.dom.Node</classname> interface offers a
- set of common operations for objects being part of a XML document.
- But a XML document tree contains different types of nodes such
- as:</para>
-
- <itemizedlist>
- <listitem>
- <para>Elements</para>
- </listitem>
-
- <listitem>
- <para>Attributes</para>
- </listitem>
-
- <listitem>
- <para>Entities</para>
- </listitem>
- </itemizedlist>
-
- <para>An XML API may address this issue by offering data types to
- represent these different kinds of nodes. The <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> <link
- linkend="gloss_Java"><trademark>Java</trademark></link> Binding
- defines an inheritance hierarchy of interfaces for this
- purpose:</para>
-
- <figure xml:id="domJavaNodeInterfaces">
- <title>Inheritance interface hierarchy in the <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> <link
- linkend="gloss_Java"><trademark>Java</trademark></link>
- binding</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/nodeHierarchy.svg"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>Two commonly used <link
- linkend="gloss_Java"><trademark>Java</trademark></link>
- implementations of these interfaces are:</para>
-
- <variablelist>
- <varlistentry>
- <term>Xerces</term>
-
- <listitem>
- <para><orgname
- xlink:href="http://xml.apache.org/xerces2-j">Apache Software
- foundation</orgname></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Jaxp</term>
-
- <listitem>
- <para><orgname xlink:href="http://java.sun.com/xml/jaxp">Sun
- microsystems</orgname></para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>Both implementations offer additional interfaces beyond the
- <acronym xlink:href="http://www.w3.org/DOM">DOM</acronym>'s
- scope.</para>
-
- <para>Going back to the <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> itself the
- specification is divided into <link
- xlink:href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/introduction.html#DOMArchitecture-h2">modules</link>:</para>
-
- <figure xml:id="figureDomModules">
- <title><acronym xlink:href="http://www.w3.org/DOM">DOM</acronym>
- modules.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Screen/dom-architecture.screen.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- </section>
-
- <section xml:id="domCreate">
- <title>Creating a new document from scratch</title>
-
- <titleabbrev>New document</titleabbrev>
-
- <para>If we want to export non-XML content (e.g. from a RDBMS) into
- XML we may achieve this by the following recipe:</para>
-
- <orderedlist>
- <listitem>
- <para>Create a document builder instance.</para>
- </listitem>
-
- <listitem>
- <para>Create an empty <link
- xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/org/w3c/dom/Document.html">Document</link>
- instance.</para>
- </listitem>
-
- <listitem>
- <para>Fill in the desired Elements and Attributes.</para>
- </listitem>
-
- <listitem>
- <para>Create a serializer.</para>
- </listitem>
-
- <listitem>
- <para>Serialize the resulting tree to a stream.</para>
- </listitem>
- </orderedlist>
-
- <para>An introductory piece of code illustrates these steps:</para>
-
- <figure xml:id="simpleDomCreate">
- <title>Creation of a XML document instance from scratch.</title>
-
- <programlisting language="none">package dom;
-...
-public class CreateDoc {
- public static void main(String[] args) throws Exception {
-
- // Create the root element
- <emphasis role="bold">final Element titel = new Element("titel");
-</emphasis>
- //Set a date
- <emphasis role="bold">titel.setAttribute("date", "23.02.2000");</emphasis>
-
- // Append a text node as child
- <emphasis role="bold">titel.addContent(new Text("Versuch 1"));</emphasis>
-
-
- // Set formatting for the XML output
- <emphasis role="bold">final Format outFormat = Format.getPrettyFormat();</emphasis>
-
- // Serialize to console
- <emphasis role="bold">final XMLOutputter printer = new XMLOutputter(outFormat);
- printer.output(titel, System.out);</emphasis>
- }
-}</programlisting>
- </figure>
-
- <para>We get the following result:</para>
-
- <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
-<titel date="23.02.2000">Versuch 1</titel></programlisting>
- </section>
-
- <section xml:id="domCreateExercises">
- <title>Exercises</title>
-
- <qandaset defaultlabel="qanda" xml:id="createDocModify">
- <title>A sub structured <tag class="starttag">title</tag></title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <label>Creation of an extended XML document instance</label>
-
- <para>In order to run the examples given during the lecture
- the <filename
- xlink:href="http://www.jdom.org/downloads">jdom2.jar</filename>
- library must be added to the
- <envar>CLASSPATH</envar>.</para>
-
- <para>The <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> creating
- example given before may be used as a starting point. Extend
- the <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> tree
- created in <xref linkend="simpleDomCreate"/> to produce an
- extended XML document:</para>
-
- <programlisting language="none"><title>
- <long>The long version of this title</long>
- <short>Short version</short>
-</title></programlisting>
- </question>
-
- <answer>
- <programlisting language="none">package dom;
-...
-public class CreateExtended {
- /**
- * @param args
- * @throws IOException
- */
- public static void main(String[] args) throws IOException {
-
- final Element titel = new Element("titel"),
- tLong = new Element("long"),
- tShort = new Element("short");
-
- <emphasis role="bold">// Append <long> and <short> to parent <title></emphasis>
- titel.addContent(tLong).addContent(tShort);
-
- <emphasis role="bold">// Append text to <long> and <short></emphasis>
- tLong.addContent(new Text("The long version of this title"));
- tShort.addContent(new Text("Short version"));
-
- <emphasis role="bold">// Set formatting for the XML output</emphasis>
- Format outFormat = Format.getPrettyFormat();
-
- <emphasis role="bold">// Serialize to console</emphasis>
- final XMLOutputter printer = new XMLOutputter(outFormat);
- printer.output(titel, System.out);
- }
-}</programlisting>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
-
- <section xml:id="domParse">
- <title>Parsing existing XML documents</title>
-
- <titleabbrev>Parsing</titleabbrev>
-
- <para>We already used a <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> to parse an XML
- document. Rather than handling <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> events
- ourselves these events may be used to construct a <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> representation of
- our document. This work is done by an instance of. We use our
- catalog example from <xref linkend="simpleCatalog"/> as an
- introductory example.</para>
-
- <para>We already noticed the need for an
- <classname>org.xml.sax.ErrorHandler</classname> object during
- <acronym xlink:href="http://www.saxproject.org">SAX</acronym>
- processing. A <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> Parser requires a
- similar type of Object in order to react to parsing errors in a
- meaningful way. In principle a <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> parser implementor
- is free to choose his implementation but most implementations are
- based on top of a <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> parser. For
- this reason it was natural to choose a <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> error handling
- interface which is similar to a <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym>
- <classname>org.xml.sax.ErrorHandler</classname>. The following code
- serves the needs described before:</para>
-
- <figure xml:id="domTreeTraversal">
- <title>Accessing a XML Tree purely by <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> methods.</title>
-
- <programlisting language="none">package dom;
-...
-public class ArticleOrder {
-
-<emphasis role="bold"> // Though we are playing DOM here, a <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> parser still
- // assembles our DOM tree.</emphasis>
- private SAXBuilder builder = new SAXBuilder();
-
- public ArticleOrder() {
- <emphasis role="bold">// Though an ErrorHandler is not strictly required it allows
- // for easierlocalization of XML document errors</emphasis>
- builder.setErrorHandler(new MySaxErrorHandler(System.out));<co
- linkends="domSetSaxErrorHandler-co"
- xml:id="domSetSaxErrorHandler"/>
- }
-
- /** Descending a catalog till its <item> elements. For each product
- * its name and order number are being written to the output.
- * @throws ...
- */
- public void process(final String filename) throws JDOMException, IOException {
-
- <emphasis role="bold">// Parsing our XML file</emphasis>
- final Document docInput = builder.build(filename);
-
- <emphasis role="bold">// Accessing the document's root element</emphasis>
- final Element docRoot = docInput.getRootElement();
-
- <emphasis role="bold">// Accessing the <item> children of parent element <catalog></emphasis>
- final List<Element> items = docRoot.getChildren(); // Element nodes only
- for (final Element item : items) {
- System.out.println("Article: " + item.getText()
- + ", order number: " + item.getAttributeValue("orderNo"));
- } ...</programlisting>
-
- <para>Note <coref linkend="domSetSaxErrorHandler"
- xml:id="domSetSaxErrorHandler-co"/>: This is our standard <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym> error handler
- implementing the <classname>org.xml.sax.ErrorHandler</classname>
- interface.</para>
- </figure>
-
- <para>Executing this method needs a driver instance providing an
- input XML filename:</para>
-
- <programlisting language="none">package dom;
-...
-public class ArticleOrderDriver {
- public static void main(String[] argv) throws Exception {
- final ArticleOrder ao = new ArticleOrder();
- ao.process("<emphasis role="bold">Input/article.xml</emphasis>");
- }
-}</programlisting>
-
- <para>This yields:</para>
-
- <programlisting language="none">Article: Swinging headset, order number: 3218
-Article: 200W Stereo Amplifier, order number: 9921</programlisting>
-
- <para>To illustrate the internal processes we take a look at the
- sequence diagram:</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/sequenceDomParser.svg"/>
- </imageobject>
- </mediaobject>
-
- <qandaset defaultlabel="qanda" xml:id="exercise_domHtmlSimple">
- <title>Creating HTML output</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <label>Simple HTML output</label>
-
- <para>Instead exporting simple text output in <xref
- linkend="domTreeTraversal"/> we may also create HTML pages
- like:</para>
-
- <programlisting language="none"><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html>
- <head>
- <title>Available articles</title>
- </head>
- <body>
- <h1>Available articles</h1>
- <table>
- <tbody>
- <tr>
- <th align="left">Article Description</th><th>Order Number</th>
- </tr>
- <tr>
- <td align="left"><emphasis role="bold">Swinging headset</emphasis></td><td><emphasis
- role="bold">3218</emphasis></td>
- </tr>
- <tr>
- <td align="left"><emphasis role="bold">200W Stereo Amplifier</emphasis></td><td><emphasis
- role="bold">9921</emphasis></td>
- </tr>
- </tbody>
- </table>
- </body>
-</html></programlisting>
-
- <para>Instead of simply writing
- <code>...println(<html>\n\t<head>...)</code>
- statements you are expected to code a more sophisticated
- solution. We may combine<xref linkend="createDocModify"/>
- and <xref linkend="createDocModify"/>. The idea is reading
- the XML catalog instance as a <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> as before.
- Then construct a <emphasis>second</emphasis> <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> tree for
- the desired HTML output and fill in the article information
- from the first <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> tree
- accordingly.</para>
- </question>
-
- <answer>
- <para>We introduce a class
- <classname>solve.dom.HtmlTree</classname>:</para>
-
- <programlisting language="none">package solve.dom;
-...
-package solve.dom;
-
-import java.io.IOException;
-import java.io.PrintStream;
-
-import org.jdom2.DocType;
-import org.jdom2.Document;
-import org.jdom2.Element;
-import org.jdom2.Text;
-import org.jdom2.output.Format;
-import org.jdom2.output.XMLOutputter;
-
-/**
- * Holding a HTML DOM to produce output.
- * @author goik
- */
-public class HtmlTree {
-
- private Document htmlOutput;
- private Element tableBody;
-
- public HtmlTree(final String titleText,
- final String[] tableHeaderFields) { <co
- linkends="programlisting_catalog2html_htmlskel_co"
- xml:id="programlisting_catalog2html_htmlskel"/>
-
- DocType doctype = new DocType("html",
- "-//W3C//DTD XHTML 1.0 Strict//EN",
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd");
-
- final Element htmlRoot = new Element("html"); <co
- linkends="programlisting_catalog2html_tablehead_co"
- xml:id="programlisting_catalog2html_tablehead"/>
- htmlOutput = new Document(htmlRoot);
- htmlOutput.setDocType(doctype);
-
- // We create a HTML skeleton including an "empty" table
- final Element head = new Element("head"),
- body = new Element("body"),
- table = new Element("table");
-
- htmlRoot.addContent(head).addContent(body);
-
- head.addContent(new Element("title").addContent(new Text(titleText)));
-
- body.addContent(new Element("h1").addContent(new Text(titleText)));
-
- body.addContent(table);
-
-
- tableBody = new Element("tbody");
- table.addContent(tableBody);
-
- final Element tr = tableBody.addContent(new Element("tr"));
- for (final String headerField: tableHeaderFields) {
- tr.addContent(new Element("th").addContent(new Text(headerField)));
- }
- }
-
- public void appendItem(final String itemName, final String orderNo) {<co
- linkends="programlisting_catalog2html_insertproduct_co"
- xml:id="programlisting_catalog2html_insertproduct"/>
- final Element tr = new Element("tr");
- tableBody.addContent(tr);
- tr.addContent(new Element("td").addContent(new Text(itemName)));
- tr.addContent(new Element("td").addContent(new Text(orderNo)));
- }
- public void serialize(PrintStream out){
-
- // Set formatting for the XML output
- final Format outFormat = Format.getPrettyFormat();
-
- // Serialize to console
- final XMLOutputter printer = new XMLOutputter(outFormat);
- try {
- printer.output(htmlOutput, System.out);
- } catch (IOException e) {
- e.printStackTrace();
- System.exit(1);
- }
- }
- /**
- * @return the table's <tbody> element
- */
- public Element getTable() {
- return tableBody;
- }
-}
-
- </programlisting>
-
- <calloutlist>
- <callout arearefs="programlisting_catalog2html_htmlskel"
- xml:id="programlisting_catalog2html_htmlskel_co">
- <para>A basic HTML skeleton is is being created:</para>
-
- <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <title>Available articles</title>
- </head>
- <body>
- <h1>Available articles</h1>
- <table>
- <emphasis role="bold"><tbody></emphasis> <!-- Data to be inserted here in next step -->
- <emphasis role="bold"></tbody></emphasis>
- </table>
- </body>
-</html></programlisting>
-
- <para>The table containing the product's data is empty
- at this point and thus invalid.</para>
- </callout>
-
- <callout arearefs="programlisting_catalog2html_tablehead"
- xml:id="programlisting_catalog2html_tablehead_co">
- <para>The table's header is appended but the actual data
- from our two products is still missing:</para>
-
- <programlisting language="none">... <h1>Available articles</h1>
- <table>
- <tbody>
- <tr>
- <th>Article Description</th>
- <th>Order Number</th>
- <emphasis role="bold"></tr></emphasis><!-- Data to be appended after this row in next step -->
- <emphasis role="bold"></tbody></emphasis>
- </table> ...</programlisting>
- </callout>
-
- <callout arearefs="programlisting_catalog2html_insertproduct"
- xml:id="programlisting_catalog2html_insertproduct_co">
- <para>Calling
- <methodname>solve.dom.HtmlTree.appendItem(String,String)</methodname>
- once per product completes the creation of our HTML DOM
- tree:</para>
-
- <programlisting language="none">... </tr>
- <tr>
- <td>Swinging headset</td>
- <td>3218</td>
- </tr>
- <tr>
- <td>200W Stereo Amplifier</td>
- <td>9921</td>
- </tr>
- </tbody> ...</programlisting>
- </callout>
- </calloutlist>
-
- <para>The class
- <classname>solve.dom.Article2Html</classname> reads the
- catalog data:</para>
-
- <programlisting language="none">package solve.dom;
-...
-public class Article2Html {
-
- private final SAXBuilder builder = new SAXBuilder();
- private final HtmlTree htmlResult;
-
- public Article2Html() {
-
- builder.setErrorHandler(new MySaxErrorHandler(System.out));
-
- htmlResult = new HtmlTree("Available articles", new String[] { <co
- linkends="programlisting_catalog2html_glue_createhtmldom_co"
- xml:id="programlisting_catalog2html_glue_createhtmldom"/>
- "Article Description", "Order Number" });
- }
-
- /** Read an Xml catalog instance and insert product names among with their
- * order numbers into the HTML DOM. Then serialize HTML tree to a stream.
- *
- * @param
- * filename of the Xml source.
- * @param out
- * The output stream for HTML serialization.
- * @throws IOException
- * @throws JDOMException
- */
- public void process(final String filename, final PrintStream out) throws JDOMException, IOException{
- final List<Element> items =
- builder.build(filename).getRootElement().getChildren();
-
- for (final Element item : items) { <co
- linkends="programlisting_catalog2html_glue_prodloop_co"
- xml:id="programlisting_catalog2html_glue_prodloop"/>
- htmlResult.appendItem(item.getText(), item.getAttributeValue("orderNo")); <co
- linkends="programlisting_catalog2html_glue_insertprod_co"
- xml:id="programlisting_catalog2html_glue_insertprod"/>
- }
- htmlResult.serialize(out); <co
- linkends="programlisting_catalog2html_glue_serialize_co"
- xml:id="programlisting_catalog2html_glue_serialize"/>
- }
-}</programlisting>
-
- <calloutlist>
- <callout arearefs="programlisting_catalog2html_glue_createhtmldom"
- xml:id="programlisting_catalog2html_glue_createhtmldom_co">
- <para>Create an instance holding a HTML <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> with a
- table header containing the strings <emphasis>Article
- Description</emphasis> and <emphasis>Order
- Number</emphasis>.</para>
- </callout>
-
- <callout arearefs="programlisting_catalog2html_glue_prodloop"
- xml:id="programlisting_catalog2html_glue_prodloop_co">
- <para>Iterate over all product nodes.</para>
- </callout>
-
- <callout arearefs="programlisting_catalog2html_glue_insertprod"
- xml:id="programlisting_catalog2html_glue_insertprod_co">
- <para>Insert the product's name an order number into the
- HTML <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym>.</para>
- </callout>
-
- <callout arearefs="programlisting_catalog2html_glue_serialize"
- xml:id="programlisting_catalog2html_glue_serialize_co">
- <para>Serialize the completed HTML <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> tree to
- the output stream.</para>
- </callout>
- </calloutlist>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
-
- <section xml:id="domJavaScript">
- <title>Using <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> with
- HTML/Javascript</title>
-
- <para>Due to script language support in a variety of browsers we may
- also use the <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> to implement client
- side event handling. As an example we <link
- xlink:href="Ref/src/tablesort.html">demonstrate</link> how a HTML
- table can be made sortable by clicking on a header's column. The
- example code along with the code description can be found at <uri
- xlink:href="http://www.kryogenix.org/code/browser/sorttable">http://www.kryogenix.org/code/browser/sorttable</uri>.</para>
-
- <para>Quite remarkably there are only few ingredients required to
- enrich an ordinary static HTML table with this functionality:</para>
-
- <itemizedlist>
- <listitem>
- <para>An external Javascript library has to be included via
- <code><script type="text/javascript"
- src="sorttable.js"></code></para>
- </listitem>
-
- <listitem>
- <para>Each sortable HTML table needs:</para>
-
- <itemizedlist>
- <listitem>
- <para>A unique <code>id</code> attribute</para>
- </listitem>
-
- <listitem>
- <para>A <code>class="sortable"</code> attribute</para>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- </section>
-
- <section xml:id="domXpath">
- <title>Using <acronym
- xlink:href="http://www.w3.org/TR/xpath">XPath</acronym></title>
-
- <para><xref linkend="domTreeTraversal"/> demonstrated the
- possibility to traverse trees solely by using <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> Method calls.
- Though this approach is possible it will in general not lead to
- stable applications. Real world examples are often based on large
- XML documents with complex hierarchical structures. Thus using this
- rather primitive approach deeply nested method calls are necessary
- to access desired sets of nodes. In addition changing a DTD will
- require rewriting large code portions..</para>
-
- <para>As we already know from <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev>
- transformations <code>Xpath</code> allows to address node sets
- inside a XML tree. The role of <acronym
- xlink:href="http://www.w3.org/TR/xpath">XPath</acronym> can be
- compared to SQL queries when working with relational databases.
- <acronym xlink:href="http://www.w3.org/TR/xpath">XPath</acronym> may
- also be used within <link
- linkend="gloss_Java"><trademark>Java</trademark></link> code. As a
- first example we show an image filename extracting application
- operating on XHTML documents. The following example contains three
- <tag class="starttag">img</tag> elements:</para>
-
- <figure xml:id="htmlGallery">
- <title>A HTML document containing <code>IMG</code> tags.</title>
-
- <programlisting language="none"><?xml version="1.0"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html>
- <head>
- <title>Picture gallery</title>
- </head>
- <body>
- <h1>Picture gallery</h1>
- <p>Images may appear inline:<emphasis role="bold"><img src="inline.gif" alt="none"/></emphasis></p>
- <table>
- <tbody>
- <tr>
- <td>Number one:</td>
- <td><emphasis role="bold"><img src="one.gif" alt="none"/></emphasis></td>
- </tr>
- <tr>
- <td>Number two:</td>
- <td><emphasis role="bold"><img src="http://www.hdm-stuttgart.de/favicon.ico" alt="none"/></emphasis></td>
- </tr>
- </tbody>
- </table>
- </body>
-</html>
-</programlisting>
- </figure>
-
- <para>A given HTML document may contain <tag
- class="starttag">img</tag> elements at
- <emphasis>arbitrary</emphasis> positions. It is sometimes desirable
- to check for existence and accessibility of such external objects
- being necessary for the page's correct rendering. A simple XSL
- script will do first part the job namely extracting the <tag
- class="starttag">img</tag> elements:</para>
-
- <figure xml:id="gallery2imagelist">
- <title>A <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> script for
- image name extraction.</title>
-
- <programlisting language="none"><xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
- xmlns:html="http://www.w3.org/1999/xhtml">
- <xsl:output method="text"/>
-
- <xsl:template match="/">
- <xsl:for-each select="//html:img">
- <xsl:value-of select="@src"/>
- <xsl:text> </xsl:text>
- </xsl:for-each>
- </xsl:template>
-
-</xsl:stylesheet></programlisting>
- </figure>
-
- <para>Note the necessity for <code>html</code> namespace inclusion
- into the <acronym
- xlink:href="http://www.w3.org/TR/xpath">XPath</acronym> expression
- in <code><xsl:for-each select="//html:img"></code>. A simple
- <code>select="//img"></code> results in an empty node set.
- Executing the <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> script yields
- a list of image filenames being contained in the HTML page i.e.
- <code>inline.gif one.gif two.gif</code>.</para>
-
- <para>Now we want to write a <link
- linkend="gloss_Java"><trademark>Java</trademark></link> application
- which allows to check whether these referenced image files do exist
- and have sufficient permissions to be accessed. A simple approach
- may pipe the <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> output to our
- application which then executes the readability checks. Instead we
- want to incorporate the <acronym
- xlink:href="http://www.w3.org/TR/xpath">XPath</acronym> based search
- into the application. Ignoring Namespaces and trying to resemble the
- <abbrev xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev>
- actions as closely as possible our application will have to search
- for <link
- xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/org/w3c/dom/Element.html">Element</link>
- Nodes by the <acronym
- xlink:href="http://www.w3.org/TR/xpath">XPath</acronym> expression
- <code>//html:img</code>:</para>
-
- <figure xml:id="domFindImages">
- <title>Extracting <tag class="emptytag">img</tag> element image
- references from a HTML document.</title>
-
- <programlisting language="none">package dom.xpath;
-...
-public class DomXpath {
- private final SAXBuilder builder = new SAXBuilder();
-
- public DomXpath() {
- builder.setErrorHandler(new MySaxErrorHandler(System.err));
- }
- public void process(final String xhtmlFilename) throws JDOMException, IOException {
-
- final Document htmlInput = builder.build(xhtmlFilename);<co
- linkends="programlisting_java_searchimg_parse_co"
- xml:id="programlisting_java_searchimg_parse"/>
- final XPathExpression<Object> xpath = XPathFactory.instance().compile( "//img" ); <co
- linkends="programlisting_java_searchimg_pf_co"
- xml:id="programlisting_java_searchimg_pf"/> <co
- linkends="programlisting_java_searchimg_newxpath_co"
- xml:id="programlisting_java_searchimg_newxpath"/>
- final List<Object> images = xpath.evaluate(htmlInput);<co
- linkends="programlisting_java_searchimg_execquery_co"
- xml:id="programlisting_java_searchimg_execquery"/>
-
- for (Object o: images) { <co
- linkends="programlisting_java_searchimg_loop_co"
- xml:id="programlisting_java_searchimg_loop"/>
- final Element image = (Element ) o;<co
- linkends="programlisting_java_searchimg_cast_co"
- xml:id="programlisting_java_searchimg_cast"/>
- System.out.print(image.getAttribute("src") + " ");
- }
- }
-}</programlisting>
-
- <caption>
- <para>This application searches for <tag
- class="emptytag">img</tag> elements and shows their
- <code>src</code> attribute value.</para>
- </caption>
- </figure>
-
- <calloutlist>
- <callout arearefs="programlisting_java_searchimg_parse"
- xml:id="programlisting_java_searchimg_parse_co">
- <para>Parse a XHTML document instance into a DOM tree.</para>
- </callout>
-
- <callout arearefs="programlisting_java_searchimg_pf"
- xml:id="programlisting_java_searchimg_pf_co">
- <para>Create a <acronym
- xlink:href="http://www.w3.org/TR/xpath">XPath</acronym>
- factory.</para>
- </callout>
-
- <callout arearefs="programlisting_java_searchimg_newxpath"
- xml:id="programlisting_java_searchimg_newxpath_co">
- <para>Create a <acronym
- xlink:href="http://www.w3.org/TR/xpath">XPath</acronym> query
- instance. This may be used to search for a set of nodes starting
- from a context node.</para>
- </callout>
-
- <callout arearefs="programlisting_java_searchimg_execquery"
- xml:id="programlisting_java_searchimg_execquery_co">
- <para>Using the document's root node as the context node we
- search for <tag class="starttag">img</tag> elements appearing at
- arbitrary positions in our document.</para>
- </callout>
-
- <callout arearefs="programlisting_java_searchimg_loop"
- xml:id="programlisting_java_searchimg_loop_co">
- <para>We iterate over the retrieved list of images.</para>
- </callout>
-
- <callout arearefs="programlisting_java_searchimg_cast"
- xml:id="programlisting_java_searchimg_cast_co">
- <para>Casting to the correct type.</para>
- </callout>
- </calloutlist>
-
- <para>The result is a list of image filename references:</para>
-
- <programlisting language="none">inline.gif one.gif http://www.hdm-stuttgart.de/favicon.ico </programlisting>
-
- <qandaset defaultlabel="qanda" xml:id="quandaentry_CastAlwaysLegal">
- <title>Legal casting?</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>Why is the cast in <coref
- linkend="programlisting_java_searchimg_cast"/> in <xref
- linkend="domFindImages"/> guaranteed to never cause a
- <classname>java.lang.ClassCastException</classname>?</para>
- </question>
-
- <answer>
- <para>The <acronym
- xlink:href="http://www.w3.org/TR/xpath">XPath</acronym>
- <code>//img</code> expression is guaranteed to return only
- <tag class="starttag">img</tag> elements. Thus within our
- <link
- linkend="gloss_Java"><trademark>Java</trademark></link>
- context we are sure to find only
- <classname>org.jdom2.Element</classname> instances.</para>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
-
- <qandaset defaultlabel="qanda" xml:id="exercise_htmlImageVerify">
- <title>Verification of referenced images readability</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>We want to extend the example given in <xref
- linkend="domFindImages"/> by testing the existence and
- checking for readability of referenced images. The following
- HTML document contains <quote>dead</quote> image
- references:</para>
-
- <programlisting language="none"
- xml:id="domCheckImageAccessibility"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"> ...
- <body>
- <h1>External Pictures</h1>
- <p>A local image reference:<img src="inline.gif" alt="none"/></p>
- <table>
- <tbody>
- <tr>
- <td>An existing picture:</td>
- <td><img
- src="http://www.hdm-stuttgart.de/bilder_navigation/laptop.gif"
- alt="none"/></td>
- </tr>
- <tr>
- <td>A non-existing picture:</td>
- <td><img src="<emphasis role="bold">http://www.hdm-stuttgart.de/rotfl.gif</emphasis>" alt="none"/></td>
- </tr>
- </tbody>
- </table>
- </body>
-</html></programlisting>
-
- <para>Write an application which checks for readability of
- <abbrev
- xlink:href="http://www.ietf.org/rfc/rfc1738.txt">URL</abbrev>
- image references to <emphasis>external</emphasis> Servers
- starting either with <code>http://</code> or
- <code>ftp://</code> ignoring other protocol types. Internal
- image references referring to the <quote>current</quote>
- server typically look like <code><img
- src="/images/test.gif"</code>. So in order to distinguish
- these two types of references we may use the XSL built in
- function <link
- xlink:href="http://www.cafeconleche.org/books/bible2/chapters/ch17.html">starts-with()</link>
- testing for the <code>http</code> or <code>ftp</code>
- protocol definition part of an <abbrev
- xlink:href="http://www.ietf.org/rfc/rfc1738.txt">URL</abbrev>.
- A possible output for the example being given is:</para>
-
- <programlisting language="none">Received 'sun.awt.image.URLImageSource' from
- http://www.hdm-stuttgart.de/bilder_navigation/laptop.gif
-Unable to open 'http://www.hdm-stuttgart.de/rotfl.gif'</programlisting>
-
- <para>The following code snippet shows a helpful class
- method to check for both correctness of <abbrev
- xlink:href="http://www.ietf.org/rfc/rfc1738.txt">URL</abbrev>'s
- and accessibility of referenced objects:</para>
-
- <programlisting language="none">package dom.xpath;
-...
-public class CheckUrl {
- public static void checkReadability(final String urlRef) {
- try {
- final URL url = new URL(urlRef);
- try {
- final Object imgCandidate = url.getContent();
- if (null == imgCandidate) {
- System.err.println("Unable to open '" + urlRef + "'");
- } else {
- System.out.println("Received '"
- + imgCandidate.getClass().getName() + "' from "
- + urlRef);
- }
- } catch (IOException e) {
- System.err.println("Unable to open '" + urlRef + "'");
- }
- } catch (MalformedURLException e) {
- System.err.println("Adress '" + urlRef + "' is malformed");
- }
- }
-}</programlisting>
- </question>
-
- <answer>
- <para>We are interested in the set of images within a given
- HTML document containing an <link
- xlink:href="http://www.w3.org/Addressing">URL</link>
- reference starting either with <code>http://</code> or
- <code>ftp://</code>. This is achieved by the following
- <acronym
- xlink:href="http://www.w3.org/TR/xpath">XPath</acronym>
- expression:</para>
-
- <programlisting language="none">//html:img[starts-with(@src, 'http://') or starts-with(@src, 'ftp://')]</programlisting>
-
- <para>The application only needs to pass the corresponding
- <abbrev
- xlink:href="http://www.ietf.org/rfc/rfc1738.txt">URL</abbrev>'s
- to the method <link
- xlink:href="domCheckUrlObjectExistence">CheckUrl.checkReadability()</link>.
- The rest of the code is identical to the <link
- linkend="domFindImages">introductory example</link>:</para>
-
- <informalfigure xml:id="solutionFintExtImgRef">
- <programlisting language="none">package dom.xpath;
-...
-public class CheckExtImage {
- private final SAXBuilder builder = new SAXBuilder();
-
- public CheckExtImage() {
- builder.setErrorHandler(new MySaxErrorHandler(System.err));
- }
- public void process(final String xhtmlFilename) throws JDOMException, IOException {
-
- final Document htmlInput = builder.build(xhtmlFilename);
- final XPathExpression<Object> xpath = XPathFactory.instance().compile(
- "<emphasis role="bold">//img[starts-with(@src, 'http://') or starts-with(@src, 'ftp://')]</emphasis>");
- final List<Object> images = xpath.evaluate(htmlInput);
-
- for (Object o: images) {
- final Element image = (Element ) o;
- <emphasis role="bold">CheckUrl.checkReadability(image.getAttributeValue("src"));</emphasis>
- }
- }
-}</programlisting>
- </informalfigure>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
-
- <section xml:id="domXsl">
- <title><acronym xlink:href="http://www.w3.org/DOM">DOM</acronym> and
- <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev></title>
-
- <para><link linkend="gloss_Java"><trademark>Java</trademark></link>
- based <link linkend="gloss_XML"><abbrev>XML</abbrev></link>
- applications may use XSL style sheets for processing. A <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> tree may for
- example be transformed into another tree. The package <link
- xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/javax/xml/transform/package-frame.html">javax.xml.transform</link>
- provides interfaces and classes for this purpose. We consider the
- following product catalog example:</para>
-
- <figure xml:id="climbingCatalog">
- <title>A simplified <link
- linkend="gloss_XML"><abbrev>XML</abbrev></link> product
- catalog</title>
-
- <programlisting language="none"><catalog xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:noNamespaceSchemaLocation="catalog.xsd">
- <title>Outdoor products</title>
- <introduction>
- <para>We offer a great variety of basic stuff for mountaineering
- such as ropes, harnesses and tents.</para>
- <para>Our shop is proud for its large number of available
- sleeping bags.</para>
- </introduction>
- <product id="x-223">
- <title>Multi freezing bag Nightmare camper</title>
- <description>
- <para>You will feel comfortable till minus 20 degrees - At
- least if you are a penguin or a polar bear.</para>
- </description>
- </product>
- <product id="r-334">
- <title>Rope 40m</title>
- <description>
- <para>Excellent for indoor climbing.</para>
- </description>
- </product>
-</catalog></programlisting>
-
- <para>A corresponding schema file <filename>catalog.xsd</filename>
- is straightforward:</para>
-
- <programlisting language="none"><xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
- xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning" elementFormDefault="qualified"
- vc:minVersion="1.0" vc:maxVersion="1.1">
-
- <xs:simpleType name="money">
- <xs:restriction base="xs:decimal">
- <xs:fractionDigits value="2"/>
- </xs:restriction>
- </xs:simpleType>
-
- <xs:element name="title" type="xs:string"/>
- <xs:element name="para" type="xs:string"/>
-
- <xs:element name="description" type="paraSequence"/>
- <xs:element name="introduction" type="paraSequence"/>
-
- <xs:complexType name="paraSequence">
- <xs:sequence>
- <xs:element ref="para" minOccurs="1" maxOccurs="unbounded"/>
- </xs:sequence>
- </xs:complexType>
-
- <xs:element name="product">
- <xs:complexType>
- <xs:sequence>
- <xs:element ref="title"/>
- <xs:element ref="description"/>
- </xs:sequence>
- <xs:attribute name="id" type="xs:ID" use="required"/>
- <xs:attribute name="price" type="money" use="optional"/>
- </xs:complexType>
- </xs:element>
-
- <xs:element name="catalog">
- <xs:complexType>
- <xs:sequence>
- <xs:element ref="title"/>
- <xs:element ref="introduction"/>
- <xs:element ref="product" minOccurs="1" maxOccurs="unbounded"/>
- </xs:sequence>
- </xs:complexType>
- </xs:element>
-
-</xs:schema>
-</programlisting>
- </figure>
-
- <para>A <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> style sheet
- may be used to transform this document into the HTML Format:</para>
-
- <figure xml:id="catalog2html">
- <title>A <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> style sheet
- for catalog transformation to HTML.</title>
-
- <programlisting language="none"><?xml version="1.0" encoding="utf-8"?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
- version="2.0" xmlns="http://www.w3.org/1999/xhtml">
-
- <xsl:template match="/catalog">
- <html>
- <head><title><xsl:value-of select="title"/></title></head>
- <body style="background-color:#FFFFFF">
- <h1><xsl:value-of select="title"/></h1>
- <xsl:apply-templates select="product"/>
- </body>
- </html>
- </xsl:template>
-
- <xsl:template match="product">
- <h3><xsl:value-of select="title"/></h3>
- <xsl:for-each select="description/para">
- <p><xsl:value-of select="."/></p>
- </xsl:for-each>
- <xsl:if test="price">
- <p>
- <xsl:text>Price:</xsl:text>
- <xsl:value-of select="price/@value"/>
- </p>
- </xsl:if>
- </xsl:template>
-</xsl:stylesheet></programlisting>
- </figure>
-
- <para>As a preparation for <xref linkend="exercise_catalogRdbms"/>
- we now demonstrate the usage of <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> within a <link
- linkend="gloss_Java"><trademark>Java</trademark></link> application.
- This is done by a <link
- xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/javax/xml/transform/Transformer.html">Transformer</link>
- instance:</para>
-
- <figure xml:id="xml2xml">
- <title>Transforming an XML document instance to HTML by a XSL
- style sheet.</title>
-
- <programlisting language="none">package dom.xsl;
-...
-public class Xml2Html {
- private final SAXBuilder builder = new SAXBuilder();
-
- final XSLTransformer transformer;
-
- public Xml2Html(final String xslFilename) throws XSLTransformException {
- builder.setErrorHandler(new MySaxErrorHandler(System.err));
- transformer = new XSLTransformer(xslFilename);
- }
- public void transform(final String xmlInFilename,
- final String resultFilename) throws JDOMException, IOException {
-
- final Document inDoc = builder.build(xmlInFilename);
- Document result = transformer.transform(inDoc);
-
- // Set formatting for the XML output
- final Format outFormat = Format.getPrettyFormat();
-
- // Serialize to console
- final XMLOutputter printer = new XMLOutputter(outFormat);
- printer.output(result.getDocument(), System.out);
-
- }
-}</programlisting>
- </figure>
-
- <para>A corresponding driver file is needed to invoke a
- transformation:</para>
-
- <figure xml:id="xml2xmlDriver">
- <title>A driver class for the xml2xml transformer.</title>
-
- <programlisting language="none">package dom.xsl;
-...
-public class Xml2HtmlDriver {
-...
- public static void main(String[] args) {
- final String
- inFilename = "Input/Dom/climbing.xml",
- xslFilename = "Input/Dom/catalog2html.xsl",
- htmlOutputFilename = "Input/Dom/climbing.html";
- try {
- final Xml2Html converter = new Xml2Html(xslFilename);
- converter.transform(inFilename, htmlOutputFilename);
- } catch (Exception e) {
- System.err.println("The conversion of '" + inFilename
- + "' by stylesheet '" + xslFilename
- + "' to output HTML file '" + htmlOutputFilename
- + "' failed with the following error:" + e);
- e.printStackTrace();
- }
- }
-}</programlisting>
- </figure>
-
- <qandaset defaultlabel="qanda" xml:id="exercise_catalogRdbms">
- <title>HTML from XML and relational data</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <label>Catalogs and RDBMS</label>
-
- <para>We want to extend the transformation being described
- before in <xref linkend="xml2xml"/> by reading price
- information from a RDBMS. Consider the following schema and
- <code>INSERT</code>s:</para>
-
- <programlisting language="none">CREATE TABLE Product(
- orderNo CHAR(10)
- ,price NUMERIC(10,2)
-);
-
-INSERT INTO Product VALUES('x-223', 330.20);
-INSERT INTO Product VALUES('w-124', 110.40);</programlisting>
-
- <para>Adding prices may be implemented the following
- way:</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/xml2html.fig"/>
- </imageobject>
- </mediaobject>
-
- <para>You may implement this by following these
- steps:</para>
-
- <orderedlist>
- <listitem>
- <para>You may reuse class
- <classname>sax.rdbms.RdbmsAccess</classname> from <xref
- linkend="saxRdbms"/>.</para>
- </listitem>
-
- <listitem>
- <para>Use the previous class to modify <xref
- linkend="xml2xml"/> by introducing a new method
- <code>addPrices(final Document catalog)</code> which
- adds prices to the <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> tree
- accordingly. The insertion points may be reached by an
- <acronym
- xlink:href="http://www.w3.org/TR/xpath">XPath</acronym>
- expression.</para>
- </listitem>
- </orderedlist>
- </question>
-
- <answer>
- <para>The additional functionality on top of <xref
- linkend="xml2xml"/> is represented by a method
- <methodname>dom.xsl.XmlRdbms2Html.addPrices()</methodname>.
- This method modifies the <acronym
- xlink:href="http://www.w3.org/DOM">DOM</acronym> input tree
- prior to applying the XSL. Prices are being inserting based
- on data received from an RDBMS via <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>:</para>
-
- <programlisting language="none">package dom.xsl;
-...
-public class XmlRdbms2Html {
- private final SAXBuilder builder = new SAXBuilder();
-
- DbAccess db = new DbAccess();
-
- final XSLTransformer transformer;
- Document catalog;
-
- final org.jdom2.xpath.XPathExpression<Object> selectProducts =
- XPathFactory.instance().compile("/catalog/product");
-
- /**
- * @param xslFilename the stylesheet being used for subsequent
- * transformations by {@link #transform(String, String)}.
- *
- * @throws XSLTransformException
- */
- public XmlRdbms2Html(final String xslFilename) throws XSLTransformException {
- builder.setErrorHandler(new MySaxErrorHandler(System.err));
- transformer = new XSLTransformer(xslFilename);
- }
-
- /**
- * The actual workhorse carrying out the transformation
- * and adding prices from the database table.
- *
- * @param xmlInFilename input file to be transformed
- * @param resultFilename the result file holding the generated HTML document
- * @throws JDOMException The transformation may fail for various reasons.
- * @throws IOException
- */
- public void transform(final String xmlInFilename,
- final String resultFilename) throws JDOMException, IOException {
-
- catalog = builder.build(xmlInFilename);
-
- addPrices();
-
- final Document htmlResult = transformer.transform(catalog);
-
- // Set formatting for the XML output
- final Format outFormat = Format.getPrettyFormat();
-
- // Serialize to console
- final XMLOutputter printer = new XMLOutputter(outFormat);
- printer.output(htmlResult, System.out);
-
- }
- private void addPrices() {
- final List<Object> products = selectProducts.evaluate(catalog.getRootElement());
-
- db.connect("jdbc:mysql://localhost:3306/hdm", "hdmuser", "XYZ");
- for (Object p: products) {
- final Element product = (Element ) p;
- final String productId = product.getAttributeValue("id");
- product.setAttribute("price", db.readPrice(productId));
- }
- db.close();
- }
-}</programlisting>
-
- <para>The method <code>addPrices(...)</code> utilizes our
- RDBMS access class:</para>
-
- <programlisting language="none">package dom.xsl;
-...
-public class DbAccess {
- public void connect(final String jdbcUrl,
- final String userName, final String password) {
- try {
- conn = DriverManager.getConnection(jdbcUrl, userName, password);
- priceQuery = conn.prepareStatement(sqlPriceQuery);
- } catch (SQLException e) {
- System.err.println("Unable to open connection to database:" + e);}
- }
- public String readPrice(final String articleNumber) {
- String result;
- try {
- priceQuery.setString(1, articleNumber);
- final ResultSet rs = priceQuery.executeQuery();
- if (rs.next()) {
- result = rs.getString("price");
- } else {
- result = "No price available for article '" + articleNumber + "'";
- }
- } catch (SQLException e) {
- result = "Error reading price for article '" + articleNumber + "':" + e;
- }
- return result;
- }
- ...
-}</programlisting>
-
- <para>Of course the connection details should be moved to a
- configuration file.</para>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
- </section>
- </chapter>
-
- <chapter xml:id="introPersistence">
- <title>Accessing Relational Data</title>
-
- <section xml:id="persistence">
- <title>Persistence in Object Oriented languages</title>
-
- <para>Following <xref linkend="Bauer05"/> we may define persistence
- by:</para>
-
- <blockquote>
- <para>persistence allows an object to outlive the process that
- created it. The state of the object may be stored to disk and an
- object with the same state re-created at some point in the
- future.</para>
- </blockquote>
-
- <para>The notion of <quote>process</quote> refers to operating
- systems. Let us start wit a simple example assuming a <link
- linkend="gloss_Java"><trademark>Java</trademark></link> class
- User:</para>
-
- <programlisting language="none">public class User {
- String cname; //The user's common name e.g. 'Joe Bix'
- String uid; //The user's unique system ID (login name) e.g. 'bix'
-
-// getters, setters and other stuff
- ...
-}</programlisting>
-
- <para>A relational implementation might look like:</para>
-
- <programlisting language="none">CREATE TABLE User(
- CHAR(80) cname
- ,CHAR(10) uid PRIMARY KEY
-)</programlisting>
-
- <para>Now a <link
- linkend="gloss_Java"><trademark>Java</trademark></link> application
- may create instances of class <code>User</code> and save these to a
- database:</para>
-
- <figure xml:id="processObjPersist">
- <title>Persistence across process boundaries</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/persistence.fig" scale="65"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>Both the <trademark
- xlink:href="http://www.oracle.com/technetwork/java/javase">JRE</trademark>
- instances and the RDBMS database server are processes (or sets of
- processes) typically existing in different address spaces. The two
- <trademark
- xlink:href="http://www.oracle.com/technetwork/java/javase">JRE</trademark>
- processes mentioned here may as well be started in disjoint address
- spaces. In fact we might even run two entirely different applications
- implemented in different programming languages like <abbrev
- xlink:href="http://www.php.net">PHP</abbrev>.</para>
-
- <para>It is important to mention that the two arrows
- Â <quote>save</quote> and <quote>load</quote> thus typically denote a
- communication across machine boundaries.</para>
- </section>
-
- <section xml:id="jdbcIntro">
- <title>Introduction to <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark></title>
-
- <section xml:id="jdbcWrite">
- <title>Write access, principles</title>
-
- <para>Connecting an application to a database means to establish a
- connection from a client to a database server:</para>
-
- <figure xml:id="jdbcClientServer">
- <title>Networking between clients and database servers</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/clientserv.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>So <trademark
- xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc">JDBC</trademark>
- is just one among a whole bunch of protocol implementations
- connecting database servers and applications. Consequently
- <trademark
- xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc">JDBC</trademark>
- is expected to appear in the lower layer of multi-tier applications.
- We take a three-tier application as a starting point:</para>
-
- <figure xml:id="jdbcThreeTier">
- <title>The role of <trademark
- xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc">JDBC</trademark>
- in a three-tier application</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/jdbcThreeTier.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>We may add an additional layer. Web applications are typically
- being build on top of an application server (<productname
- xlink:href="http://www.ibm.com/software/de/websphere/">WebSphere</productname>,
- <productname
- xlink:href="http://glassfish.java.net">Glassfish</productname>,
- <productname
- xlink:href="http://www.jboss.org/jbossas">Jboss</productname>,...)
- providing additional services:</para>
-
- <figure xml:id="jdbcFourTier">
- <title><trademark
- xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc">JDBC</trademark>
- connecting application server and database.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/jdbcFourTier.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>So what is actually required to connect to a database server?
- A client requires the following parameter values to open a
- connection:</para>
-
- <orderedlist>
- <listitem xml:id="ItemJdbcProtocol">
- <para>The type of database server i.e. <productname
- xlink:href="http://www.oracle.com/us/products/database">Oracle</productname>,
- <productname
- xlink:href="www.ibm.com/software/data/db2">DB2</productname>,
- <productname
- xlink:href="http://www-01.ibm.com/software/data/informix">Informix</productname>,
- <productname
- xlink:href="http://www.mysql.com">Mysql</productname> etc. This
- information is needed because of vendor dependent <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- protocol implementations.</para>
- </listitem>
-
- <listitem>
- <para>The server's <link
- xlink:href="http://en.wikipedia.org/wiki/Domain_Name_System">DNS</link>
- name or IP number</para>
- </listitem>
-
- <listitem>
- <para>The database service's port number at the previously
- defined host. The database server process listens for
- connections to this port number.</para>
- </listitem>
-
- <listitem xml:id="itemJdbcDatabaseName">
- <para>The database name within the given database server</para>
- </listitem>
-
- <listitem>
- <para>Optional: A database user's account name and
- password.</para>
- </listitem>
- </orderedlist>
-
- <para>Items <xref linkend="ItemJdbcProtocol"/> - <xref
- linkend="itemJdbcDatabaseName"/> will be encapsulated into a so
- called <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- <link
- xlink:href="http://en.wikipedia.org/wiki/Uniform_Resource_Locator">URL</link>.
- We consider a typical example corresponding to the previous
- parameter list:</para>
-
- <figure xml:id="jdbcUrlComponents">
- <title>Components of a <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- URL</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/jdbcurl.fig" scale="65"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>In fact this <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- URL example closely resembles other types of URL strings as being
- defined in <uri
- xlink:href="http://www.ietf.org/rfc/rfc2396.txt">http://www.ietf.org/rfc/rfc2396.txt</uri>.
- Look for <code>opaque_part</code> to understand the second
- <quote>:</quote> in the protocol definition part of a <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- URL. Common example for <abbrev
- xlink:href="http://www.ietf.org/rfc/rfc1738.txt">URL</abbrev>s
- are:</para>
-
- <itemizedlist>
- <listitem>
- <para><code>http://www.hdm-stuttgart.de/aaa</code></para>
- </listitem>
-
- <listitem>
- <para><code>http://someserver.com:8080/someResource</code></para>
- </listitem>
-
- <listitem>
- <para><code>ftp://mirror.mi.hdm-stuttgart.de/Firmen</code></para>
- </listitem>
- </itemizedlist>
-
- <para>We notice the explicit mentioning of a port number 8080 in the
- second example; The default <abbrev
- xlink:href="http://www.w3.org/Protocols">http</abbrev> protocol port
- number is 80. So if a web server accepts connections at port 80 we
- do not have to specify this value. A web browser will automatically
- use this default port.</para>
-
- <para>Actually the notion <quote><code>jdbc:mysql</code></quote>
- denotes a sub protocol implementation namely<orgname>
- Mysql</orgname>'s implementation of <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>.
- Connecting to an IBM DB2 server would require jdbc:db2 for this
- protocol part.</para>
-
- <para>In contrast to <abbrev
- xlink:href="http://www.w3.org/Protocols">http</abbrev> no standard
- ports are <quote>officially</quote> assigned for <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- protocol variants. Due to vendor specific implementations this does
- not make any sense. Thus we <emphasis role="bold">always</emphasis>
- have to specify the port number when opening <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- connections.</para>
-
- <para>Writing <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- based applications follows a simple scheme:</para>
-
- <figure xml:id="jdbcArchitecture">
- <title>Architecture of JDBC</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/jdbcarch.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>From a programmer's point of view the
- <classname>java.sql.DriverManager</classname> is a bootstrapping
- object: Other objects like Statement instances are created from this
- central and unique object.</para>
-
- <para>The first instance being created by the
- <classname>java.sql.DriverManager</classname> is an object of type
- <classname>java.sql.Connection</classname>. In <xref
- linkend="exerciseJdbcWhyInterface"/> we discuss the way vendor
- specific implementation details are hidden by Interfaces. We can
- distinguish between:</para>
-
- <orderedlist>
- <listitem>
- <para>Vendor neutral specific parts of a <trademark
- xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc">JDBC</trademark>
- environment. These are those components being shipped by Oracle
- or other organizations providing <link
- linkend="gloss_Java"><trademark>Java</trademark></link>
- runtimes. The class
- <classname>java.sql.DriverManager</classname> belongs to this
- domain.</para>
- </listitem>
-
- <listitem>
- <para>Vendor specific parts. In <xref
- linkend="jdbcArchitecture"/> this starts with the
- <classname>java.sql.Connection</classname> object.</para>
- </listitem>
- </orderedlist>
-
- <para>The <classname>java.sql.Connection</classname> object thus
- marks the boundary between a <trademark
- xlink:href="http://www.oracle.com/technetwork/java/javase">JDK</trademark>
- / <trademark
- xlink:href="http://www.oracle.com/technetwork/java/javase">JRE</trademark>
- and a <trademark
- xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc">JDBC</trademark>
- Driver implementation from e.g. Oracle or other institutions.</para>
-
- <para><xref linkend="jdbcArchitecture"/> does not show details about
- the relations between <classname>java.sql.Connection</classname>,
- <classname>java.sql.Statement</classname> and
- <classname>java.sql.ResultSet</classname> objects. We start by
- giving a rough description of the tasks and responsibilities these
- three types have:</para>
-
- <glosslist>
- <glossentry>
- <glossterm><classname>java.sql.Connection</classname></glossterm>
-
- <glossdef>
- <para>Holding a permanent connection to a database server.
- Both client and server can contact each other. The database
- server may for example terminate a transaction if problems
- like deadlocks occur.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm><classname>java.sql.Statement</classname></glossterm>
-
- <glossdef>
- <para>We have two distinct classes of actions:</para>
-
- <orderedlist>
- <listitem>
- <para>Instructions to modify data on the database server.
- These include <code>INSERT</code>, <code>UPDATE</code> and
- <code>DELETE</code> operations as far as
- <abbrev>SQL-DML</abbrev> is concerned. <trademark
- xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc">JDBC</trademark>
- acts as a means of transport and merely returns integer
- values back to the client like the number of rows being
- affected by an UPDATE.</para>
- </listitem>
-
- <listitem>
- <para>Instructions reading data from the server. This is
- done by sending SELECT statements. It is not sufficient to
- just return integer values: Instead <trademark
- xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc">JDBC</trademark>
- needs to copy complete datasets back to the client to fill
- containers being accessible by applications. This is being
- discussed in <xref linkend="jdbcRead"/>.</para>
- </listitem>
- </orderedlist>
- </glossdef>
- </glossentry>
- </glosslist>
-
- <para>We shed some light on the relationship between these important
- <trademark
- xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc">JDBC</trademark>
- components and their respective creation:<figure
- xml:id="jdbcObjectCreation">
- <title>Important <trademark
- xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc">JDBC</trademark>
- instances and relationships.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/jdbcObjectRelation.fig"/>
- </imageobject>
- </mediaobject>
- </figure></para>
- </section>
-
- <section xml:id="writeAccessCoding">
- <title>Write access, coding!</title>
-
- <para>So how does it actually work with respect to coding? You may
- want to read <xref linkend="toolingConfigJdbc"/> before starting
- your exercises. We first prepare a database table using Eclipse's
- database tools:</para>
-
- <figure xml:id="figSchemaPerson">
- <title>A relation <code>Person</code> containing names and email
- addresses</title>
-
- <programlisting language="none"><emphasis role="strong">CREATE</emphasis> <emphasis
- role="strong">TABLE</emphasis> Person (
- name CHAR(20)
- ,email CHAR(20) <emphasis>UNIQUE</emphasis>)</programlisting>
- </figure>
-
- <para>Our actual (toy) <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- application will insert a single object ('Jim', 'jim@foo.org') into
- the <code>Person</code> relation. This is simpler than reading data
- since no client <classname>java.sql.ResultSet</classname> container
- is needed:</para>
-
- <figure xml:id="figJdbcSimpleWrite">
- <title>A simple <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- application inserting data into a relational table.</title>
-
- <programlisting language="none">01 package sda.jdbc.intro.v1;
-02
-03 import java.sql.Connection;
-04 import java.sql.DriverManager;
-05 import java.sql.SQLException;
-06 import java.sql.Statement;
-07
-08 public class SimpleInsert {
-09
-10 public static void main(String[] args) throws SQLException {
-11 // Step 1: Open a connection to the database server
-12 final Connection conn = DriverManager.getConnection(
-13 "jdbc:mysql://localhost:3306/hdm", "hdmuser", "XYZ");
-14 // Step 2: Create a Statement instance
-15 final Statement stmt = conn.createStatement();
-16 // Step 3: Execute the desired INSERT
-17 final int updateCount = stmt.executeUpdate(
-18 "INSERT INTO Person VALUES('Jim', 'jim@foo.org')");
-19 // Step 4: Give feedback to the enduser
-20 System.out.println("Successfully inserted " + updateCount + " dataset(s)");
-21 }
-22 }</programlisting>
- </figure>
-
- <para>Looks simple? Unfortunately it does not (yet) work:</para>
-
- <programlisting language="none">Exception in thread "main" java.sql.SQLException: <emphasis
- role="bold">
- No suitable driver found for jdbc:mysql://localhost:3306/hdm</emphasis>
- at java.sql.DriverManager.getConnection(DriverManager.java:604)
- at java.sql.DriverManager.getConnection(DriverManager.java:221)
- at sda.jdbc.intro.SimpleInsert.main(SimpleInsert.java:12)</programlisting>
-
- <para>What's wrong here? In <xref linkend="figureConfigJdbcDriver"/>
- we needed a <productname
- xlink:href="http://www.mysql.com">Mysql</productname> <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- Driver implementation <filename>mysql-connector-java.jar</filename>
- as a prerequisite to open connections to a database server. This
- implementation is mandatory for our toy application as well. All we
- have to do is adding <filename>mysql-connector-java.jar</filename>
- to our <link linkend="gloss_Java"><trademark>Java</trademark></link>
- <varname>CLASSPATH</varname> at <emphasis
- role="bold">runtime</emphasis>.</para>
-
- <para>Depending on our <link
- linkend="gloss_Java"><trademark>Java</trademark></link> environment
- this will be achieved by different means. Eclipse requires the
- definition of a run configuration as being described in <uri
- xlink:href="http://help.eclipse.org/juno/index.jsp?topic=/org.eclipse.jdt.doc.user/tasks/tasks-java-local-configuration.htm">http://help.eclipse.org/juno/index.jsp?topic=/org.eclipse.jdt.doc.user/tasks/tasks-java-local-configuration.htm</uri>.
- When configuring a run-time configuration for
- <classname>sda.jdbc.intro.SimpleInsert</classname> we have to add
- <filename>mysql-connector-java.jar</filename> to the
- <varname>Classpath</varname> tab. The following screen shot shows a
- working configuration:</para>
-
- <figure xml:id="figureConfigRunExtJar">
- <title>Creating an Eclipse run time configuration containing a
- <productname xlink:href="http://www.mysql.com">Mysql</productname>
- <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- Driver Jar marked red.</title>
-
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Screen/runConfigJarAnnot.screen.png"
- scale="70"/>
- </imageobject>
- </mediaobject>
- </screenshot>
- </figure>
-
- <para>This time execution works as expected:</para>
-
- <programlisting language="none">Successfully inserted 1 dataset(s)</programlisting>
-
- <qandaset defaultlabel="qanda" xml:id="quandaentry_DupInsert">
- <title>Exception on inserting objects</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>A second invocation of
- <classname>sda.jdbc.intro.v1.SimpleInsert</classname> yields
- the following runtime error:</para>
-
- <programlisting language="none">Exception in thread "main"
- com.mysql.jdbc.exceptions.jdbc4.MySQLIntegrityConstraintViolationException:
- <emphasis role="bold">Duplicate entry 'jim@foo.org' for key 'email'</emphasis>
-...
- at com.mysql.jdbc.StatementImpl.executeUpdate(StatementImpl.java:1617)
- at sda.jdbc.intro.SimpleInsert.main(SimpleInsert.java:17)</programlisting>
- </question>
-
- <answer>
- <para>This expected error is easy to understand: The
- exception's message text <emphasis role="bold">Duplicate
- entry 'Jim' for key 'PRIMARY'</emphasis> informs us about a
- UNIQUE key constraint violation with respect to the
- attribute <code>email</code> in our schema definition in
- <xref linkend="figSchemaPerson"/>. We cannot add a second
- entry with the same value <code>'jim@foo.org'</code>.</para>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
-
- <para>It is worth to mention that the <productname
- xlink:href="http://www.mysql.com">Mysql</productname> driver
- implementation does not have to be available at compile time.
- <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- defines interfaces in favour of (concrete) classes. The latter are
- only required at runtime.</para>
-
- <para>When working with eclipse we need a separate runtime
- configuration for each runnable <link
- linkend="gloss_Java"><trademark>Java</trademark></link> application
- to add the <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- driver implementation to the runtime <envar>CLASSPATH</envar>. This
- may become tedious. Judging the pros and cons you may simply add
- <filename>mysql-connector-java.jar</filename> to your compile time
- <envar>CLASSPATH as well</envar>. As a drawback all <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- implementing classes will now become visible wen e.g. hitting
- auto-completion.</para>
-
- <para>We now discuss some important methods being defined in the
- <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- interfaces:</para>
-
- <glosslist>
- <glossentry>
- <glossterm><classname>java.sql.Connection</classname></glossterm>
-
- <glossdef>
- <itemizedlist>
- <listitem>
- <para><link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#createStatement()">createStatement()</link></para>
- </listitem>
-
- <listitem>
- <para><link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#setAutoCommit(boolean)">setAutoCommit()</link>,
- <link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#getAutoCommit()">getAutoCommit()</link></para>
- </listitem>
-
- <listitem>
- <para><link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#getWarnings()">getWarnings()</link></para>
- </listitem>
-
- <listitem>
- <para><link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#isClosed()">isClosed()</link>,
- <link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#isValid(int)">isValid(int
- timeout)</link></para>
- </listitem>
-
- <listitem>
- <para><link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#rollback()">rollback()</link>,
- <link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#commit()">commit()</link>
- and .</para>
- </listitem>
-
- <listitem>
- <para><link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#close()">close()</link></para>
- </listitem>
- </itemizedlist>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm><classname>java.sql.Statement</classname></glossterm>
-
- <glossdef>
- <itemizedlist>
- <listitem>
- <para><link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Statement.html#executeUpdate(java.lang.String)">executeUpdate(String
- sql)</link></para>
- </listitem>
-
- <listitem>
- <para><link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Statement.html#getConnection()">getConnection()</link></para>
- </listitem>
-
- <listitem>
- <para><link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Statement.html#getResultSet()">getResultSet()</link></para>
- </listitem>
-
- <listitem>
- <para><link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Statement.html#close()">close()</link>
- and <link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Statement.html#isClosed()">isClosed()</link></para>
- </listitem>
- </itemizedlist>
- </glossdef>
- </glossentry>
- </glosslist>
-
- <qandaset defaultlabel="qanda" xml:id="quandaentry_AutoCommit">
- <title><trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- and transactions</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para><link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#setAutoCommit(boolean)">How
- does the method setAutoCommit()</link> relate to <link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#commit()">commit()</link>
- and <link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#rollback()">rollback()</link>?</para>
- </question>
-
- <answer>
- <para>A connections default state is <code>autocommit ==
- true</code>. This means that individual SQL statements are
- executed as separate transactions.</para>
-
- <para>If we want to group two or more statements into a
- transaction we have to:</para>
-
- <orderedlist>
- <listitem>
- <para>Call
- <code>connection.setAutoComit(false)</code></para>
- </listitem>
-
- <listitem>
- <para>From now on subsequent SQL statements will
- implicitly become part of a transaction till either of
- the three events happens:</para>
-
- <orderedlist numeration="loweralpha">
- <listitem>
- <para><code>connection.commit()</code></para>
- </listitem>
-
- <listitem>
- <para><code>connection.rollback()</code></para>
- </listitem>
-
- <listitem>
- <para>The transaction gets aborted by the database
- server. This may for example happen in case of a
- deadlock conflict with a second transaction.</para>
- </listitem>
- </orderedlist>
-
- <para>Note that the first two events are initiated by
- our client software. The third possible action is being
- carried out by the database server.</para>
- </listitem>
- </orderedlist>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
-
- <qandaset defaultlabel="qanda" xml:id="quandaentry_Close">
- <title>Closing <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- connections</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>Why is it very important to call the close() method
- for <classname>java.sql.Connection</classname> and / or
- <classname>java.sql.Statement</classname> instances?</para>
- </question>
-
- <answer>
- <para>A <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- connection ties network resources (socket connections).
- These may be used up if e.g. new connections get established
- within a loop without being closed.</para>
-
- <para>The situation is comparable to memory leaks when using
- programming languages lacking a garbage collector.</para>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
-
- <qandaset defaultlabel="qanda" xml:id="quandaentry_AbortTran">
- <title>Aborted transactions</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>In the previous exercise we mentioned the possibility
- of a transaction abort issued by the database server. Which
- responsibility arises for an application programmer? Hint:
- How may an implementation become aware of such an abort
- transaction event?</para>
- </question>
-
- <answer>
- <para>If a database server aborts a transaction a
- <classname>java.sql.SQLException</classname> will be thrown.
- An application must be aware of this possibility and thus
- implement a sensible <code>catch(...)</code> clause
- accordingly.</para>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
-
- <qandaset defaultlabel="qanda" xml:id="exerciseJdbcWhyInterface">
- <title>Interfaces and classes in <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark></title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>The <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- standard mostly defines interfaces as
- <classname>java.sql.Connection</classname> and
- <classname>java.sql.Statement</classname>. Why are these not
- being defined as classes? Moreover why is
- <classname>java.sql.DriverManager</classname> being defined
- as a class rather than an interface?</para>
-
- <para>You may want to supply code examples to explain your
- argumentation.</para>
- </question>
-
- <answer>
- <para>Figure <xref linkend="jdbcArchitecture"/> tells us
- about the vendor independent architecture of <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>.
- Oracle for example may implement a class
- <code>com.oracle.jdbc.OracleConnection</code>:</para>
-
- <programlisting annotations="nojavadoc" language="java">package com.oracle.jdbc;
-
-import java.sql.Connection;
-import java.sql.Statement;
-import java.sql.SQLException;
-
-public class OracleConnection implements Connection {
-
-...
-
-Statement createStatement(int resultSetType,
- int resultSetConcurrency)
- throws SQLException) {
- // Implementation omitted here due to
- // limited personal hacking capabilities
- ...
-}
-...
-}</programlisting>
-
- <para>If a programmer only uses the <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- interfaces rather than a vendor's classes it is much easier
- to make the resulting application work with different
- databases from other vendors. This way a company's
- implementation is not exposed to our own <link
- linkend="gloss_Java"><trademark>Java</trademark></link>
- code.</para>
-
- <para>Regarding the special role of
- <classname>java.sql.DriverManager</classname> we notice the
- need of a starting point: We have to create an initial
- instance of some class. In theory (<emphasis role="bold">BUT
- NOT IN PRACTICE!!!</emphasis>) the following (ugly code)
- might be possible:</para>
-
- <programlisting language="none">package my.personal.application;
-
-import java.sql.Connection;
-import java.sql.Statement;
-import java.sql.SQLException;
-
-public someClass {
-
- public void someMethod(){
-
- Connection conn = <emphasis role="bold">new OracleConnection()</emphasis>; // bad idea!
- ...
- }
- ...
-}</programlisting>
-
- <para>The problem with this approach is the explicit
- constructor call: Whenever we want to use another database
- we have two possibilities:</para>
-
- <itemizedlist>
- <listitem>
- <para>Rewrite our code.</para>
- </listitem>
-
- <listitem>
- <para>Introduce some sort of switch statement to provide
- a fixed number of databases beforehand:</para>
-
- <programlisting language="none">public void someMethod(final String vendor){
-
- final Connection conn;
-
- switch(vendor) {
- case "ORACLE":
- conn = new OracleConnection();
- break;
-
- case "DB2":
- conn = new Db2Connection();
- break;
-
- default:
- conn = null;
- break;
- }
- ...
-}</programlisting>
-
- <para>Adding a new database still requires code
- rewriting.</para>
- </listitem>
- </itemizedlist>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
-
- <qandaset defaultlabel="qanda" xml:id="quandaentry_DriverDispatch">
- <title>Driver dispatch mechanism</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>In exercise <xref linkend="exerciseJdbcWhyInterface"/>
- we saw a hypothetic way to resolve the interface/class
- resolution problem by using a switch clause. How is this
- <code>switch</code> clause's logic actually realized in a
- <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- based application? (<quote>behind the scenes</quote>)</para>
-
- <para>Hint: Read the documentation of
- <classname>java.sql.DriverManager</classname>.</para>
- </question>
-
- <answer>
- <para>Prior to opening a Connection a <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- driver registers itself at the
- <classname>java.sql.DriverManager</classname> singleton
- instance. For this purpose the standard defined the method
- <link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/DriverManager.html#registerDriver(java.sql.Driver)">registerDriver(Driver)</link>.
- On success the <classname>java.sql.DriverManager</classname>
- adds the driver to an internal dictionary:</para>
-
- <informaltable border="1">
- <col width="20%"/>
-
- <col width="30%"/>
-
- <tr>
- <th>protocol</th>
-
- <th>driver instance</th>
- </tr>
-
- <tr>
- <td>jdbc:mysql</td>
-
- <td>mysqlDriver instance</td>
- </tr>
-
- <tr>
- <td>jdbc:oracle</td>
-
- <td>oracleDriver instance</td>
- </tr>
-
- <tr>
- <td>...</td>
-
- <td>...</td>
- </tr>
- </informaltable>
-
- <para>So whenever the method <link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/DriverManager.html#getConnection(java.lang.String,%20java.lang.String,%20java.lang.String)">getConnection()</link>
- is being called the
- <classname>java.sql.DriverManager</classname> will scan the
- <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- URL and isolate the protocol part. If we start with
- <code>jdbc:mysql://someserver.com:3306/someDatabase</code>
- this is just <code>jdbc:mysql</code>. The value is then
- being looked up in the above table of registered drivers to
- choose an appropriate instance or null otherwise. This way
- our hypothetic switch including the default value null is
- actually implemented.</para>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
-
- <section xml:id="propertiesFile">
- <title>Connection properties</title>
-
- <para>So far our application depicted in <xref
- linkend="figJdbcSimpleWrite"/> suffers both from missing error
- handling and hard-coded parameters.</para>
-
- <para>Professional applications must be configurable. Changing the
- password currently requires source code modification and
- recompilation. <link
- linkend="gloss_Java"><trademark>Java</trademark></link> offers a
- standard procedure to externalize parameters like
- <varname>username</varname>, <varname>password</varname> an
- <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- connection URL as being present in <xref
- linkend="figJdbcSimpleWrite"/>: We may externalize these parameters
- to external so called properties files:</para>
-
- <figure xml:id="propertyExternalization">
- <title>Externalize a single string <code>"User name"</code> to a
- separate file <filename>message.properties</filename>.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/externalize.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>The current figure shows the externalization of just a single
- property. The file <filename>message.properties</filename> contains
- key-value pairs. The key <code>PropHello.uname</code> contains the
- value <code>User name</code>. Multiple strings may be externalized
- to the same properties file.</para>
-
- <para>Eclipse does have tool support for externalization. Simply hit
- Source --> Externalize Strings from the context menu. This
- activates a wizard to define property keys, renaming the generated
- helper class' name and finally create the actual
- <filename>message.properties</filename> file.</para>
-
- <qandaset defaultlabel="qanda" xml:id="quandaentry_WritProps">
- <title>Moving <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- <abbrev
- xlink:href="http://www.ietf.org/rfc/rfc1738.txt">URL</abbrev> and
- credentials to a property file</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>Start executing the code given in <xref
- linkend="figJdbcSimpleWrite"/>. Then extend this example by
- externalizing all <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- related connection parameters to a
- <filename>jdbc.properties</filename> file like:</para>
-
- <programlisting language="none">SimpleInsert.jdbcUrl=jdbc:mysql://localhost:3306/hdm
-SimpleInsert.password=XYZ
-SimpleInsert.username=hdmuser</programlisting>
-
- <para>As being stated earlier the eclipse wizard assists you
- by generating both the properties file and a helper class
- reading that file at runtime.</para>
- </question>
-
- <answer>
- <para>The current exercise is mostly related to tooling.
- From our <link
- linkend="gloss_Java"><trademark>Java</trademark></link> code
- the context menu allows us to choose the desired
- wizard:</para>
-
- <informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Screen/externalize.screen.png"/>
- </imageobject>
- </mediaobject>
- </informalfigure>
-
- <para>We may now:</para>
-
- <itemizedlist>
- <listitem>
- <para>Select the strings to be externalized.</para>
- </listitem>
-
- <listitem>
- <para>Supply key names. In the subsequent screenshot
- this task has already been started by manually replacing
- the default <code>SimpleInsert.1</code> by
- <code>Simpleinsert.jdbc</code>.</para>
- </listitem>
-
- <listitem>
- <para>Redefine other parameters like prefix, properties
- file name etc. In the following screenshot only the
- first of three keys has been manually renamed to the
- sensible value
- <varname>SimpleInsert.jdbc</varname>.</para>
- </listitem>
- </itemizedlist>
-
- <informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Screen/externalize2.screen.png"/>
- </imageobject>
- </mediaobject>
- </informalfigure>
-
- <para>The wizard also generates a class
- <classname>sda.jdbc.intro.v1.DbProps</classname> to actually
- access our properties:</para>
-
- <programlisting language="none">package sda.jdbc.intro.v1;
-...
-public class DbProps {
- private static final String BUNDLE_NAME = "sda.jdbc.intro.v1.database";
-
- private static final ResourceBundle RESOURCE_BUNDLE = ResourceBundle
- .getBundle(BUNDLE_NAME);
-
- private DbProps() {
- }
-
- public static String getString(String key) {
- try {
- return RESOURCE_BUNDLE.getString(key);
- } catch (MissingResourceException e) {
- return '!' + key + '!';
- }
- }
-}</programlisting>
-
- <para>Our <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- related code now contains three references to external
- properties:</para>
-
- <programlisting language="none">package sda.jdbc.intro.v1;
-...
-public class SimpleInsert {
-
-
- public static void main(String[] args) throws SQLException {
- // Step 1: Open a connection to the database server
- final Connection conn = DriverManager.getConnection (
- <emphasis role="bold">DbProps.getString("PersistenceHandler.jdbcUrl"), </emphasis>
- <emphasis role="bold">DbProps.getString("PersistenceHandler.username")</emphasis>,
- <emphasis role="bold">DbProps.getString("PersistenceHandler.password")</emphasis>);
- // Step 2: Create a Statement instance
- final Statement stmt = conn.createStatement();
- // Step 3: Execute the desired INSERT
- final int updateCount = stmt.executeUpdate(
- "INSERT INTO Person VALUES('Jim', 'jim@foo.org')");
- // Step 4: Give feedback to the enduser
- System.out.println("Successfully inserted " + updateCount + " dataset(s)");
- }
-}</programlisting>
-
- <para>The current base name
- <classname>sda.jdbc.intro.v1.PersistenceHandler</classname>
- is related to a later exercise.</para>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
-
- <section xml:id="sectSimpleInsertGui">
- <title>A first GUI sketch</title>
-
- <para>So far all data records being transferred to the database
- server are still hard-coded in our application. In practice a user
- wants to enter data of persons to be submitted to the
- database.</para>
-
- <para>We now guide you to develop a first version of a simple GUI
- for this tasks. A more <link linkend="figureDataInsert2">elaborate
- version</link> will be presented in a follow-up exercise. The
- screenshot illustrates the intended application behaviour:</para>
-
- <figure xml:id="simpleInsertGui">
- <title>A simple GUI to insert data into a database server.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Screen/simpleInsertGui.screen.png"/>
- </imageobject>
-
- <caption>
- <para>After clicking <quote>Insert</quote> a message is being
- presented to the user. This message may as well indicate a
- failure.</para>
- </caption>
- </mediaobject>
- </figure>
-
- <para>Implementing Swing GUI applications requires knowledge as
- being taught in e.g. <link
- xlink:href="http://www.hdm-stuttgart.de/studenten/stundenplan/vorlesungsverzeichnis/vorlesung_detail?vorlid=5212221">113300
- Entwicklung von Web-Anwendungen</link>. If you do not (yet) feel
- comfortable writing <productname
- xlink:href="http://docs.oracle.com/javase/tutorial/uiswing/index.html">Swing</productname>
- applications you may want to read <uri
- xlink:href="http://www.javamex.com/tutorials/swing">http://www.javamex.com/tutorials/swing</uri>
- and <emphasis role="bold">really</emphasis> understand the examples
- being presented therein.</para>
-
- <qandaset defaultlabel="qanda" xml:id="quandaentry_GuiDb">
- <title>GUI for inserting Person data to a database server</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>Write a GUI application as being outlined in <xref
- linkend="simpleInsertGui"/>. You may proceed as
- follows:</para>
-
- <orderedlist>
- <listitem>
- <para>Write a dummy GUI without any database
- functionality. Only present the two labels an input
- fields and the Insert button.</para>
- </listitem>
-
- <listitem>
- <para>Add an
- <classname>java.awt.event.ActionListener</classname>
- which generates a SQL INSERT Statement when clicking the
- Insert button. Return this string to the user as being
- shown in the message window of <xref
- linkend="simpleInsertGui"/>.</para>
-
- <para>At this point you still do not need a database
- connection. The message shown to the user is just a
- fake, so the GUI <emphasis
- role="bold">appears</emphasis> to be working.</para>
- </listitem>
-
- <listitem>
- <para>Establish a
- <classname>java.sql.Connection</classname> and create a
- <classname>java.sql.Statement</classname> instance when
- launching your application. Use the latter in your
- <classname>java.awt.event.ActionListener</classname> to
- actually insert datasets into your database.</para>
- </listitem>
- </orderedlist>
- </question>
-
- <answer>
- <para>The complete implementation resides in
- <classname>sda.jdbc.intro.v01.InsertPerson</classname>:</para>
-
- <programlisting language="none">package sda.jdbc.intro.v01;
-
-import ...
-
-public class InsertPerson extends JFrame {
-
- ...
-
- public InsertPerson () throws SQLException{
- super ("Add a person's data");
-
- setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
-
- final JPanel databaseFieldPanel = new JPanel();
- databaseFieldPanel.setLayout(new GridLayout(0,2));
- add(databaseFieldPanel, BorderLayout.CENTER);
-
- databaseFieldPanel.add(new JLabel("Name:"));
- final JTextField nameField = new JTextField(15);
- databaseFieldPanel.add(nameField);
-
- databaseFieldPanel.add(new JLabel("E-mail:"));
- final JTextField emailField = new JTextField(15);
- databaseFieldPanel.add(emailField);
-
- final JButton insertButton = new JButton("Insert");
- add(insertButton, BorderLayout.SOUTH);
-
- final Connection conn = DriverManager.getConnection(
- "jdbc:mysql://localhost:3306/hdm", "hdmuser", "XYZ");
- final Statement stmt = conn.createStatement();
-
- insertButton.addActionListener(new ActionListener() {
- // Linking the GUI to the database server. We assume an open
- // connection and a correctly initialized Statement instance
- @Override
- public void actionPerformed(ActionEvent event) {
- final String sql = "INSERT INTO Person VALUES('" + nameField.getText()+ "', '"
- + emailField.getText() + "')";
- // We have to catch this Exception because an ActionListener's signature
- // prohibits the existence of a "throws" clause.
- try {
- final int updateCount = stmt.executeUpdate(sql);
- JOptionPane.showMessageDialog(null, "Successfully executed \n'" + sql + "'\nand inserted "
- + updateCount + " dataset");
- } catch (SQLException e) {
- e.printStackTrace();
- }
- }
- });
- pack();
- }
-}</programlisting>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
-
- <section xml:id="jdbcExceptions">
- <title>Handling possible exceptions</title>
-
- <para>Our current code lacks any kind of error handling: Exceptions
- will not be caught at all and invariably lead to program
- termination. This is of course inadequate regarding professional
- software. In case of problems we have to:</para>
-
- <itemizedlist>
- <listitem>
- <para>Gracefully recover or shut down our application. We may
- for example show a pop up window <quote>Terminating due to an
- internal error</quote>.</para>
- </listitem>
-
- <listitem>
- <para>Enable the customer to supply the development team with
- helpful information. The user may for example be asked to submit
- a log file in case of errors.</para>
- </listitem>
- </itemizedlist>
-
- <para>In addition the solution
- <classname>sda.jdbc.intro.v01.InsertPerson</classname> contains an
- ugly mix of GUI components and database related code. We take a
- first step to decouple these two distinct concerns:</para>
-
- <qandaset defaultlabel="qanda" xml:id="quandaentry_DbLayer">
- <title>Handling the database layer</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>Implement a class <code>PersistenceHandler</code> to
- be later used as a component of our next step GUI
- application prototype. This class should have the following
- methods:</para>
-
- <programlisting language="none">...
-/**
- * Handle database communication. There are two
- * distinct internal states <q>disconnected</q> and <q>connected</q>, see
- * {@link #isConnected()}. These two states may be toggled by invoking
- * {@link #connect()} and {@link #disconnect()} respectively.
- *
- * The following snippet illustrates the intended usage:
- * <pre> public static void main(String[] args) {
- final PersistenceHandler ph = new PersistenceHandler();
- if (ph.connect()) {
- if (!ph.add("Jim", "jim@foo.com")) {
- System.err.println("Insert Error:" + ph.getErrorMessage());
- }
- } else {
- System.err.println("Connect error:" + ph.getErrorMessage());
- }
- }</pre>
- *
- * @author goik
- */
-public class PersistenceHandler {
- ...
- /**
- * Instance in <q>disconnected</q> state. See {@link #isConnected()}
- */
- public PersistenceHandler() {/* only present here to supply Javadoc comment */}
-
- /**
- * Inserting a (name, email) record into the database server. In case of
- * errors corresponding messages may subsequently be retrieved by calling
- * {@link #getErrorMessage()}.
- *
- * <dt><b>Precondition:</b></dt> <dd>must be in
- * <q>connected</q> state, see {@link #isConnected()}</dd>
- *
- * @param name
- * A person's name
- * @param email
- * A person's email address
- *
- * @return true if the current data record has been successfully inserted
- * into the database server. false in case of error(s).
- */
- public boolean add(final String name, final String email){
- ...
- }
-
- /**
- * Retrieving error messages in case a call to {@link #add(String, String)},
- * {@link #connect()}, or {@link #disconnect()} yields an error.
- *
- * @return the error explanation corresponding to the latest failed
- * operation, null if no error yet occurred.
- */
- public String getErrorMessage() {
- return ...;
- }
-
- /**
- * Open a connection to a database server.
- *
- * <dt><b>Precondition:</b><dd>
- * <dd>must be in <q>disconnected</q> state, see {@link #isConnected()}</dd>
- *
- * <dt><b>Precondition:</b><dd>
- * <dd>The following properties must be set:
- * <pre>PersistenceHandler.jdbcUrl=jdbc:mysql://localhost:3306/hdm
-PersistenceHandler.password=XYZ
-PersistenceHandler.username=foo</pre>
- * </dd>
- *
- * @return true if connecting was successful
- */
- public boolean connect () {
- ...
- }
-
- /**
- * Close a connection to a database server and clean up JDBC related resources
- *
- * Error messages in case of failure may subsequently be retrieved by
- * calling {@link #getErrorMessage()}.
- *
- * <dt><b>Precondition:</b></dt>
- * <dd>must be in <q>connected</q> state, see {@link #isConnected()}</dd>
- *
- * @return true if disconnecting was successful, false in case error(s) occur.
- */
- public boolean disconnect() {
- ...
- }
-
- /**
- * An instance can either be in <q>connected</q> or <q>disconnected</q> state. The
- * state can be toggled by invoking {@link #connect()} or
- * {@link #disconnect()} respectively.
- *
- * @return true if connected, false otherwise
- */
- public boolean isConnected() {
- return ...;
- }
-}</programlisting>
-
- <para>Notice the two internal states
- <quote>disconnected</quote> and
- <quote>connected</quote>:</para>
-
- <figure xml:id="figPersistenceHandlerStates">
- <title>Possible states and transitions for instances of
- <code>PersistenceHandler</code>.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/persistHandlerStates.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>According to the above documentation a newly created
- <code>PersistenceHandler</code> instance should be in
- disconnected state. As being shown in the <link
- linkend="gloss_Java"><trademark>Java</trademark></link>
- class description you may test your implementation without
- any GUI code. If you are already familiar with unit testing
- this might be a good start as well.</para>
- </question>
-
- <answer>
- <para>We show a possible implementation of
- <classname>sda.jdbc.intro.v1.PersistenceHandler</classname>:</para>
-
- <programlisting language="none">package sda.jdbc.intro.v1;
-...
-
-public class PersistenceHandler {
-
- Connection conn = null;
- Statement stmt = null;
-
- String errorMessage = null;
-
- /**
- * New instances are in <q>disconnected</q> state. See {@link #isConnected()}
- */
- public PersistenceHandler() {/* only present here to supply Javadoc comment */}
-
- /**
- * Inserting a (name, email) record into the database server. In case of
- * errors corresponding messages may subsequently be retrieved by calling
- * {@link #getErrorMessage()}.
- *
- * <dt><b>Precondition:</b></dt> <dd>must be in
- * <q>connected</q> state, see {@link #isConnected()}</dd>
- *
- * @param name
- * A person's name
- * @param email
- * A person's email address
- *
- * @return true if the current data record has been successfully inserted
- * into the database server. false in case of error(s).
- */
- public boolean add(final String name, final String email){
- final String sql = "INSERT INTO Person VALUES('" + name + "', '" +
- email + "')";
- try {
- stmt.executeUpdate(sql);
- return true;
- } catch (SQLException e) {
- errorMessage = "Unable to execute '" + sql + "': '" + e.getMessage() + "'";
- return false;
- }
- }
-
- /**
- * Retrieving error messages in case a call to {@link #add(String, String)},
- * {@link #connect()}, or {@link #disconnect()} yields an error.
- *
- * @return the error explanation corresponding to the latest failed
- * operation, null if no error yet occurred.
- */
- public String getErrorMessage() {
- return errorMessage;
- }
-
- /**
- * Open a connection to a database server.
- *
- * <dt><b>Precondition:</b><dd>
- * <dd>must be in <q>disconnected</q> state, see {@link #isConnected()}</dd>
- *
- * <dt><b>Precondition:</b><dd>
- * <dd>The following properties must be set:
- * <pre>PersistenceHandler.jdbcUrl=jdbc:mysql://localhost:3306/hdm
-PersistenceHandler.password=XYZ
-PersistenceHandler.username=foo</pre>
- * </dd>
- *
- * @return true if connecting was successful
- */
- public boolean connect () {
- try {
- conn = DriverManager.getConnection(
- DbProps.getString("PersistenceHandler.jdbcUrl"),
- DbProps.getString("PersistenceHandler.username"),
- DbProps.getString("PersistenceHandler.password"));
- try {
- stmt = conn.createStatement();
- return true;
- } catch (SQLException e) {
- errorMessage = "Connection opened but Statement creation failed:\"" + e.getMessage() + "\".";
- try {
- conn.close();
- } catch (SQLException ee) {
- errorMessage += "Closing connection failed:\"" + e.getMessage() + "\".";
- }
- conn = null;
- }
-
- } catch (SQLException e) {
- errorMessage = "Unable to open connection:\"" + e.getMessage() + "\".";
- }
- return false;
- }
-
- /**
- * Close a connection to a database server and clean up JDBC related resources
- *
- * Error messages in case of failure may subsequently be retrieved by
- * calling {@link #getErrorMessage()}.
- *
- * <dt><b>Precondition:</b></dt>
- * <dd>must be in <q>connected</q> state, see {@link #isConnected()}</dd>
- *
- * @return true if disconnecting was successful, false in case error(s) occur.
- */
- public boolean disconnect() {
- boolean resultStatus = true;
- final StringBuffer messageCollector = new StringBuffer();
- try {
- stmt.close();
- } catch (SQLException e) {
- resultStatus = false;
- messageCollector.append("Unable to close Statement:\"" + e.getMessage() + "\".");
- }
- stmt = null;
- try {
- conn.close();
- } catch (SQLException e) {
- resultStatus = false;
- messageCollector.append("Unable to close connection:\"" + e.getMessage() + "\".");
- }
- conn = null;
- if (!resultStatus) {
- errorMessage = messageCollector.toString();
- }
- return resultStatus;
- }
-
- /**
- * An instance can either be in <q>connected</q> or <q>disconnected</q> state. The
- * state can be toggled by invoking {@link #connect()} or
- * {@link #disconnect()} respectively.
- *
- * @return true if connected, false otherwise
- */
- public boolean isConnected() {
- return null != conn;
- }
-}</programlisting>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
-
- <para>We may now complete the next enhancement step of our GUI
- database client.</para>
-
- <qandaset defaultlabel="qanda" xml:id="exerciseGuiWriteTakeTwo">
- <title>Connection on user action</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <label>An application writing records to a database
- server</label>
-
- <para>Our aim is to enhance the first GUI prototype being
- described in <xref linkend="simpleInsertGui"/>. The
- application shall start being disconnected from the database
- server. Prior to entering data the user shall be guided to
- open a connection. The following video illustrates the
- desired user interface:</para>
-
- <figure xml:id="figureDataInsert2">
- <title>A GUI frontend for adding personal data to a
- server.</title>
-
- <mediaobject>
- <videoobject>
- <videodata fileref="Ref/Video/dataInsert.mp4"/>
- </videoobject>
- </mediaobject>
- </figure>
-
- <para>In case a user closes the main window while still
- being connected a disconnect from the database server shall
- be enforced. For this purpose we must handle the event when
- the user clicks on the closing button within the window
- decoration. An exit handler method is being required to
- terminate a potentially open database connection.</para>
- </question>
-
- <answer>
- <para>Our implementation uses the class
- <classname>sda.jdbc.intro.v1.PersistenceHandler</classname>
- for handling all database communication. The GUI needs to
- visualize the two different states
- <quote>disconnected</quote> and <quote>connected</quote>. In
- <quote>disconnected</quote> state the whole input pane for
- entering datasets and clicking the <quote>Insert</quote>
- button is locked. So the user is forced to actively open a
- database connection.</para>
-
- <para>Notice also the
- <classname>java.awt.event.WindowAdapter</classname>
- implementation being executed when closing the application's
- main window. The
- <methodname>java.awt.event.WindowAdapter.windowClosing(java.awt.event.WindowEvent)</methodname>
- method disconnects any existing database connection thus
- freeing resources.</para>
-
- <programlisting language="none">package sda.jdbc.intro.v1;
-
-import ...
-
-public class InsertPerson extends JFrame {
-
- private static final long serialVersionUID = 6815975741605247675L;
-
- final PersistenceHandler persistenceHandler = new PersistenceHandler();
-
- final JTextField nameField = new JTextField(15),
- emailField = new JTextField(20);
-
- final JButton toggleConnectButton = new JButton(),
- insertButton = new JButton("Insert");
-
- final JPanel databaseFieldPanel = new JPanel();
-
- private void setGuiConnectionState(final boolean state) {
- if (state) {
- toggleConnectButton.setText("Disconnect");
- } else {
- toggleConnectButton.setText("Connect");
- }
- for (final Component c: databaseFieldPanel.getComponents()){
- c.setEnabled(state);
- }
- }
-
- public static void main(String[] args) throws SQLException {
- InsertPerson app = new InsertPerson();
- app.setVisible(true);
- }
-
- public InsertPerson (){
- super ("Add a person's data");
-
- setSize(500, 500);
-
- addWindowListener(new WindowAdapter() {
- // In case a user closes our application window while still being connected
- // we have to close the database connection.
- @Override
- public void windowClosing(WindowEvent e) {
- super.windowClosing(e);
- if (persistenceHandler.isConnected() && !persistenceHandler.disconnect()) {
- System.exit(1);
- } else {
- System.exit(0);
- }
- });
- Box top = Box.createHorizontalBox();
- add(top, BorderLayout.NORTH);
- top.add(toggleConnectButton);
-
- toggleConnectButton.addActionListener(new ActionListener() {
-
- @Override
- public void actionPerformed(ActionEvent e) {
- if (persistenceHandler.isConnected()) {
- if (persistenceHandler.disconnect()){
- setGuiConnectionState(false);
- } else {
- JOptionPane.showMessageDialog(null, persistenceHandler.getErrorMessage());
- }
- } else {
- if (persistenceHandler.connect()){
- setGuiConnectionState(true);
- } else {
- JOptionPane.showMessageDialog(null, persistenceHandler.getErrorMessage());
- }
- }
- }
- });
-
- databaseFieldPanel.setLayout(new GridLayout(0,2));
- add(databaseFieldPanel);
-
- databaseFieldPanel.add(new JLabel("Name:"));
- databaseFieldPanel.add(nameField);
-
- databaseFieldPanel.add(new JLabel("E-mail:"));
- databaseFieldPanel.add(emailField);
-
- insertButton.addActionListener(new ActionListener() {
- @Override
- public void actionPerformed(ActionEvent e) {
- if (persistenceHandler.add(nameField.getText(), emailField.getText())) {
- nameField.setText("");
- emailField.setText("");
- JOptionPane.showMessageDialog(null, "Succesfully inserted dataset");
- } else {
- JOptionPane.showMessageDialog(null, persistenceHandler.getErrorMessage());
- }
- }
- });
- databaseFieldPanel.add(Box.createGlue());
- databaseFieldPanel.add(insertButton);
- setGuiConnectionState(false);
- pack();
- }
-}</programlisting>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
-
- <section xml:id="jdbcSecurity">
- <title><trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- and security</title>
-
- <section xml:id="jdbcSecurityNetwork">
- <title>Network sniffing</title>
-
- <para>Sniffing <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- network traffic is one possibility for intruders to compromise
- database applications. This requires physical access to either
- of:</para>
-
- <itemizedlist>
- <listitem>
- <para>Server host</para>
- </listitem>
-
- <listitem>
- <para>Client host</para>
- </listitem>
-
- <listitem>
- <para>intermediate hub, switch or router.</para>
- </listitem>
- </itemizedlist>
-
- <figure xml:id="figJdbcSniffing">
- <title>Sniffing a <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- connection by an intruder.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/jdbcSniffing.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>We demonstrate a possible attack by analyzing the network
- traffic between our application shown in <xref
- linkend="figJdbcSimpleWrite"/> and the <productname
- xlink:href="http://www.mysql.com">Mysql</productname> database
- server. Prior to starting the application we set up <productname
- xlink:href="http://www.wireshark.org">Wireshark</productname> for
- filtered capturing:</para>
-
- <itemizedlist>
- <listitem>
- <para>Connecting to the <varname>loopback</varname> (lo)
- interface only. This is sufficient since our client connects
- to <varname>localhost</varname>.</para>
- </listitem>
-
- <listitem>
- <para>Filtering packets if not of type <acronym
- xlink:href="http://en.wikipedia.org/wiki/Transmission_Control_Protocol">TCP</acronym>
- and having port number 3306</para>
- </listitem>
- </itemizedlist>
-
- <para>This yields the following capture being shortened for the
- sake of brevity:</para>
-
- <programlisting language="none">[...
-5.5.24-0ubuntu0.12.04.1.%...X*e?I1ZQ...................e,F[yoA5$T[N.mysql_native_password.
- A...........!.......................hdmuser <co xml:id="tcpCaptureUsername"/>......U.>S.%..~h...!.xhdm............j..../*
-
- ... INSERT INTO Person VALUES('Jim', 'jim@foo.org') <co
- xml:id="tcpCaptureSqlInsert"/>6...
- .&.#23000Duplicate entry 'jim@foo.org' for key 'email' <co
- xml:id="tcpCaptureErrmsg"/></programlisting>
-
- <calloutlist>
- <callout arearefs="tcpCaptureUsername">
- <para>The <varname>username</varname> initiating the
- connection to the database server.</para>
- </callout>
-
- <callout arearefs="tcpCaptureSqlInsert">
- <para>The <code>INSERT ...</code> statement.</para>
- </callout>
-
- <callout arearefs="tcpCaptureErrmsg">
- <para>The resulting error message being sent back to the
- client.</para>
- </callout>
- </calloutlist>
-
- <para>Something seems to be missing here: The user's password. Our
- code in <xref linkend="figJdbcSimpleWrite"/> contains the password
- <quote><varname>XYZ</varname></quote> in clear text. But even
- using the search function of <productname
- xlink:href="http://www.wireshark.org">Wireshark</productname> does
- not show any such string within the above capture. The
- <productname xlink:href="http://www.mysql.com">Mysql</productname>
- documentation however <link
- xlink:href="http://dev.mysql.com/doc/refman/5.0/en/security-against-attack.html">reveals</link>
- that everything but the password is transmitted in clear text. So
- all we might identify is a hash of <code>XYZ</code>.</para>
-
- <para>So regarding our (current) <productname
- xlink:href="http://www.mysql.com">Mysql</productname>
- implementation the impact of this attack type is somewhat limited
- but still severe: All data being transmitted between client and
- server may be disclosed. This typically comprises sensible data as
- well. Possible solutions:</para>
-
- <itemizedlist>
- <listitem>
- <para>Create an encrypted tunnel between client and server
- like e.g. <link
- xlink:href="http://www.debianadmin.com/howto-use-ssh-local-and-remote-port-forwarding.html">ssh
- port forwarding</link> or <link
- xlink:href="http://de.wikipedia.org/wiki/Virtual_Private_Network">VPN</link>.</para>
- </listitem>
-
- <listitem>
- <para>Many database vendors <link
- xlink:href="http://dev.mysql.com/doc/refman/5.1/de/connector-j-reference-using-ssl.html">supply
- SSL</link> or similar <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- protocol encryption extensions. This requires additional
- configuration procedures like setting up server side
- certificates. Moreover similar to the http/https protocols
- encryption generally slows down data traffic.</para>
- </listitem>
- </itemizedlist>
-
- <para>Of course this is only relevant if the transport layer is
- considered to be insecure. If both server and client reside within
- the same trusted infrastructure no action has to be taken. We also
- note that this kind of problem is not limited to <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>.
- In fact all protocols lacking encryption are subject to this type
- of attack.</para>
- </section>
-
- <section xml:id="sqlInjection">
- <title>SQL injection</title>
-
- <para>Before diving into technical details we shed some light on
- the possible impact of this common attack type being described in
- this chapter. Our example is the well known Heartland Payment
- Systems data breach:</para>
-
- <figure xml:id="figHeartlandSecurityBreach">
- <title>Summary about possible SQL injection impact based on the
- Heartland security breach</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/heartland.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>Why should we be concerned with SQL injection? In the
- introduction of <xref linkend="bibClarke09"/> a compelling
- argument is being given:</para>
-
- <blockquote>
- <para>Many people say they know what SQL injection is, but all
- they have heard about or experienced are trivial examples. SQL
- injection is one of the most devastating vulnerabilities to
- impact a business, as it can lead to exposure of all of the
- sensitive information stored in an application's database,
- including handy information such as usernames, passwords, names,
- addresses, phone numbers, and credit card details.</para>
- </blockquote>
-
- <para>In this lecture due to limited resources we only deal with
- trivial examples mentioned above. One possible way SQL injection
- attacks work is by inserting SQL code into fields being designed
- for end user input:</para>
-
- <figure xml:id="figSqlInject">
- <title>SQL injection triggered by ordinary user input.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/sqlinject.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <qandaset defaultlabel="qanda" xml:id="sqlInjectDropTable">
- <title>Attack from the dark side</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>Use the application from <xref
- linkend="exerciseGuiWriteTakeTwo"/> and <xref
- linkend="figSqlInject"/> to launch a SQL injection attack.
- We provide some hints:</para>
-
- <orderedlist>
- <listitem>
- <para>The <productname
- xlink:href="http://www.mysql.com">Mysql</productname>
- <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- driver implementation already provides precautions to
- hamper SQL injection attacks. In its default
- configuration a sequence of SQL commands separated by
- semicolons (<quote>;</quote>) will not be executed but
- flagged as a SQL syntax error. We take an
- example:</para>
-
- <programlisting language="none">INSERT INTO Person VALUES (...);DROP TABLE Person</programlisting>
-
- <para>In order to execute these so called multi user
- queries we explicitly have to enable a <productname
- xlink:href="http://www.mysql.com">Mysql</productname>
- property. This may be achieved by extending our
- <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- URL:</para>
-
- <programlisting language="none">jdbc:mysql://localhost:3306/hdm?<emphasis
- role="bold">allowMultiQueries=true</emphasis></programlisting>
-
- <para>The <productname
- xlink:href="http://www.mysql.com">Mysql</productname>
- manual <link
- xlink:href="http://dev.mysql.com/doc/refman/5.1/en/connector-j-reference-configuration-properties.html">contains
- </link>a remark regarding this parameter:</para>
-
- <remark>Notice that this has the potential for SQL
- injection if using plain java.sql.Statements and your
- code doesn't sanitize input correctly.</remark>
-
- <para>In other words: You have been warned!</para>
- </listitem>
-
- <listitem>
- <para>You may now use either of the two input fields
- <quote>name</quote> or <quote>email</quote> to inject
- arbitrary SQL code.</para>
- </listitem>
- </orderedlist>
- </question>
-
- <answer>
- <para>We construct a suitable string being injected to
- drop our <code>Person</code> table:</para>
-
- <programlisting language="none">Jim', 'jim@c.com');DROP TABLE Person;INSERT INTO Person VALUES('Joe</programlisting>
-
- <para>This being entered into the name field kills our
- <code>Table</code> relation effectively. As the error
- message shows two INSERT statements are separated by a
- DROP TABLE statement. So after executing the first INSERT
- our database server drops the whole table. At last the
- second INSERT statement fails giving rise to an error
- message no end user will ever understand:</para>
-
- <figure xml:id="figSqlInjectDropPerson">
- <title>Dropping the <code>Person</code> table by SQL
- injection</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Screen/sqlInject.screen.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>According to the message text the table
- <code>Person</code> gets dropped as expected. Thus the
- subsequent (second) <code>INSERT</code> action is bound to
- fail.</para>
-
- <para>In practice this result my be avoided. The database
- user will (hopefully!) not have sufficient permissions to
- drop the whole table. Malicious modifications by INSERT,
- UPDATE or DELETE statements are still possible.</para>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
-
- <section xml:id="sanitizeUserInput">
- <title>Sanitizing user input</title>
-
- <para>There are at least two general ways to deal with the
- disastrous result of <xref linkend="sqlInjectDropTable"/>:</para>
-
- <itemizedlist>
- <listitem>
- <para>Keep the database server from interpreting user input
- completely. This is probably the best way and will be
- discussed in <xref linkend="sectPreparedStatements"/>.</para>
- </listitem>
-
- <listitem>
- <para>Let the application check and process user input.
- Dangerous user input may be modified prior to being embedded
- in SQL statements or being rejected completely.</para>
- </listitem>
- </itemizedlist>
-
- <para>The first method is definitely superior in most cases. There
- are however cases where the restrictions being implied are too
- severe. We may for example choose dynamically which tables shall
- be accessed. So an SQL statement's structure rather than just its
- predicates is affected by user input. There are at least two
- standard procedures dealing with this problem:</para>
-
- <glosslist>
- <glossentry>
- <glossterm>Input Filtering</glossterm>
-
- <glossdef>
- <para>In the simplest case we check a user's input by
- regular expressions. An example is an input field in a login
- window representing a system user name. Legal input may
- allows letters and digits only. Special characters,
- whitespace etc. are typically prohibited. The input does
- have a minimum length of one character. A maximum length may
- be imposed as well. So we may choose the regular expression
- <code>[A-Za-z0-9]+</code> to check valid user names.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm><foreignphrase>Whitelisting</foreignphrase></glossterm>
-
- <glossdef>
- <para>In many cases Input fields only allow a restricted set
- of values. Consider an input field for names of planets. An
- application may keep a dictionary table to validate user
- input:</para>
-
- <informaltable border="1">
- <col width="10%"/>
-
- <col width="5%"/>
-
- <tr>
- <td>Mercury</td>
-
- <td>1</td>
- </tr>
-
- <tr>
- <td>Venus</td>
-
- <td>2</td>
- </tr>
-
- <tr>
- <td>Earth</td>
-
- <td>3</td>
- </tr>
-
- <tr>
- <td>...</td>
-
- <td>...</td>
- </tr>
-
- <tr>
- <td>Neptune</td>
-
- <td>9</td>
- </tr>
-
- <tr>
- <td><emphasis role="bold">Default:</emphasis></td>
-
- <td><emphasis role="bold">0</emphasis></td>
- </tr>
- </informaltable>
-
- <para>So if a user enters a valid planet name a
- corresponding number representing this particular planet
- will be sent to the database. If the user enters an invalid
- string an error message may be raised.</para>
-
- <para>In a GUI in many situations this may be better
- accomplished by presenting the list of planets to choose
- from. In this case a user has no chance to enter invalid or
- even malicious code.</para>
- </glossdef>
- </glossentry>
- </glosslist>
-
- <para>So we have an <quote>interceptor</quote> sitting between
- user input fields and SQL generating code:</para>
-
- <figure xml:id="figInputFiltering">
- <title>Validating user input prior to dynamically composing SQL
- statements.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/filtering.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <qandaset defaultlabel="qanda" xml:id="quandaentry_RegexpUse">
- <title>Using regular expressions in <link
- linkend="gloss_Java"><trademark>Java</trademark></link></title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>This exercise is a preparation for <xref
- linkend="exercisefilterUserInput"/>. The aim is to deal
- with regular expressions and to use them in <link
- linkend="gloss_Java"><trademark>Java</trademark></link>.
- If you don't know yet about regular expressions / pattern
- matching you may want to read either of:</para>
-
- <itemizedlist>
- <listitem>
- <para><link
- xlink:href="http://www.aivosto.com/vbtips/regex.html">Regular
- expressions - An introduction</link></para>
- </listitem>
-
- <listitem>
- <para><link
- xlink:href="http://www.codeproject.com/Articles/939/An-Introduction-to-Regular-Expressions">An
- Introduction to Regular Expressions</link></para>
- </listitem>
-
- <listitem>
- <para><link
- xlink:href="http://www.regular-expressions.info/tutorial.html">Regular
- Expression Tutorial</link></para>
- </listitem>
- </itemizedlist>
-
- <para>Complete the implementation of the following
- skeleton:</para>
-
- <programlisting language="none">...
-import java.util.regex.Matcher;
-import java.util.regex.Pattern;
-
-public static void main(String[] args) {
- final String [] wordList = new String [] {"Eric", "126653BBb", "_login","some text"};
- final String [] regexpList = new String[] {"[A-K].*", "[^0-9]+.*", "_[a-z]+", ""};
-
- for (final String word: wordList) {
- for (final String regexp: regexpList) {
- testMatch(word, regexp);
- }
- }
-}
-
-/**
- * Matching a given word by a regular expression. A log message is being
- * written to stdout.
- *
- * Hint: The implementation is based on the explanation being given in the
- * introduction to {@link Pattern}
- *
- * @param word This string will be matched by the subsequent argument.
- * @param regexp The regular expression tested to match the previous argument.
- * @return true if regexp matches word, false otherwise.
- */
-public static boolean testMatch(final String word, final String regexp) {
-.../* to be implemented by <emphasis role="bold">**YOU**</emphasis> */
-}</programlisting>
-
- <para>As being noted in the <link
- linkend="gloss_Java"><trademark>Java</trademark></link>
- above you may want to read the documentation of class
- <classname>java.util.regex.Pattern</classname>. The
- intended output of the above application is:</para>
-
- <programlisting language="none">The expression '[A-K].*' matches 'Eric'
-The expression '[^0-9]+.*' ...
-...</programlisting>
- </question>
-
- <answer>
- <para>A possible implementation is given by
- <classname>sda.regexp.RegexpPrimer</classname>.</para>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
-
- <qandaset defaultlabel="qanda" xml:id="exercisefilterUserInput">
- <title>Input validation by regular expressions</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>The application of <xref
- linkend="sqlInjectDropTable"/> proved to be vulnerable to
- SQL injection. Sanitize the two user input field's values
- to prevent such behaviour.</para>
-
- <itemizedlist>
- <listitem>
- <para>Find appropriate regular expressions to check
- both username and email. Some hints:</para>
-
- <glosslist>
- <glossentry>
- <glossterm>username</glossterm>
-
- <glossdef>
- <para>Regarding SQL injection the <quote>;</quote>
- character is among the most critical. You may want
- to exclude certain special characters. This doesn't
- harm since their presence in a user's name is likely
- to be a typo rather then any sensitive input.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>email</glossterm>
-
- <glossdef>
- <para>There are tons of <quote>ultimate</quote>
- regular expressions available to check email
- addresses. Remember that rather avoiding
- <quote>wrong</quote> email addresses the present
- task is to avoid SQL injection. So find a reasonable
- one which may be too permissive regarding RFC email
- syntax rules but sufficient to secure your
- application.</para>
-
- <para>A concise definition of an email's syntax is
- being given in <link
- xlink:href="http://tools.ietf.org/html/rfc5322#section-3.4.1">RFC5322</link>.
- Its implementation is beyond scope of the current
- lecture. Moreover it is questionable whether E-mail
- clients and mail transfer agents implement strict
- RFC compliance.</para>
- </glossdef>
- </glossentry>
- </glosslist>
-
- <para>Both regular expressions must cover the whole
- user input from the beginning to the end. This can be
- achieved by using <code>^ ... $</code>.</para>
- </listitem>
-
- <listitem>
- <para>The <link
- linkend="gloss_Java"><trademark>Java</trademark></link>
- standard class
- <classname>javax.swing.InputVerifier</classname> may
- help you validating user input.</para>
- </listitem>
-
- <listitem>
- <para>The following screenshot may provide an idea for
- GUI realization and user interaction in case of
- errors. Of course the submit button's action should be
- disabled in case of erroneous input. The user should
- receive a helpful error message instead.</para>
-
- <figure xml:id="figInsertValidate">
- <title>Error message being presented to the
- user.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Screen/insertValidate.screen.png"/>
- </imageobject>
-
- <caption>
- <para>In the current example the trailing
- <quote>;</quote> within the E-Mail field is
- invalid.</para>
- </caption>
- </mediaobject>
- </figure>
- </listitem>
- </itemizedlist>
- </question>
-
- <answer>
- <para>Extending
- <classname>javax.swing.InputVerifier</classname> allows us
- to build a generic class to filter user text input by
- arbitrary regular expressions:</para>
-
- <programlisting language="none">package sda.jdbc.intro.v1.sanitize;
-...
-public class RegexpVerifier extends InputVerifier {
-
- final Pattern syntaxPattern;
- final JLabel validationLabel;
- private boolean inputValid = false;
- private final String errMsg;
-...
- public RegexpVerifier (final String regex, final JLabel validationLabel, final String errMsg) {
- this.validationLabel = validationLabel;
- this.errMsg = errMsg;
- syntaxPattern = Pattern.compile(regex);
- }
-
- @Override
- public boolean verify(JComponent input) {
- if (input instanceof JTextField) {
- final String userInput = ((JTextField) input).getText();
- if (syntaxPattern.matcher(userInput).find()) {
- validationLabel.setText("");
- inputValid = true;
- } else {
- validationLabel.setText(errMsg);
- inputValid = false;
- }
- }
- return inputValid;
- }
- public boolean inputIsValid () {
- return inputValid;
- }
-}</programlisting>
-
- <para>Instances of
- <classname>sda.jdbc.intro.v1.sanitize.RegexpVerifier</classname>
- <coref linkend="emailVerifier"/> <coref
- linkend="nameVerifier"/> may now be used to validate our
- two input data fields <coref linkend="setNameValidation"/>
- <coref linkend="setEmailValidation"/>. We put emphasis on
- the changes with respect to
- <classname>sda.jdbc.intro.v1.InsertPerson</classname>:</para>
-
- <programlisting language="none">package sda.jdbc.intro.v1.sanitize;
-...
-public class InsertPerson extends JFrame {
-
- final JTextField nameField = new JTextField(15);
- final JLabel nameFieldValidationLabel <co xml:id="nameVerifier"/> = new JLabel();
- final RegexpVerifier nameFieldVerifier = new RegexpVerifier(
- "^[^;'\"]+$",
- nameFieldValidationLabel,
- "No special characters");
-
- final JTextField emailField = new JTextField(20);
- final JLabel emailFieldValidationLabel <co xml:id="emailVerifier"/> = new JLabel();
- final RegexpVerifier emailFieldVerifier =
- new RegexpVerifier("^[\\w\\-\\.\\_]+@[\\w\\-\\.]*[a-zA-Z]{2,4}$",
- emailFieldValidationLabel,
- "email not valid");
-...
- public static void main(String[] args) throws SQLException {
- InsertPerson app = new InsertPerson();
- app.setVisible(true);
- }
- public InsertPerson (){
-...
- databaseFieldPanel.add(nameField);
- <emphasis role="bold">nameFieldValidationLabel.setForeground(Color.RED);
- databaseFieldPanel.add(nameFieldValidationLabel);
- nameField.setInputVerifier(nameFieldVerifier);</emphasis> <co
- xml:id="setNameValidation"/>
-
- databaseFieldPanel.add(new JLabel("E-mail:"));
- databaseFieldPanel.add(emailField);
- <emphasis role="bold">databaseFieldPanel.add(emailFieldValidationLabel);
- emailFieldValidationLabel.setForeground(Color.RED);
- emailField.setInputVerifier(emailFieldVerifier);</emphasis> <co
- xml:id="setEmailValidation"/>
-
- insertButton.addActionListener(new ActionListener() {
- @Override
- public void actionPerformed(ActionEvent e) {
- <emphasis role="bold">if (!nameFieldVerifier.inputIsValid() || !emailFieldVerifier.inputIsValid()) {
- JOptionPane.showMessageDialog(null, "Invalid input value(s)");
- }</emphasis> else {
-...</programlisting>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
-
- <section xml:id="sectPreparedStatements">
- <title><classname>java.sql.PreparedStatement</classname>
- objects</title>
-
- <para>Sanitizing user input is an essential means to secure an
- application. The <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- standard however provides a mechanism being superior regarding the
- purpose of protecting applications against SQL injection attacks.
- We shed some light on our current mechanism sending SQL statements
- to a database server:</para>
-
- <figure xml:id="sqlTransport">
- <title>SQL statements in <link
- linkend="gloss_Java"><trademark>Java</trademark></link>
- applications get parsed at the database server</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/sqlTransport.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>This architecture raises two questions:</para>
-
- <orderedlist>
- <listitem>
- <para>What happens in case identical SQL statements are
- executed repeatedly? This may happen inside a loop when
- thousands of records with identical structure are being sent
- to a database.</para>
- </listitem>
-
- <listitem>
- <para>Is this architecture adequate with respect to security
- concerns?</para>
- </listitem>
- </orderedlist>
-
- <para>The first question is related to performance: Parsing
- statements being identical despite the properties being contained
- within is a waste of resources. We consider the transfer of
- records between different databases:</para>
-
- <programlisting language="none">INSERT INTO Person VALUES ('Jim', 'jim@q.org')
-INSERT INTO Person VALUES ('Eve', 'eve@y.org')
-INSERT INTO Person VALUES ('Pete', 'p@rr.com')
-...</programlisting>
-
- <para>In this case it does not make sense to repeatedly parse
- identical SQL statements. Using single <code>INSERT</code>
- statements with multiple data records may not be an option when
- the number of records grows.</para>
-
- <para>The second question is related to our current security
- topic: The database server's interpreter my be so
- <quote>kind</quote> to interpret an attacker's malicious code as
- well.</para>
-
- <para>Both topics are being addressed by
- <classname>java.sql.PreparedStatement</classname> objects.
- Basically these objects allow for separation of an SQL statements
- structure from parameter values contained within. The scenario
- given in <xref linkend="sqlTransport"/> may be implemented
- as:</para>
-
- <figure xml:id="sqlTransportPrepare">
- <title>Using <classname>java.sql.PreparedStatement</classname>
- objects.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/sqlTransportPrepare.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>Prepared statements are an example for parameterized SQL
- statements which exist in various programming languages. When
- using <classname>java.sql.PreparedStatement</classname> instances
- we actually have three distinct phases:</para>
-
- <orderedlist>
- <listitem>
- <para xml:id="exerciseGuiWritePrepared">Creating an instance
- of <classname>java.sql.PreparedStatement</classname>. The SQL
- statement possibly containing place holders gets
- parsed.</para>
- </listitem>
-
- <listitem>
- <para>Setting all placeholder values. This does not involve
- any further SQL syntax parsing.</para>
- </listitem>
-
- <listitem>
- <para>Execute the statement.</para>
- </listitem>
- </orderedlist>
-
- <para>Steps 2. and 3. may be repeated as often as desired without
- any re-parsing of SQL statements thus saving resources on the
- database server side.</para>
-
- <para>Our introductory toy application <xref
- linkend="figJdbcSimpleWrite"/> may be rewritten using
- <classname>java.sql.PreparedStatement</classname> objects:</para>
-
- <programlisting language="none">sda.jdbc.intro.v1;
-...
-public class SimpleInsert {
-
- public static void main(String[] args) throws SQLException {
-
- final Connection conn = DriverManager.getConnection (...
-
- // Step 2: Create a PreparedStatement instance
- final PreparedStatement pStmt = conn.prepareStatement(
- "INSERT INTO Person VALUES(<emphasis role="bold">?, ?</emphasis>)");<co
- xml:id="listPrepCreate"/>
-
- // Step 3a: Fill in desired attribute values
- pStmt.setString(1, "Jim");<co xml:id="listPrepSet1"/>
- pStmt.setString(2, "jim@foo.org");<co xml:id="listPrepSet2"/>
-
- // Step 3b: Execute the desired INSERT
- final int updateCount = pStmt.executeUpdate();<co xml:id="listPrepExec"/>
-
- // Step 4: Give feedback to the enduser
- System.out.println("Successfully inserted " + updateCount + " dataset(s)");
- }
-}</programlisting>
-
- <calloutlist>
- <callout arearefs="listPrepCreate">
- <para>An instance of
- <classname>java.sql.PreparedStatement</classname> is being
- created. Notice the two question marks representing two place
- holders for string values to be inserted in the next
- step.</para>
- </callout>
-
- <callout arearefs="listPrepSet1 listPrepSet2">
- <para>Fill in the two placeholder values being defined at
- <coref linkend="listPrepCreate"/>.</para>
-
- <caution>
- <para>Since half the world of programming folks will index a
- list of n elements starting from 0 to n-1, <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- apparently counts from 1 to n. Working with <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- would have been too easy otherwise.</para>
- </caution>
- </callout>
-
- <callout arearefs="listPrepExec">
- <para>Execute the beast! Notice the empty parameter list. No
- SQL is required since we already prepared it in <coref
- linkend="listPrepCreate"/>.</para>
- </callout>
- </calloutlist>
-
- <para>The problem of SQL injection disappears completely when
- using <classname>java.sql.PreparedStatement</classname> instances.
- An attacker may safely enter offending strings like:</para>
-
- <programlisting language="none">Jim', 'jim@c.com');DROP TABLE Person;INSERT INTO Person VALUES('Joe</programlisting>
-
- <para>The above string will be taken <quote>as is</quote> and thus
- simply becomes part of the database server's content.</para>
-
- <qandaset defaultlabel="qanda" xml:id="exerciseSqlInjectPrepare">
- <title>Prepared Statements to keep the barbarians at the
- gate</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>In <xref linkend="sqlInjectDropTable"/> we found our
- implementation in <xref
- linkend="exerciseGuiWriteTakeTwo"/> to be vulnerable with
- respect to SQL injection. Rather than sanitizing user
- input you shall use
- <classname>java.sql.PreparedStatement</classname> objects
- to secure the application.</para>
- </question>
-
- <answer>
- <para>Due to our separation of GUI and persistence
- handling we only need to re-implement
- <classname>sda.jdbc.intro.sqlinject.PersistenceHandler</classname>.
- We have to replace
- <classname>java.sql.Statement</classname> by
- <classname>java.sql.PreparedStatement</classname>
- instances. A possible implementation is
- <classname>sda.jdbc.intro.v1.prepare.PersistenceHandler</classname>.
- We may now safely enter offending strings like:</para>
-
- <programlisting language="none">Jim', 'jim@c.com');DROP TABLE Person;INSERT INTO Person VALUES('Joe</programlisting>
-
- <para>This time the input value is taken <quote>as
- is</quote> and yields the following error message:</para>
-
- <informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Screen/sqlInjectPrepare.screen.png"/>
- </imageobject>
- </mediaobject>
- </informalfigure>
-
- <para>The offending string exceeds the length of the
- attribute <code>name</code> within the database table
- <code>Person</code>. We may enlarge this value to allow
- the <code>INSERT</code> operation:</para>
-
- <programlisting language="none">CREATE TABLE Person (
- name char(<emphasis role="bold">80</emphasis>) <emphasis role="bold">-- a little bit longer --</emphasis>
- ,email CHAR(20) UNIQUE
-);</programlisting>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
-
- <para>We may have followed the track of test-driven development.
- In that case we would have written tests before actually
- implementing our application. In the current lecture we will do
- this the other way round in the following exercise. The idea is to
- assure software quality when fixing bugs or extending an
- application.</para>
-
- <para>The subsequent exercise requires the <productname
- xlink:href="http://testng.org/doc/eclipse.html#eclipse-installation">TestNG</productname>
- plugin for Eclipse to be installed. This should already be the
- case both in the MI exercise classrooms and in the Virtualbox
- image provided at <uri
- xlink:href="ftp://mirror.mi.hdm-stuttgart.de/ubuntu/VirtualBox/lubuntu.vdi">ftp://mirror.mi.hdm-stuttgart.de/ubuntu/VirtualBox/lubuntu.vdi</uri>.
- If you use a private Eclipse installation you may want to follow
- <xref linkend="testngInstall"/>.</para>
-
- <qandaset defaultlabel="qanda"
- xml:id="quandaentry_DbLayerUnitTest">
- <title>Testing
- <classname>sda.jdbc.intro.v1.PersistenceHandler</classname>
- using <productname
- xlink:href="http://testng.org">TestNG</productname></title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>Read <xref linkend="chapUnitTesting"/>. Then
- test:</para>
-
- <itemizedlist>
- <listitem>
- <para>Proper behaviour when opening and closing
- connections.</para>
- </listitem>
-
- <listitem>
- <para>Proper behavior when inserting data</para>
- </listitem>
-
- <listitem>
- <para>Expected behaviour when entering duplicate
- values violating integrity constraints. Look for error
- messages as well.</para>
- </listitem>
- </itemizedlist>
-
- <para>You may write code to initialize the database state
- appropriately prior to start tests.</para>
- </question>
-
- <answer>
- <para><productname
- xlink:href="http://testng.org">TestNG</productname> may be
- directed by
- <classname>sda.jdbc.intro.v1.prepare.PersistenceHandlerTest</classname>.</para>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
- </section>
-
- <section xml:id="jdbcRead">
- <title>Read Access</title>
-
- <para>So far we've sent records to a database server. Applications
- however need both directions: Pushing data to a Server and receiving
- data as well. The overall process looks like:</para>
-
- <figure xml:id="jdbcReadWrite">
- <title>Server / client object's life cycle</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/jdbcReadWrite.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>So far we've only covered the second (<code>UPDATE</code>)
- part of this picture. Reading objects from a database server into a
- client's (transient) address space requires a container object to
- hold the data in question. Though <link
- linkend="gloss_Java"><trademark>Java</trademark></link> offers
- standard container interfaces like
- <classname>java.util.List</classname> the <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- standard has created separate specifications like
- <classname>java.sql.ResultSet</classname>. Instances of
- <classname>java.sql.ResultSet</classname> will hold transient copies
- of (database) objects. The next figure outlines the basic
- approach:</para>
-
- <figure xml:id="figJdbcRead">
- <title>Reading data from a database server.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/jdbcread.fig" scale="65"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>We take an example. Suppose our database contains a table of
- our friends' nicknames and their respective birth dates:</para>
-
- <table border="1" xml:id="figRelationFriends">
- <caption>Names and birth dates of friends.</caption>
-
- <tr>
- <td><programlisting language="none">CREATE TABLE Friends (
- id INTEGER NOT NULL PRIMARY KEY
- ,nickname char(10)
- ,birthdate DATE
-);</programlisting></td>
-
- <td><programlisting language="none">INSERT INTO Friends VALUES
- (1, 'Jim', '1991-10-10')
- ,(2, 'Eve', '2003-05-24')
- ,(3, 'Mick','2001-12-30')
- ;</programlisting></td>
- </tr>
- </table>
-
- <para>Following the outline in <xref linkend="figJdbcRead"/> we may
- access our data by:</para>
-
- <figure xml:id="listingJdbcRead">
- <title>Accessing relational data</title>
-
- <programlisting language="none">package sda.jdbc.intro;
-...
-public class SimpleRead {
-
- public static void main(String[] args) throws SQLException {
-
- // Step 1: Open a connection to the database server
- final Connection conn = DriverManager.getConnection (
- DbProps.getString("PersistenceHandler.jdbcUrl"),
- DbProps.getString("PersistenceHandler.username"),
- DbProps.getString("PersistenceHandler.password"));
-
- // Step 2: Create a Statement instance
- final Statement stmt = conn.createStatement();
-
- <emphasis role="bold">// Step 3: Creating the client side JDBC container holding our data records</emphasis>
- <emphasis role="bold">final ResultSet data = stmt.executeQuery("SELECT * FROM Friends");</emphasis> <co
- linkends="listingJdbcRead-1" xml:id="listingJdbcRead-1-co"/>
-
- <emphasis role="bold">// Step 4: Dataset iteration
- while (data.next()) {</emphasis> <co linkends="listingJdbcRead-2"
- xml:id="listingJdbcRead-2-co"/>
- <emphasis role="bold">System.out.println(data.getInt("id")</emphasis> <co
- linkends="listingJdbcRead-3" xml:id="listingJdbcRead-3-co"/>
- <emphasis role="bold">+ ", " + data.getString("nickname")</emphasis> <co
- linkends="listingJdbcRead-3" xml:id="listingJdbcRead-4-co"/>
- <emphasis role="bold">+ ", " + data.getString("birthdate"));</emphasis> <co
- linkends="listingJdbcRead-3" xml:id="listingJdbcRead-5-co"/>
- }
- }
-}</programlisting>
- </figure>
-
- <para>The marked code segment above shows difference with respect to
- our data insertion application
- <classname>sda.jdbc.intro.SimpleInsert</classname>. Some remarks are
- in order:</para>
-
- <calloutlist>
- <callout arearefs="listingJdbcRead-1-co"
- xml:id="listingJdbcRead-1">
- <para>As being mentioned in the introduction to this section the
- <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- standard comes with its own container interface rather than
- <classname>java.util.List</classname> or similar.</para>
- </callout>
-
- <callout arearefs="listingJdbcRead-2-co"
- xml:id="listingJdbcRead-2">
- <para>Calling <link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/ResultSet.html#next()">next()</link>
- prior to actually accessing data on the client side is
- mandatory! The <link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/ResultSet.html#next()">next()</link>
- method places the internal iterator to the first element of our
- dataset if not empty. Follow the link address and **read** the
- documentation.</para>
- </callout>
-
- <callout arearefs="listingJdbcRead-3-co listingJdbcRead-4-co listingJdbcRead-5-co"
- xml:id="listingJdbcRead-3">
- <para>The access methods have to be chosen according to matching
- types. An overview of database/<link
- linkend="gloss_Java"><trademark>Java</trademark></link> type
- mappings is being given in <uri
- xlink:href="http://docs.oracle.com/javase/1.3/docs/guide/jdbc/getstart/mapping.html">http://docs.oracle.com/javase/1.3/docs/guide/jdbc/getstart/mapping.html</uri>.</para>
- </callout>
- </calloutlist>
-
- <qandaset defaultlabel="qanda"
- xml:id="quandaentry_JdbcTypeConversion">
- <title>Getter methods and type conversion</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>Apart from type mappings the <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- access methods like <link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/ResultSet.html#getString(int)">getString()</link>
- may also be used for type conversion. Modify <xref
- linkend="listingJdbcRead"/> by:</para>
-
- <itemizedlist>
- <listitem>
- <para>Read the database attribute <code>id</code> by
- <link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/ResultSet.html#getString(java.lang.String)">getString(String)</link>.</para>
- </listitem>
-
- <listitem>
- <para>Read the database attribute nickname by <link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/ResultSet.html#getInt(java.lang.String)">getInt(String)</link>.</para>
- </listitem>
- </itemizedlist>
-
- <para>What do you observe?</para>
- </question>
-
- <answer>
- <para>Modifying our iteration loop:</para>
-
- <programlisting language="none">// Step 4: Dataset iteration
-while (data.next()) {
- System.out.println(data.<emphasis role="bold">getString</emphasis>("id") <co
- linkends="jdbcReadWrongType-1"
- xml:id="jdbcReadWrongType-1-co"/>
- + ", " + data.<emphasis role="bold">getInt</emphasis>("nickname") <co
- linkends="jdbcReadWrongType-2"
- xml:id="jdbcReadWrongType-2-co"/>
- + ", " + data.getString("birthdate"));
-}</programlisting>
-
- <para>We observe:</para>
-
- <calloutlist>
- <callout arearefs="jdbcReadWrongType-1-co"
- xml:id="jdbcReadWrongType-1">
- <para>Calling <link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/ResultSet.html#getString(int)">getString()</link>
- for a database attribute of type INTEGER does not cause
- any trouble: The value gets silently converted to a
- string value.</para>
- </callout>
-
- <callout arearefs="jdbcReadWrongType-2-co"
- xml:id="jdbcReadWrongType-2">
- <para>Calling <link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/ResultSet.html#getInt(java.lang.String)">getInt(String)</link>
- for the database field of type CHAR yields an (expected)
- Exception:</para>
- </callout>
- </calloutlist>
-
- <programlisting language="none">Exception in thread "main" java.sql.SQLException: Invalid value for getInt() - 'Jim'
- at com.mysql.jdbc.SQLError.createSQLException(SQLError.java:1073)
-...</programlisting>
-
- <para>We may however provide <quote>compatible</quote> data
- records:</para>
-
- <programlisting language="none">DELETE FROM Friends;
-INSERT INTO Friends VALUES (1, <emphasis role="bold">'31'</emphasis>, '1991-10-10');</programlisting>
-
- <para>This time our application executes perfectly
- well:</para>
-
- <programlisting language="none">1, 31, 1991-10-10</programlisting>
-
- <para>Conclusion: The <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
- driver performs a conversion from a string type to an
- integer similar like the <link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/lang/Integer.html#parseInt(java.lang.String)">parseInt(String)</link>
- method.</para>
-
- <para>The next series of exercises aims on a more powerful
- implementation of our person data insertion application in
- <xref linkend="exerciseInsertLoginCredentials"/>.</para>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
-
- <qandaset defaultlabel="qanda" xml:id="quandaentry_HandlingNull">
- <title>Handling NULL values.</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>The attribute <code>birthday</code> in our database
- table Friends allows <code>NULL</code> values:</para>
-
- <programlisting language="none">INSERT INTO Friends VALUES
- (1, 'Jim', '1991-10-10')
- ,(2, <emphasis role="bold"> NULL</emphasis>, '2003-5-24')
- ,(3, 'Mick', '2001-12-30');</programlisting>
-
- <para>Starting our current application yields:</para>
-
- <programlisting language="none">1, Jim, 1991-10-10
-2, null, 2003-05-24
-3, Mick, 2001-12-30</programlisting>
-
- <para>This might be confuses with a person having the
- nickname <quote>null</quote>. Instead we would like to
- have:</para>
-
- <programlisting language="none">1, Jim, 1991-10-10
-2, -Name unknown- , 2003-05-24
-3, Mick, 2001-12-30</programlisting>
-
- <para>Extend the current code of
- <classname>sda.jdbc.intro.SimpleRead</classname> to produce
- the above result in case of nickname <code>NULL</code>
- values.</para>
-
- <para>Hint: Read the documentation of <link
- xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/ResultSet.html#wasNull()">wasNull()</link>.</para>
- </question>
-
- <answer>
- <para>A possible implementation is being given in
- <classname>sda.jdbc.intro.v1.SimpleRead</classname>.</para>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
-
- <qandaset defaultlabel="qanda" xml:id="exerciseInsecureAuth">
- <title>A user authentication <quote>strategy</quote></title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>Our current application for entering
- <code>Person</code> records lacks authentication: A user
- simply connects to the database using credentials being hard
- coded in a properties file. A programmer suggests to
- implement authentication based on the following extension of
- the <code>Person</code> table:</para>
-
- <programlisting language="none">CREATE TABLE Person (
- name char(80) NOT NULL
- ,email CHAR(20) NOT NULL UNIQUE
- ,login CHAR(10) UNIQUE -- login names must be unique --
- ,password CHAR(20)
-);</programlisting>
-
- <para>On clicking <quote>Connect</quote> a user may enter
- his login name and password, <quote>fred</quote> and
- <quote>12345678</quote> in the following example:</para>
-
- <figure xml:id="figLogin">
- <title>Login credentials for database connection</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Screen/login.screen.png"
- scale="90"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>Based on these input values the following SQL query is
- being executed by a
- <classname>java.sql.Statement</classname> object:</para>
-
- <programlisting language="none">SELECT * FROM Person WHERE login='<emphasis
- role="bold">fred</emphasis>' and password = '<emphasis
- role="bold">12345678</emphasis>'</programlisting>
-
- <para>Since the login attribute is UNIQUE we are sure to
- receive either 0 or 1 dataset. Our programmer proposes to
- grant login if the query returns at least one
- dataset.</para>
-
- <para>Discuss this implementation sketch with a colleague.
- Do you think this is a sensible approach? <emphasis
- role="bold">Write down</emphasis> your results.</para>
- </question>
-
- <answer>
- <para>The approach is essentially unusable due to severe
- security implications. Since it is based on
- <classname>java.sql.Statement</classname> rater than on
- <classname>java.sql.PreparedStatement</classname> objects it
- is vulnerable to SQL injection attacks. A user my enter the
- following password value in the GUI:</para>
-
- <programlisting language="none">sd' OR '1' = '1</programlisting>
-
- <para>Based on the login name <quote>fred</quote> the
- following SQL string is being crafted:</para>
-
- <programlisting language="none">SELECT * FROM Person WHERE login='fred' and password = 'sd' OR <emphasis
- role="bold">'1' = '1'</emphasis>;</programlisting>
-
- <para>Since the WHERE clause's last component always
- evaluates to true, all objects from the <code>Person</code>
- relation are returned thus permitting login.</para>
-
- <para>The implementation approach suffers from a second
- deficiency: The passwords are stored in clear text. If an
- attacker gains access to the <code>Person</code> table he'll
- immediately retrieve the passwords of all users. This
- problem can be solved by storing hash values of passwords
- rather than the clear text values themselves.</para>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
-
- <qandaset defaultlabel="qanda" xml:id="exerciseHashTraining">
- <title>Passwords and hash values</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>In exercise <xref linkend="exerciseInsecureAuth"/> we
- discarded the idea of clear text passwords in favour of
- password hashes. In order to avoid Rainbow cracking so
- called salted hashes are superior. You should read <uri
- xlink:href="https://www.heckrothindustries.co.uk/articles/an-introduction-to-password-hashes">https://www.heckrothindustries.co.uk/articles/an-introduction-to-password-hashes</uri>
- for overview purposes. The article contains further
- references on the bottom of the page.</para>
-
- <para>With respect to an implementation <uri
- xlink:href="http://stackoverflow.com/questions/2860943/suggestions-for-library-to-hash-passwords-in-java#11038230">http://stackoverflow.com/questions/2860943/suggestions-for-library-to-hash-passwords-in-java</uri>
- provides a simple example for:</para>
-
- <itemizedlist>
- <listitem>
- <para>Creating a salted hash from a given password
- string.</para>
- </listitem>
-
- <listitem>
- <para>Verify if a hash string matches a given clear text
- password.</para>
- </listitem>
- </itemizedlist>
-
- <para>The example uses an external library. On <productname
- xlink:href="http://www.ubuntu.com">Ubuntu</productname>
- Linux this may be installed by issuing
- <command>aptitude</command> <option>install</option>
- <option>libcommons-codec-java</option>. On successful
- install the file
- <filename>/usr/share/java/commons-codec-1.5.jar</filename>
- may be appended to your <envar>CLASSPATH</envar>.</para>
-
- <para>You may as well use <uri
- xlink:href="http://crackstation.net/hashing-security.htm#javasourcecode">http://crackstation.net/hashing-security.htm#javasourcecode</uri>
- as a starting point. This example works standalone without
- needing an external library. Note: Tis example produces
- different (incompatible) hash values.</para>
-
- <para>Create a simple main() method to experiment with the
- two class methods.</para>
- </question>
-
- <answer>
- <para>Starting from <uri
- xlink:href="http://stackoverflow.com/questions/2860943/suggestions-for-library-to-hash-passwords-in-java#11038230">http://stackoverflow.com/questions/2860943/suggestions-for-library-to-hash-passwords-in-java</uri>
- we create a slightly modified class
- <classname>sda.jdbc.intro.auth.HashProvider</classname>
- offering both hash providing <coref
- linkend="hashProviderMethod"/> and verifying <coref
- linkend="hashVerifyMethod"/> methods:</para>
-
- <programlisting language="none">package sda.jdbc.intro.auth;
-...
-public class HashProvider {
-...
- /** Computes a salted PBKDF2 hash of given plaintext password
- suitable for storing in a database. */
- public static <emphasis role="bold">String getSaltedHash</emphasis> <co
- xml:id="hashProviderMethod"/>(char [] password) {
- byte[] salt;
- try {
- salt = SecureRandom.getInstance("SHA1PRNG").generateSeed(saltLen);
- // store the salt with the password
- return Base64.encodeBase64String(salt) + "$" + hash(password, salt);
- } catch (NoSuchAlgorithmException e) {
- e.printStackTrace();
- }
- System.exit(1);
- return null;
- }
-
- /** Checks whether given plaintext password corresponds
- to a stored salted hash of the password. */
- public static <emphasis role="bold">boolean check</emphasis> <co
- xml:id="hashVerifyMethod"/>(char[] password, String stored){
- String[] saltAndPass = stored.split("\\$");
- if (saltAndPass.length != 2)
- return false;
- String hashOfInput = hash(password, Base64.decodeBase64(saltAndPass[0]));
- return hashOfInput.equals(saltAndPass[1]);
- }
-...}</programlisting>
-
- <para>We may test the two class methods
- <methodname>sda.jdbc.intro.auth.HashProvider.getSaltedHash(char[])</methodname>(...)
- and
- <methodname>sda.jdbc.intro.auth.HashProvider.check(char[],String)</methodname>
- by a separate driver class. Notice the <quote>$</quote> sign
- <coref linkend="saltPwhashSeparator"/> separating salt and
- password hash:</para>
-
- <programlisting language="none">package sda.jdbc.intro.auth;
-
-public class TestHashProvider {
-
- public static void main(String [] args) throws Exception {
- final char [] clearText = {'s', 'e', 'c'};
- final String hash = <emphasis role="bold">HashProvider.getSaltedHash(clearText)</emphasis>;
- System.out.println("Hash:" + hash);
- if (HashProvider.check(clearText, <co
- xml:id="saltPwhashSeparator"/>
- "<emphasis role="bold">HwX2DkuYiwp7xogm3AGndza8DKRVvCMntxRvCrCGFPw=</emphasis>$<emphasis
- role="bold">6Ix11yHNB4uPZuF2IQYxVV/MYragJwTDE33OIFR9a24=</emphasis>")) {
- System.out.println("hash matches");
- } else {
- System.out.println("hash does not match"); ...</programlisting>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
-
- <qandaset defaultlabel="qanda"
- xml:id="exerciseInsertLoginCredentials">
- <title>Gui authentication: The real McCoy</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>We now implement a refined version to enter
- <code>Person</code> records based on the solutions of two
- related exercises:</para>
-
- <glosslist>
- <glossentry>
- <glossterm><xref
- linkend="exercisefilterUserInput"/></glossterm>
-
- <glossdef>
- <para>Avoiding SQL injection by sanitizing user
- input</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm><xref
- linkend="exerciseSqlInjectPrepare"/></glossterm>
-
- <glossdef>
- <para>Avoiding SQL injection by using
- <classname>java.sql.PreparedStatement</classname>
- objects.</para>
- </glossdef>
- </glossentry>
- </glosslist>
-
- <para>A better solution should combine both techniques.
- Non-vulnerability a basic requirement. Checking an E-Mail
- for minimal conformance is an added value.</para>
-
- <para>In order to address authentication the relation Person
- has to be extended appropriately. The GUI needs two
- additional fields for login name and password as well. The
- following video demonstrates the intended behaviour:</para>
-
- <figure xml:id="videoConnectAuth">
- <title>Intended usage behaviour for insertion of data
- records.</title>
-
- <mediaobject>
- <videoobject>
- <videodata fileref="Ref/Video/connectauth.mp4"/>
- </videoobject>
- </mediaobject>
- </figure>
-
- <para>Don't forget to use password hashes like those from
- <xref linkend="exerciseHashTraining"/>. Due to their length
- you may want to consider the data type
- <code>TEXT</code>.</para>
- </question>
-
- <answer>
- <para>In comparison to earlier versions it does make sense
- to add some internal container structures. First we note,
- that each GUI input field requires:</para>
-
- <itemizedlist>
- <listitem>
- <para>A label like <quote>Enter password</quote>.</para>
- </listitem>
-
- <listitem>
- <para>A corresponding field object to hold user entered
- input.</para>
- </listitem>
-
- <listitem>
- <para>A validator checking for correctness of entered
- data.</para>
- </listitem>
-
- <listitem>
- <para>A label or text field for warning messages in case
- of invalid user input.</para>
- </listitem>
- </itemizedlist>
-
- <para>First we start by grouping label <coref
- linkend="uiuLabel"/>, input field's verifier <coref
- linkend="uiuVerifier"/> and the error message label <coref
- linkend="uiuErrmsg"/> in
- <classname>sda.jdbc.intro.auth.UserInputUnit</classname>:</para>
-
- <programlisting language="none">package sda.jdbc.intro.auth;
-...
-public class UserInputUnit {
-
- final JLabel label; <co xml:id="uiuLabel"/>
- final InputVerifierNotify verifier; <co xml:id="uiuVerifier"/>
- final JLabel errorMessage; <co xml:id="uiuErrmsg"/>
-
- public UserInputUnit(final String guiText, final InputVerifierNotify verifier) {
- this.label = new JLabel(guiText);
- this.verifier = verifier;
- errorMessage = new JLabel();
- } ...</programlisting>
-
- <para>The actual GUI text field is being defined <coref
- linkend="verfierGuiField"/> in class
- <classname>sda.jdbc.intro.auth.InputVerifierNotify</classname>:</para>
-
- <programlisting language="none">package sda.jdbc.intro.auth;
-...
-public abstract class InputVerifierNotify extends InputVerifier {
-
- protected final String errorMessage;
- public final JLabel validationLabel;
- public final JTextField field; <co xml:id="verfierGuiField"/>
-
- public InputVerifierNotify(final JTextField field, final String errorMessage) { ...</programlisting>
-
- <para>We need two field verifier classes being derived from
- <classname>sda.jdbc.intro.auth.InputVerifierNotify</classname>:</para>
-
- <glosslist>
- <glossentry>
- <glossterm><classname>sda.jdbc.intro.auth.RegexpVerifier</classname></glossterm>
-
- <glossdef>
- <para>This one is well known from earlier versions and
- is used to validate text input fields by regular
- expressions.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm><classname>sda.jdbc.intro.auth.InputVerifierNotify</classname></glossterm>
-
- <glossdef>
- <para>This verifier class is responsible for comparing
- our two password fields to have identical
- values.</para>
- </glossdef>
- </glossentry>
- </glosslist>
-
- <para>All these components get assembled in
- <classname>sda.jdbc.intro.auth.InsertPerson</classname>. We
- remark some important points:</para>
-
- <programlisting language="none">package sda.jdbc.intro.auth;
-...
-public class InsertPerson extends JFrame {
-... // GUI attributes for user input
- final UserInputUnit name = <co linkends="listingInsertUserAuth-1"
- xml:id="listingInsertUserAuth-1-co"/>
- new UserInputUnit(
- "Name",
- new RegexpVerifier(new JTextField(15), "^[^;'\"]+$", "No special characters allowed"));
-
- // We need a reference to the password field to avoid
- // casting from JTextField later.
- private final JPasswordField passwordField = new JPasswordField(10); <co
- linkends="listingInsertUserAuth-2"
- xml:id="listingInsertUserAuth-2-co"/>
- private final UserInputUnit password =
- new UserInputUnit(
- "Password",
- new RegexpVerifier(passwordField, "^.{6,20}$", "length from 6 to 20 characters"));
-...
- private final UserInputUnit passwordRepeat =
- new UserInputUnit(
- "repeat pass.",
- new EqualValueVerifier <co linkends="listingInsertUserAuth-3"
- xml:id="listingInsertUserAuth-3-co"/> (new JPasswordField(10), passwordField, "Passwords do not match"));
-
- private final UserInputUnit [] userInputUnits = <co
- linkends="listingInsertUserAuth-4"
- xml:id="listingInsertUserAuth-4-co"/>
- {name, email, login, password, passwordRepeat};
-...
- private void userLoginDialog() {...}
-...
- public InsertPerson (){
-...
- databaseFieldPanel.setLayout(new GridLayout(0, 3)); //Third column for validation label
- add(databaseFieldPanel);
-
- for (UserInputUnit unit: userInputUnits) { <co
- linkends="listingInsertUserAuth-5"
- xml:id="listingInsertUserAuth-5-co"/>
- databaseFieldPanel.add(unit.label);
- databaseFieldPanel.add(unit.verifier.field);
- databaseFieldPanel.add(unit.verifier.validationLabel);
- }
- insertButton.addActionListener(new ActionListener() {
- @Override public void actionPerformed(ActionEvent e) {
- if (inputValuesAllValid()) {
- if (persistenceHandler.add( <co
- linkends="listingInsertUserAuth-6"
- xml:id="listingInsertUserAuth-6-co"/>
- name.getText(),
- email.getText(),
- login.getText(),
- passwordField.getPassword())) {
- clearMask();
-...}
- private void clearMask() { <co linkends="listingInsertUserAuth-7"
- xml:id="listingInsertUserAuth-7-co"/>
- for (UserInputUnit unit: userInputUnits) {
- unit.verifier.field.setText("");
- unit.verifier.clear();
- }
- }
- private boolean inputValuesAllValid() {<co
- linkends="listingInsertUserAuth-8"
- xml:id="listingInsertUserAuth-8-co"/>
- for (UserInputUnit unit: userInputUnits) {
- if (!unit.verifier.verify(unit.verifier.field)){
- return false;
- }
- }
- return true;
- }
-}</programlisting>
-
- <calloutlist>
- <callout arearefs="listingInsertUserAuth-1-co"
- xml:id="listingInsertUserAuth-1">
- <para>All GUI related stuff for entering a user's
- name</para>
- </callout>
-
- <callout arearefs="listingInsertUserAuth-2-co"
- xml:id="listingInsertUserAuth-2">
- <para>Password fields need special treatment:
- <code>getText()</code> is superseded by
- <code>getPassword()</code>. In order to avoid casts from
- <classname>javax.swing.JTextField</classname> to
- <classname>javax.swing.JPasswordField</classname> we
- simply keep an extra reference.</para>
- </callout>
-
- <callout arearefs="listingInsertUserAuth-3-co"
- xml:id="listingInsertUserAuth-3">
- <para>In order to check both password fields for
- identical values we need a different validator
- <classname>sda.jdbc.intro.auth.EqualValueVerifier</classname>
- expecting both password fields in its
- constructor.</para>
- </callout>
-
- <callout arearefs="listingInsertUserAuth-4-co"
- xml:id="listingInsertUserAuth-4">
- <para>All 5 user input elements get grouped by an array.
- This allows for iterations like in <coref
- linkend="listingInsertUserAuth-7-co"/> or <coref
- linkend="listingInsertUserAuth-8-co"/>.</para>
- </callout>
-
- <callout arearefs="listingInsertUserAuth-5-co"
- xml:id="listingInsertUserAuth-5">
- <para>Adding all GUI elements to the base pane in a
- loop.</para>
- </callout>
-
- <callout arearefs="listingInsertUserAuth-6-co"
- xml:id="listingInsertUserAuth-6">
- <para>Providing user entered values to the persistence
- provider.</para>
- </callout>
-
- <callout arearefs="listingInsertUserAuth-7-co"
- xml:id="listingInsertUserAuth-7">
- <para>Whenever a dataset has been successfully sent to
- the database we have to clean our GUI to possibly enter
- another record.</para>
- </callout>
-
- <callout arearefs="listingInsertUserAuth-8-co"
- xml:id="listingInsertUserAuth-8">
- <para>Thanks to our grouping aggregation of individual
- input GUI field validation states becomes easy.</para>
- </callout>
- </calloutlist>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
-
- <qandaset defaultlabel="qanda" xml:id="quandaentry_ArchSecurity">
- <title>Architectural security considerations</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>In <xref linkend="exerciseInsertLoginCredentials"/> we
- achieved end user credential protection. How about the
- overall application security? Provide improvement proposals
- if appropriate. Hint: Consider the way credentials are being
- supplied.</para>
- </question>
-
- <answer>
- <para>Connecting the client to our database server solely
- depends on credentials <coref
- linkend="databaseUserHdmPassword"/> being stored in a
- properties file
- <filename>database.properties</filename>:</para>
-
- <programlisting language="none">PersistenceHandler.jdbcUrl=jdbc:mysql://localhost:3306/hdm
-PersistenceHandler.username=hdmuser <co xml:id="databaseUserHdmUsername"/>
-PersistenceHandler.password=<emphasis role="bold">XYZ</emphasis> <co
- xml:id="databaseUserHdmPassword"/></programlisting>
-
- <para>This properties file is user accessible and contains
- the password in clear text. Arbitrary applications
- connecting to the database server using this account do have
- all permissions being granted to <code>hdmuser</code> <coref
- linkend="databaseUserHdmUsername"/>. In order for our
- application to work correctly the set of granted permissions
- contains at least inserting datasets. Thus new users e.g.
- <code>smith</code> including credentials may be inserted.
- Afterwards the original application can be started by
- logging in as <code>smith</code>.</para>
-
- <para>Conclusion: The current application architecture is
- seriously flawed with respect to security.</para>
-
- <para>Rather then using a common database account
- <code>hdmuser</code> we may configure per-user accounts on
- the database server having individual user credentials. This
- way user credentials are no longer stored in our
- <code>Person</code> table but are being managed by the
- database server's user management and privilege facilities.
- This completely avoids storing credentials on the client
- side.</para>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
-
- <section xml:id="sda1SaxRdbms">
- <title>SAX and RDBMS</title>
-
- <qandaset defaultlabel="qanda" xml:id="exercise_saxAttrib">
- <title>Reading XML attributes</title>
-
- <qandadiv>
- <qandaentry xml:id="saxRdbms">
- <question>
- <label>SAX processing with RDBMS access.</label>
-
- <para>Implement the example given in <xref
- linkend="saxRdbmsAccessPrinciple"/> to produce the output
- sketched in <xref linkend="saxPriceOut"/>. You may start
- by implementing <emphasis>and testing</emphasis> the
- following methods of a RDBMS interfacing class using
- <trademark
- xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>:</para>
-
- <programlisting language="none">package sax.rdbms;
-
-public class RdbmsAccess {
-
- public void connect(final String host, final int port,
- final String userName, final String password) {
- // <emphasis role="bold">open connection to a database</emphasis>
- }
- public String readPrice(final String articleNumber) {
- return "0"; // <emphasis role="bold">To be implemented as access to a ResultSet object</emphasis>
- }
- public void close() {
- // <emphasis role="bold">close database connection</emphasis>
- }
-}</programlisting>
-
- <para>You may find it helpful to write a small testbed for
- the RDBMS access functionality prior to integrate it into
- your <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym>
- application producing HTML output.</para>
- </question>
-
- <answer>
- <para>We start by creating a suitable RDBMS Table:</para>
-
- <programlisting language="none">CREATE SCHEMA AUTHORIZATION midb2
-CREATE TABLE Product(
- orderNo CHAR(10) NOT NULL PRIMARY KEY
- ,price DECIMAL (9,2) NOT NULL
-)</programlisting>
-
- <para>Next we feed some toy data:</para>
-
- <programlisting language="none">INSERT INTO Product VALUES('x-223', 330.20);
-INSERT INTO Product VALUES('w-124', 110.40);</programlisting>
-
- <para>Now we implement our RDBMS access class:</para>
-
- <programlisting language="none">package dom.xsl;
-...
-public class DbAccess {
-
- public void connect(final String jdbcUrl,
- final String userName, final String password) {
- try {
- conn = DriverManager.getConnection(jdbcUrl, userName, password);
- priceQuery = conn.prepareStatement(sqlPriceQuery);
- } catch (SQLException e) {
- System.err.println("Unable to open connection to database:" + e);}
- }
- public String readPrice(final String articleNumber) {
- String result;
- try {
- priceQuery.setString(1, articleNumber);
- final ResultSet rs = priceQuery.executeQuery();
- if (rs.next()) {
- result = rs.getString("price");
- } else {
- result = "No price available for article '" + articleNumber + "'";
- }
- } catch (SQLException e) {
- result = "Error reading price for article '" + articleNumber + "':" + e;
- }
- return result;
- }
- public void close() {
- try {conn.close();} catch (SQLException e) {
- System.err.println("Error closing database connection:" + e);
- }
- }
- static {
- try { Class.forName("com.ibm.db2.jcc.DB2Driver");
- } catch (ClassNotFoundException e) {
- System.err.println("Unable to register Driver:" + e);}
- }
- private static final String sqlPriceQuery =
- "SELECT price FROM Product WHERE orderNo = ?";
- private PreparedStatement priceQuery = null;
- private Connection conn = null;
-}</programlisting>
-
- <para>This access layer may be tested independently from
- handling catalog instances:</para>
-
- <programlisting language="none">package dom/xsl;
-
-public class DbAccessDriver {
-
- public static void main(String[] args) {
- final DbAccess dbaccess = new DbAccess();
- dbaccess.connect("jdbc:db2://db2.mi.hdm-stuttgart.de:10000/hdm",
- "midb2", "password");
- System.out.println(dbaccess.readPrice("x-223"));
- System.out.println(dbaccess.readPrice("..aaargh!"));
- dbaccess.close();
- }
-}</programlisting>
-
- <para>If the above test succeeds we may embed the RDBMS
- access layer into our The <acronym
- xlink:href="http://www.saxproject.org">SAX</acronym>
- handler:</para>
-
- <programlisting language="none">package sax.rdbms;
-...
-public class HtmlEventHandler extends DefaultHandler{
- public void startDocument() {
- dbaccess.connect("jdbc:db2://db2.mi.hdm-stuttgart.de:10000/hdm",
- "midb2", "password");
- System.out.println("<html><head><title>Catalog</title></head>");
- }
- public void endDocument() {
- System.out.println("</html>");
- dbaccess.close();
- }
- public void startElement(String namespaceUri, String localName,
- String rawName, Attributes attrs){
- if (rawName.equals("catalog")){
- System.out.println("<body><H1>A catalog</H1>"
- +"<table border='1'><tbody>");
- System.out.println("<tr><th>Order number</th>\n"
- + "<th>Price</th>\n"
- +" <th>Product</th></tr>");
- } else if (rawName.equals("item")){
- final String orderNo = attrs.getValue("orderNo");
- System.out.print("<tr><td>" + orderNo
- + "</td>\n<td>" + dbaccess.readPrice(orderNo)
- + "</td>\n<td>");
- } else {
- System.err.println("Element '" + rawName + "' unknown");
- }
- }
- public void endElement(String namespaceUri, String localName,
- String rawName) {
- if (rawName.equals("catalog")){
- System.out.println("</tbody></table>");
- } else if (rawName.equals("item")){
- System.out.println("</td></tr>\n");
- }
- }
- public void characters(char[] ch, int start, int length) {
- System.out.print(new String(ch, start, length));
- }
- private DbAccess dbaccess = new DbAccess();
-}</programlisting>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
- </section>
- </section>
- </chapter>
-
- <chapter xml:id="chapUnitTesting">
- <title>Unit testing with <productname
- xlink:href="http://testng.org">TestNG</productname></title>
-
- <para>This chapter presents a very short introduction to the basic usage
- of unit testing. We start with a simple stack implementation:</para>
-
- <programlisting language="none">package sda.unittesting;
-
-public class MyStack {
- int [] data = new int[5];
- int numElements = 0;
-
- public void push(final int n) {
- data[numElements] = n;
- numElements++;
- }
- public int pop() {
- numElements--;
- return data[numElements];
- }
- public int top() {
- return data[numElements - 1];
- }
- public boolean empty() {
- return 0 == numElements;
- }
-}</programlisting>
-
- <para>Readers being familiar with stacks will immediately notice a
- deficiency in the above code: This stack is actually bounded. It only
- allows us to store a maximum number of five integer values.</para>
-
- <para>The following implementation allows us to functionally test our
- <classname>sda.unittesting.MyStack</classname> implementation with
- respect to the usual stack behaviour:</para>
-
- <programlisting language="none" linenumbering="numbered">package sda.unittesting;
-
-public class MyStackFuncTest {
-
- private static void assertTrue(boolean status) {
- if (!status) {
- throw new RuntimeException("Assert failed");
- }
- }
- public static void main(String[] args) {
- final MyStack stack = new MyStack();
- // Test 1: A new MyStack instance should not contain any elements.
- assertTrue(stack.empty());
-
- // Test 2: Adding and removal
- stack.push(4);
- assertTrue (!stack.empty());
- assertTrue (4 == stack.top());
- assertTrue (4 == stack.pop());
- assertTrue (stack.empty());
-
- // Test 3: Trying to add more than five values
- stack.push(1);stack.push(2);stack.push(3);stack.push(4);
- stack.push(5);
- stack.push(6);
- assertTrue(6 == stack.pop());
- }
-}</programlisting>
-
- <para>Execution yields a runtime exception which is due to the attempted
- insert operation <code>stack.push(6)</code>:</para>
-
- <programlisting language="none">Exception in thread "main" java.lang.ArrayIndexOutOfBoundsException: 5
- at sda.unittesting.MyStack.push(MyStack.java:8)
- at sda.unittesting.MyStackFuncTest.main(MyStackFuncTest.java:20)</programlisting>
-
- <para>The execution result is easy to understand since our
- <classname>sda.unittesting.MyStack </classname> implementation only
- allows to store 5 values.</para>
-
- <para>Our testing application is fine so far. It does however lack some
- features:</para>
-
- <itemizedlist>
- <listitem>
- <para>automatic initialization before starting tests and
- finalization at the end.</para>
- </listitem>
-
- <listitem>
- <para>Our test is monolithic: We used comments to document different
- tests. This knowledge is implicit and thus invisible to testing
- frameworks. Test results (failure/success) cannot be assigned to
- test 1, test 2 for example.</para>
- </listitem>
-
- <listitem>
- <para>Aggregation and visualization of test results</para>
- </listitem>
-
- <listitem>
- <para>Dependencies between individual tests</para>
- </listitem>
-
- <listitem>
- <para>Ability to enable and disable tests according to a project's
- maturity level. In our example test 3 might be disabled till an
- unbounded implementation gets completed.</para>
- </listitem>
- </itemizedlist>
-
- <para>Testing frameworks like <productname
- xlink:href="http://junit.org">Junit</productname> or <productname
- xlink:href="http://testng.org">TestNG</productname> provide means for
- efficient and flexible test organization. Using <productname
- xlink:href="http://testng.org">TestNG</productname> our current test
- application including only test 1 and test 2 reads:</para>
-
- <programlisting language="none">package sda.unittesting;
-
-import org.testng.annotations.Test;
-
-public class MyStackTestSimple {
-
- final MyStack stack = new MyStack();
-
- @Test
- public void empty() {
- assert(stack.empty());
- }
- @Test
- public void pushPopEmpty() {
- assert (stack.empty());
- stack.push(4);
- assert (!stack.empty());
- assert (4 == stack.top());
- assert (4 == stack.pop());
- assert (stack.empty());
- }
-}</programlisting>
-
- <para>We notice the absence of a <function>main()</function> method. Our
- testing framework uses the above code for test definitions. In contrast
- to our homebrew solution the individual tests are now defined in a
- machine readable fashion. This allows for sophisticated statistics.
- Executing inside <productname
- xlink:href="http://testng.org">TestNG</productname> produces the
- following results:</para>
-
- <programlisting language="none">PASSED: empty
-PASSED: pushPopEmpty
-
-===============================================
- Default test
- Tests run: 2, Failures: 0, Skips: 0
-===============================================
-
-
-===============================================
-Default suite
-Total tests run: 2, Failures: 0, Skips: 0
-===============================================</programlisting>
-
- <para>Both tests run successfully. So why did we omit test 3 which is
- bound to fail? We now add it to the test suite:</para>
-
- <programlisting language="none">package sda.unittesting;
-...
-public class MyStackTestSimple1 {
-...
- @Test
- public void empty() {
- assert(stack.empty());
-...
-
- @Test
- public void push6() {
- stack.push(1);
- stack.push(2);
- stack.push(3);
- stack.push(4);
- stack.push(5);
- stack.push(6);
- assert (6 == stack.pop());
- } ...</programlisting>
-
- <para>As expected test 3 fails. But the result shows test 2 failing as
- well:</para>
-
- <programlisting language="none">PASSED: empty
-FAILED: push6
-java.lang.ArrayIndexOutOfBoundsException: 5
- at sda.unittesting.MyStack.push(MyStack.java:8)
- at sda.unittesting.MyStackTestSimple1.push6(MyStackTestSimple1.java:30)
- at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
- ...
-
-FAILED: pushPopEmpty
-java.lang.AssertionError
- at sda.unittesting.MyStackTestSimple1.pushPopEmpty(MyStackTestSimple1.java:15)
- at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
- ...
-
-===============================================
- Default test
- Tests run: 3, Failures: 2, Skips: 0
-===============================================</programlisting>
-
- <para>This unexpected result is due to the execution order of the three
- individual tests. Within our class
- <classname>sda.unittesting.MyStackTestSimple1</classname> the three
- tests appear in the sequence test 1, test 2 and test 3. This however is
- just the order of source code. The testing framework will not infer any
- order and thus execute our three tests in <emphasis
- role="bold">arbitrary</emphasis> order. The execution log shows the
- actual order:</para>
-
- <orderedlist>
- <listitem>
- <para>Test <quote><code>empty</code></quote></para>
- </listitem>
-
- <listitem>
- <para>Test <quote><code>push6</code></quote></para>
- </listitem>
-
- <listitem>
- <para>Test <quote><code>pushPopEmpty</code></quote></para>
- </listitem>
- </orderedlist>
-
- <para>So the second test will raise an exception and leave the stack
- filled with the maximum possible five elements. Thus it is not empty and
- the <quote><code>pushPopEmpty</code></quote> test fails as well.</para>
-
- <para>If we want to avoid this type of errors we may:</para>
-
- <itemizedlist>
- <listitem>
- <para>Declare tests within separate (test class) definitions</para>
- </listitem>
-
- <listitem>
- <para>Define dependencies like test X can only be executed after
- test Y.</para>
- </listitem>
- </itemizedlist>
-
- <para>The <productname
- xlink:href="http://testng.org">TestNG</productname> framework offers a
- feature which allows the definition of test groups and dependencies
- between them. We use this feature to refine our test definition:</para>
-
- <programlisting language="none">package sda.unittesting;
-...
-public class MyStackTest {
- ...
- @Test (<emphasis role="bold">groups = "basic"</emphasis>)
- public void empty() {
- assert(stack.empty());
- }
- @Test (<emphasis role="bold">groups = "basic"</emphasis>)
- public void pushPopEmpty() {
- ...
- }
-
- @Test (<emphasis role="bold">dependsOnGroups = "basic"</emphasis>)
- public void push6() {
- ...
- }</programlisting>
-
- <para>The first two tests will now belong to the same test group
- <quote>basic</quote>. The <emphasis role="bold"><code>dependsOnGroups =
- "basic"</code></emphasis> declaration will guarantee that our
- <code>push6</code> test will be launched as the last one. So we get the
- expected result:</para>
-
- <programlisting language="none">PASSED: empty
-PASSED: pushPopEmpty
-FAILED: push6
-java.lang.ArrayIndexOutOfBoundsException: 5
- at sda.unittesting.MyStack.push(MyStack.java:8)
- at sda.unittesting.MyStackTest.push6(MyStackTest.java:30)
- at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
-...
-
-
-===============================================
- Default test
- Tests run: 3, Failures: 1, Skips: 0
-===============================================</programlisting>
-
- <para>In fact the order between the first two tests might be critical as
- well. The <quote><code>pushPopEmpty</code></quote> test leaves our stack
- in an empty state. If this is not the case reversing the execution order
- of <quote><code>pushPopEmpty</code></quote> and
- <quote><code>empty</code></quote> would cause an error as well.</para>
-
- <para>Programming <abbrev
- xlink:href="http://en.wikipedia.org/wiki/Integrated_development_environment">IDE</abbrev>s
- like eclipse provide elements for test result visualization. Our last
- test gets summarized as:</para>
-
- <screenshot>
- <info>
- <title><productname
- xlink:href="http://testng.org">TestNG</productname> result
- presentation in eclipse</title>
- </info>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Screen/eclipseTestngResult.screen.png"
- scale="75"/>
- </imageobject>
- </mediaobject>
- </screenshot>
-
- <para>We can drill down from a result of type failure to its occurrence
- within the corresponding code.</para>
- </chapter>
-
- <chapter xml:id="fo">
- <title>Generating printed output</title>
-
- <titleabbrev>Print</titleabbrev>
-
- <section xml:id="foIntro">
- <title>Online and print versions</title>
-
- <titleabbrev>online / print</titleabbrev>
-
- <para>We already learned how to transform XML documents into HTML by
- means of a <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> style sheet
- processor. In principle we may create printed output by using a HTML
- Browser's print function. However the result will not meet reasonable
- typographical standards. A list of commonly required features for
- printed output includes:</para>
-
- <variablelist>
- <varlistentry>
- <term>Line breaks</term>
-
- <listitem>
- <para>Text paragraphs have to be divided into lines. To achieve
- best results the processor must implement the hyphenation rules
- of the language in question in order to automatically hyphenate
- long words. This is especially important for text columns of
- limited width as appearing in newspapers.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Page breaks</term>
-
- <listitem>
- <para>Since printed pages are limited in height the content has
- to be broken into pages. This may be difficult to
- achieve:</para>
-
- <itemizedlist>
- <listitem>
- <para>Large images being indivisible may have to be deferred
- to the following page leaving large amounts of empty
- space.</para>
- </listitem>
-
- <listitem>
- <para>Long tables may have to be subdivided into smaller
- blocks. Thus it may be required to define sets of additional
- footers like <quote>to be continued on the next page</quote>
- and additional table headers containing column descriptions
- on subsequent pages.</para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Page references</term>
-
- <listitem>
- <para>Document internal references via <link
- xlink:href="http://www.w3.org/TR/xml#id">ID</link> / <link
- xlink:href="http://www.w3.org/TR/xml#idref">IDREF</link> pairs
- may be represented as page references like <quote>see page
- 32</quote>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Left and right pages</term>
-
- <listitem>
- <para>Books usually have a different layout for
- <quote>left</quote> and <quote>right</quote> pages. Page numbers
- usually appear on the left side of a <quote>left</quote> page
- and vice versa.</para>
-
- <para>Very often the head of each page contains additional
- information e.g. a chapter's name on each <quote>left</quote>
- page head and the actual section's name on each
- <quote>right</quote> page's head.</para>
-
- <para>In addition chapters usually start on a
- <quote>right</quote> page. Sometimes a chapter's starting page
- has special layout features e.g. a missing description in the
- page's head which will only be given on subsequent pages.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Footnotes</term>
-
- <listitem>
- <para>Footnotes have to be numbered on a per page basis and have
- to appear on the current page.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section xml:id="foStart">
- <title>A simple <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- document</title>
-
- <titleabbrev>Simple <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev></titleabbrev>
-
- <para>A renderer for printed output from XML content also needs
- instructions how to format the different elements. A common way to
- define these formatting properties is by using <emphasis>Formatting
- Objects</emphasis> (<abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>)
- standard. <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- documents may be compared to HTML. A HTML document has to be rendered
- by a piece of software called a browser in order to be viewed as an
- image. Likewise <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- documents have to be rendered by a piece of software called a
- formatting objects processor which typically yields PostScript or PDF
- output. As a starting point we take a simple example:</para>
-
- <figure xml:id="foHelloWorld">
- <title>The most simple <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- document</title>
-
- <programlisting language="none"><?xml version="1.0" encoding="utf-8"?>
-<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
-
- <fo:layout-master-set>
- <!-- Define a simple page layout -->
- <fo:simple-page-master master-name="simplePageLayout"
- page-width="60mm" page-height="100mm">
- <fo:region-body/>
- </fo:simple-page-master>
- </fo:layout-master-set>
- <!-- Print a set of pages using the previously defined layout -->
- <fo:page-sequence master-reference="simplePageLayout">
- <fo:flow flow-name="xsl-region-body">
- <emphasis role="bold"><fo:block>Hello, World ...</fo:block></emphasis>
- </fo:flow>
- </fo:page-sequence>
-</fo:root></programlisting>
- </figure>
-
- <para>PDF generation is initiated by executing a <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- processor. At the MI department the script <code>fo2pdf</code> invokes
- <orgname>RenderX</orgname>'s <productname
- xlink:href="http://www.renderx.com">xep</productname>
- processor:</para>
-
- <programlisting language="none">fo2pdf -fo hello.fo -pdf hello.pdf</programlisting>
-
- <para>This creates a PDF file which may be printed or previewed by
- e.g. <productname
- xlink:href="http://www.adobe.com">Adobe</productname>'s acrobat reader
- or evince under Linux. For a list of command line options see
- <productname xlink:href="http://www.renderx.com/reference.html">xep's
- documentation</productname>.</para>
- </section>
-
- <section xml:id="layoutParam">
- <title>Page layout</title>
-
- <para>The result from of our <quote>Hello, World ...</quote> code is
- not very impressive. In order to develop more elaborated examples we
- have to understand the underlying layout model being defined in a
- <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_simple-page-master">fo:simple-page-master</link>
- element. First of all <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- allows to subdivide a physical page into different regions:</para>
-
- <figure xml:id="foRegionList">
- <title>Regions being defined in a page.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/regions.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>The most important area in this model is denoted by <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_region-body">fo:region-body</link>.
- Other regions like <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_region-before">fo:region-before</link>
- are typically used as containers for meta information such as chapter
- headings and page numbering. We take a closer look to the <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_region-body">fo:region-body</link>
- area and supply an example of parameterization:</para>
-
- <figure xml:id="foParamRegBody">
- <title>A complete <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- parameterizing of a physical page and the <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_region-body">fo:region-body</link>.</title>
-
- <programlisting language="none"><?xml version="1.0" encoding="utf-8"?>
-<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"
- font-size="6pt">
-
- <fo:layout-master-set> <co xml:id="programlisting_fobodyreg_masterset"/>
- <fo:simple-page-master master-name="<emphasis role="bold">simplePageLayout</emphasis>" <co
- xml:id="programlisting_fobodyreg_simplepagelayout"/>
- page-width = "50mm" page-height = "80mm"
- margin-top = "5mm" margin-bottom = "20mm"
- margin-left = "5mm" margin-right = "10mm">
-
- <fo:region-body <co xml:id="programlisting_fobodyreg_regionbody"/>
- margin-top = "10mm" margin-bottom = "5mm"
- margin-left = "10mm" margin-right = "5mm"/>
- </fo:simple-page-master>
- </fo:layout-master-set>
-
- <fo:page-sequence master-reference="<emphasis role="bold">simplePageLayout</emphasis>"> <co
- xml:id="programlisting_fobodyreg_pagesequence"/>
- <fo:flow flow-name="xsl-region-body"> <co
- xml:id="programlisting_fobodyreg_flow"/>
- <fo:block space-after="2mm">Dumb text .. dumb text.</fo:block> <co
- xml:id="programlisting_fobodyreg_block"/>
- <fo:block space-after="2mm">Dumb text .. dumb text.</fo:block> <coref
- linkend="programlisting_fobodyreg_block"/>
- <fo:block space-after="2mm">Dumb text .. dumb text.</fo:block> <coref
- linkend="programlisting_fobodyreg_block"/>
- <fo:block space-after="2mm">Dumb text .. dumb text.</fo:block> <coref
- linkend="programlisting_fobodyreg_block"/>
- </fo:flow>
- </fo:page-sequence>
-</fo:root></programlisting>
- </figure>
-
- <calloutlist>
- <callout arearefs="programlisting_fobodyreg_masterset">
- <para>As the name suggests multiple layout definitions can appear
- here. In this example only one layout is defined.</para>
- </callout>
-
- <callout arearefs="programlisting_fobodyreg_simplepagelayout">
- <para>Each layout definition carries a key attribute master-name
- being unique with respect to all defined layouts appearing in
- <emphasis>the</emphasis> <tag
- class="starttag">fo:layout-master-set</tag>. We may thus call it a
- <emphasis>primary key</emphasis> attribute. The current layout
- definition's key has the value <code>simplePageLayout</code>. The
- length specifications appearing here are visualized in <xref
- linkend="paramRegBodyVisul"/> and correspond to the white
- rectangle.</para>
- </callout>
-
- <callout arearefs="programlisting_fobodyreg_regionbody">
- <para>Each layout definition <emphasis>must</emphasis> have a
- region body being the region in which the documents main text flow
- will appear. A layout definition <emphasis>may</emphasis> also
- define top, bottom and side regions as we will see <link
- linkend="paramHeadFoot">later</link>. The body region is shown
- with pink background in <xref
- linkend="paramRegBodyVisul"/>.</para>
- </callout>
-
- <callout arearefs="programlisting_fobodyreg_pagesequence">
- <para>A <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- document may have multiple page sequences for example one per each
- chapter of a book. It <emphasis>must</emphasis> reference an
- <emphasis>existing</emphasis> layout definition via its
- <code>master-reference</code> attribute. So we may regard this
- attribute as a foreign key targeting the set of all defined layout
- definitions.</para>
- </callout>
-
- <callout arearefs="programlisting_fobodyreg_flow">
- <para>A flow allows us to define in which region output shall
- appear. In the current example only one layout containing one
- region of type body definition being able to receive text output
- exists.</para>
- </callout>
-
- <callout arearefs="programlisting_fobodyreg_block">
- <para>A <tag class="starttag">fo:block</tag> element may be
- compared to a paragraph element <tag class="starttag">p</tag> in
- HTML. The attribute <link
- xlink:href="http://www.w3.org/TR/xsl/#space-after">space-after</link>="2mm"
- adds a space of two mm after each <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_block">fo:block</link>
- container.</para>
- </callout>
- </calloutlist>
-
- <para>The result looks like:</para>
-
- <figure xml:id="paramRegBodyVisul">
- <title>Parameterizing page- and region view port. All length
- dimensions are in mm.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/overlay.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
- </section>
-
- <section xml:id="headFoot">
- <title>Headers and footers</title>
-
- <titleabbrev>Header/footer</titleabbrev>
-
- <para>Referring to <xref linkend="foRegionList"/> we now want to add
- fixed headers and footers frequently being used for page numbers. In a
- textbook each page might have the actual chapter's name in its header.
- This name should not change as long as the text below <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_region-body">fo:region-body</link>
- still belongs to the same chapter. In <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- this is achieved by:</para>
-
- <itemizedlist>
- <listitem>
- <para>Encapsulating each chapter's content in a <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_page-sequence">fo:page-sequence</link>
- of its own.</para>
- </listitem>
-
- <listitem>
- <para>Defining the desired header text below <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_static-content">fo:static-content</link>
- in the area defined by <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_region-before">fo:region-before</link>.</para>
- </listitem>
- </itemizedlist>
-
- <para>The notion <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_static-content">fo:static-content</link>
- refers to the fact that the content is constant (static) within the
- given page sequence. The new version reads:</para>
-
- <figure xml:id="paramHeadFoot">
- <title>Parameterizing header and footer.</title>
-
- <programlisting language="none"><?xml version="1.0" encoding="utf-8"?>
-<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"
- font-size="6pt">
-
- <fo:layout-master-set>
- <fo:simple-page-master master-name="simplePageLayout"
- page-width = "50mm" page-height = "80mm"
- margin-top = "5mm" margin-bottom = "20mm"
- margin-left = "5mm" margin-right = "10mm">
-
- <fo:region-body margin-top = "10mm" margin-bottom = "5mm" <co
- xml:id="programlisting_head_foot_bodydef"/>
- margin-left = "10mm" margin-right = "5mm"/>
-
- <fo:region-before extent="5mm"/> <co
- xml:id="programlisting_head_foot_beforedef"/>
- <fo:region-after extent="5mm"/> <co
- xml:id="programlisting_head_foot_afterdef"/>
-
- </fo:simple-page-master>
- </fo:layout-master-set>
-
- <fo:page-sequence master-reference="simplePageLayout">
-
- <fo:static-content flow-name="xsl-region-before"> <co
- xml:id="programlisting_head_foot_beforeflow"/>
- <fo:block
- font-weight="bold"
- font-size="8pt">Headertext</fo:block>
- </fo:static-content>
-
- <fo:static-content flow-name="xsl-region-after"> <co
- xml:id="programlisting_head_foot_afterflow"/>
- <fo:block>
- <fo:page-number/>
- </fo:block>
- </fo:static-content>
-
- <fo:flow flow-name="xsl-region-body">
- <fo:block space-after="8mm">Dumb text .. dumb text.</fo:block>
- <fo:block space-after="8mm">Dumb text .. dumb text.</fo:block>
- <fo:block space-after="8mm">More text .. more text.</fo:block>
- <fo:block space-after="8mm">More text .. more text.</fo:block>
- <fo:block space-after="8mm">More text .. more text.</fo:block>
- </fo:flow>
- </fo:page-sequence>
-</fo:root></programlisting>
- </figure>
-
- <calloutlist>
- <callout arearefs="programlisting_head_foot_bodydef">
- <para>Defining the body region.</para>
- </callout>
-
- <callout arearefs="programlisting_head_foot_beforedef programlisting_head_foot_afterdef">
- <para>Defining two regions at the top and bottom of each page. The
- <code>extent</code> attribute denotes the height of these regions.
- <emphasis>Caveat</emphasis>: The attribute <code>extent</code>'s
- value gets subtracted from the <code>margin-top</code> or
- <code>margin-bottom</code> value being defined in the
- corresponding <tag class="starttag">fo:region-body</tag> element.
- So if we consider for example the <tag>fo:region-before</tag> we
- have to obey:</para>
-
- <para>extent <= margin-top</para>
-
- <para>Otherwise we may not even see any output.</para>
- </callout>
-
- <callout arearefs="programlisting_head_foot_beforeflow">
- <para>A <code>fo:static-content</code> denotes text portions which
- are decoupled from the <quote>usual</quote> text flow. For example
- as a book's chapter advances over multiple pages we expect the
- constant chapter's title to appear on top of each page. In the
- current example the static string <code>Headertext</code> will
- appear on each page's top for the whole <tag
- class="starttag">fo:page-sequence</tag> in which it is defined.
- Notice the <code>flow-name="xsl-region-after"</code> reference to
- the region being defined in <coref
- linkend="programlisting_head_foot_beforedef"/>.</para>
- </callout>
-
- <callout arearefs="programlisting_head_foot_afterflow">
- <para>We do the same here for the page's footer. Instead of static
- text we output <tag>fo_page-number</tag> yielding the current
- page's number.</para>
-
- <para>This time <code>flow-name="xsl-region-after"</code>
- references the region definition in <coref
- linkend="programlisting_head_foot_afterdef"/>. Actually the
- attribute <code>flow-name</code> is restricted to the following
- five values corresponding to all possible region definitions
- within a layout:</para>
-
- <informaltable>
- <?dbhtml table-width="50%" ?>
-
- <?dbfo table-width="50%" ?>
-
- <tgroup cols="2">
- <colspec align="left" colwidth="1*"/>
-
- <colspec align="left" colwidth="1*"/>
-
- <tbody>
- <row>
- <entry><tag class="starttag">fo:region-body</tag></entry>
-
- <entry>xsl-region-body</entry>
- </row>
-
- <row>
- <entry><tag
- class="starttag">fo:region-before</tag></entry>
-
- <entry>xsl-region-before</entry>
- </row>
-
- <row>
- <entry><tag class="starttag">fo:region-after</tag></entry>
-
- <entry>xsl-region-after</entry>
- </row>
-
- <row>
- <entry><tag class="starttag">fo:region-start</tag></entry>
-
- <entry>xsl-region-start</entry>
- </row>
-
- <row>
- <entry><tag class="starttag">fo:region-end</tag></entry>
-
- <entry>xsl-region-end</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </callout>
- </calloutlist>
-
- <para>This results in two pages with page numbers 1 and 2:</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/headfoot.fig"/>
- </imageobject>
- </mediaobject>
-
- <para>The free chapter from <xref linkend="bibHarold04"/> book
- contains additional information on extended <link
- xlink:href="http://www.cafeconleche.org/books/bible2/chapters/ch18.html#d1e2250">layout
- definitions</link>. The <orgname
- xlink:href="http://w3.org">W3C</orgname> as the holder of the FO
- standard defines the elements <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_layout-master-set">fo:layout-master-set</link>,
- <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_simple-page-master">fo:simple-page-master</link>
- and <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_page-sequence">fo:page-sequence</link></para>
- </section>
-
- <section xml:id="foContainer">
- <title>Important Objects</title>
-
- <section xml:id="fo_block">
- <title><code>fo:block</code></title>
-
- <para>The FO standard borrows a lot from the CSS standard. Most
- formatting objects may have <link
- xlink:href="http://www.w3.org/TR/xsl/#section-N19349-Description-of-Property-Groups">CSS
- like properties</link> with similar semantics, some properties have
- been added. We take a <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_block">fo:block</link>
- container as an example:</para>
-
- <figure xml:id="blockInline">
- <title>A <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_block">fo:block</link>
- with a <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_inline">fo:inline</link>
- descendant.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/blockprop.fo.pdf"/>
- </imageobject>
- </mediaobject>
-
- <programlisting language="none">...
-<fo:block font-weight='bold'
- border-bottom-style='dashed'
- border-style='solid'
- border='1mm'>A lot of attributes and <fo:inline background-color='black'
- color='white'>inverted</fo:inline> text.</fo:block> ...</programlisting>
- </figure>
-
- <para>The <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_inline">fo:inline</link>
- descendant serves as a means to change the <quote>current</quote>
- property set. In HTML/CSS this may be achieved by using the
- <code>SPAN</code> tag:</para>
-
- <programlisting language="none"><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html>
- <head>
- <title>Blocks/spans and CSS</title>
- </head>
- <body>
- <h1>Blocks/spans and CSS</h1>
- <p style="font-weight: bold; border: 1mm;
- border-style: solid; border-bottom-style: dashed;"
- >A lot of attributes and
- <span style="color: white;background-color: black;"
- >inverted</span> text.</p>
- </body>
-</html></programlisting>
-
- <para>Though being encapsulated in an attribute <code>class</code>
- we find a one-to-one correspondence between FO and CSS in this case.
- The HTML rendering works as expected.<mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Screen/mozparaspancss.screen.png"/>
- </imageobject>
- </mediaobject>:</para>
- </section>
-
- <section xml:id="fo_list">
- <title>Lists</title>
-
- <para>The easiest type of lists are unlabeled (itemized) lists as
- being expressed by the <code>UL</code>/<code>LI</code> tags in HTML.
- FO allows a much more detailed parametrization regarding indents and
- distances between labels and item content. Relevant elements are
- <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_list-block">fo:list-block</link>,
- <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_list-item">fo:list-item</link>
- and <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_list-item-body">fo:list-item-body</link>.
- The drawback is a more complex setup for <quote>default</quote>
- lists:</para>
-
- <figure xml:id="listItemize">
- <title>An itemized list and result.</title>
-
- <programlisting language="none">...
-<fo:list-block
- provisional-distance-between-starts="2mm">
- <fo:list-item>
- <fo:list-item-label end-indent="label-end()">
- <fo:block>&#8226;</fo:block>
- </fo:list-item-label>
- <fo:list-item-body start-indent="body-start()">
- <fo:block>Flowers</fo:block>
- </fo:list-item-body>
- </fo:list-item>
-
- <fo:list-item>
- <fo:list-item-label end-indent="label-end()">
- <fo:block>&#8226;</fo:block>
- </fo:list-item-label>
- <fo:list-item-body start-indent="body-start()">
- <fo:block>Animals</fo:block>
- </fo:list-item-body>
- </fo:list-item>
-</fo:list-block> ...</programlisting>
-
- <mediaobject>
- <imageobject>
- <imagedata align="left" fileref="Ref/Fig/itemize.fo.pdf"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>The result looks somewhat primitive in relation to the amount
- of source code it necessitates. The power of these constructs shows
- up when trying to format nested lists of possibly different types
- like enumerations or definition lists under the requirement of
- typographical excellence. More complex examples are presented in
- <link
- xlink:href="http://www.cafeconleche.org/books/bible2/chapters/ch18.html#d1e4979">Xmlbible
- book</link> of <xref linkend="bibHarold04"/>.</para>
- </section>
-
- <section xml:id="leaderRule">
- <title>Leaders and rules</title>
-
- <titleabbrev>Leaders/rules</titleabbrev>
-
- <para>Sometimes adjustable horizontal space between two neighbouring
- objects has to be filled e.g. in a book's table of contents. The
- <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_leader">fo:leader</link>
- serves this purpose:</para>
-
- <figure xml:id="leaderToc">
- <title>Two simulated entries in a table of contents.</title>
-
- <programlisting language="none">...
-<fo:block text-align-last='justify'>Valid
- XML<fo:leader leader-pattern="dots"/>
-page 7</fo:block>
-
-<fo:block text-align-last='justify'>XSL
-<fo:leader leader-pattern='dots'/>
-page 42</fo:block> ...</programlisting>
-
- <mediaobject>
- <imageobject>
- <imagedata align="left" fileref="Ref/Fig/leader.fo.pdf"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>The attributes' value <link
- xlink:href="http://www.w3.org/TR/xsl/#text-align-last">text-align-last</link>
- = <code>'justify'</code> forces the <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_block">fo:block</link> to
- extend to the available width of the current <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_region-body">fo:region-body</link>
- area. The <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_leader">fo:leader</link>
- inserts the necessary amount of content of the specified type
- defined in in <link
- xlink:href="http://www.w3.org/TR/xsl/#leader-pattern">leader-pattern</link>
- to fill up the gap between its neighbouring components. This
- principle can be extended to multiple objects:</para>
-
- <figure xml:id="leaderMulti">
- <title>Four entries separated by equal amounts of dotted
- space.</title>
-
- <programlisting language="none"><fo:block text-align-last='justify'>A<fo:leader
-leader-pattern="dots"/>B<fo:leader
-leader-pattern="dots"/>C<fo:leader leader-pattern="dots"/>D</fo:block></programlisting>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/leadermulti.fo.pdf"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>A <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_leader">fo:leader</link>
- may also be used to draw horizontal lines to separate objects. In
- this case there are no neighbouring components within the
- <quote>current</quote> line in which the <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_leader">fo:leader</link>
- appears. This is frequently used to draw a border between
- <code>xsl-region-body</code> and <code>xsl-region-before</code>
- and/or <code>xsl-region-after</code>:</para>
-
- <figure xml:id="leaderSeparate">
- <title>A horizontal line separator between header and body of a
- page.</title>
-
- <programlisting language="none">...
-<fo:page-sequence master-reference="simplePageLayout">
- <fo:static-content flow-name="xsl-region-before">
- <fo:block text-align-last='justify'>FO<fo:leader/>page 5</fo:block>
- <fo:block text-align-last='justify'>
- <fo:leader leader-pattern="rule" leader-length="100%"/>
- </fo:block>
- </fo:static-content>
- <fo:flow flow-name="xsl-region-body">
- <fo:block>Some body text ...</fo:block>
- </fo:flow>
-</fo:page-sequence>...</programlisting>
-
- <mediaobject>
- <imageobject>
- <imagedata align="left" fileref="Ref/Fig/separate.fo.pdf"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>Note the empty leader <code><</code> <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_leader">fo:leader</link>
- <code>/></code> between the <quote> <code>FO</code> </quote> and
- the <quote>page 5</quote> text node inserting horizontal whitespace
- to get the page number centered to the header's right edge. This is
- in accordance with the <link
- xlink:href="http://www.w3.org/TR/xsl/#leader-pattern">leader-pattern</link>
- attributes default value <code>space</code>.</para>
- </section>
-
- <section xml:id="pageNumbering">
- <title>Page numbers</title>
-
- <para>We already saw an example of page numbering via <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_page-number">fo:page-number</link>
- in <xref linkend="paramHeadFoot"/>. Sometimes a different style for
- page numbering is desired. The default page numbering style may be
- changed by means of the <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_page-sequence">fo:page-sequence</link>
- element's attribute <link
- xlink:href="http://www.w3.org/TR/xsl/#format">format</link>. For a
- closer explanation the <link
- xlink:href="http://www.w3.org/TR/2007/REC-xslt20-20070123/#convert">W3X
- XSLT standards documentation</link> may be consulted:</para>
-
- <figure xml:id="pageNumberingRoman">
- <title>Roman style page numbers.</title>
-
- <programlisting language="none">...
-<fo:page-sequence format="i"
- master-reference="simplePageLayout">
- <fo:static-content
- flow-name="xsl-region-after">
- <fo:block text-align-last='justify'>
- <fo:leader leader-pattern="rule"
- leader-length="100%"/>
- </fo:block>
- <fo:block font-weight="bold">
- <fo:page-number/>
- </fo:block>
- </fo:static-content>
-
- <fo:flow flow-name="xsl-region-body">
- <fo:block>Some text...</fo:block>
- <fo:block>More text, more text,
- more text.</fo:block>
- <fo:block>More text, more text,
- more text.</fo:block>
- <fo:block>Enough text.</fo:block>
- </fo:flow>
-</fo:page-sequence> ...</programlisting>
-
- <mediaobject>
- <imageobject>
- <imagedata align="left" fileref="Ref/Fig/pageStack.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
- </section>
-
- <section xml:id="foMarker">
- <title>Marker</title>
-
- <figure xml:id="dictionary">
- <title>A dictionary with running page headers.</title>
-
- <programlisting language="none">...
-<fo:page-sequence
- master-reference="simplePageLayout">
- <fo:static-content flow-name="xsl-region-before">
- <fo:block font-weight="bold">
- <fo:retrieve-marker retrieve-class-name="alpha"
- retrieve-position="first-starting-within-page"
- />-<fo:retrieve-marker
- retrieve-position="last-starting-within-page"
- retrieve-class-name="alpha"/>
- </fo:block>
- <fo:block text-align-last='justify'>
- <fo:leader leader-pattern="rule" leader-length="100%"/></fo:block>
- </fo:static-content>
-
- <fo:flow flow-name="xsl-region-body">
- <fo:block>
- <fo:marker marker-class-name="alpha">A
- </fo:marker>Ant</fo:block>
- <fo:block>
- <fo:marker marker-class-name="alpha">B
- </fo:marker>Bug</fo:block>
- <fo:block>
- <fo:marker marker-class-name="alpha">L
- </fo:marker>Lion</fo:block>
- <fo:block>
- <fo:marker marker-class-name="alpha">N
- </fo:marker>Nose</fo:block>
- <fo:block>
- <fo:marker marker-class-name="alpha">P
- </fo:marker>Peg</fo:block>
- </fo:flow>
-</fo:page-sequence> ...</programlisting>
-
- <mediaobject>
- <imageobject>
- <imagedata align="left" fileref="Ref/Fig/dictionaryStack.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
- </section>
-
- <section xml:id="foIntRef">
- <title>Internal references</title>
-
- <titleabbrev>References</titleabbrev>
-
- <para>Regarding printed documents we may define two categories of
- document internal references:</para>
-
- <variablelist>
- <varlistentry>
- <term><emphasis>Page number references</emphasis></term>
-
- <listitem>
- <para>This is the <quote>classical</quote> type of a reference
- e.g. in books. An author refers the reader to a distant
- location by writing <quote>... see further explanation in
- section 4.5 on page 234</quote>. A book's table of contents
- assigning page numbers to topics is another example. This way
- the implementation of a reference relies solely on the
- features a printed document offers.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis>Hypertext references</emphasis></term>
-
- <listitem>
- <para>This way of implementing references utilizes features of
- (online) viewers for printable documents. For example PDF
- viewers like <productname
- xlink:href="http://www.adobe.com">Adobe's Acrobat
- reader</productname> or the evince application are able to
- follow hypertext links in a fashion known from HTML browsers.
- This browser feature is based on hypertext capabilities
- defined in the Adobe's PDF de-facto standard.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>Of course the second type of references is limited to people
- who use an online viewer application instead of reading a document
- from physical paper.</para>
-
- <para>We now show the implementation of <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- based page references. As already being discussed for <link
- xlink:href="http://www.w3.org/TR/xml#id">ID</link> / <link
- xlink:href="http://www.w3.org/TR/xml#idref">IDREF</link> pairs we
- need a link destination (anchor) and a link source. The <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- standard uses the same anchor implementation as in XML for <link
- xlink:href="http://www.w3.org/TR/xml#id">ID</link> typed attributes:
- <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- objects <emphasis>may</emphasis> have an attribute <link
- xlink:href="http://www.w3.org/TR/xsl/#id">id</link> with a document
- wide unique value. The <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- element <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_page-number-citation">fo:page-number-citation</link>
- is used to actually create a page reference via its attribute <link
- xlink:href="http://www.w3.org/TR/xsl/#ref-id">ref-id</link>:</para>
-
- <figure xml:id="refJavaXml">
- <title>Two blocks mutual page referencing each other.</title>
-
- <programlisting language="none">...
- <fo:flow flow-name='xsl-region-body'>
- <fo:block id='xml'>Java section see page
- <fo:page-number-citation ref-id='java'/>.
- </fo:block>
-
- <fo:block id='java'>XML section see page
- <fo:page-number-citation ref-id='xml'/>.
- </fo:block>
- </fo:flow> ...</programlisting>
-
- <mediaobject>
- <imageobject>
- <imagedata align="left" fileref="Ref/Fig/pagerefStack.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>NB: Be careful defining <link
- xlink:href="http://www.w3.org/TR/xsl/#id">id</link> attributes for
- objects being descendants of <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_static-content">fo:static-content</link>
- nodes. Such objects typically appear on multiple pages and are
- therefore no unique anchors. A reference carrying such an id value
- thus actually refers to 1 <= n values on n different pages.
- Typically a user agent will choose the first object of this set when
- clicking the link. So in effect the parent <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_page-sequence">fo:page-sequence</link>
- is chosen as the effective link target.</para>
-
- <para>The element <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_basic-link">fo:basic-link</link>
- creates PDF hypertext links. We extend the previous example:</para>
-
- <figure xml:id="refJavaXmlHyper">
- <title>Two blocks with mutual page- and hypertext
- references.</title>
-
- <programlisting language="none"><fo:flow flow-name='xsl-region-body'>
- <fo:block id='xml'>Java section see <fo:basic-link color="blue"
- internal-destination="java">page<fo:page-number-citation
- ref-id='java'/>.</fo:basic-link></fo:block>
-
-<fo:block id='java'>XML section see
- <fo:basic-link color="blue"
- internal-destination="xml">page <fo:page-number-citation
- ref-id='xml'/>.</fo:basic-link></fo:block >
-</fo:flow></programlisting>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/pagerefhyperStack.fig"/>
- </imageobject>
- </mediaobject>
- </figure>
- </section>
-
- <section xml:id="pdfBookmarks">
- <title>PDF bookmarks</title>
-
- <titleabbrev>Bookmarks</titleabbrev>
-
- <para>The PDF specification allows to define so called bookmarks
- offering an explorer like navigation:</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Screen/pdfbookmarks.screen.png"/>
- </imageobject>
- </mediaobject>
-
- <para>PDF bookmarks are <link
- xlink:href="http://www.w3.org/TR/2006/REC-xsl11-20061205/#d0e14206">part
- of the XSL-FO 1.1</link> Standard. Some <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- processors still continue to use proprietary solutions for bookmark
- creation with respect to the older <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- 1.0 standard. For details of bookmark extensions by
- <orgname>RenderX</orgname>'s processor see <link
- xlink:href="http://www.renderx.com/tutorial.html#PDF_Bookmarks">xep's
- documentation</link>.</para>
- </section>
- </section>
-
- <section xml:id="xml2fo">
- <title>Constructing <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- from XML documents</title>
-
- <titleabbrev><abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- from XML</titleabbrev>
-
- <para>So far we have learnt some basic <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- elements. As with HTML we typically generate FO code from other
- sources rather than crafting it by hand. The general picture
- is:</para>
-
- <figure xml:id="htmlFoProduction">
- <title>Different target formats from common source.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/crossmedia.fig" scale="65"/>
- </imageobject>
-
- <caption>
- <para>We may generate both online and printed documentation from
- a common source. This requires style sheets for the desired
- destination formats in question.</para>
- </caption>
- </mediaobject>
- </figure>
-
- <para>We discussed the <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- standard as an input format for printable output production by a
- renderer. In this way a <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- document is similar to HTML being a format to be rendered by a web
- browser for visual (screen oriented) output production. The
- transformation from a XML source (e.g. a memo document) to <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- is still missing. As for HTML we may use <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> as a
- transformation means. We generate the sender's surname from a memo
- document instance:</para>
-
- <figure xml:id="memo2fosurname">
- <title>Generating a sender's surname for printing.</title>
-
- <programlisting language="none"><?xml version="1.0" encoding="utf-8"?>
-<xsl:stylesheet version="1.0"
- xmlns:fo="http://www.w3.org/1999/XSL/Format"
- xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
-
- <xsl:output method="xml" indent="yes"/>
-
- <xsl:template match="/">
- <fo:root>
- <fo:layout-master-set>
- <fo:simple-page-master master-name="simplePageLayout"
- page-width="294mm" page-height="210mm" margin="5mm">
- <fo:region-body margin="15mm"/>
- </fo:simple-page-master>
- </fo:layout-master-set>
- <fo:page-sequence master-reference="simplePageLayout">
- <fo:flow flow-name="xsl-region-body">
- <fo:block font-size="20pt">
- <xsl:text>Sender:</xsl:text>
- <fo:inline font-weight='bold'>
- <xsl:value-of select="memo/from/surname"/>
- </fo:inline>
- </fo:block>
- </fo:flow>
- </fo:page-sequence>
- </fo:root>
- </xsl:template>
-</xsl:stylesheet></programlisting>
- </figure>
-
- <para>A suitable XML document instance reads:</para>
-
- <figure xml:id="memoMessage">
- <title>A <code>memo</code> document instance.</title>
-
- <programlisting language="none"><?xml version="1.0" ?>
-<!DOCTYPE memo SYSTEM "memo.dtd">
-<memo>
- <from>
- <name>Martin</name>
- <surname>Goik</surname>
- </from>
- <to>
- <name>Adam</name>
- <surname>Hacker</surname>
- </to>
- <to>
- <name>Eve</name>
- <surname>Intruder</surname>
- </to>
- <date year="2005" month="1" day="6"/>
- <subject>Firewall problems</subject>
- <content>
- <para>Thanks for your excellent work.</para>
- <para>Our firewall is definitely broken!</para>
- </content>
-</memo></programlisting>
- </figure>
-
- <para>Some remarks:</para>
-
- <orderedlist>
- <listitem>
- <para>The <link
- xlink:href="http://www.w3.org/TR/2007/REC-xslt20-20070123/#element-stylesheet">xsl_stylesheet</link>
- element contains a namespace definition for the target FO
- document's namespace, namely:</para>
-
- <programlisting language="none">xmlns:xsl="http://www.w3.org/1999/XSL/Transform"</programlisting>
-
- <para>This is required to use elements like <link
- xlink:href="http://www.w3.org/TR/xsl/#fo_block">fo:block</link>
- belonging to the FO namespace.</para>
- </listitem>
-
- <listitem>
- <para>The option value <code>indent="yes"</code> in <link
- xlink:href="http://www.w3.org/TR/2007/REC-xslt20-20070123/#element-output">xsl_output</link>
- is usually set to "no" in a production environment to avoid
- whitespace related problems.</para>
- </listitem>
-
- <listitem>
- <para>The generation of a print format like PDF is actually a two
- step process. To generate message.pdf from message.xml by a
- stylesheet memo2fo.xsl we need the following calls:</para>
-
- <variablelist>
- <varlistentry>
- <term><emphasis>XML document instance to FO</emphasis></term>
-
- <listitem>
- <programlisting language="none">xml2xml message.xml memo2fo.xsl -o message.fo</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis>FO to PDF</emphasis></term>
-
- <listitem>
- <programlisting language="none">fo2pdf -fo message.fo -pdf message.pdf</programlisting>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Ref/Fig/xml2fo2pdf.fig"/>
- </imageobject>
- </mediaobject>
-
- <para>When debugging of the intermediate <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- file is not required both steps may be combined into a single
- call:</para>
-
- <programlisting language="none">fo2pdf -xml message.xml -xsl memo2fo.xsl -pdf message.pdf</programlisting>
- </listitem>
- </orderedlist>
- </section>
-
- <section xml:id="foCatalog">
- <title>Formatting a catalog.</title>
-
- <titleabbrev>A catalog</titleabbrev>
-
- <para>We now take the <link linkend="climbingCatalog">climbing catalog
- example</link> with prices being added and incrementally create a
- series of PDF versions improving from one version to another.</para>
-
- <qandaset defaultlabel="qanda" xml:id="idCatalogStart">
- <title>A first PDF version of the catalog</title>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>Write a <abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> script
- to generate a starting version <filename
- xlink:href="Ref/src/Dom/climbenriched.start.pdf">climbenriched.start.pdf</filename>.</para>
- </question>
-
- <answer>
- <programlisting language="none"><?xml version="1.0" encoding="utf-8"?>
-<xsl:stylesheet version="1.0"
- xmlns:fo="http://www.w3.org/1999/XSL/Format"
- xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
-
- <xsl:output method="xml" indent="yes"/>
-
- <xsl:template match="/">
- <fo:root font-size="10pt">
- <fo:layout-master-set>
- <fo:simple-page-master master-name="productPage"
- page-width="80mm" page-height="110mm" margin="5mm">
- <fo:region-body margin="15mm"/>
- <fo:region-before extent="10mm"/>
- </fo:simple-page-master>
- </fo:layout-master-set>
- <xsl:apply-templates select="catalog/product" />
- </fo:root>
- </xsl:template>
-
- <xsl:template match="product">
- <fo:page-sequence master-reference="productPage">
- <fo:static-content flow-name="xsl-region-before">
- <fo:block font-weight="bold">
- <xsl:value-of select="title"/>
- </fo:block>
- </fo:static-content>
- <fo:flow flow-name="xsl-region-body">
- <xsl:apply-templates select="description/para"/>
-
- <fo:block>Price:<xsl:value-of select="@price"/></fo:block>
- <fo:block>Order no:<xsl:value-of select="@id"/></fo:block>
- </fo:flow>
- </fo:page-sequence>
- </xsl:template>
-
- <xsl:template match="para">
- <fo:block space-after="10px">
- <xsl:value-of select="."/>
- </fo:block>
- </xsl:template>
-
-</xsl:stylesheet></programlisting>
- </answer>
- </qandaentry>
-
- <qandaentry xml:id="idCatalogProduct">
- <question>
- <label>Header, page numbers and table formatting</label>
-
- <para>Extend <xref linkend="idCatalogStart"/> by adding page
- numbers. The order number and prices shall be formatted as
- tables. Add a ruler to each page's head. The result should
- look like <filename
- xlink:href="Ref/src/Dom/climbenriched.product.pdf">climbenriched.product.pdf</filename></para>
- </question>
-
- <answer>
- <para>Solution see <filename
- xlink:href="Ref/src/Dom/catalog2fo.product.xsl">catalog2fo.product.xsl</filename>.</para>
- </answer>
- </qandaentry>
-
- <qandaentry xml:id="idCatalogToc">
- <question>
- <label>A table of contents.</label>
-
- <para>Each product description's page number shall appear in a
- table of contents together with the product's
- <code>title</code> as in <filename
- xlink:href="Ref/src/Dom/climbenriched.toc.pdf">climbenriched.toc.pdf</filename>.</para>
- </question>
-
- <answer>
- <para>Solution see <filename
- xlink:href="Ref/src/Dom/catalog2fo.toc.xsl">catalog2fo.toc.xsl</filename>.</para>
- </answer>
- </qandaentry>
-
- <qandaentry xml:id="idCatalogToclink">
- <question>
- <label>A table of contents with hypertext links.</label>
-
- <para>The table of contents' entries may offer hypertext
- features to supporting browsers as in <filename
- xlink:href="Ref/src/Dom/climbenriched.toclink.pdf">climbenriched.toclink.pdf</filename>.
- In addition include the document's <tag
- class="starttag">introduction</tag>.</para>
- </question>
-
- <answer>
- <para>Solution see <filename
- xlink:href="Ref/src/Dom/catalog2fo.toclink.xsl">catalog2fo.toclink.xsl</filename>.</para>
- </answer>
- </qandaentry>
-
- <qandaentry xml:id="idCatalogFinal">
- <question>
- <label>A final version.</label>
-
- <para>Add the following features:</para>
-
- <orderedlist>
- <listitem>
- <para>Number the table of contents starting with page i,
- ii, iii, iv and so on. Start the product descriptions with
- page 1. On each page's footer a text <quote>page xx of
- yy</quote> shall be displayed. This requires the
- definition of an anchor <code>id</code> on the <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- document's last page.</para>
- </listitem>
-
- <listitem>
- <para>Add PDF bookmarks by using <orgname>XEP</orgname>'s
- <abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
- extensions. This requires the namespace declaration
- <code>xmlns:rx="http://www.renderx.com/XSL/Extensions"</code>
- in the XSLT script's header.</para>
- </listitem>
- </orderedlist>
-
- <para>The result may look like <filename
- xlink:href="Ref/src/Dom/climbenriched.final.pdf">climbenriched.final.pdf</filename>.
- N.B.: It may take some effort to achieve this result. This
- effort is left to the <emphasis>interested</emphasis>
- participants.</para>
- </question>
-
- <answer>
- <para>Solution see <filename
- xlink:href="Ref/src/Dom/catalog2fo.toclink.xsl">catalog2fo.toclink.xsl</filename>.</para>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
- </chapter>
-
- <appendix>
- <title>W3C production rules</title>
-
- <productionset>
- <title><link
- xlink:href="http://www.w3.org/TR/2008/REC-xml-20081126/#charsets">Characters</link></title>
-
- <production xml:id="w3RecXml_NT-Letter">
- <lhs>Letter</lhs>
-
- <rhs><nonterminal def="#w3RecXml_NT-BaseChar">BaseChar</nonterminal>
- | <nonterminal
- def="#w3RecXml_NT-Ideographic">Ideographic</nonterminal></rhs>
- </production>
-
- <production xml:id="w3RecXml_NT-BaseChar">
- <lhs>BaseChar</lhs>
-
- <rhs>[#x0041-#x005A] |Â [#x0061-#x007A] |Â [#x00C0-#x00D6]
- |Â [#x00D8-#x00F6] |Â [#x00F8-#x00FF] |Â [#x0100-#x0131]
- |Â [#x0134-#x013E] |...(values omitted here, see W3C
- documentation)</rhs>
- </production>
-
- <production xml:id="w3RecXml_NT-Ideographic">
- <lhs>Ideographic</lhs>
-
- <rhs>[#x4E00-#x9FA5] |Â #x3007 |Â [#x3021-#x3029]</rhs>
- </production>
-
- <production xml:id="w3RecXml_NT-CombiningChar">
- <lhs>CombiningChar</lhs>
-
- <rhs>[#x0300-#x0345] |Â ...(values omitted here)</rhs>
- </production>
-
- <production xml:id="w3RecXml_NT-Digit">
- <lhs>Digit</lhs>
-
- <rhs>[#x0030-#x0039] |Â [#x0660-#x0669] |Â [#x06F0-#x06F9]
- |Â [#x0966-#x096F] |Â [#x09E6-#x09EF] |Â [#x0A66-#x0A6F]
- |Â [#x0AE6-#x0AEF] |Â [#x0B66-#x0B6F] |Â [#x0BE7-#x0BEF]
- |Â [#x0C66-#x0C6F] |Â [#x0CE6-#x0CEF] |Â [#x0D66-#x0D6F]
- |Â [#x0E50-#x0E59] |Â [#x0ED0-#x0ED9] |Â [#x0F20-#x0F29]</rhs>
- </production>
-
- <production xml:id="w3RecXml_NT-Extender">
- <lhs>Extender</lhs>
-
- <rhs>#x00B7 |Â #x02D0 |Â #x02D1 |Â #x0387 |Â #x0640 |Â #x0E46 |Â #x0EC6
- |Â #x3005 |Â [#x3031-#x3035] |Â [#x309D-#x309E] |Â [#x30FC-#x30FE]</rhs>
- </production>
- </productionset>
- </appendix>
- </part>
-
- <appendix>
- <title>Glossary</title>
-
- <para/>
-
- <glossary>
- <glossentry xml:id="gloss_API">
- <glossterm><abbrev xlink:href="http://en.wikipedia.org/wiki/Api"
- xml:id="abbr_api">API</abbrev></glossterm>
-
- <glossdef>
- <para>Application programming interface</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_SqlDdl">
- <glossterm><abbrev
- xlink:href="http://en.wikipedia.org/wiki/Data_definition_language"
- xml:id="abbr_Ddl">DDL</abbrev> <link
- linkend="gloss_SQL">(SQL)</link></glossterm>
-
- <glossdef>
- <para>Data definition language. The subset of <link
- linkend="gloss_SQL">SQL</link> dealing with the creation of tables,
- views etc.</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_DOM">
- <glossterm><acronym xlink:href="http://www.w3.org/DOM"
- xml:id="abbr_Dom">DOM</acronym></glossterm>
-
- <glossdef>
- <para>The <link linkend="gloss_W3C">W3C</link> <link
- xlink:href="http://www.w3.org/DOM">Document Object Model</link>
- standard</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_DTD">
- <glossterm><abbrev
- xlink:href="http://en.wikipedia.org/wiki/Document_Type_Declaration"
- xml:id="abbr_Dtd">DTD</abbrev></glossterm>
-
- <glossdef>
- <para>Document Type Definition. An older standard with respect to
- <link linkend="gloss_RelaxNG">RelaxNG</link> and <link
- linkend="gloss_RelaxNG">XML schema</link> to define an XML documents
- grammar.</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_EBNF">
- <glossterm><abbrev>EBNF</abbrev></glossterm>
-
- <glossdef>
- <para>Extended Backus-Naur form.</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_ftp">
- <glossterm><abbrev
- xlink:href="http://en.wikipedia.org/wiki/File_Transfer_Protocol"
- xml:id="abbr_Ftp">ftp</abbrev></glossterm>
-
- <glossdef>
- <para>File Transfer Protocol</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_FO">
- <glossterm><abbrev
- xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section"
- xml:id="abbr_Fo">FO</abbrev></glossterm>
-
- <glossdef>
- <para>The Formatting Objects Standard for printable output
- generation</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_HDM">
- <glossterm><orgname xlink:href="http://www.hdm-stuttgart.de"
- xml:id="org_Hdm">Hdm</orgname></glossterm>
-
- <glossdef>
- <para xml:lang="de">Hochschule der Medien.</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_Hql">
- <glossterm><abbrev
- xlink:href="http://docs.jboss.org/hibernate/orm/4.1/manual/en-US/html/ch16.html"
- xml:id="abbr_Hql">HQL</abbrev></glossterm>
-
- <glossdef>
- <para>The <link
- xlink:href="http://docs.jboss.org/hibernate/orm/3.3/reference/en/html/queryhql.html">Hibernate
- Query Language</link>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_http">
- <glossterm><abbrev xlink:href="http://www.w3.org/Protocols"
- xml:id="abbr_Http">http</abbrev></glossterm>
-
- <glossdef>
- <para>The Hypertext Transfer Protocol</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_IDE">
- <glossterm><abbrev
- xlink:href="http://en.wikipedia.org/wiki/Integrated_development_environment"
- xml:id="abbr_Ide">IDE</abbrev></glossterm>
-
- <glossdef>
- <para>Integrated Development Environment</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_J2EE">
- <glossterm><trademark
- xlink:href="http://www.oracle.com/technetwork/java/javaee"
- xml:id="tm_J2ee">J2EE</trademark></glossterm>
-
- <glossdef>
- <para>Java Platform, Enterprise Edition</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_Java">
- <glossterm><trademark
- xlink:href="http://www.oracle.com/us/legal/third-party-trademarks/index.html">Java</trademark></glossterm>
-
- <glossdef>
- <para>General purpose programming language with support for object
- oriented concepts.</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_Javadoc">
- <glossterm><trademark
- xlink:href="http://docs.oracle.com/javase/1.5.0/docs/guide/javadoc">Javadoc</trademark></glossterm>
-
- <glossdef>
- <para>Extracting documentation embedded in <link
- linkend="gloss_Java"><trademark>Java</trademark></link> source
- code.</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_JDBC">
- <glossterm><trademark
- xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc"
- xml:id="tm_Jdbc">JDBC</trademark></glossterm>
-
- <glossdef>
- <para>XXX.</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_JDK">
- <glossterm><trademark
- xlink:href="http://www.oracle.com/technetwork/java/javase"
- xml:id="tm_Jdk">JDK</trademark></glossterm>
-
- <glossdef>
- <para>Java Development Kit.</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_JPA">
- <glossterm><abbrev
- xlink:href="http://www.javaworld.com/javaworld/jw-01-2008/jw-01-jpa1.html"
- xml:id="abbr_Jpa">JPA</abbrev></glossterm>
-
- <glossdef>
- <para><link
- xlink:href="http://www.javaworld.com/javaworld/jw-01-2008/jw-01-jpa1.html">Java
- Persistence Architecture</link></para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_JRE">
- <glossterm><trademark
- xlink:href="http://www.oracle.com/technetwork/java/javase"
- xml:id="tm_Jre">JRE</trademark></glossterm>
-
- <glossdef>
- <para>Java Runtime Environment</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_MathML">
- <glossterm><abbrev>MathML</abbrev></glossterm>
-
- <glossdef>
- <para><link xlink:href="http://www.w3.org/Math">Mathematical Markup
- Language</link></para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_MIB">
- <glossterm><orgname xlink:href="http://www.mi.hdm-stuttgart.de"
- xml:id="org_Mib">MIB</orgname></glossterm>
-
- <glossdef>
- <para xml:lang="de">Bachelor Studiengang Medieninformatik</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_Mysql">
- <glossterm><trademark
- xlink:href="http://www.mysql.com/about/legal/trademark.html"
- xml:id="tm_Mysql">Mysql</trademark></glossterm>
-
- <glossdef>
- <para>Open source Oracle database product</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_MP3">
- <glossterm><abbrev>MP3</abbrev></glossterm>
-
- <glossdef>
- <para>Audio codec.</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_ORM">
- <glossterm><abbrev>ORM</abbrev></glossterm>
-
- <glossdef>
- <para>Object relational mapping.</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_PHP">
- <glossterm><abbrev
- xlink:href="http://www.php.net">PHP</abbrev></glossterm>
-
- <glossdef>
- <para>Hypertext preprocessor</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_RelaxNG">
- <glossterm><acronym
- xlink:href="http://relaxng.org">RelaxNG</acronym></glossterm>
-
- <glossdef>
- <para>An <link
- xlink:href="http://standards.iso.org/ittf/PubliclyAvailableStandards/c037605_ISO_IEC_19757-2_2003(E).zip">ISO</link>
- standard to define the grammar of XML documents. Primary use for
- document oriented applications.</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_SAX">
- <glossterm><acronym
- xlink:href="http://www.saxproject.org">SAX</acronym></glossterm>
-
- <glossdef>
- <para><link xlink:href="http://www.saxproject.org">Simple API for
- XML</link>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_SQL">
- <glossterm><acronym
- xlink:href="http://en.wikipedia.org/wiki/Sql">SQL</acronym></glossterm>
-
- <glossdef>
- <para><link xlink:href="http://en.wikipedia.org/wiki/SQL">Structured
- query language</link>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_SVG">
- <glossterm><abbrev>SVG</abbrev></glossterm>
-
- <glossdef>
- <para><link xlink:href="http://www.w3.org/Graphics/SVG">Scalable
- Vector Graphics</link>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_TCP">
- <glossterm><acronym
- xlink:href="http://en.wikipedia.org/wiki/Transmission_Control_Protocol"
- xml:id="abbr_Tcp">TCP</acronym></glossterm>
-
- <glossdef>
- <para>Transmission Control Protocol</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_URL">
- <glossterm><abbrev xlink:href="http://www.ietf.org/rfc/rfc1738.txt"
- xml:id="abbr_Url">URL</abbrev></glossterm>
-
- <glossdef>
- <para>Uniform Resource Locator</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_W3C">
- <glossterm><orgname
- xlink:href="http://www.w3.org">W3C</orgname></glossterm>
-
- <glossdef>
- <para>World Wide Web Consortium</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_XHTML">
- <glossterm><abbrev>XHTML</abbrev></glossterm>
-
- <glossdef>
- <para>Html as <link linkend="gloss_XML">XML</link> <link
- xlink:href="http://www.w3.org/TR/xhtml11">standard</link>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_XML">
- <glossterm><abbrev
- xlink:href="http://www.w3.org/XML">Xml</abbrev></glossterm>
-
- <glossdef>
- <para>The <link xlink:href="http://www.w3.org/XML">Extensible Markup
- Language</link>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_XmlSchema">
- <glossterm>XML Schema</glossterm>
-
- <glossdef>
- <para>A W3C standard to define grammars for XML documents. Rich set
- of features with respect to data modeling.</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_XPath">
- <glossterm><acronym xlink:href="http://www.w3.org/TR/xpath"
- xml:id="abbr_Xpath">XPath</acronym></glossterm>
-
- <glossdef>
- <para>XML Path Language</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_XSD">
- <glossterm><abbrev
- xlink:href="http://www.w3.org/Style/XSL">XSD</abbrev></glossterm>
-
- <glossdef>
- <para>XML Schema description Language</para>
- </glossdef>
- </glossentry>
-
- <glossentry xml:id="gloss_XSL">
- <glossterm><abbrev xlink:href="http://www.w3.org/Style/XSL"
- xml:id="abbr_Xsl">XSL</abbrev></glossterm>
-
- <glossdef>
- <para>Extensible Stylesheet Language</para>
- </glossdef>
- </glossentry>
- </glossary>
- </appendix>
-
- <xi:include href="../bibliography.xml" xpointer="element(/1)"/>
-</book>
diff --git a/Doc/sda1.xml b/Doc/sda1.xml
old mode 100755
new mode 100644
index a0b2492357fc825aaf17e0066a12bb0a0a406c0a..a62bbbd89bf2997f3ad79fe4908c4a239db90016
--- a/Doc/sda1.xml
+++ b/Doc/sda1.xml
@@ -1,5 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
-<book version="5.0" xmlns="http://docbook.org/ns/docbook"
+<book xml:id="sda1"
+ version="5.0" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg"
@@ -7,413 +8,13978 @@
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook">
<info>
- <title xml:id="sda1"/>
+ <title>Structured Data and Applications 1</title>
<author>
- <personname><firstname/><surname/></personname>
+ <personname><firstname>Martin</firstname>
+ <surname>Goik</surname></personname>
<affiliation>
- <orgname/>
+ <orgname>http://medieninformatik.hdm-stuttgart.de</orgname>
</affiliation>
</author>
- <pubdate/>
+ <legalnotice>
+ <para>Source code available at <uri
+ xlink:href="https://version.mi.hdm-stuttgart.de/git/GoikLectures">https://version.mi.hdm-stuttgart.de/git/GoikLectures</uri></para>
+ </legalnotice>
</info>
- <chapter xml:id="company">
- <title>Data models</title>
- <para>Wanted: A data model to represent entities and their
- relationships</para>
+ <chapter xml:id="prerequisites">
+ <title>Prerequisites</title>
- <section xml:id="companyRepresent">
- <title>Representing a company</title>
+ <section xml:id="resources">
+ <title>Lecture resources</title>
- <para>Entities to be represented:</para>
+ <glosslist>
+ <glossentry>
+ <glossterm>Recommended book</glossterm>
- <itemizedlist>
- <listitem>
- <para>Employee</para>
- </listitem>
+ <glossdef>
+ <para><link linkend="fawcett2012">Beginning XML</link></para>
- <listitem>
- <para>Departments</para>
- </listitem>
+ <caution>
+ <para>Some figures including videos are left blank.</para>
+ </caution>
+ </glossdef>
+ </glossentry>
- <listitem>
- <para>Projects</para>
- </listitem>
+ <glossentry>
+ <glossterm>Lecture notes as PDF</glossterm>
- <listitem>
- <para>...</para>
- </listitem>
- </itemizedlist>
+ <glossdef>
+ <para><uri
+ xlink:href="http://www.mi.hdm-stuttgart.de/freedocs/topic/de.hdm_stuttgart.mi.sda1/printversion.pdf">http://www.mi.hdm-stuttgart.de/freedocs/topic/de.hdm_stuttgart.mi.sda1/printversion.pdf</uri></para>
- <para>Relationships:</para>
+ <caution>
+ <para>Some figures including videos are left blank.</para>
+ </caution>
+ </glossdef>
+ </glossentry>
- <itemizedlist>
- <listitem>
- <para>Each employee is being assigned to exactly one
- department</para>
- </listitem>
+ <glossentry>
+ <glossterm>Live lecture additions</glossterm>
- <listitem>
- <para>Each employee may participate in an arbitrary number of
- projects. For each project an employee's number of weekly working
- hours participation is being defined.</para>
- </listitem>
+ <glossdef>
+ <para><link
+ xlink:href="https://cloud.mi.hdm-stuttgart.de/owncloud/public.php?service=files&t=dae5c53f0a05d6661209527cee45d323">https://cloud.mi.hdm-stuttgart.de/owncloud/public.php?service=files&t=dae5c53f0a05d6661209527cee45d323</link></para>
+ </glossdef>
+ </glossentry>
- <listitem>
- <para>Each department may have a parent department</para>
- </listitem>
- </itemizedlist>
+ <glossentry>
+ <glossterm>List of exercises</glossterm>
- <para>We start creating a database table representing
- <code>Department</code> entities:</para>
+ <glossdef>
+ <para>The lecture notes contain exercises to be solved by you! A
+ complete list is available at <uri
+ xlink:href="http://www.mi.hdm-stuttgart.de/freedocs/topic/de.hdm_stuttgart.mi.sda1/apb.html">http://www.mi.hdm-stuttgart.de/freedocs/topic/de.hdm_stuttgart.mi.sda1/apb.html</uri>.
+ You may also use the corresponding PDF version within <filename
+ xlink:href="http://www.mi.hdm-stuttgart.de/freedocs/topic/de.hdm_stuttgart.mi.sda1/printversion.pdf">printversion.pdf</filename>
+ to keep track of your personal advance by filling in your
+ completion status.</para>
+ </glossdef>
+ </glossentry>
- <programlisting>CREATE TABLE Department(
- id BIGINT PRIMARY KEY <co linkends="departmentTable-1"
- xml:id="deptTableSurrogateKey"/>
- ,name CHAR(20) NOT NULL UNIQUE <co linkends="departmentTable-2"
- xml:id="deptTableBusinessKey"/>
-)</programlisting>
+ <glossentry>
+ <glossterm><link
+ linkend="gloss_Javadoc"><trademark>Javadoc</trademark></link>
+ references and source code</glossterm>
- <calloutlist>
- <callout arearefs="deptTableSurrogateKey" xml:id="departmentTable-1">
- <para>The <code>Department</code> table's
- <emphasis>surrogate</emphasis> key</para>
- </callout>
-
- <callout arearefs="deptTableBusinessKey" xml:id="departmentTable-2">
- <para>The <code>Department</code> table's unique name, e.g.
- <quote>Sales</quote>.</para>
- </callout>
- </calloutlist>
-
- <para>Each <code>Employee</code> is being affiliated (see <coref
- linkend="employeeAffiliation"/> below) with exactly one
- <code>Department</code>. Its fax number is the only nullable
- property.</para>
-
- <programlisting>CREATE TABLE Employee (
- id BIGINT PRIMARY KEY
- ,number INTEGER NOT NULL UNIQUE
- ,name CHAR(20) NOT NULL
- ,surname CHAR(20) NOT NULL
- ,department BIGINT NOT NULL REFERENCES Department <co
- xml:id="employeeAffiliation"/>
- ,telephone CHAR(4) NOT NULL
- ,fax CHAR(4)
-);</programlisting>
+ <glossdef>
+ <para>The lecture notes contain a lot of <link
+ linkend="gloss_Javadoc"><trademark>Javadoc</trademark></link>
+ references. Most classes appearing within these lecture notes
+ have <link
+ linkend="gloss_Javadoc"><trademark>Javadoc</trademark></link>
+ generated links to the source code as well. For example when
+ clicking on the class name in
+ <classname>sda.jdbc.intro.v1.SimpleInsert</classname> you will
+ see the complete implementation.</para>
+ </glossdef>
+ </glossentry>
- <qandaset>
- <qandadiv>
- <qandaentry>
- <question>
- <para>Explain the (<acronym linkend="gloss_Sql">SQL</acronym>)
- technical difference between a <code>PRIMARY KEY</code> and a
- UNIQUE <acronym linkend="gloss_SqlDdl">DDL</acronym> statement
- with respect to data integrity constraints.</para>
- </question>
-
- <answer>
- <para>A primary key attribute must not be <code>NULL</code> and
- defines a unique set of attribute values within a given table. A
- UNIQUE attribute allows <code>NULL</code> values and may thus be
- complemented by a NOT NULL constraint to form a <link
- linkend="glossCandidateKey">candidate key</link> for the sake of
- allowing to identify <emphasis>all</emphasis> datasets of a
- given table..</para>
- </answer>
- </qandaentry>
- </qandadiv>
-
- <qandadiv>
- <qandaentry>
- <question>
- <para>Explain the above notion of <emphasis>surrogate
- key</emphasis>s, business keys and their roles for application
- developers. Why should surrogate be preferred when defining
- foreign key targets?</para>
- </question>
-
- <answer>
- <para>A surrogate key is being defined as a technical means to
- reference objects on database level by foreign keys in a
- <quote>sound </quote> manner. Its values are not intended to be
- visible to end users and should thus not appear in e.g. <abbrev
- linkend="gloss_Gui">GUI</abbrev> components. This allows
- surrogate keys to be implemented by immutable attributes.</para>
-
- <para>On contrary business keys should not be used as reference
- targets. This avoids transactional hassles being imposed by e.g.
- <code>ON UPDATE CASCADE</code> and other transitive foreign key
- attribute updates caused by changing business key values. The
- following variant uses a business key as a foreign key
- target:</para>
-
- <programlisting>CREATE TABLE Department(
- id BIGINT PRIMARY KEY
- ,name CHAR(20) NOT NULL UNIQUE <co linkends="cascadeBusinessKey-1"
- xml:id="employeeDepartmentBusiness"/>
-);
+ <glossentry>
+ <glossterm>Links to animated figures</glossterm>
-CREATE TABLE Employee (
- id BIGINT PRIMARY KEY
- ,number INTEGER NOT NULL UNIQUE
- ,name CHAR(20) NOT NULL
- ,surname CHAR(20) NOT NULL
- ,department CHAR(20) NOT NULL REFERENCES Department(name) <co
- linkends="cascadeBusinessKey-2"
- xml:id="employeeDepartmentCascade"/>
- ,telephone CHAR(4) NOT NULL
- ,fax CHAR(4)
-);</programlisting>
+ <glossdef>
+ <para>The lecture notes' online version contains links to <uri
+ xlink:href="http://www.mi.hdm-stuttgart.de/freedocs/topic/de.hdm_stuttgart.mi.sda1/jdbcWrite.html">PDF
+ images</uri>. Clicking on <quote>Animated PDF Version</quote>
+ takes you to a referenced PDF which in full screen mode of
+ Acrobat Reader or <trademark>google-chrome</trademark> provides
+ a slide like animation.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm><trademark>Virtualbox</trademark> image</glossterm>
+
+ <glossdef>
+ <para>A <productname
+ xlink:href="https://www.virtualbox.org">Virtualbox</productname>
+ image is available at <uri
+ xlink:href="ftp://mirror.mi.hdm-stuttgart.de/ubuntu/VirtualBox/lubuntu.rar">ftp://mirror.mi.hdm-stuttgart.de/ubuntu/VirtualBox/lubuntu.rar</uri>
+ <link
+ xlink:href="ftp://mirror.mi.hdm-stuttgart.de/ubuntu/VirtualBox/lubuntu.vdi">ftp://mirror.mi.hdm-stuttgart.de/ubuntu/VirtualBox/lubuntu.vdi</link>.</para>
+
+ <caution>
+ <para>Access from networks being external to
+ <uri>hdm-stuttgart.de</uri> requires <acronym>VPN</acronym>
+ access.</para>
+ </caution>
+
+ <para>It contains (hopefully) all related tools from the <link
+ xlink:href="http://www.mi.hdm-stuttgart.de">CSM</link>
+ department's lecture room Linux installation:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Eclipse J2EE version with <productname
+ xlink:href="http://www.eclipse.org/datatools">Database
+ developer tools</productname>, <productname
+ xlink:href="http://git-scm.com">git</productname>,
+ <trademark
+ xlink:href="http://oxygenxml.com">Oxygenxml</trademark>,
+ <productname
+ xlink:href="http://testng.org/doc/eclipse.html">TestNG</productname>
+ and <productname
+ xlink:href="http://subversion.apache.org/">svn</productname>
+ plugins installed.</para>
+ </listitem>
+
+ <listitem>
+ <para>A running <productname
+ xlink:href="http://www.mysql.com/">Mysql</productname>
+ server preconfigured with user
+ <quote><code>hdmuser</code></quote>, password
+ <quote><code>XYZ</code></quote> (<emphasis
+ role="bold">capital letters!</emphasis>) and database
+ <quote><code>hdm</code></quote>.</para>
+ </listitem>
+
+ <listitem>
+ <para><productname
+ xlink:href="http://www.xmlmind.com/xmleditor">Xmlmind XML
+ editor</productname> for visually editing technical
+ documents based on <productname
+ xlink:href="http://docbook.org/tdg5/index.html">docbook</productname>
+ or <productname
+ xlink:href="http://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture">DITA</productname>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <caution>
+ <para>This VM is only accessible from within the <orgname
+ xlink:href="http://www.hdm-stuttgart.de">HdM</orgname>
+ network. External downloads require <productname
+ xlink:href="https://wiki.mi.hdm-stuttgart.de/wiki/VPN">OpenVPN</productname>.</para>
+ </caution>
+
+ <para>The virtual machine is based on the <productname
+ xlink:href="http://lubuntu.net">Lubuntu</productname> fork of
+ the <productname
+ xlink:href="http://www.ubuntu.com">Ubuntu</productname> Linux
+ distribution for resource saving reasons.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="oxygenLicenseKey">
+ <glossterm><uri>Oxygen Xml Editor</uri> license key</glossterm>
+
+ <glossdef>
+ <para>This is the only software component in this lecture
+ requiring a license. Your <orgname>HdM</orgname> affiliation
+ entitles you to use the <productname
+ xlink:href="http://oxygenxml.com/">Oxygenxml</productname>
+ software for educational (non-commercial) purposes. The
+ corresponding key is available at <uri
+ xlink:href="ftp://mirror.mi.hdm-stuttgart.de/Firmen/Oxygen/Keys">ftp://mirror.mi.hdm-stuttgart.de/Firmen/Oxygen/Keys</uri>.</para>
+
+ <para>This license key is compatible both with the standalone
+ and the eclipse plugin version of the product.</para>
+
+ <caution>
+ <para>The license key's <abbrev
+ xlink:href="http://en.wikipedia.org/wiki/File_Transfer_Protocol">ftp</abbrev>
+ URL is only accessible from within the <orgname
+ xlink:href="http://www.hdm-stuttgart.de">HdM</orgname>
+ network. External access requires <link
+ xlink:href="https://wiki.mi.hdm-stuttgart.de/wiki/VPN">Vpn
+ activation</link>.</para>
+ </caution>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Source code of lecture resources</glossterm>
+
+ <glossdef>
+ <para>The complete lecture sources are available from <link
+ xlink:href="https://version.mi.hdm-stuttgart.de/git/GoikLectures">https://version.mi.hdm-stuttgart.de/git/GoikLectures</link>.</para>
+
+ <para>You may simply execute <quote><command
+ xlink:href="http://git-scm.com/">git</command>
+ <option>clone</option>
+ <option>https://version.mi.hdm-stuttgart.de/git/GoikLectures</option>
+ <option>.</option></quote> to check out the master tree.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Source code of exercises and examples</glossterm>
+
+ <glossdef>
+ <para>These sources contain a subdirectory
+ <filename>ws/eclipse/Jdbc</filename> which can be imported as an
+ eclipse project. This allows for browsing solutions to the
+ exercises and executing sample applications. Import into eclipse
+ works the following way:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>When starting eclipse choose
+ <filename>.../ws/eclipse</filename> as workspace</para>
+ </listitem>
+
+ <listitem>
+ <para>In eclipse click <quote>File --> Import -->
+ General --> Existing Projects into Workspace</quote>.
+ After re-selecting the current workspace
+ <filename>.../ws/eclipse</filename> the folder
+ <filename>Jdbc</filename> should be on the list of
+ importable projects.</para>
+
+ <para>Depending on your eclipse installation you may have to
+ adjust the <link
+ linkend="gloss_Java"><trademark>Java</trademark></link>
+ system libraries. Right click on your project root in the
+ package explorer and choose <quote>Build Path -->
+ Configure Buildpath</quote>. The <quote>JRE System
+ Library</quote> entry in the <quote>Libraries</quote> tab
+ may have to be changed to suit your eclipse's installation
+ needs. You may want to create a dummy <link
+ linkend="gloss_Java"><trademark>Java</trademark></link>
+ project to find the correct setting.</para>
+ </listitem>
+ </itemizedlist>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+ </section>
+
+ <section xml:id="tools">
+ <title>Tools</title>
+
+ <para>The subsequent sections describe tools being helpful to
+ successfully carry out the exercises. These descriptions are suitable
+ for current Linux/Ubuntu systems. However these tool are available for
+ <trademark>Windows</trademark> or <trademark>Apple</trademark> systems
+ as well. For the latter some command line hints may have to be
+ replaced by using GUI based tools.</para>
+
+ <para>You may want to use the <link
+ xlink:href="ftp://mirror.mi.hdm-stuttgart.de/ubuntu/VirtualBox/lubuntu.vdi">corresponding</link>
+ <link xlink:href="https://www.virtualbox.org">Virtualbox image</link>
+ containing a complete system avoiding installation hassles. This
+ should work well one reasonable current hardware systems.</para>
+
+ <section xml:id="eclipse">
+ <title><productname
+ xlink:href="http://www.oracle.com/technetwork/java/javase/jdk-7-readme-429198.html">JDK</productname>
+ and Eclipse</title>
+
+ <para>So you like to take the hard way rather than using <link
+ xlink:href="ftp://mirror.mi.hdm-stuttgart.de/ubuntu/VirtualBox/lubuntu.vdi">the
+ virtualbox image</link>? Good! Real programmers tend to complicate
+ things!</para>
+
+ <para>The Eclipse IDE will be used as the primary coding tool
+ especially for <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> and XML.
+ Users may use different tools like e.g. <productname
+ xlink:href="http://netbeans.org">Netbeans</productname> or
+ <productname
+ xlink:href="http://www.altova.com/de/xmlspy.html">XML-Spy</productname>.
+ There are however some caveats:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Certain functionalities may not be provided</para>
+ </listitem>
+
+ <listitem>
+ <para><orgname>HdM</orgname> staff support in case of troubles
+ will be limited to coding excluding tool support. In other
+ words: You are on your own!</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Installation of eclipse requires a suitable <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> Development
+ Kit.</para>
+
+ <caution>
+ <para>Your<productname
+ xlink:href="http://www.oracle.com/technetwork/java/javase/jdk-7-readme-429198.html">JDK</productname>
+ selection may be affected by your system's hardware. On a 64 bit
+ system you may install either a 32 bit or a 64 bit <productname
+ xlink:href="http://www.oracle.com/technetwork/java/javase/jdk-7-readme-429198.html">JDK</productname>.
+ If you subsequently install eclipse you must select the
+ appropriate 32 or 64 Bit version matching your <productname
+ xlink:href="http://www.oracle.com/technetwork/java/javase/jdk-7-readme-429198.html">JDK</productname>
+ choice.</para>
+ </caution>
+
+ <para>Due to Oracle's (end-user unfriendly) licensing policy you may
+ have to install this component manually. For <productname
+ xlink:href="http://www.ubuntu.com">Ubuntu</productname> and
+ <productname xlink:href="http://www.debian.org">Debian</productname>
+ systems a standard (package manager compatible) procedure is being
+ described at <uri
+ xlink:href="http://www.webupd8.org/2012/01/install-oracle-java-jdk-7-in-ubuntu-via.html">http://www.webupd8.org/2012/01/install-oracle-java-jdk-7-in-ubuntu-via.html</uri>.
+ This boils down to (being executed as user root or preceded by
+ <command>sudo</command> <option>...</option>):</para>
+
+ <programlisting language="none">add-apt-repository ppa:webupd8team/java
+apt-get update
+apt-get install oracle-jdk7-installer</programlisting>
+
+ <para>During the installation process you will have to accept
+ Oracle's license terms. If you do so this information will be cached
+ and not be asked again for when updating via <command>aptitude
+ </command><option>update</option>;<command>aptitude</command>
+ <option>safe-upgrade</option>. After successful installation when
+ executing <command
+ xlink:href="http://www.oracle.com/us/technologies/java">java</command>
+ <option>-version</option> in a shell you should see something
+ similar to:</para>
+
+ <programlisting language="none">goik@goiki:~$ <emphasis role="bold">java -version</emphasis>
+java version "1.7.0_07"
+Java(TM) SE Runtime Environment (build 1.7.0_07-b10)
+Java HotSpot(TM) Server VM (build 23.3-b01, mixed mode)</programlisting>
+
+ <para>The Eclipse IDE comes <link
+ xlink:href="http://www.eclipse.org/downloads">with various
+ flavours</link> depending on which plugins are already being
+ shipped. For our purposes the <quote><productname>Eclipse
+ Classic</productname></quote> <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> edition is
+ sufficient. You may however want to install other flavours like
+ <quote><productname>Eclipse IDE for Java EE
+ Developers</productname></quote> if you require features beyond this
+ course's needs. Remember to download the correct 32 or 64 bit
+ version corresponding to your<productname
+ xlink:href="http://www.oracle.com/technetwork/java/javase/jdk-7-readme-429198.html">JDK</productname>.</para>
+
+ <para>Follow <uri
+ xlink:href="http://askubuntu.com/questions/26632/how-to-install-eclipse#answer-145018">http://askubuntu.com/questions/26632/how-to-install-eclipse#answer-145018</uri>
+ to install eclipse on your system.</para>
+ </section>
+
+ <section xml:id="oxygenxmlInstall">
+ <title><productname
+ xlink:href="http://oxygenxml.com">Oxygenxml</productname>
+ plugin</title>
+
+ <para>Go to <uri
+ xlink:href="http://www.oxygenxml.com/download_oxygenxml_developer.html?os=Eclipse">http://www.oxygenxml.com/download_oxygenxml_developer.html?os=Eclipse</uri>.
+ You may choose between the <quote>Plugin Update site</quote> and
+ <quote>Plugin zip distribution</quote> installation method. The
+ latter allows for better long term eclipse plugin management and is
+ being described at</para>
+
+ <para>There are two different ways to install Eclipse
+ plugins:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Use Eclipse's built in Update manager by <link
+ xlink:href="http://www.oxygenxml.com/download_oxygenxml_developer.html?os=Eclipse#eclipse_install_instructions">defining
+ a corresponding update site</link>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Unzip <filename>com.oxygenxml.developer_XYZ.zip</filename>
+ in a subfolder of <filename>.../eclipse/dropins</filename> and
+ restart eclipse (as root).</para>
+ </listitem>
+ </itemizedlist>
- <calloutlist>
- <callout arearefs="employeeDepartmentBusiness"
- xml:id="cascadeBusinessKey-1">
- <para>Defining a business key</para>
- </callout>
+ <para>See <xref linkend="oxygenLicenseKey"/> for obtaining a license
+ key. You may as well install the standalone version of the Oxygen
+ XML Editor.</para>
+ </section>
- <callout arearefs="employeeDepartmentCascade"
- xml:id="cascadeBusinessKey-2">
- <para>Referencing a business key</para>
- </callout>
- </calloutlist>
+ <section xml:id="erMaster">
+ <title>ERMaster</title>
- <para>If we update a <code>Department.name</code> attribute, all
- <code>Employee</code> datasets referencing this department have
- to be changed as well. Thus the intended change of a single
- attribute possibly causes a whole bunch of transitive updates
- adding to potential lock conflicts in a concurrent database
- application .</para>
+ <para>Visual editing of physical entity relationship diagrams. See
+ <link xlink:href="http://ermaster.sourceforge.net">installation
+ instructions</link> on top of an existing eclipse
+ installation.</para>
+ </section>
- <para>If being intended though we should at least add a CASCADE
- clause;</para>
+ <section xml:id="testngInstall">
+ <title><foreignphrase>TestNG</foreignphrase> plugin</title>
- <programlisting>CREATE TABLE Employee (
+ <para>Some exercises require the TestNG plugin to be installed in
+ the Eclipse IDE. You may proceed in a similar way as in <uri
+ linkend="oxygenxmlInstall">Oxygenxml</uri>. According to <uri
+ xlink:href="http://testng.org/doc/eclipse.html#eclipse-installation">http://testng.org/doc/eclipse.html#eclipse-installation</uri>
+ the Eclipse URL being needed is
+ <quote>http://beust.com/eclipse</quote>.</para>
+ </section>
+
+ <section xml:id="mysql">
+ <title><productname
+ xlink:href="http://www.mysql.com">Mysql</productname> Database
+ components</title>
+
+ <para>We start by installing the <productname
+ xlink:href="http://www.mysql.com">Mysql</productname> server:</para>
+
+ <programlisting language="none">root@goiki:~# aptitude install mysql-server
+The following NEW packages will be installed:
+ libdbd-mysql-perl{a} libdbi-perl{a} libnet-daemon-perl{a} libplrpc-perl{a}
+ mysql-client-5.5{a} mysql-server-5.5
+0 packages upgraded, 6 newly installed, 0 to remove and 0 not upgraded.
+Need to get 0 B/17.8 MB of archives. After unpacking 63.2 MB will be used.
+Do you want to continue? [Y/n/?]</programlisting>
+
+ <para>Hit <keycap>Y - return</keycap> to start. During the
+ installation you will be asked for the <productname
+ xlink:href="http://www.mysql.com">Mysql</productname> servers
+ <quote>root</quote> (Administrator) password:</para>
+
+ <programlisting language="none">Package configuration
+
+
+ ┌───────────────────────────┤ Configuring mysql-server-5.5 ├────────────────────────────â”
+ │ While not mandatory, it is highly recommended that you set a password for the MySQL │
+ │ administrative "root" user. │
+ │ │
+ │ If this field is left blank, the password will not be changed. │
+ │ │
+ │ New password for the MySQL "root" user: │
+ │ │
+ │ ********_____________________________________________________________________________ │
+ │ │
+ │ <Ok> │
+ │ │
+ └───────────────────────────────────────────────────────────────────────────────────────┘
+
+
+ </programlisting>
+
+ <para>This has to be entered twice. Keep a <emphasis
+ role="bold">permanent</emphasis> record of this entry. Alternatively
+ set a bookmark to <uri
+ xlink:href="https://help.ubuntu.com/community/MysqlPasswordReset">https://help.ubuntu.com/community/MysqlPasswordReset</uri>
+ for later reference *** and don't blame me! ***.</para>
+
+ <para>At this point we should be able to connect to our newly
+ installed Server. We create a database <quote>hdm</quote> to be used
+ for our exercises:</para>
+
+ <programlisting language="none">goik@goiki:~$ mysql -u root -p
+Enter password:
+Welcome to the MySQL monitor. Commands end with ; or \g.
+Your MySQL connection id is 42
+Server version: 5.5.24-0ubuntu0.12.04.1 (Ubuntu)
+
+Copyright (c) 2000, 2011, Oracle and/or its affiliates. All rights reserved.
+
+Oracle is a registered trademark of Oracle Corporation and/or its
+affiliates. Other names may be trademarks of their respective
+owners.
+
+Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
+
+mysql> <emphasis role="bold">create database hdm;</emphasis>
+Query OK, 1 row affected (0.00 sec)</programlisting>
+
+ <para>Following <uri
+ xlink:href="https://dev.mysql.com/doc/refman/5.5/en/adding-users.html">https://dev.mysql.com/doc/refman/5.5/en/adding-users.html</uri>
+ we add a new user and grant full access to the newly created
+ database:</para>
+
+ <programlisting language="none">goik@goiki:~$ mysql -u root -p
+Enter password:
+ ...
+mysql> CREATE USER 'hdmuser'@'localhost' IDENTIFIED BY 'XYZ';
+mysql> use hdm;
+mysql> GRANT ALL PRIVILEGES ON *.* TO 'hdmuser'@'localhost' WITH GRANT OPTION;
+mysql> FLUSH PRIVILEGES;</programlisting>
+
+ <para>The next step is optional. The <productname
+ xlink:href="http://www.ubuntu.com">Ubuntu</productname> <productname
+ xlink:href="http://www.mysql.com">Mysql</productname> server default
+ configuration allows connections only via
+ <varname>loopback</varname> interface i.e.
+ <varname>localhost</varname>. If you want your <productname
+ xlink:href="http://www.mysql.com">Mysql</productname> server to
+ listen to the external network interface comment out the
+ bind-address parameter in
+ <filename>/etc/mysql/my.cnf</filename>:</para>
+
+ <programlisting language="none"># Instead of skip-networking the default is now to listen only on
+# localhost which is more compatible and is not less secure.
+# <emphasis role="bold">bind-address = 127.0.0.1</emphasis></programlisting>
+
+ <para>Since we are dealing with <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> a <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ driver is needed to connect Applications to our <productname
+ xlink:href="http://www.mysql.com">Mysql</productname> server:</para>
+
+ <programlisting language="none">root@goiki:~# aptitude install libmysql-java</programlisting>
+
+ <para>This provides the file
+ /usr/share/java/mysql-connector-java-5.1.16.jar and two symbolic
+ links:</para>
+
+ <programlisting language="none">goik@goiki:~$ cd /usr/share/java
+goik@goiki:/usr/share/java$ ls -al mysql*
+-rw-r--r-- 1 ... 2011 <emphasis role="bold">mysql-connector-java-5.1.16.jar</emphasis>
+lrwxrwxrwx 1 ... 2011 <emphasis role="bold">mysql-connector-java.jar -> mysql-connector-java-5.1.16.jar</emphasis>
+lrwxrwxrwx 1 ... 2011 <emphasis role="bold">mysql.jar -> mysql-connector-java.jar</emphasis></programlisting>
+ </section>
+ </section>
+
+ <section xml:id="lectureNotes">
+ <title>Lecture related resources</title>
+
+ <para>The sources for lecture notes and exercises are available from
+ the <orgname xlink:href="http://www.mi.hdm-stuttgart.de">MIB</orgname>
+ <productname xlink:href="http://git-scm.com">git</productname>
+ repository:</para>
+
+ <para><uri
+ xlink:href="https://version.mi.hdm-stuttgart.de/git/GoikLectures">https://version.mi.hdm-stuttgart.de/git/GoikLectures</uri></para>
+
+ <para>Check-out is straightforward:</para>
+
+ <programlisting language="none">goik@goiki:~$ mkdir StructuredData;cd StructuredData
+
+goik@goiki:~/StructuredData$ git clone https://version.mi.hdm-stuttgart.de/git/GoikLectures .
+Cloning into '.'...
+remote: Counting objects: 694, done
...
- ,department CHAR(20) NOT NULL REFERENCES Department(name)
- <emphasis role="bold">ON UPDATE CASCADE</emphasis>
-...</programlisting>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
+Resolving deltas: 100% (296/296), done.</programlisting>
+
+ <para>After checkout an eclipse workspace holding the complete example
+ source code becomes visible:</para>
+
+ <programlisting language="none">goik@goiki:~/StructuredData$ cd ws/eclipse
+goik@goiki:~/StructuredData/ws/eclipse$ ls -al
+insgesamt 16
+drwxr-xr-x 3 goik fb1prof 4096 Nov 8 22:04 .
+drwxr-xr-x 4 goik fb1prof 4096 Nov 8 22:04 ..
+-rw-r--r-- 1 goik fb1prof 11 Nov 8 22:04 .gitignore
+<emphasis role="bold">drwxr-xr-x 6 goik fb1prof 4096 Nov 8 22:04 Jdbc</emphasis></programlisting>
+
+ <para>The subdirectory <filename>Jdbc</filename> can be imported as an
+ eclipse project via File --> import --> General --> Existing
+ Projects into workspace. This should enable each participant to browse
+ and execute the examples being provided in the lecture notes. It also
+ contains the a <productname
+ xlink:href="http://www.mysql.com">Mysql</productname> driver in
+ Jdbc/lib/mysql-connector-java-5.1.16.jar being required to set up a
+ <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ connection.</para>
+ </section>
+
+ <section xml:id="repeatRelational">
+ <title>Some notes on relational databases</title>
+
+ <qandaset defaultlabel="qanda" xml:id="airlineRelationalSchema">
+ <title>Airlines, airports and flights</title>
- <para>We now add projects <coref linkend="projectEntity"/> and employee
- affiliations to projects <coref linkend="projectAffiliation"/>:</para>
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>Implement a relational schema describing airlines,
+ flights, airports and their respective relationships:</para>
- <programlisting>CREATE TABLE Project ( <co xml:id="projectEntity"/>
- id BIGINT PRIMARY KEY
- ,number INTEGER NOT NULL UNIQUE
+ <itemizedlist>
+ <listitem>
+ <para>Airline:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>An informal unique name like e.g.
+ <quote>Lufthansa</quote>.</para>
+ </listitem>
+
+ <listitem>
+ <para>A unique <link
+ xlink:href="http://en.wikipedia.org/wiki/List_of_airline_codes">ICAO
+ abbreviation</link>.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>Destination</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Full name like <quote>Frankfurt am Main
+ International</quote></para>
+ </listitem>
+
+ <listitem>
+ <para>World airport code like
+ <quote>FRA</quote>.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>Flight</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>A unique flight number e.g. LH 4234</para>
+ </listitem>
+
+ <listitem>
+ <para>The <quote>owning</quote> airline.</para>
+ </listitem>
+
+ <listitem>
+ <para>originating airport</para>
+ </listitem>
+
+ <listitem>
+ <para>destination airport</para>
+ </listitem>
+
+ <listitem>
+ <para>Constraint: origin and destination must differ.
+ Hint: Mysql provides a syntactical means to implement
+ this constraint. It will however not be enforced at
+ runtime. Database vendors like Oracle, IBM/DB2 support
+ this type of runtime integrity constraint
+ enforcement.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+
+ <para>Provide surrogate keys for all entities.</para>
+ </question>
+
+ <answer>
+ <programlisting language="sql">DROP TABLE IF EXISTS Flight;
+DROP TABLE IF EXISTS Destination;
+DROP TABLE IF EXISTS Airline;
+
+
+CREATE Table Airline (
+ id INT NOT NULL PRIMARY KEY
,name CHAR(20) NOT NULL UNIQUE
- ,status SMALLINT NOT NULL
- ,CHECK (status IN (1,2,3,3)) -- planned, active, on hold, finished --
+ ,airlineCode CHAR(5)NOT NULL UNIQUE
);
-CREATE TABLE EmployeeProject ( <co xml:id="projectAffiliation"/>
- employee BIGINT NOT NULL REFERENCES Employee
- ,project BIGINT NOT NULL REFERENCES Project
- ,PRIMARY KEY(employee, project)
- ,weeklyHours INTEGER NOT NULL
-)</programlisting>
+CREATE TABLE Destination (
+ id INT NOT NULL PRIMARY KEY
+ ,fullName CHAR(20) NOT NULL
+ ,airportCode CHAR(20) NOT NULL UNIQUE
+);
- <qandaset>
- <qandadiv>
- <qandaentry>
- <question>
- <para>The property <code>status</code> has been implemented as
- type <code>SMALLINT</code>. Consider the following
- alternative:</para>
-
- <programlisting>CREATE TABLE Project (
- id BIGINT PRIMARY KEY
- ,number INTEGER NOT NULL UNIQUE
- ,name CHAR(20) NOT NULL UNIQUE
- ,<emphasis role="bold">status CHAR(10) NOT NULL</emphasis>
- ,CHECK (<emphasis role="bold">status IN ('planned', 'active', 'onHold','finished')</emphasis>)
+
+CREATE TABLE Flight (
+ id INT NOT NULL PRIMARY KEY
+ ,flightNumber CHAR(10) NOT NULL UNIQUE
+ ,airline INT NOT NULL REFERENCES Airline
+ ,origin int NOT NULL REFERENCES Destination
+ ,destination int NOT NULL REFERENCES Destination
+ ,CHECK(NOT(origin = destination))
);</programlisting>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
- <para>What are the pros and cons?</para>
- </question>
-
- <answer>
- <glosslist>
- <glossentry>
- <glossterm>Advantage of CHAR(10) implementation</glossterm>
-
- <glossdef>
- <para>Data residing in a database can be easily retrieved
- by <code>SELECT</code> statements without having
- difficulties interpreting both <code>WHERE </code>clauses
- and result sets:</para>
-
- <programlisting>SELECT * FROM Project
-WHERE status = 'active'</programlisting>
-
- <para>On contrary using the <code>SMALLINT</code>
- implementation requires: </para>
-
- <programlisting>SELECT * FROM Project
-WHERE status = 2 -- any clue about status definitions when lacking documentation? --</programlisting>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>Advantage of <code>SMALLINT</code>
- implementation</glossterm>
-
- <glossdef>
- <para>When building applications our <code>SMALLINT</code>
- status field will best be mapped as an user defined
- <code>enum</code>:</para>
-
- <programlisting>public enum ProjectStatus {
- planned
- ,active
- ,onHold
- ,finished;
-}</programlisting>
-
- <para>This allows for easily understandable switch
- statements:</para>
-
- <programlisting>ProjectStatus status;
- ...
-switch (status) {
- case planned:
- ...
- break;
-
- case active:
- ...
- break;
- default:
- ...
-}
-...</programlisting>
+ <section xml:id="toolingConfigJdbc">
+ <title>Tooling: Configuring and using the <link
+ xlink:href="http://www.eclipse.org/datatools">Eclipse database
+ development</link> plugin</title>
- <para>In fact starting from Java 1.7 the above
- <code>switch</code> statement will work for
- <classname>String</classname> objects as well:</para>
-
- <programlisting>String status;
- ...
-switch (status) {
- case "planned":
- ...
- break;
-
- case "active":
- ...
- break;
- default:
- ...
-}</programlisting>
+ <para>For some basic SQL communications the Eclipse environment offers
+ a standard plugin (Database development). Establishing connections to
+ a specific database server generally requires prior installation of a
+ <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ driver on the client side as being shown in the following
+ video:</para>
- <para>But despite being syntactic sugar the above code
- actually implements an <code>if ... else if ...
- else</code> block relying on
- <methodname>String.equals()</methodname> rather than a
- true integer based jump table:</para>
+ <figure xml:id="figureConfigJdbcDriver">
+ <title>Adding a <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ Driver for <productname
+ xlink:href="http://www.mysql.com">Mysql</productname> to the
+ database plugin.</title>
- <programlisting>String status;
- ...
- if (status.equals("planned")) {
- ...
- } else if (status.equals("active")) {
- } else {
- ...
- }
-}</programlisting>
- </glossdef>
- </glossentry>
- </glosslist>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- </section>
-
- <section>
- <title>A media store</title>
-
- <para>The media store example has been chosen as a second main example
- in addition to the company database. It will be developed by you in a
- step by step manner thereby exploring lecture related features and
- technological standards.</para>
-
- <para>We have outlined a schema forming a building block for a company's
- internal organization. You are now being expected to develop a data
- model suitable to build a media store. After talking to potential
- customers the following entities have been identified to be
- required:</para>
-
- <glosslist>
- <glossentry>
- <glossterm>Album</glossterm>
-
- <glossdef>
- <para>The basic building block to be sold. An album is being
- composed of tracks. Each Album does have a name not necessarily
- unique across your media store. Albums may be related to
- performing artists.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>Track</glossterm>
-
- <glossdef>
- <para>Each song belongs to exactly one Album. The smallest media
- item having the following properties:</para>
+ <mediaobject>
+ <videoobject>
+ <videodata fileref="Ref/Video/jdbcDriverConfig.mp4"/>
+ </videoobject>
+ </mediaobject>
+ </figure>
- <glosslist>
- <glossentry>
- <glossterm>name</glossterm>
+ <para>During the exercises the eclipse database development
+ perspective may be used to browse and structure SQL tables and data.
+ The following video demonstrates the configuration of a <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ connection to a local (<varname>localhost</varname> network interface)
+ database server. With respect to the introduction given in <xref
+ linkend="mysql"/> we assume the existence of a database
+ <code>hdm</code> and a corresponding account <quote>hdmuser</quote>
+ and password <quote><code>XYZ</code></quote> (<emphasis
+ role="bold">capital letters!</emphasis>) on our database
+ server.</para>
- <glossdef>
- <para>A song's name is unique with respect to its
- <quote>owning</quote> album.</para>
- </glossdef>
- </glossentry>
+ <figure xml:id="figureConfigJdbcConnection">
+ <title>Configuring a <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ connection to a (local) <productname
+ xlink:href="http://www.mysql.com">Mysql</productname> database
+ server.</title>
- <glossentry>
- <glossterm>format</glossterm>
+ <mediaobject>
+ <videoobject>
+ <videodata fileref="Ref/Video/jdbcConnection.mp4"/>
+ </videoobject>
+ </mediaobject>
+ </figure>
- <glossdef>
- <para>One of <code>mp3</code>, <code>flac</code> or
- <code>mp4</code>.</para>
- </glossdef>
- </glossentry>
- </glosslist>
- </glossdef>
- </glossentry>
+ <para>We are now ready to communicate with our database server. The
+ last video in this section shows some basic SQL tasks:</para>
+
+ <figure xml:id="figureEclipseBasicSql">
+ <title>Executing SQL statements, browsing schema and retrieving
+ data</title>
+
+ <mediaobject>
+ <videoobject>
+ <videodata fileref="Ref/Video/eclipseBasicSql.mp4"/>
+ </videoobject>
+ </mediaobject>
+ </figure>
+ </section>
+ </chapter>
+
+ <chapter xml:id="xmlIntro">
+ <title>Introduction to XML</title>
+
+ <section xml:id="xmlBasic">
+ <title>The XML industry standard</title>
+
+ <para>A short question might be: <quote>What is XML?</quote> An answer
+ might be: The acronym XML stands for
+ <quote>E<emphasis>x</emphasis>tensible <emphasis>M</emphasis>arkup
+ <emphasis>L</emphasis><foreignphrase>anguage</foreignphrase></quote>
+ and is an industry standard being published by the W3C standardization
+ organization. Like other industry software standards talking about XML
+ leads to talk about XML based software: Applications and frameworks
+ supplying added values to software implementors and enhancing data
+ exchange between applications.</para>
+
+ <para>Many readers are already familiar with XML without explicitly
+ referring to the standard itself: The world wide web's
+ <foreignphrase>lingua franca</foreignphrase> HTML has been ported to
+ an XML dialect forming the <link
+ xlink:href="http://www.w3.org/MarkUp">XHTML</link> Standard. The idea
+ behind this standard is to distinguish between an abstract markup
+ language and rendered results being generated from so called document
+ instances by a browser:</para>
+
+ <figure xml:id="renderXhtmlMarkup">
+ <title>Rendering XHTML markup</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/xhtml.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Xhtml is actually a good example to illustrate the tree like,
+ hierarchical structure of XML documents:</para>
+
+ <figure xml:id="xhtmlTree">
+ <title>Xhtml tree structure</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/xhtmlexample.fig" scale="65"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>We may extend this example by representing a mathematical
+ formula via a standard called <link
+ xlink:href="http://www.w3.org/Math">Mathml</link>:</para>
+
+ <figure xml:id="mathmlExample">
+ <title>A formula in <link
+ xlink:href="http://www.w3.org/Math">MathML</link>
+ representation.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/sqrtrender.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Again we observe a similar situation: A database like
+ <emphasis>representation</emphasis> of a formula on the left and a
+ <emphasis>rendered</emphasis> version on the right. Regarding XML we
+ have:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The <link xlink:href="http://www.w3.org/Math">MathML</link>
+ standard intended to describe mathematical formulas. The standard
+ defines a set of <emphasis>tags</emphasis> like e.g. <tag
+ class="starttag">math:msqrt</tag> with well-defined semantics
+ regarding permitted attribute values and nesting rules.</para>
+ </listitem>
+
+ <listitem>
+ <para>Informal descriptions of formatting expectations.</para>
+ </listitem>
+
+ <listitem>
+ <para>Software transforming an XML formula representation into
+ visible or printable output. In other words: A rendering
+ engine.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>XML documents may also be regarded as a persistence mechanism to
+ represent and store data. Similarities to Relational Database Systems
+ exist. A RDBMS
+ (<emphasis>R</emphasis><foreignphrase>elational</foreignphrase>
+ <emphasis>D</emphasis><foreignphrase>atabase</foreignphrase>
+ <emphasis>M</emphasis><foreignphrase>anagement</foreignphrase>
+ <emphasis>S</emphasis><foreignphrase>ystem</foreignphrase>) is
+ typically capable to hold Tera bytes of data being organized in
+ tables. The arrangement of data may be subject to various constraints
+ like candidate- or foreign key rules. With respect to both end users
+ and software developers a RDBMS itself is a building block in a
+ complete solution. We need an application on top of it acting as a
+ user interface to the data being contained.</para>
+
+ <para>In contrast to a RDBMS XML allows data to be organized
+ hierarchically. The <link
+ xlink:href="http://www.w3.org/Math">MathML</link> representation given
+ in <xref linkend="mathmlExample"/> may be graphically
+ visualized:</para>
+
+ <figure xml:id="mathmltree">
+ <title>A tree graph representation of the <link
+ xlink:href="http://www.w3.org/Math">MathML</link> example given
+ before.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/sqrtree.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>CAD applications may user XML documents as a representation of
+ graphical primitives:</para>
+
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/attributes.fig" scale="65"/>
+ </imageobject>
+ </mediaobject>
+ </informalfigure>
+
+ <para>Of course RDBMS also allow the representation of tree like
+ structures or arbitrary graphs. But these have to be modelled by using
+ foreign key constraints since relational tables themselves have a
+ <quote>flat</quote> structure. Some RDBMS vendors provide extensions
+ to the SQL standard which allow <quote>native</quote> representations
+ of <link linkend="gloss_XML"><abbrev>XML</abbrev></link>
+ documents.</para>
+ </section>
+
+ <section xml:id="xmlHtml">
+ <title>Well formed XML documents</title>
+
+ <para>The general structure of an <link
+ linkend="gloss_XML"><abbrev>XML</abbrev></link> document is as
+ follows:</para>
+
+ <figure xml:id="xmlbase">
+ <title><link linkend="gloss_XML"><abbrev>XML</abbrev></link> basic
+ structure</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/xmlbase.fig" scale="65"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>We explore a simple XML document representing messages like
+ E-mails:</para>
+
+ <figure xml:id="memoWellFormed">
+ <title>The representation of a short message.</title>
+
+ <programlisting language="none"><?xml<co
+ xml:id="first_xml_code_magic"/> version="1.0"<co
+ xml:id="first_xml_code_version"/> encoding="UTF-8"<co
+ xml:id="first_xml_code_encoding"/>?>
+<memo><co xml:id="first_xml_code_topelement"/>
+ <from>M. Goik</from><co xml:id="first_xml_code_from"/>
+ <to>B. King</to>
+ <to>A. June</to>
+ <subject>Best whishes</subject>
+ <content>Hi all, congratulations to your splendid party</content>
+</memo></programlisting>
+ </figure>
+
+ <calloutlist>
+ <callout arearefs="first_xml_code_magic">
+ <para>The very first characters <code><?xml</code> may be
+ regarded as a <link
+ xlink:href="http://en.wikipedia.org/wiki/Magic_number_(programming)">magic
+ number string</link> being used as a format indicator which allows
+ to distinguish between different file types i.e. GIF, JPEG, HTML
+ and so on.</para>
+ </callout>
+
+ <callout arearefs="first_xml_code_version">
+ <para>The <code>version="1.0"</code> attribute tells us that all
+ subsequent lines will conform to the <link
+ xlink:href="http://www.w3.org/TR/xml">XML</link> standard of
+ version 1.0. This way a document can express its conformance to
+ the version 1.0 standard even if in the future this standard
+ evolves to a higher version e.g.
+ <code>version="2.1"</code>.</para>
+ </callout>
+
+ <callout arearefs="first_xml_code_encoding">
+ <para>The attribute <code>encoding="UTF-8"</code> tells us that
+ all text in the current document uses <link
+ xlink:href="http://unicode.org">Unicode</link> encoding. <link
+ xlink:href="http://unicode.org">Unicode</link> is a widely
+ accepted industry standard for font encoding. Thus European,
+ Cyrillic and most Asian font codes are allowed to be used in
+ documents <emphasis>simultaneously</emphasis>. Other encodings may
+ limit the set of allowed characters, e.g.
+ <code>encoding="ISO-8859-1"</code> will only allow characters
+ belonging to western European languages. However a system also
+ needs to have the corresponding fonts (e.g. TrueType) being
+ installed in order to render the document appropriately. A
+ document containing Chinese characters is of no use if the
+ underlying rendering system lacks e.g. a set of Chinese True Type
+ fonts.</para>
+ </callout>
+
+ <callout arearefs="first_xml_code_topelement">
+ <para>An XML document has exactly one top level
+ <emphasis>node</emphasis>. In contrast to the HTML standard these
+ nodes are commonly called elements rather than tags. In this
+ example the top level (root) element is <tag
+ class="starttag">memo</tag>.</para>
+ </callout>
+
+ <callout arearefs="first_xml_code_from">
+ <para>Each XML element like <tag class="starttag">from</tag> has a
+ corresponding counterpart <tag class="endtag">from</tag>. In terms
+ of XML we say each element being opened has to be closed. In
+ conjunction with the precedent point this is equivalent to the
+ fact that each XML document represents a tree structure as being
+ shown in the <link linkend="mathmltree">tree graph</link>
+ representation.</para>
+ </callout>
+ </calloutlist>
+
+ <para>As with the introductory formula example this representation
+ itself is of limited usefulness: In an office environment we need a
+ rendered version being given either as print or as some online format
+ like E-Mail or HTML.</para>
+
+ <para>From a software developer's point of view we may use a piece of
+ software called a <emphasis>parser</emphasis> to test the document's
+ standard conformance. At the MI department we may simply invoke
+ <userinput><command>xmlparse</command> message.xml</userinput> to
+ start a check:</para>
+
+ <programlisting language="none"><errortext>goik>xmlparse wellformed.xml
+Parsing was successful</errortext></programlisting>
+
+ <para>Various XML related plugins are supplied for the <productname
+ xlink:href="http://eclipse.org">eclipse platform</productname> like
+ the <productname xlink:href="http://oxygenxml.com">Oxygen
+ software</productname> supplying <quote>life</quote> conformance
+ checking while editing XML documents. Now we test our assumptions by
+ violating some of the rules stated before. We deliberately omit the
+ closing element <tag class="endtag">from</tag>:</para>
+
+ <figure xml:id="omitFrom">
+ <title>An invalid XML document due to the omission of <tag
+ class="endtag">from</tag>.</title>
+
+ <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
+<memo>
+ <from>M. Goik <co xml:id="omitFromMissingElement"/>
+ <to>B. King</to>
+ <to>A. June</to>
+ <subject>Best whishes</subject>
+ <content>Hi all, congratulations to your splendid party</content>
+</memo></programlisting>
+
+ <calloutlist>
+ <callout arearefs="omitFromMissingElement">
+ <para>The opening element <tag class="starttag">from</tag> is
+ not terminated by <tag class="endtag">from</tag>.</para>
+ </callout>
+ </calloutlist>
+ </figure>
+
+ <para>Consequently the parser's output reads:</para>
+
+ <programlisting language="none"><errortext>goik>xmlparse omitfrom.xml
+file:///ma/goik/workspace/Vorlesungen/Input/Memo/omitfrom.xml:8:3:
+fatal error org.xml.sax.SAXParseException: The element type "from"
+must be terminated by the matching end-tag "</from>". parsing error</errortext></programlisting>
+
+ <para>Experienced HTML authors may be confused: In fact HTML is not an
+ XML standard. Instead HTML belongs to the set of SGML applications.
+ SGML is a much older standard namely the <emphasis>Standard
+ Generalized Markup Language</emphasis>.</para>
+
+ <para>Even if every XML element has a closing counterpart the
+ resulting XML may be invalid:</para>
+
+ <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
+<memo>
+ <from>M. Goik<to>B. King</from></to>
+ <to>A. June</to>
+ <subject>Best whishes</subject>
+ <content>Hi all, congratulations to your splendid party</content>
+</memo></programlisting>
+
+ <para>The parser echoes:</para>
+
+ <programlisting language="none"><computeroutput>file:///ma/goik/workspace/Vorlesungen/Input/Memo/nonest.xml:3:29:
+fatal error org.xml.sax.SAXParseException: The element type "to" must be
+terminated by the matching end-tag "</to>". parsing error</computeroutput></programlisting>
+
+ <para>This type of error is caused by so called improper nesting of
+ elements: The element <tag class="starttag">from</tag>is closed before
+ the <quote>inner</quote> element <tag class="starttag">to</tag> has
+ been closed. Actually this violates the expressibility of XML
+ documents as a tree like structure. The situation may be resolved by
+ choosing:</para>
+
+ <programlisting language="none">...<from>M. Goik<to>B. King</to></from>...</programlisting>
+
+ <para>We provide two examples illustrating proper and improper nesting
+ of XML documents:</para>
+
+ <figure xml:id="fig_nestingProper">
+ <title>Proper nesting of XML elements</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/propernest.fig" scale="65"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The following example violates proper nesting constraint and
+ thus does not provide an XML document:</para>
+
+ <figure xml:id="fig_improperNest">
+ <title>Improperly nested elements</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/impropernest.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
- <glossentry>
- <glossterm>Artist</glossterm>
+ <!-- goik:later
+ <para>An animation showing the usage of the Oxygen plug in for the
+ examples given above can be found <uri
+ xlink:href="src/viewlet/wellformed/wellformed_viewlet_swf.html">here</uri>.</para>
+-->
- <glossdef>
- <para>An artist may participate in arbitrary albums. It shall be
- possible to annotate an artist's <quote>lead</quote> role with
- respect to an album he/she is being affiliated with.</para>
+ <para>XML elements may have so called attributes like <tag
+ class="attribute">date</tag> in the following example:</para>
+
+ <figure xml:id="memoWellAttrib">
+ <title>An XML document with attributes.</title>
+
+ <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
+<memo date="10.02.2006" priority="high">
+ <from>M. Goik</from>
+ <to>B. King</to>
+ <to>A. June</to>
+ <subject>Best whishes</subject>
+ <content>Hi all, congratulations to your splendid party</content>
+</memo></programlisting>
+ </figure>
+
+ <para>The conformance of a XML document with the following rules may
+ be verified by invoking a parser:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Within the <emphasis>scope</emphasis> of a given element an
+ attribute name must be unique. In the example above one may not
+ define a second attribute <varname>date="..."</varname> within the
+ same element <memo ... >. This reflects the usual
+ programming language semantics of attributes: In a <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> class an
+ attribute is represented by an unique identifier and thus cannot
+ appear twice.</para>
+ </listitem>
+
+ <listitem>
+ <para>An attribute value must be enclosed either in single (') or
+ double (") quotes. This is different from the HTML standard which
+ allows attribute values without quotes provided the given
+ attribute value does not give rise to ambiguities. For example
+ <tag class="starttag">td align=left</tag> is allowed since the
+ attribute value <tag class="attvalue">left</tag> does not contain
+ any spaces thus allowing a parser to recognize the end of the
+ value's definition.</para>
+ </listitem>
+ </itemizedlist>
+
+ <qandaset defaultlabel="qanda" xml:id="example_memoAttribTree">
+ <title>A graphical representation of a memo.</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>Draw a graphical representation similar as in <xref
+ linkend="mathmltree"/> of the memo document being given in
+ <xref linkend="memoWellAttrib"/>.</para>
+ </question>
+
+ <answer>
+ <para>The <link linkend="memoWellAttrib">memo
+ document's</link> structure may be visualized as:</para>
+
+ <informalfigure xml:id="memotreeFigure">
+ <para>A graphical representation of <xref
+ linkend="memoWellAttrib"/>:</para>
+
+ <informalfigure xml:id="memotreeFigureFalse">
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/memotree.fig"/>
+ </imageobject>
+ </mediaobject>
+ </informalfigure>
+
+ <para>The sequence of <emphasis>element</emphasis> child
+ nodes is important in XML and has to be preserved. Only the
+ order of the two attributes <tag
+ class="attribute">date</tag> and <tag
+ class="attribute">priority</tag> is undefined: They actually
+ belong to the <tag class="starttag">memo</tag> node serving
+ as a dictionary with the attribute names being the keys and
+ the attribute values being the values of the
+ dictionary.</para>
+ </informalfigure>
+ </answer>
+ </qandaentry>
+
+ <qandaentry xml:id="example_attribInQuotes">
+ <question>
+ <label>Attributes and quotes</label>
+
+ <para>As stated before XML attributes have to be enclosed in
+ single or double quotes. Construct an XML document with mixed
+ quotes like <code><date day="monday'></code>. How does
+ the parser react? Find the corresponding syntax definition of
+ legal attribute values in the <link
+ xlink:href="http://www.w3.org/TR/xml">XML standard W3C
+ Recommendation</link>.</para>
+ </question>
+
+ <answer>
+ <para>The parser flags a mixture of single and double quotes
+ for a given attribute as an error. The XML standard <link
+ xlink:href="http://www.w3.org/TR/xml#NT-AttValue">defines</link>
+ the syntax of attribute values: An attribute value has to be
+ enclosed <emphasis>either</emphasis> in two single
+ <emphasis>or</emphasis> in two double quotes as being defined
+ in <uri
+ xlink:href="http://www.w3.org/TR/xml/#NT-AttValue">http://www.w3.org/TR/xml/#NT-AttValue</uri>.</para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry xml:id="quoteInAttributValue">
+ <question>
+ <label>Quotes as part of an attributes value?</label>
+
+ <para>Single and double quote are used to delimit an attribute
+ value. May quotes appear themselves as part of an at tribute's
+ value, e.g. like in a person's name <code>Gary "King"
+ Mandelson</code>?</para>
+ </question>
+
+ <answer>
+ <para>Attribute values may contain double quotes if the
+ attributes value is enclosed in single quotes and vice versa.
+ As a limitation the value of an an attribute may not contain
+ single quotes and double quotes at the same time:</para>
+
+ <informalfigure xml:id="exampleSingleDoubleQuotes">
+ <para>Quotes as part of attribute values.</para>
+
+ <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
+<test>
+ <person name='Gary "King" Mandelson'/> <!-- o.k. -->
+ <person name="Gary 'King' Mandelson"/> <!-- o.k. -->
+ <person name="Gary 'King 'S.' "Mandelson"'/> <!-- oops! -->
+</test></programlisting>
+ </informalfigure>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+
+ <para>Some constraints being imposed on XML documents by the standard
+ defined so far may be summarized as:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>A XML documents requires to have exactly one top level
+ element.</para>
+ </listitem>
+
+ <listitem>
+ <para>Elements have to be properly nested. An element must not be
+ closed if an <quote>inner</quote> Element is still open.</para>
+ </listitem>
+
+ <listitem>
+ <para>Attribute names within a given Element must be
+ unique.</para>
+ </listitem>
+
+ <listitem>
+ <para>Attribute values <emphasis>must</emphasis> be quoted
+ correctly.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The very last rule shows one of several differences to the HTML
+ Standard: In HTML a lot of elements don't have to be closed. For
+ example paragraphs (<tag class="starttag">p</tag>) or images (<tag
+ class="starttag">img src='foo.gif'</tag>) don't have to be closed
+ explicitly. This is due to the fact that HTML used to be defined in
+ accordance with the older <emphasis><emphasis
+ role="bold">S</emphasis>tandard <emphasis
+ role="bold">G</emphasis>eneralized <emphasis
+ role="bold">M</emphasis>arkup <emphasis
+ role="bold">L</emphasis>anguage</emphasis> (SGML) Standard.</para>
+
+ <para>These constraints are part of the definition of a <link
+ xlink:href="http://www.w3.org/TR/xml#sec-well-formed">well formed
+ document</link>. The specification imposes additional constraints for
+ a document to be well-formed.</para>
+ </section>
+ </chapter>
+
+ <chapter xml:id="dtd">
+ <title>Beyond well- formedness</title>
+
+ <section xml:id="motivationDdt">
+ <title>Motivation</title>
+
+ <para>So far we are able to create XML documents containing
+ hierarchically structured data. We may nest elements and thus create
+ tree structures of arbitrary depth. The only restrictions being
+ imposed by the XML standard are the constraints of well - formedness.
+ For many purposes in software development this is not
+ sufficient.</para>
+
+ <para>A company named <productname>Softmail</productname> might
+ implement an email system which uses <link
+ linkend="memoWellAttrib">memo</link> document files as low level data
+ representation serving as a persistence layer. Now a second company
+ named <productname>Hardmail</productname> wants to integrate mails
+ generated by <productname>Softmail</productname>'s system into its own
+ business product. The <productname>Hardmail</productname> software
+ developers might <emphasis>infer</emphasis> the logical structure of
+ <productname>Softmail</productname>'s email representation but the
+ following problems arise:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The logical structure will in practice become more complex:
+ E-mails may contain attachments leading to multi part messages.
+ Additional header information is required for standard Internet
+ mail compliance. This adds additional complexity to the XML
+ structure being mandatory for data representation. Relying only on
+ well-formedness the specification of an internal E-mail format can
+ only be achieved <emphasis>informally</emphasis>. Thus a rule like
+ <quote>Each E-mail must have a subject</quote> may be written down
+ in the specification. A software developer will code these rules
+ but probably make mistakes as the set of rules grows.</para>
+
+ <para>In contrast a RDBMS based solution offers to solve such
+ problems in a declarative manner: A developer may use a <code>NOT
+ NULL</code> constraint on a subject attribute of type
+ <code>VARCHAR</code> thus inhibiting empty subjects.</para>
+ </listitem>
+
+ <listitem>
+ <para>As <productname>Softmail</productname>'s product evolves its
+ internal E-mail XML format is subject to change due to functional
+ extensions and possibly bug fixes both giving rise to
+ interoperability problems.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Generally speaking well formed XML documents lack grammar
+ constraints as being available for programming languages. In case of
+ RDBMS developers can impose primary-, foreign and <code>CHECK</code>
+ constraints in a <emphasis>declarative</emphasis> manner rather than
+ hard coding them into their applications (A solution bad programmers
+ are in favour of though...). Various XML standards exist for
+ declarative constraint definitions namely:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>DTDs</para>
+ </listitem>
+
+ <listitem>
+ <para><link xlink:href="http://www.w3.org/XML/Schema">XML
+ Schema</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link
+ xlink:href="http://www.relaxng.org">RelaxNG</link></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section xml:id="dtdBasic">
+ <title>XML Schema</title>
+
+ <section xml:id="dtdFirstExample">
+ <title>Structural descriptions for documents</title>
+
+ <para>As an example we choose documents of type
+ <emphasis>memo</emphasis> as a starting point. Documents like the
+ example from <xref linkend="memoWellAttrib"/> may be
+ <emphasis>informally</emphasis> described to be a sequence of the
+ following mandatory items:</para>
+
+ <figure xml:id="figure_memo_informalconstraints">
+ <title>Informal constraints on <tag class="element">memo</tag>
+ document instances</title>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>Exactly one</emphasis> sender.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>One or more</emphasis> recipients.</para>
+ </listitem>
+
+ <listitem>
+ <para>Subject</para>
+ </listitem>
+
+ <listitem>
+ <para>Content</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>In addition we have:</para>
<itemizedlist>
<listitem>
- <para>name, surname</para>
+ <para>A date string <emphasis>must</emphasis> be
+ supplied</para>
</listitem>
<listitem>
- <para>sex</para>
+ <para>A priority <emphasis>may</emphasis> be supplied with
+ allowed values to be chosen from the set of values <tag
+ class="attvalue">low</tag>, <tag class="attvalue">medium</tag>
+ or <tag class="attvalue">high</tag>.</para>
</listitem>
</itemizedlist>
- </glossdef>
- </glossentry>
- </glosslist>
- </section>
- </chapter>
+ </figure>
+
+ <para>All these fields contain ordinary text to be filled in by a
+ user and shall appear exactly in the defined order. For simplicity
+ we do not care about email address syntax rules being described in
+ <link xlink:href="http://www.w3.org/Protocols/rfc822">RFC based
+ address schemes</link>. We will see how the
+ <emphasis>constraints</emphasis> mentioned above can be modelled in
+ XML by an extension to the concept of well formed documents.</para>
+ </section>
+
+ <section xml:id="section_memo_machinereadable">
+ <title>A machine readable description</title>
+
+ <para>We now introduce an example of an XML schema. It allows for
+ the specification of additional constraints to both element nodes
+ and their attributes. Our set of <link
+ linkend="figure_memo_informalconstraints" revision="">informal
+ constraints</link> on memo documents may be expressed as:</para>
+
+ <figure xml:id="figure_memo_dtd">
+ <title>A schema to describe memo documents.</title>
+
+ <programlisting language="none"><xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+ xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning" elementFormDefault="qualified"
+ vc:minVersion="1.0" vc:maxVersion="1.1">
+
+ <xs:element name="memo">
+ <xs:complexType>
+ <xs:sequence> <co xml:id="memodtd_memodef"/>
+ <xs:element name="from" type="xs:string"/> <co
+ xml:id="memodtd_elem_from"/>
+ <xs:element name="to" minOccurs="1" maxOccurs="unbounded" type="xs:string"/>
+ <xs:element name="subject" type="xs:string"/>
+ <xs:element name="content" type="xs:string"/>
+ </xs:sequence>
+ <xs:attribute name="date" type="xs:date" use="required"/> <co
+ xml:id="memodtd_memo_attribs"/>
+ <xs:attribute name="priority" type="Priority" use="optional"/>
+ </xs:complexType>
+
+ </xs:element>
+
+ <xs:simpleType name="Priority">
+ <xs:restriction base="xs:string">
+ <xs:enumeration value="low"/>
+ <xs:enumeration value="medium"/>
+ <xs:enumeration value="high"/>
+ </xs:restriction>
+ </xs:simpleType>
+
+</xs:schema></programlisting>
+
+ <calloutlist>
+ <callout arearefs="memodtd_memodef">
+ <para>A <tag class="element">memo</tag> consists of a sender,
+ at least one recipient, a subject and content.</para>
+ </callout>
+
+ <callout arearefs="memodtd_memo_attribs">
+ <para>A <tag class="element">memo</tag> has got one required
+ attribute <varname>date</varname> and an optional attribute
+ <varname>priority</varname> being restricted to the three
+ allowed values <tag class="attvalue">low</tag>, <tag
+ class="attvalue">medium</tag> and <tag
+ class="attvalue">high</tag> being defined by a separate <tag
+ class="starttag">xs:simpleType</tag> directive.</para>
+ </callout>
+
+ <callout arearefs="memodtd_elem_from">
+ <para>A <tag class="starttag">from</tag> element consists of
+ ordinary text. This disallows XML markup. For example
+ <code><from>Smith & partner</from></code> is
+ disallowed since XML uses the ampersand (&) to denote the
+ beginning of an entity like <tag class="genentity">auml</tag>
+ for the German a-umlaut (ä). The correct form is
+ <code><from>Smith &amp; partner</from></code>
+ using the predefined entity <tag class="genentity">amp</tag>
+ as an escape sequence for the ampersand.</para>
+
+ <para><code>type="xs:string"</code> is a built in XML Schema
+ type representing a restricted version of ordinary strings.
+ Without digging into details a <code>xs:string</code> string
+ must not contain any markup code like e.g. <tag
+ class="starttag">msqrt</tag>. This ensures that a string does
+ not interfere with the document's XML markup.</para>
+ </callout>
+ </calloutlist>
+ </figure>
+
+ <para>We notice our schema's syntax itself is an XML
+ document.</para>
+
+ <para>From the viewpoint of software modeling an XML Schema instance
+ is a <emphasis>schema</emphasis> describing the syntax of a class of
+ XML document instances adhering to it. In the context of XML
+ technologies <link xlink:href="http://www.w3.org/XML/Schema">XML
+ Schema</link> is one of several language alternatives which allow
+ for XML document structure descriptions.</para>
+
+ <para>Readers being familiar with <abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Backus-Naur_form">BNF</abbrev>
+ or <abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Extended_Backus_Naur_form">EBNF</abbrev>
+ will be able to understand the grammatical rules being expressed
+ here.</para>
+
+ <productionset>
+ <title>A message of type <tag class="starttag">memo</tag></title>
+
+ <production xml:id="memo.ebnf.memo">
+ <lhs>Memo Message</lhs>
+
+ <rhs>'<memo>' <nonterminal
+ def="#memo.ebnf.sender">Sender</nonterminal> [<nonterminal
+ def="#memo.ebnf.recipient">Recipient</nonterminal>]+
+ <nonterminal def="#memo.ebnf.subject">Subject</nonterminal>
+ <nonterminal def="#memo.ebnf.content">Content</nonterminal>
+ '</memo>'</rhs>
+ </production>
+
+ <production xml:id="memo.ebnf.sender">
+ <lhs>Sender</lhs>
+
+ <rhs>'<from>' <nonterminal def="#memo.ebnf.text"> Text
+ </nonterminal> '</from>'</rhs>
+ </production>
+
+ <production xml:id="memo.ebnf.recipient">
+ <lhs>Recipient</lhs>
+
+ <rhs>'<to>' <nonterminal def="#memo.ebnf.text"> Text
+ </nonterminal> '</to>'</rhs>
+ </production>
+
+ <production xml:id="memo.ebnf.subject">
+ <lhs>Subject</lhs>
+
+ <rhs>'<subject>' <nonterminal def="#memo.ebnf.text"> Text
+ </nonterminal> '</subject>'</rhs>
+ </production>
+
+ <production xml:id="memo.ebnf.content">
+ <lhs>Content</lhs>
+
+ <rhs>'<content>' <nonterminal def="#memo.ebnf.text"> Text
+ </nonterminal> '</content>'</rhs>
+ </production>
+
+ <production xml:id="memo.ebnf.text">
+ <lhs>Text</lhs>
+
+ <rhs>[a-zA-Z0-9]* <lineannotation>In real documents this is too
+ restrictive!</lineannotation></rhs>
+ </production>
+ </productionset>
+
+ <para>We may as well supply a graphical representation:</para>
+
+ <figure xml:id="extendContModelGraph">
+ <title>Graphical representation of the extended
+ <code>content</code> model.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/contentmixed.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>In comparison to our informal description of memo documents a
+ schema offers an added value: The grammar is machine readable and
+ may thus become input to a parser which in turn gets enabled to
+ check whether an XML document obeys the constraints being imposed.
+ So the parser must be instructed to use a schema in addition to the
+ XML document in question. For this purpose an XML document may
+ define a reference to a schema:</para>
+
+ <figure xml:id="memo_external_dtd">
+ <title>A memo document instance holding a reference to a document
+ external schema.</title>
+
+ <programlisting language="none"><memo <co
+ xml:id="memo_external_dtd_top_element"/> xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="memo.xsd" <co
+ xml:id="memo_external_dtd_url"/>
+ date="2014-09-24" priority="high">
+ <from>M. Goik</from>
+ <to>B. King</to>
+ <to>A. June</to>
+ <subject>Best whishes</subject>
+ <content>Hi all, congratulations to your splendid party</content>
+</memo></programlisting>
+
+ <calloutlist>
+ <callout arearefs="memo_external_dtd_top_element">
+ <para>The element <tag class="starttag">memo</tag> is chosen
+ to be the top (root) element of the document's tree. It must
+ be defined in our schema <filename>memo.xsd</filename>. This
+ is really a choice since an XML schema defines a
+ <emphasis>set</emphasis> of elements in
+ <emphasis>arbitrary</emphasis> order. There is no such rule as
+ <quote>define before use</quote>. So an XML schema does not
+ tell us which element has to appear on top of a
+ document.</para>
+
+ <para>Suppose a given XML schema offers both <tag
+ class="starttag">book</tag> and <tag
+ class="starttag">report</tag> elements. An XML author writing
+ a complex document will choose <tag
+ class="starttag">book</tag> as top level element rather than
+ <tag class="starttag">report</tag> being more appropriate for
+ a small piece of documentation. Consequently it is an XML
+ authors <emphasis>choice</emphasis> which of the elements
+ being defined in a schema shall appear as
+ <emphasis>the</emphasis> top level element</para>
+ </callout>
+
+ <callout arearefs="memo_external_dtd_url">
+ <para>The address of the schema's rule set. In the given
+ example it is just a filename but it may as well be an <link
+ xlink:href="http://www.w3.org/Addressing">URL</link> of type
+ <abbrev
+ xlink:href="http://en.wikipedia.org/wiki/File_Transfer_Protocol">ftp</abbrev>,
+ <abbrev xlink:href="http://www.w3.org/Protocols">http</abbrev>
+ and so on, see <xref linkend="memoDtdOnFtp"/>.</para>
+ </callout>
+ </calloutlist>
+ </figure>
+
+ <para>In presence of a schema parsing a document is actually a two
+ step process: First the parser will check the document for well
+ -formedness. Then the parser will read the referenced schema
+ <filename>memo.xsd</filename> and check the document for the
+ additional constraints being defined within.</para>
+
+ <para>In the current example both the schema and the XML memo
+ document reside as text files in a common file system folder. For
+ general use a schema is usually kept at a centralized location. The
+ attribute <varname>xsi:noNamespaceSchemaLocation</varname> value is
+ actually a
+ <emphasis>U</emphasis><foreignphrase>niform</foreignphrase>
+ <emphasis>R</emphasis><foreignphrase>esource</foreignphrase>
+ <emphasis>L</emphasis><foreignphrase>ocator</foreignphrase> <link
+ xlink:href="http://www.w3.org/Addressing">(URL)</link>. Thus our
+ <filename>memo.xsd</filename> may also be supplied as a <abbrev
+ xlink:href="http://www.w3.org/Protocols">http</abbrev> or <abbrev
+ xlink:href="http://en.wikipedia.org/wiki/File_Transfer_Protocol">ftp</abbrev>
+ <link xlink:href="http://www.w3.org/Addressing">URL</link>:</para>
+
+ <figure xml:id="memoDtdOnFtp">
+ <title>A schema reference to a FTP server.</title>
+
+ <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
+<memo ... xsi:noNamespaceSchemaLocation="https://someserver.org/memo.xsd">
+ <from>M. Goik</from>
+ ...
+</memo></programlisting>
+ </figure>
+
+ <para>Some terms are helpful in the context of schemas:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Validating / non-validating:</term>
+
+ <listitem>
+ <para>A non-validating parser only checks a document for well-
+ formedness. If it also checks XML documents for conformance to
+ schema it is a <emphasis>validating</emphasis> parser.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Valid / invalid documents:</term>
+
+ <listitem>
+ <para>An XML document referencing a schema may either be valid
+ or invalid depending on its conformance to the schema in
+ question.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Document instance:</term>
+
+ <listitem>
+ <para>An XML memo document may conform to the <link
+ linkend="figure_memo_dtd">memo schema</link>. In this case we
+ call it a <emphasis>document instance</emphasis> of the memo
+ schema.</para>
+
+ <para>This situation is quite similar as in typed programming
+ languages: A <link
+ linkend="gloss_Java"><trademark>Java</trademark></link>
+ <code>class</code> declaration is a blueprint for the <link
+ linkend="gloss_Java"><trademark>Java</trademark></link>
+ runtime system to construct <link
+ linkend="gloss_Java"><trademark>Java</trademark></link>
+ objects in memory. This is done by e.g. a statement<code>
+ String name = new String();</code>. The identifier
+ <code>name</code> will hold a reference to an
+ <emphasis>instance of class String</emphasis>. So in a <link
+ linkend="gloss_Java"><trademark>Java</trademark></link>
+ runtime environment a class declaration plays the same role as
+ a schema declaration in XML. See also <xref
+ linkend="example_memoJavaClass"/>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>For further discussions it is very useful to clearly
+ distinguish element definitions in a schema from their
+ <emphasis>realizations</emphasis> in a corresponding document
+ instance: Our memo schema defines an element <tag
+ class="starttag">from</tag> to be of content <type>xs:string</type>.
+ According to the schema at least one <tag
+ class="starttag">from</tag> clause must appear in a valid
+ (conforming) document instance . If we were talking about HTML
+ document instances we would prefer to talk about a <tag
+ class="starttag">from</tag> <emphasis>tag</emphasis> rather than a
+ <tag class="starttag">from</tag>
+ <emphasis>element</emphasis>.</para>
+
+ <para>In this document we will use the term <emphasis>element
+ type</emphasis> to denote an <code><!ELEMENT ...</code>
+ definition in a DTD. Thus we will talk about an element type <tag
+ class="element">subject</tag> being defined in
+ <filename>memo.dtd</filename>.</para>
+
+ <para>An element type being defined in a <abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Document_Type_Declaration">schema</abbrev>
+ may have document instances as realizations. For example the
+ document instance shown in <xref linkend="memo_external_dtd"/> has
+ two <emphasis>nodes</emphasis> of element type <tag
+ class="element">to</tag>. Thus we say that the document instance
+ contains two <emphasis>element nodes</emphasis> of type <tag
+ class="element">to</tag>. We will frequently abbreviate this by
+ saying the instance contains to <tag class="starttag">from</tag>
+ element nodes. And we may even omit the term
+ <emphasis>nodes</emphasis> and simply talk about two <tag
+ class="starttag">from</tag> elements. But the careful reader should
+ always distinguish between a single type <code>foo</code> being
+ defined in a <abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Document_Type_Declaration">schema</abbrev>
+ and the possibly empty set of <tag class="starttag">foo</tag> nodes
+ appearing in valid document instances.</para>
+
+ <para><abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Document_Type_Declaration">Schema</abbrev>'s
+ appear on top of well-formed XML documents:</para>
+
+ <figure xml:id="wellformedandvalid">
+ <title>Well-formed and valid documents</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/wellformedandvalid.fig" scale="65"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <qandaset defaultlabel="qanda" xml:id="example_memoTestValid">
+ <title>Validation of memo document instances.</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>Copy the two files <link
+ xlink:href="Ref/src/Memo.1/message.xml">message.xml</link>
+ and <link
+ xlink:href="Ref/src/Memo.1/memo.dtd">memo.xsd</link> into
+ your eclipse project. Use the Oxygen XML plug in to check if
+ the document is valid. Then subsequently do and undo the
+ following changes each time checking the document for
+ validity:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Omit the <tag class="starttag">from</tag>
+ element.</para>
+ </listitem>
+
+ <listitem>
+ <para>Change the order of the two sub elements <tag
+ class="starttag">subject</tag> and <tag
+ class="starttag">content</tag>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Erase the <varname>date</varname> attribute and
+ its value.</para>
+ </listitem>
+
+ <listitem>
+ <para>Erase the <varname>priority</varname> attribute
+ and its value.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>What do you observe?</para>
+ </question>
+
+ <answer>
+ <para>The <tag class="attribute">priority</tag> attribute is
+ declared as <code>optional</code> and may thus be omitted.
+ Erasing the <tag class="attribute">priority</tag> attribute
+ thus leaves the document in a valid state. The remaining
+ three edit actions yield an invalid document
+ instance.</para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry xml:id="example_memoJavaClass">
+ <question>
+ <label>A memo implementation sketch in Java</label>
+
+ <para>The aim of this exercise is to clarify the (abstract)
+ relation between XML <abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Document_Type_Declaration">schema</abbrev>'s
+ and sets of <link
+ linkend="gloss_Java"><trademark>Java</trademark></link>
+ classes rather then building a running application. We want
+ to model the <link xlink:href="Ref/src/Memo.1/memo.dtd">memo
+ schema</link> as a set of <link
+ linkend="gloss_Java"><trademark>Java</trademark></link>
+ classes.</para>
+ </question>
+
+ <answer>
+ <para>The XML attributes <tag class="attribute">date</tag>
+ and <tag class="attribute">priority</tag> can be mapped as
+ <link
+ linkend="gloss_Java"><trademark>Java</trademark></link>
+ attributes. The same applies for the Memo elements <tag
+ class="element">from</tag>, <tag
+ class="element">subject</tag> and <tag
+ class="element">content</tag> which may be implemented as
+ simple Strings or alternatively as separate Classes wrapping
+ the String content. The latter method of implementation
+ should be preferred if the Memo schema is expected to grow
+ in complexity. A simple sketch reads:</para>
+
+ <programlisting language="none">import java.util.Date;
+import java.util.SortedSet;
+
+public class Memo {
+ private Date date;
+ Priority priority = Priority.standard;
+ private String from, subject,content;
+ private SortedSet<String> to;
+ // Accessors not yet implemented
+}</programlisting>
+
+ <para>The only thing to note here is the implementation of
+ the <tag class="element">to</tag> element: We want to be
+ able to address a <emphasis>set</emphasis> of recipients.
+ Thus we have to disallow duplicates. Note that this is an
+ <emphasis>informal</emphasis> constraint not being handled
+ by our schema: A Memo document instance
+ <emphasis>may</emphasis> have duplicate content in <tag
+ class="starttag">to</tag> nodes. This is a weakness of
+ <abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Document_Type_Declaration">schema</abbrev>s:
+ We are unable to impose uniqueness constraints on the
+ content of partial sets of document nodes.</para>
+
+ <para>On the other hand our set of recipients has to be
+ ordered: In a XML document instance the order of <tag
+ class="starttag">to</tag> nodes is important and has to be
+ preserved in a <link
+ linkend="gloss_Java"><trademark>Java</trademark></link>
+ representation. Thus we choose an
+ <classname>java.util.SortedSet</classname> parametrized with
+ String type to fulfill both requirements.</para>
+
+ <para>Our schema defines:</para>
+
+ <programlisting language="none"><!ATTLIST memo ... priority (low|medium|high) #IMPLIED></programlisting>
+
+ <para>Starting from <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> 1.5
+ we may implement this constraint by a type safe enumeration
+ in a file <filename>Priority.java</filename>:</para>
+
+ <programlisting language="none">public enum Priority{low, standard, high};</programlisting>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+
+ <para>In the following chapters we will extend the memo document
+ type (<code><!DOCTYPE memo ... ></code>) to demonstrate
+ various concepts of <abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Document_Type_Declaration">schema</abbrev>'s
+ and other XML related standards. In parallel a series of exercises
+ deals with building a schema usable to edit books. This schema gets
+ extended as our knowledge about XML advances. We start with an
+ initial exercise:</para>
+
+ <qandaset defaultlabel="qanda" xml:id="example_bookDtd">
+ <title>A schema for editing books</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>Write a schema describing book document instances with
+ the following features:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>A book shall have a title to describe the book
+ itself.</para>
+ </listitem>
+
+ <listitem>
+ <para>A book shall have at least one but possibly a
+ sequence of chapters.</para>
+ </listitem>
+
+ <listitem>
+ <para>Each chapter shall have a title and at least one
+ paragraph.</para>
+ </listitem>
+
+ <listitem>
+ <para>The titles and paragraphs shall consist of
+ ordinary text.</para>
+ </listitem>
+ </itemizedlist>
+ </question>
+
+ <answer>
+ <para>A possible schema looks like:</para>
+
+ <figure xml:id="figure_book.dtd_v1">
+ <title>A first schema version for book documents</title>
+
+ <programlisting language="none"><xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+ xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning" elementFormDefault="qualified"
+ vc:minVersion="1.0" vc:maxVersion="1.1">
+
+ <xs:element name="book">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element ref="title"/>
+ <xs:element ref="chapter" minOccurs="1" maxOccurs="unbounded"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+
+ <xs:element name="title" type="xs:string"/>
+ <xs:element name="chapter">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element ref="title"/>
+ <xs:element ref="para" minOccurs="1" maxOccurs="unbounded"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+
+ <xs:element name="para" type="xs:string"/>
+
+</xs:schema></programlisting>
+ </figure>
+
+ <para>We supply a valid document instance:</para>
+
+ <informalfigure xml:id="bookInitialInstance">
+ <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book SYSTEM "book.dtd">
+<book>
+ <title>Introduction to Java</title>
+ <chapter>
+ <title>Introduction</title>
+ <para>Java is a programming language</para>
+ </chapter>
+ <chapter>
+ <title>The virtual machine</title>
+ <para>We also call it the runtime system.</para>
+ </chapter>
+ <chapter>
+ <title>Annotations</title>
+ <para>Annotations provide a means to add meta information.</para>
+ <para>This is especially useful for framework authors.</para>
+ </chapter>
+</book></programlisting>
+ </informalfigure>
+
+ <para>.</para>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+
+ <section xml:id="dtdVsSqlDdl">
+ <title>Relating <abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Document_Type_Declaration">schema</abbrev>'s
+ and <acronym
+ xlink:href="http://en.wikipedia.org/wiki/Sql">SQL</acronym> -
+ <abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Data_definition_language">DDL</abbrev></title>
+
+ <para>XML <abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Document_Type_Declaration">schema</abbrev>'s
+ and <acronym
+ xlink:href="http://en.wikipedia.org/wiki/Sql">SQL</acronym> -
+ <abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Data_definition_language">DDL</abbrev>
+ are related: They both describe data models and thus integrity
+ constraints. We consider a simple invoice example:</para>
+
+ <figure xml:id="invoiceIntegrity">
+ <title>Invoice integrity constraints</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/invoicedata.fig" scale="65"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>A relational implementation may look like:</para>
+
+ <figure xml:id="invoiceSqlDdl">
+ <title>Relational implementation</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/invoicedataimplement.fig"
+ scale="65"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <qandaset defaultlabel="qanda" xml:id="qandaInvoiceSchema">
+ <title>An XML schema representing invoices</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>Represent the relational schema being described in
+ <xref linkend="invoiceSqlDdl"/> by an XML Schema and provide
+ an appropriate instance example.</para>
+ </question>
+
+ <answer>
+ <para>A possible schema implementation:</para>
+
+ <programlisting language="none"><xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+ xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning" elementFormDefault="qualified"
+ vc:minVersion="1.0" vc:maxVersion="1.1">
+
+ <xs:simpleType name="money">
+ <xs:restriction base="xs:decimal">
+ <xs:fractionDigits value="2"/>
+ </xs:restriction>
+ </xs:simpleType>
+
+ <xs:element name="data">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element ref="customer" maxOccurs="unbounded"/>
+ <xs:element ref="invoice" maxOccurs="unbounded"/>
+ </xs:sequence>
+ </xs:complexType>
+ <xs:key name="customerId">
+ <xs:selector xpath="customer"/>
+ <xs:field xpath="@id"/>
+ </xs:key>
+
+ <xs:keyref refer="customerId" name="customerToInvoice">
+ <xs:selector xpath="invoice"/>
+ <xs:field xpath="@customer"></xs:field>
+ </xs:keyref>
+ </xs:element>
+
+ <xs:element name="customer">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="name" type="xs:string"/>
+ <xs:element name="phoneNumber" type="xs:string" minOccurs="0"/>
+ </xs:sequence>
+ <xs:attribute name="id" type="xs:int" use="required"/>
+ </xs:complexType>
+ </xs:element>
+
+ <xs:element name="invoice">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="amount" type="money"/>
+ <xs:element name="status">
+ <xs:simpleType>
+ <xs:restriction base="xs:token">
+ <xs:enumeration value="open"/>
+ <xs:enumeration value="due"/>
+ <xs:enumeration value="cleared"/>
+ </xs:restriction>
+ </xs:simpleType>
+ </xs:element>
+ </xs:sequence>
+ <xs:attribute name="customer" type="xs:int" use="required"/>
+ </xs:complexType>
+ </xs:element>
+
+</xs:schema></programlisting>
+
+ <para>An example data set:</para>
+
+ <programlisting language="none"><data xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="invoice.xsd">
+ <customer id="5">
+ <name>Clarke Jefferson</name>
+ </customer>
+
+ <invoice customer="5">
+ <amount>33.12</amount>
+ <status>due</status>
+ </invoice>
+</data></programlisting>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+
+ <section xml:id="xmlAndJava">
+ <title>Relating <abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Document_Type_Declaration">schema</abbrev>'s
+ and <link linkend="gloss_Java"><trademark>Java</trademark></link>
+ class descriptions.</title>
+
+ <para>We may also compare XML data constraints to <link
+ linkend="gloss_Java"><trademark>Java</trademark></link>. A <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> class
+ declaration is actually a blueprint for a <trademark
+ xlink:href="http://www.oracle.com/technetwork/java/javase">JRE</trademark>
+ to instantiate compatible objects. Likewise an XML schema restricts
+ well-formed documents:</para>
+
+ <figure xml:id="fig_XmlAndJava">
+ <title>XML <abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Document_Type_Declaration">schema</abbrev>'s
+ and <link linkend="gloss_Java"><trademark>Java</trademark></link>
+ class declarations.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/xmlattribandjava.fig" scale="65"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+
+ <section xml:id="xmlSchemaExercise">
+ <title>XML schema exercises</title>
+
+ <section xml:id="sectSchemaProductCatalog">
+ <title>A product catalog</title>
+
+ <qandaset defaultlabel="qanda" xml:id="quandaProductCatalog">
+ <title>Product catalog schema</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>Consider the following product catalog
+ example:</para>
+
+ <programlisting language="none"><catalog xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="catalog.xsd">
+ <title>Outdoor products</title>
+ <introduction>
+ <para>We offer a great variety of basic stuff for mountaineering
+ such as ropes, harnesses and tents.</para>
+ <para>Our shop is proud for its large number of available
+ sleeping bags.</para>
+ </introduction>
+ <product id="x-223">
+ <title>Multi freezing bag Nightmare camper</title>
+ <description>
+ <para>You will feel comfortable till minus 20 degrees - At
+ least if you are a penguin or a polar bear.</para>
+ </description>
+ </product>
+ <product id="r-334">
+ <title>Rope 40m</title>
+ <description>
+ <para>Excellent for indoor climbing.</para>
+ </description>
+ </product>
+</catalog></programlisting>
+
+ <para>As you may have inferred the following rules shall
+ apply for arbitrary catalog documents:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Each <tag class="starttag">catalog</tag> shall
+ have exactly one <tag class="starttag">title</tag> and
+ <tag class="starttag">introduction</tag>
+ element.</para>
+ </listitem>
+
+ <listitem>
+ <para><tag class="starttag">introduction</tag> and
+ <tag class="starttag">description</tag> shall have at
+ least one <tag class="starttag">para</tag>
+ child.</para>
+ </listitem>
+
+ <listitem>
+ <para>Each <tag class="starttag">catalog</tag> shall
+ have at least one <tag
+ class="starttag">product</tag>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Each <tag class="starttag">product</tag> shall
+ have exactly one <tag class="starttag">title</tag> and
+ at least one <tag class="starttag">para</tag> child
+ element.</para>
+ </listitem>
+
+ <listitem>
+ <para>The required <code>id</code> attribute shall not
+ contain whitespace and be unique with respect to all
+ <tag class="starttag">product</tag> elements.</para>
+ </listitem>
+
+ <listitem>
+ <para>The attribute price shall represent money
+ amounts and be optional.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Provide a suitable <filename>catalog.xsd</filename>
+ schema.</para>
+ </question>
+
+ <answer>
+ <programlisting language="none"><xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+ xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning" elementFormDefault="qualified"
+ vc:minVersion="1.0" vc:maxVersion="1.1">
+
+ <xs:simpleType name="money">
+ <xs:restriction base="xs:decimal">
+ <xs:fractionDigits value="2"/>
+ </xs:restriction>
+ </xs:simpleType>
+
+ <xs:element name="title" type="xs:string"/>
+ <xs:element name="para" type="xs:string"/>
+
+ <xs:element name="description" type="paraSequence"/>
+ <xs:element name="introduction" type="paraSequence"/>
+
+ <xs:complexType name="paraSequence">
+ <xs:sequence>
+ <xs:element ref="para" minOccurs="1" maxOccurs="unbounded"/>
+ </xs:sequence>
+ </xs:complexType>
+
+ <xs:element name="product">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element ref="title"/>
+ <xs:element ref="description"/>
+ </xs:sequence>
+ <xs:attribute name="id" type="xs:token" use="required"/>
+ <xs:attribute name="price" type="money" use="optional"/>
+ </xs:complexType>
+ </xs:element>
+
+ <xs:element name="catalog">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element ref="title"/>
+ <xs:element ref="introduction"/>
+ <xs:element ref="product" minOccurs="1" maxOccurs="unbounded"/>
+ </xs:sequence>
+ </xs:complexType>
+
+ <xs:key name="uniqueProductId">
+ <xs:selector xpath="product"></xs:selector>
+ <xs:field xpath="@id"/>
+ </xs:key>
+ </xs:element>
+
+</xs:schema></programlisting>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+
+ <section xml:id="sectQandaBookV1">
+ <title>Book like documents</title>
+
+ <qandaset defaultlabel="qanda" xml:id="example_operatorprecedence">
+ <title>Book documents with mixed content and itemized
+ lists</title>
+
+ <qandadiv>
+ <qandaentry xml:id="example_book_v2">
+ <question>
+ <para>Extend the first version of <link
+ linkend="example_bookDtd">book.xsd</link> to support the
+ following features:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Within a <tag class="starttag">chapter</tag>
+ node <tag class="starttag">para</tag> and <tag
+ class="starttag">itemizedlist</tag> elements in
+ arbitrary order shall be allowed.</para>
+ </listitem>
+
+ <listitem>
+ <para><tag class="starttag">itemizedlist</tag> nodes
+ shall contain at least one <tag
+ class="starttag">listitem</tag>.</para>
+ </listitem>
+
+ <listitem>
+ <para><tag class="starttag">listitem</tag> nodes shall
+ be composed of one or more para or nested list item
+ elements.</para>
+ </listitem>
+
+ <listitem>
+ <para>Within a <tag class="starttag">para</tag> we
+ want to be able to emphasize text passages.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The following sample document instance shall be
+ valid:</para>
+
+ <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book SYSTEM "book.dtd">
+<book>
+ <title>Introduction to Java</title>
+ <chapter>
+ <title>Introduction</title>
+ <para>Java supports <emphasis>lots</emphasis> of concepts:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Single <emphasis>implementation</emphasis> inheritance.</para>
+ </listitem>
+ <listitem>
+ <para>Multiple <emphasis>interface</emphasis> inheritance.</para>
+ <itemizedlist>
+ <listitem><para>Built in types</para></listitem>
+ <listitem><para>User defined types</para></listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </chapter>
+</book></programlisting>
+ </question>
+
+ <answer>
+ <para>An extended DTD looks like:</para>
+
+ <figure xml:id="paraListEmphasize">
+ <title>Version 2 of book.dtd</title>
+
+ <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+ xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning" elementFormDefault="qualified"
+ vc:minVersion="1.0" vc:maxVersion="1.1">
+
+ <xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="http://www.w3.org/2001/03/xml.xsd" />
+
+
+ <xs:include schemaLocation="table.xsd"/>
+
+ <!-- Type definitions -->
+ <xs:simpleType name="languageType">
+ <xs:restriction base="xs:string">
+ <xs:enumeration value="en"/>
+ <xs:enumeration value="fr"/>
+ <xs:enumeration value="de"/>
+ <xs:enumeration value="it"/>
+ <xs:enumeration value="es"/>
+ </xs:restriction>
+ </xs:simpleType>
+
+
+ <!-- Elements having no inner structure -->
+ <xs:element name="emphasis" type="xs:string"/>
+ <xs:element name="title" type="xs:string"/>
+ <xs:element name="link">
+ <xs:complexType mixed="true">
+ <xs:attribute name="linkend" type="xs:IDREF" use="required"/>
+ </xs:complexType>
+ </xs:element>
+
+ <!-- Starting the game ... -->
+ <xs:element name="book">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element ref="title"/>
+ <xs:element ref="chapter" minOccurs="1" maxOccurs="unbounded"/>
+ </xs:sequence>
+ <xs:attribute name="lang" type="languageType" use="optional"/>
+ </xs:complexType>
+ </xs:element>
+
+ <xs:element name="chapter">
+ <xs:complexType>
+ <xs:sequence> <co xml:id="figure_book.dtd_v2_chapter"/>
+ <xs:element ref="title"/>
+ <xs:choice minOccurs="1" maxOccurs="unbounded">
+ <xs:element ref="para"/>
+ <xs:element ref="itemizedlist"/>
+ <xs:element ref="table"/>
+ </xs:choice>
+ </xs:sequence>
+ <xs:attribute name="id" type="xs:ID" use="optional"/>
+ <xs:attribute ref="xml:base"/> <!-- This allows for <xi:include ...> -->
+ </xs:complexType>
+ </xs:element>
+
+ <xs:element name="para">
+ <xs:complexType mixed="true"> <co
+ xml:id="figure_book.dtd_v2_para"/>
+ <xs:choice minOccurs="0" maxOccurs="unbounded">
+ <xs:element ref="emphasis"/>
+ <xs:element ref="link"/>
+ </xs:choice>
+ <xs:attribute name="id" type="xs:ID" use="optional"/>
+ </xs:complexType>
+ </xs:element>
+
+ <xs:element name="itemizedlist">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element ref="listitem" minOccurs="1" <co
+ xml:id="figure_book.dtd_v2_itemizedlist"/> maxOccurs="unbounded"/>
+ </xs:sequence>
+ <xs:attribute name="id" type="xs:ID" use="optional"/>
+ </xs:complexType>
+ </xs:element>
+
+ <xs:element name="listitem">
+ <xs:complexType>
+ <xs:choice minOccurs="1" maxOccurs="unbounded"> <co
+ xml:id="figure_book.dtd_v2_listitem"/>
+ <xs:element ref="para"/>
+ <xs:element ref="itemizedlist"/>
+ </xs:choice>
+ </xs:complexType>
+ </xs:element>
+
+</xs:schema></programlisting>
+
+ <caption>
+ <para>This allows emphasized text in <tag
+ class="starttag">para</tag> nodes and <tag
+ class="starttag">itemizedlists</tag>.</para>
+ </caption>
+ </figure>
+
+ <calloutlist>
+ <callout arearefs="figure_book.dtd_v2_chapter">
+ <para>We hook into <tag class="starttag">chapter</tag>
+ to allow arbitrary sequences of at least one <tag
+ class="starttag">para</tag> or <tag
+ class="starttag">itemizedlist</tag> element
+ node.</para>
+ </callout>
+
+ <callout arearefs="figure_book.dtd_v2_para">
+ <para><tag class="starttag">para</tag> nodes now allow
+ mixed content.</para>
+ </callout>
+
+ <callout arearefs="figure_book.dtd_v2_itemizedlist">
+ <para>An <tag class="starttag">itemizedlist</tag>
+ contains at least one list item.</para>
+ </callout>
+
+ <callout arearefs="figure_book.dtd_v2_listitem">
+ <para>A <tag class="starttag">listitem</tag> contains
+ a sequence of at least one <tag
+ class="starttag">para</tag> or <tag
+ class="starttag">itemizedlist</tag> child node. The
+ latter gives rise to nested lists. We find a similar
+ construct in HTML namely unnumbered lists defined by
+ <code><UL><LI>...
+ </code>constructs.</para>
+ </callout>
+ </calloutlist>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+
+ <section xml:id="sectQandaBookLang">
+ <title>Allow different languages</title>
+
+ <qandaset defaultlabel="qanda" xml:id="example_book.dtd_v3">
+ <title>book.dtd and languages</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>We want to extend our schema from <xref
+ linkend="example_book_v2"/> by allowing an author to
+ define the language to be used within the whole or parts
+ of the document in question. Add an attribute
+ <code>lang</code> to all relevant elements like e.g. <tag
+ class="starttag">para lang="es"</tag>. An XML editor may
+ use this attribute to activate corresponding dictionaries
+ for spell checking.</para>
+
+ <para>The <code>lang</code> attribute shall be restricted
+ to the following values:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><token>en</token></para>
+ </listitem>
+
+ <listitem>
+ <para><token>fr</token></para>
+ </listitem>
+
+ <listitem>
+ <para><token>de</token></para>
+ </listitem>
+
+ <listitem>
+ <para><token>it</token></para>
+ </listitem>
+
+ <listitem>
+ <para><token>es</token></para>
+ </listitem>
+ </itemizedlist>
+ </question>
+
+ <answer>
+ <para>We define a suitable <tag
+ class="starttag">xs:attribute</tag> type:</para>
+
+ <programlisting language="none"><xs:attribute <emphasis
+ role="bold">name="lang"</emphasis>>
+ <xs:simpleType>
+ <xs:restriction base="xs:string">
+ <xs:enumeration value="en"/>
+ <xs:enumeration value="fr"/>
+ <xs:enumeration value="de"/>
+ <xs:enumeration value="it"/>
+ <xs:enumeration value="es"/>
+ </xs:restriction>
+ </xs:simpleType>
+</xs:attribute></programlisting>
+
+ <para>Than we add this attribute to our elements like <tag
+ class="starttag">chapter</tag> and others:</para>
+
+ <programlisting language="none"> <xs:element name="chapter">
+ <xs:complexType>
+ <xs:sequence> ... </xs:sequence>
+ <xs:attribute <emphasis role="bold">ref="lang"</emphasis> use="optional"/>
+ ...
+ </xs:complexType>
+ </xs:element></programlisting>
+
+ <para>This allows us to set a language on arbitrary
+ hierarchy level. But of course we may define it on top
+ level as well:</para>
+
+ <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
+<book ... lang="english">
+ <title>Introduction to Java</title>
+...</programlisting>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+
+ <section xml:id="sectMixQuotes">
+ <title>Mixing attribute quotes</title>
+
+ <qandaset defaultlabel="qanda" xml:id="example_quotes">
+ <title>Single and double quotes reconsidered</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>We recall the problem of nested quotes yielding
+ non-well formed XML code:</para>
+
+ <programlisting language="none"><img src="bold.gif" alt="We may use "quotes" here" /></programlisting>
+
+ <para>The XML specification defines legal attribute value
+ definitions as:</para>
+
+ <productionset>
+ <title><link
+ xlink:href="http://www.w3.org/TR/2008/REC-xml-20081126/#d0e888">Literals</link></title>
+
+ <production xml:id="w3RecXml_NT-EntityValue">
+ <lhs>EntityValue</lhs>
+
+ <rhs>'"' ([^%&"] | <nonterminal
+ def="#w3RecXml_NT-PEReference">PEReference</nonterminal>
+ | <nonterminal
+ def="#w3RecXml_NT-Reference">Reference</nonterminal>)*
+ '"' |Â "'" ([^%&'] | <nonterminal
+ def="#w3RecXml_NT-PEReference">PEReference</nonterminal>
+ | <nonterminal
+ def="#w3RecXml_NT-Reference">Reference</nonterminal>)*
+ "'"</rhs>
+ </production>
+
+ <production xml:id="w3RecXml_NT-AttValue">
+ <lhs>AttValue</lhs>
+
+ <rhs>'"' ([^<&"] | <nonterminal
+ def="#w3RecXml_NT-Reference">Reference</nonterminal>)*
+ '"' |Â "'" ([^<&'] | <nonterminal
+ def="#w3RecXml_NT-Reference">Reference</nonterminal>)*
+ "'"</rhs>
+ </production>
+
+ <production xml:id="w3RecXml_NT-SystemLiteral">
+ <lhs>SystemLiteral</lhs>
+
+ <rhs>('"' [^"]* '"') |Â ("'" [^']* "'")</rhs>
+ </production>
+
+ <production xml:id="w3RecXml_NT-PubidLiteral">
+ <lhs>PubidLiteral</lhs>
+
+ <rhs>'"' <nonterminal
+ def="#w3RecXml_NT-PubidChar">PubidChar</nonterminal>*
+ '"' | "'" (<nonterminal
+ def="#w3RecXml_NT-PubidChar">PubidChar</nonterminal> -
+ "'")* "'"</rhs>
+ </production>
+
+ <production xml:id="w3RecXml_NT-PubidChar">
+ <lhs>PubidChar</lhs>
+
+ <rhs>#x20 | #xD | #xA |Â [a-zA-Z0-9]
+ |Â [-'()+,./:=?;!*#@$_%]</rhs>
+ </production>
+ </productionset>
+
+ <para>Find out how it is possible to set the attribute
+ <tag class="attribute">alt</tag>'s value to the string
+ <code>We may use "quotes" here</code>.</para>
+ </question>
+
+ <answer>
+ <para>The production rule for attribute values
+ reads:</para>
+
+ <productionset>
+ <productionrecap linkend="w3RecXml_NT-AttValue"/>
+ </productionset>
+
+ <para>This allows us to use either of two alternatives to
+ delimit attribute values:</para>
+
+ <glosslist>
+ <glossentry>
+ <glossterm><tag class="starttag">img ...
+ alt="..."/</tag></glossterm>
+
+ <glossdef>
+ <para><emphasis>Validity constraint:</emphasis> do
+ not use <code>"</code> inside the value
+ string.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm><tag class="starttag">img ...
+ alt='...'/</tag></glossterm>
+
+ <glossdef>
+ <para><emphasis>Validity constraint:</emphasis> do
+ not use <code>'</code> inside the value
+ string.</para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+
+ <para>We may take advantage of the second rule:</para>
+
+ <programlisting language="none"><img src="bold.gif" alt='We may use "quotes" here' /></programlisting>
+
+ <para>Notice that according to <xref
+ linkend="w3RecXml_NT-AttValue"/> the delimiting quotes
+ must not be mixed. The following code is thus not well
+ formed:</para>
+
+ <programlisting language="none"><img src="bold.gif'/></programlisting>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+
+ <section xml:id="qandasetInternalRef">
+ <title>Internal references</title>
+
+ <qandaset defaultlabel="qanda" xml:id="example_book.dtd_v5">
+ <title>book.dtd and internal references</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>We want to extend our DTD from <xref
+ linkend="example_book.dtd_v3"/> to allow document internal
+ references by:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Allowing each <tag
+ class="starttag">chapter</tag>, <tag
+ class="starttag">para</tag> and <tag
+ class="starttag">itemizedlist</tag> to become
+ reference targets.</para>
+ </listitem>
+
+ <listitem>
+ <para>Extending the element <tag
+ class="element">para</tag>'s mixed content model by a
+ new element <tag class="element">link</tag> with an
+ attribute <tag class="attribute">linkend</tag> being a
+ reference to a target.</para>
+ </listitem>
+ </itemizedlist>
+ </question>
+
+ <answer>
+ <para>We extend our DTD:</para>
+
+ <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+ xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning" elementFormDefault="qualified"
+ vc:minVersion="1.0" vc:maxVersion="1.1">
+
+ <xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="http://www.w3.org/2001/03/xml.xsd" />
+
+
+ <xs:include schemaLocation="table.xsd"/>
+
+ <!-- Type definitions -->
+
+ <xs:attribute name="lang">
+ <xs:simpleType>
+ <xs:restriction base="xs:string">
+ <xs:enumeration value="en"/>
+ <xs:enumeration value="fr"/>
+ <xs:enumeration value="de"/>
+ <xs:enumeration value="it"/>
+ <xs:enumeration value="es"/>
+ </xs:restriction>
+ </xs:simpleType>
+ </xs:attribute>
+
+ <!-- Elements having no inner structure -->
+ <xs:element name="emphasis" type="xs:string"/>
+ <xs:element name="title" type="xs:string"/>
+ <xs:element name="link">
+ <xs:complexType mixed="true"> <co
+ xml:id="progamlisting_book_v5_link"/>
+ <xs:attribute name="linkend" <co
+ xml:id="progamlisting_book_v5_link_linkend"/> type="xs:IDREF" use="required"/>
+ </xs:complexType>
+ </xs:element>
+
+ <!-- Starting the game ... -->
+ <xs:element name="book">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element ref="title"/>
+ <xs:element ref="chapter" minOccurs="1" maxOccurs="unbounded"/>
+ </xs:sequence>
+ <xs:attribute ref="lang" use="optional"/>
+ </xs:complexType>
+ </xs:element>
+
+ <xs:element name="chapter">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element ref="title"/>
+ <xs:choice minOccurs="1" maxOccurs="unbounded">
+ <xs:element ref="para"/>
+ <xs:element ref="itemizedlist"/>
+ <xs:element ref="table"/>
+ </xs:choice>
+ </xs:sequence>
+ <xs:attribute ref="lang" use="optional"/>
+ <xs:attribute name="id" <co
+ xml:id="progamlisting_book_v5_chapter_id"/> type="xs:ID" use="optional"/>
+ <xs:attribute ref="xml:base"/> <!-- This allows for <xi:include ...> -->
+ </xs:complexType>
+ </xs:element>
+
+ <xs:element name="para">
+ <xs:complexType mixed="true"> <co
+ xml:id="progamlisting_book_v5_mixed_link"/>
+ <xs:choice minOccurs="0" maxOccurs="unbounded">
+ <xs:element ref="emphasis"/>
+ <xs:element ref="link"/>
+ </xs:choice>
+ <xs:attribute ref="lang" use="optional"/>
+ <xs:attribute name="id" <co
+ xml:id="progamlisting_book_v5_para_id"/> type="xs:ID" use="optional"/>
+ </xs:complexType>
+ </xs:element>
+
+ <xs:element name="itemizedlist">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element ref="listitem" minOccurs="1" maxOccurs="unbounded"/>
+ </xs:sequence>
+ <xs:attribute ref="lang" use="optional"/>
+ <xs:attribute name="id" type="xs:ID" use="optional"/>
+ </xs:complexType>
+ </xs:element>
+
+ <xs:element name="listitem">
+ <xs:complexType>
+ <xs:choice minOccurs="1" maxOccurs="unbounded">
+ <xs:element ref="para"/>
+ <xs:element ref="itemizedlist"/>
+ </xs:choice>
+ <xs:attribute ref="lang" use="optional"/>
+ </xs:complexType>
+ </xs:element>
+
+</xs:schema></programlisting>
+
+ <calloutlist>
+ <callout arearefs="progamlisting_book_v5_chapter_id">
+ <para>Defining an attribute <tag
+ class="attribute">id</tag> of type <code>ID</code> for
+ the elements <tag class="element">chapter</tag>, <tag
+ class="element">para</tag> and <tag
+ class="element">itemizedList</tag>. This enables an
+ author to define internal reference targets.</para>
+ </callout>
+
+ <callout arearefs="progamlisting_book_v5_mixed_link">
+ <para>A link is part of the element <tag
+ class="element">para</tag>'s mixed content model. Thus
+ an author may define internal references along with
+ ordinary text.</para>
+ </callout>
+
+ <callout arearefs="progamlisting_book_v5_link">
+ <para>Like in HTML a link may contain text. If
+ converted to HTML the formatting expectation is a
+ hypertext link.</para>
+ </callout>
+
+ <callout arearefs="progamlisting_book_v5_link_linkend">
+ <para>The attribute <tag
+ class="attribute">linkend</tag> holds the reference to
+ an internal target being either a <tag
+ class="element">chapter</tag>, a <tag
+ class="element">para</tag> or an <tag
+ class="element">itemizedList</tag>.</para>
+ </callout>
+ </calloutlist>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+ </section>
+ </section>
+ </chapter>
+
+ <chapter xml:id="xsl">
+ <title>The Extensible Stylesheet Language XSL</title>
+
+ <para>XSL is a <link xlink:href="http://www.w3.org/Style/XSL">W3C
+ standard</link> which defines a language to transform XML documents into
+ the following output formats:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Ordinary text e.g in <link
+ xlink:href="http://unicode.org">Unicode</link> encoding.</para>
+ </listitem>
+
+ <listitem>
+ <para>XML.</para>
+ </listitem>
+
+ <listitem>
+ <para>HTML</para>
+ </listitem>
+
+ <listitem>
+ <para>XHTML</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Transforming a source XML document into a target XML document may
+ be required if:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The target document expresses similar semantics but uses a
+ different XML dialect i.e. different tag names.</para>
+ </listitem>
+
+ <listitem>
+ <para>The target document is only a view on the source document. We
+ may for example extract the chapter names from a <tag
+ class="starttag">book</tag> document to create a table of
+ contents.</para>
+ </listitem>
+ </itemizedlist>
+
+ <section xml:id="xsl_helloworld">
+ <title>A <quote>Hello, world</quote> <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> example</title>
+
+ <para>We start from an extended version of our
+ <filename>memo.dtd</filename>:</para>
+
+ <programlisting language="none"><!ELEMENT memo (from, to+, subject, content)>
+<!ATTLIST memo date CDATA #REQUIRED
+ priority (low|medium|high) #IMPLIED>
+<!ELEMENT from (#PCDATA)>
+<!ATTLIST from id ID #IMPLIED >
+<!ELEMENT to (#PCDATA)>
+<!ATTLIST to id ID #IMPLIED >
+
+<!ELEMENT subject (#PCDATA)>
+<!ELEMENT content (para)+>
+<!ELEMENT para (#PCDATA|link)*>
+<!ELEMENT link (#PCDATA) >
+<!ATTLIST link linkend IDREF #REQUIRED ></programlisting>
+
+ <para>This DTD allows a memo's document content to be structured into
+ paragraphs. A paragraph may contain links either to the sender or to
+ one of the memo's recipients.</para>
+
+ <figure xml:id="figure_memoref_instance">
+ <title>A memo document instance with an internal reference.</title>
+
+ <programlisting language="none"><?xml version="1.0" ?>
+<!DOCTYPE memo SYSTEM "memo.dtd">
+<memo date="9.9.2099" priority="high">
+ <from id="goik">Martin Goik</from>
+ <to>Adam Hacker</to>
+ <to id="eve">Eve Intruder</to>
+ <subject>Firewall problems</subject>
+ <content>
+ <para>Thanks for your excellent work.</para>
+ <para>Our firewall is definitely broken! This bug has been reported by
+ the <link linkend="goik">sender</link>.</para>
+ </content>
+</memo></programlisting>
+ </figure>
+
+ <para>We want to extract the sender's name from an arbitrary <tag
+ class="element">memo</tag> document instance. Using <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> this task can be
+ accomplished by a script <filename>memo2sender.xsl</filename>:</para>
+
+ <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="2.0">
+
+ <xsl:output method="text"/>
+
+ <xsl:template match="/memo">
+ <xsl:value-of select="from"/>
+ </xsl:template>
+
+</xsl:stylesheet></programlisting>
+
+ <para>Before closer examining this code we first show its effect. We
+ need a piece of software called a <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> processor. It
+ reads both a <tag>memo</tag> document instance and a style sheet and
+ produces the following output:</para>
+
+ <programlisting language="none"><computeroutput>[goik@mupter Memoref]$ xml2xml message.xml memo2sender.xsl
+Martin Goik</computeroutput></programlisting>
+
+ <para>The result is the sender's name <computeroutput>Martin
+ Goik</computeroutput>. We may sketch the transformation
+ principle:</para>
+
+ <figure xml:id="figure_xsl_principle">
+ <title>An <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> processor
+ transforming a XML document into a result using a stylesheet</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/xslconvert.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The executable <filename>xml2xml</filename> defined at the MI
+ department is actually a script wrapping the <productname
+ xlink:href="http://saxon.sourceforge.net">Saxon XSLT
+ processor</productname>. We may also use the Eclipse/Oxygen plugin
+ replacing the shell command by a GUI <link
+ xlink:href="http://www.oxygenxml.com/doc/ug-editorEclipse/#topics/defining-new-transformation-scenario.html">as
+ being described in the corresponding documentation</link>. Next we
+ closer examine the <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> example
+ code:</para>
+
+ <programlisting language="none"><xsl:stylesheet <co
+ xml:id="programlisting_helloxsl_stylesheet"/> xmlns:xsl <co
+ xml:id="programlisting_helloxsl_namespace_abbv"/> ="http://www.w3.org/1999/XSL/Transform"
+ version="2.0" <co xml:id="programlisting_helloxsl_xsl_version"/> >
+
+ <xsl:output method="text" <co
+ xml:id="programlisting_helloxsl_method_text"/>/>
+
+ <xsl:template <co xml:id="programlisting_helloxsl_template"/> match <co
+ xml:id="programlisting_helloxsl_match"/> ="/memo">
+ <xsl:value-of <co xml:id="programlisting_helloxsl_value-of"/> select <co
+ xml:base="" xml:id="programlisting_helloxsl_valueof_select_att"/> ="from" />
+ </xsl:template>
+
+</xsl:stylesheet></programlisting>
+
+ <calloutlist>
+ <callout arearefs="programlisting_helloxsl_stylesheet">
+ <para>The element stylesheet belongs the the namespace
+ <code>http://www.w3.org/1999/XSL/Transform</code>. This namespace
+ is <emphasis>represented</emphasis> by the literal
+ <literal>xsl</literal>. As an alternative we might also use <tag
+ class="starttag">stylesheet
+ xmlns="http://www.w3.org/1999/XSL/Transform"</tag> instead of <tag
+ class="starttag">xsl:stylesheet ...</tag>. The value of the
+ namespace itself gets defined next.</para>
+ </callout>
+
+ <callout arearefs="programlisting_helloxsl_namespace_abbv">
+ <para>The keyword <code>xmlns</code> is reserved by the <link
+ xlink:href="http://www.w3.org/TR/REC-xml-names/">Namespaces in
+ XML</link> specification. In <quote>pure</quote> XML the whole
+ term <code>xmlns:xsl</code> would simply define an attribute. In
+ presence of a namespace aware XML parser however the literal
+ <literal>xsl</literal> represents the attribute value <tag
+ class="attvalue">http://www.w3.org/1999/XSL/Transform</tag>. This
+ value <emphasis>must not</emphasis> be changed! Otherwise a XSL
+ converter will fail since it cannot distinguish processing
+ instructions from other XML elements. An element <tag
+ class="starttag">stylesheet</tag> belonging to a different
+ namespace <code>http//someserver.org/SomeNamespace</code> may have
+ to be generated.</para>
+ </callout>
+
+ <callout arearefs="programlisting_helloxsl_xsl_version">
+ <para>The <link xlink:href="http://www.w3.org/TR/xslt20">XSL
+ standard</link> is still evolving. The version number identifies
+ the conformance level for the subsequent code.</para>
+ </callout>
+
+ <callout arearefs="programlisting_helloxsl_method_text">
+ <para>The <tag class="attribute">method</tag> attribute in the
+ <link
+ xlink:href="http://www.w3.org/TR/xslt20/#element-output"><xsl:output></link>
+ element specifies the type of output to be generated. Depending on
+ this type we may also define indentation depths and/or encoding.
+ Allowed <tag class="attvalue">method</tag> values are:</para>
+
+ <glosslist>
+ <glossentry>
+ <glossterm>text</glossterm>
+
+ <glossdef>
+ <para>Ordinary text.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>html</glossterm>
+
+ <glossdef>
+ <para><link
+ xlink:href="http://www.w3.org/TR/html4">HTML</link>
+ markup.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>xhtml</glossterm>
+
+ <glossdef>
+ <para><link
+ xlink:href="http://www.w3.org/TR/xhtml1">Xhtml</link> markup
+ differing from the former by e.g. the closing
+ <quote>/></quote> in <tag><img
+ src="..."/></tag>.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>xml</glossterm>
+
+ <glossdef>
+ <para>XML code. This is most commonly used to create views
+ on or different dialects of a XML document instance.</para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+ </callout>
+
+ <callout arearefs="programlisting_helloxsl_template">
+ <para>A <tag class="starttag">xsl:template</tag> defines the
+ output that will be created for document nodes being defined by a
+ selector.</para>
+ </callout>
+
+ <callout arearefs="programlisting_helloxsl_match">
+ <para>The attribute <tag class="attribute">match</tag> tells us
+ for which nodes of a document instance the given <tag
+ class="starttag">xsl:template</tag> is appropriate. In the given
+ example the value <code>/memo</code> tells us that the template is
+ only responsible for <tag class="element">memo</tag> nodes
+ appearing at top level i.e. being the root element of the document
+ instance.</para>
+ </callout>
+
+ <callout arch=""
+ arearefs="programlisting_helloxsl_value-of programlisting_helloxsl_valueof_select_att">
+ <para>A <tag class="element">value-of</tag> element writes content
+ to the <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> process'
+ output. In this example the <code>#PCDATA</code> content from the
+ element <tag class="element">from</tag> will be written to the
+ output.</para>
+ </callout>
+ </calloutlist>
+ </section>
+
+ <section xml:id="xpath">
+ <title><link xlink:href="http://www.w3.org/TR/xpath">XPath</link> and
+ node sets</title>
+
+ <para>The <acronym
+ xlink:href="http://www.w3.org/TR/xpath">XPath</acronym> standard
+ allows us to retrieve node sets from XML documents by predicate based
+ queries. Thus its role may be compared to <acronym
+ xlink:href="http://en.wikipedia.org/wiki/Sql">SQL</acronym>
+ <code>SELECT</code> ... <code>FROM</code> ...<code>WHERE</code>
+ queries. Some simple examples:</para>
+
+ <figure xml:id="fig_Xpath">
+ <title>Simple <acronym
+ xlink:href="http://www.w3.org/TR/xpath">XPath</acronym>
+ queries</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/xpath.fig" scale="65"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>We are now interested in a list of all recipients being defined
+ in a <tag class="element">memo</tag> element. We introduce the element
+ <tag class="element">xsl:for-each</tag> which iterates over a result
+ set of nodes:</para>
+
+ <figure xml:id="programlisting_tolist_xpath">
+ <title>Iterating over the list of recipient nodes.</title>
+
+ <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="2.0">
+
+ <xsl:output method="text"/>
+
+ <xsl:template match="/" <co xml:id="programlisting_tolist_match_root"/>>
+ <xsl:for-each select="memo/to" <co
+ xml:id="programlisting_tolist_xpath_memo_to"/> >
+ <xsl:value-of select="." <co xml:id="programlisting_tolist_value_of"/> />
+ <xsl:text>,</xsl:text> <co
+ xml:id="programlisting_tolist_xsl_text"/>
+ </xsl:for-each>
+ </xsl:template>
+
+</xsl:stylesheet></programlisting>
+ </figure>
+
+ <calloutlist>
+ <callout arearefs="programlisting_tolist_match_root">
+ <para>This template matches the XML document instance,
+ <emphasis>not</emphasis> the visible <tag
+ class="element"><memo></tag> node.</para>
+ </callout>
+
+ <callout arearefs="programlisting_tolist_xpath_memo_to">
+ <para>The <link
+ xlink:href="http://www.w3.org/TR/xpath">XPath</link> expression
+ <tag class="attvalue">memo/to</tag> gets evaluated starting from
+ the invisible top level document node being the context node. For
+ the given document instance this will define a result set
+ containing both <tag class="element"><to></tag> recipient
+ nodes, see <xref linkend="figure_memo_xpath_memo_to"/>.</para>
+ </callout>
+
+ <callout arearefs="programlisting_tolist_value_of">
+ <para>The dot <quote>.</quote> represents the <code>#PCDATA</code>
+ content of the current <tag class="element">to</tag>
+ element.</para>
+ </callout>
+
+ <callout arearefs="programlisting_tolist_xsl_text">
+ <para>A comma is appended. This is not quite correct since it
+ should be absent for the last element.</para>
+ </callout>
+ </calloutlist>
+
+ <figure xml:id="figure_recipientlist_trailing_comma">
+ <title>A list of recipients.</title>
+
+ <para>The <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> presented
+ before yields:</para>
+
+ <programlisting language="none"><computeroutput>Adam Hacker,Eve Intruder</computeroutput><emphasis
+ role="bold">,</emphasis></programlisting>
+ </figure>
+
+ <para>Right now we do not bother about the trailing <quote>,</quote>
+ after the last recipient. The surrounding
+ <code><xsl:text></code>,<code></xsl:text></code> elements
+ <emphasis>may</emphasis> be omitted. We encourage the reader to leave
+ them in place since they increase readability when a template's body
+ gets more complex. The element <tag class="starttag">xsl:text</tag> is
+ used to append static text to the output. This way we append a
+ separator after each recipient. We now discuss the role of the two
+ attributes <tag class="attribute">match="/"</tag> and <tag
+ class="attribute">select=memo/to</tag>. Both are examples of so called
+ <link xlink:href="http://www.w3.org/TR/xpath">XPath</link>
+ expressions. They allow to define <emphasis>node sets</emphasis> being
+ subsets from the set of all nodes from a given document
+ instance.</para>
+
+ <para>Conceptually <link
+ xlink:href="http://www.w3.org/TR/xpath">XPath</link> expressions may
+ be compared to the <acronym
+ xlink:href="http://en.wikipedia.org/wiki/Sql">SQL</acronym> language
+ the latter allowing the retrieval of data<emphasis>sets</emphasis>
+ from a relational database. We illustrate the current example by a
+ figure:</para>
+
+ <figure xml:id="figure_memo_xpath_memo_to">
+ <title>Selecting node sets from <tag class="element">memo</tag>
+ document instances</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/memoxpath.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>This figure needs some explanation. We observe an additional
+ node <quote>above</quote> <tag class="starttag">memo</tag> being
+ represented as <quote>filled</quote>. This node represents the
+ document instance as a whole and has got <tag>memo</tag> as its only
+ child. We will rediscover this additional root node when we discuss
+ the <abbrev
+ xlink:href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407">DOM</abbrev>
+ application programming interface.</para>
+
+ <para>As already mentioned the expression <code>memo/to</code>
+ evaluates to a <emphasis>set</emphasis> of nodes. In our example this
+ set consists of two nodes of type <tag class="starttag">to</tag> each
+ of them representing a recipient of the memo. We observe a subtle
+ difference between the two <abbrev
+ xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev>
+ expressions:</para>
+
+ <glosslist>
+ <glossentry>
+ <glossterm><code>match="/"</code></glossterm>
+
+ <glossdef>
+ <para>The expression starts and actually consists of the string
+ <quote>/</quote>. Thus it can be called an
+ <emphasis>absolute</emphasis> <abbrev
+ xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev>
+ expression. Like a file specification
+ <filename>C:\dos\myprog.exe</filename> it starts on top level
+ and needs no further context information to get
+ evaluated.</para>
+
+ <para>A <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> style
+ sheet <emphasis>must</emphasis> have an <link
+ xlink:href="http://www.w3.org/TR/xslt20/#initiating">initial
+ context node</link> to start the transformation. This is
+ achieved by providing exactly one <tag
+ class="starttag">xsl:template</tag> with an absolute <abbrev
+ xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev> value for
+ its <tag class="attribute">match</tag> attribute like <tag
+ class="attvalue">/memo</tag>.<emphasis/></para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm><code>select="memo/to"</code></glossterm>
+
+ <glossdef>
+ <para>This expression can be compared to a
+ <emphasis>relative</emphasis> file path specification like e.g.
+ <filename>../images/hdm.gif</filename>. We need to add the base
+ (context) directory in order for a relative file specification
+ to become meaningful. If the base directory is
+ <filename>/home/goik/xml</filename> than this
+ <emphasis>relative</emphasis> file specification will address
+ the file <filename>/home/goik/images/hdm.gif</filename>.</para>
+
+ <para>Likewise we have to define a <emphasis>context</emphasis>
+ node if we want to evaluate a relative <abbrev
+ xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev>
+ expression. In our example this is the root node. The XSL
+ specification introduces the term <link
+ xlink:href="http://www.w3.org/TR/xslt20/#context">evaluation
+ context</link> for this purpose.</para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+
+ <para>In order to explain relative <abbrev
+ xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev> expressions we
+ consider <code>content/para</code> starting from the (unique!) <tag
+ class="element">memo</tag> node:</para>
+
+ <figure xml:id="memoXpathPara">
+ <title>The node set represented by <code>content/para</code>
+ starting at the context node <tag
+ class="starttag">memo</tag>.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/memorelativexpath.fig"/>
+ </imageobject>
+
+ <caption>
+ <para>The dashed lines represent the relative <abbrev
+ xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev>
+ expressions starting from the context node to each of the nodes
+ in the result set.</para>
+ </caption>
+ </mediaobject>
+ </figure>
+ </section>
+
+ <section xml:id="xsl_important_elements">
+ <title>Some important <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> elements</title>
+
+ <section xml:id="xsl_if">
+ <title><tag class="starttag">xsl:if</tag></title>
+
+ <para>Sometimes we need conditional processing rules. We might want
+ create a list of sender and recipients with a defined value for the
+ attribute <tag class="attribute">id</tag>. In the <link
+ linkend="figure_memoref_instance">given example</link> this is only
+ valid for the (unique) sender and the recipient <code><to
+ id="eve">Eve Intruder</to></code>. We assume this set of
+ persons shall be inserted into a relational database table
+ <code>Customer</code> consisting of two <code>NOT NULL</code>
+ columns <code>id</code> an <code>name</code>. Thus both attributes
+ <emphasis>must</emphasis> be specified and we must exclude <tag
+ class="starttag">from</tag> or <tag class="starttag">to</tag> nodes
+ with undefined <tag class="attribute">id</tag> attributes:</para>
+
+ <figure xml:id="programlisting_memo_export_sql">
+ <title>Exporting SQL statements.</title>
+
+ <programlisting language="none">...
+<xsl:variable name="newline" <co xml:id="programlisting_xsl_if_definevar"/>> <!-- A newline \n -->
+ <xsl:text>
+</xsl:text>
+</xsl:variable>
+
+<xsl:template match="/memo">
+ <xsl:for-each select="from|to" <co xml:id="programlisting_xsl_if_foreach"/>>
+ <xsl:if <emphasis role="bold">test="@id"</emphasis> <co
+ xml:id="programlisting_xsl_if_test"/>>
+ <xsl:text>INSERT INTO Customer (id, name) VALUES ('</xsl:text>
+ <xsl:value-of select="@id" <co
+ xml:id="programlisting_xsl_if_select_idattrib"/>/>
+ <xsl:text>', '</xsl:text>
+ <xsl:value-of select="." <co
+ xml:id="programlisting_xsl_if_selectcontent"/>/>
+ <xsl:text>')</xsl:text>
+ <xsl:value-of select="$newline" <co
+ xml:id="programlisting_xsl_if_usevar"/>/>
+ </xsl:if>
+ </xsl:for-each>
+</xsl:template></programlisting>
+
+ <caption>
+ <para>We want to export data from XML documents to a database
+ server. For this purpose INSERT statements are being crafted
+ from a XML document containing relevant data.</para>
+ </caption>
+ </figure>
+
+ <calloutlist>
+ <callout arearefs="programlisting_xsl_if_definevar">
+ <para>Define a file local variable <code>newline</code>. Dealing
+ with text output frequently requires the insertion of newlines.
+ Due to the syntax of the <tag class="element">xsl:text</tag>
+ elements this tends to clutter the code.</para>
+ </callout>
+
+ <callout arearefs="programlisting_xsl_if_foreach">
+ <para>Iterate over the set of the sender node and all recipient
+ nodes.</para>
+ </callout>
+
+ <callout arearefs="programlisting_xsl_if_test">
+ <para>The attribute value of <tag class="attribute">test</tag>
+ will be <link
+ xlink:href="http://www.w3.org/TR/xslt20/#xsl-if">evaluated</link>
+ as a boolean. In this example it evaluates to <code>true</code>
+ iff the attribute <tag class="attribute">id</tag> is defined for
+ the context node. Since we are inside the <tag
+ class="element">xsl:for-each</tag> block all context nodes are
+ either of type <tag class="starttag">from</tag> or <tag
+ class="starttag">to</tag> and thus <emphasis>may</emphasis> have
+ an <tag class="attribute">id</tag> attribute.</para>
+ </callout>
+
+ <callout arearefs="programlisting_xsl_if_select_idattrib">
+ <para>The <tag class="attribute">id</tag> attributes value is
+ copied to the output. The <quote>@</quote> character in
+ <code>select="@id"</code> tells the <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> processor
+ to read the value of an <emphasis>attribute</emphasis> with name
+ <tag class="attribute">id</tag> rather then the content of a
+ nested sub<emphasis>element</emphasis> like in <code><to
+ id="foo"><id>I am
+ nested!</id></to></code>.</para>
+ </callout>
+
+ <callout arearefs="programlisting_xsl_if_selectcontent">
+ <para>As stated earlier the dot <quote>.</quote> denotes the
+ current context element. In this example simply the
+ <code>#PCDATA</code> content is copied to the output.</para>
+ </callout>
+
+ <callout arearefs="programlisting_xsl_if_usevar">
+ <para>The <quote>$</quote> sign in front of <code>newline</code>
+ tells the <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> processor
+ to access the variable <varname>newline</varname> previously
+ defined in <coref linkend="programlisting_xsl_if_definevar"/>
+ rather then interpreting it as the name of a sub element or an
+ attribute.</para>
+ </callout>
+ </calloutlist>
+
+ <para>As expected the recipient entry <quote>Adam Hacker</quote>
+ does not appear due to the fact that no <tag
+ class="attribute">id</tag> attribute is defined in its <tag
+ class="starttag">to</tag> element:</para>
+
+ <programlisting language="none"><computeroutput>INSERT INTO Customer (id, name) VALUES ('goik', 'Martin Goik')
+INSERT INTO Customer (id, name) VALUES ('eve', 'Eve intruder')</computeroutput></programlisting>
+
+ <qandaset defaultlabel="qanda" xml:id="example_position_last">
+ <title>The XPath functions position() and last()</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>We return to our recipient list in <xref
+ linkend="figure_recipientlist_trailing_comma"/>. We are
+ interested in a list of recipients avoiding the trailing
+ comma:</para>
+
+ <programlisting language="none"><computeroutput>Adam Hacker,Eve Intruder</computeroutput></programlisting>
+
+ <para>We may use a <tag class="element">xsl:if</tag> to
+ insert a comma for all but the very last recipient node.
+ This can be achieved by using the <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev>
+ functions <link
+ xlink:href="http://www.w3.org/TR/xpath#function-position">position()</link>
+ and <link
+ xlink:href="http://www.w3.org/TR/xpath#function-last">last()</link>.
+ Hint: The arithmetic operator <quote><</quote> may be
+ used in <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> to
+ compare two integer numbers. However it must be escaped as
+ <code>&lt;</code> in order to be XML compatible.</para>
+ </question>
+
+ <answer>
+ <para>We have to exclude the comma for the last node of the
+ recipient list. If we have e.g. 10 recipients the function
+ <code>position()</code> will return values integer values
+ starting at 1 and ending with 10. So for the last node the
+ comparison <code>10 < 10</code> will evaluate to
+ false:</para>
+
+ <programlisting language="none"><xsl:for-each select="memo/to">
+ <xsl:value-of select="."/>
+ <xsl:if test="position() &lt; last()">
+ <xsl:text>,</xsl:text>
+ </xsl:if>
+</xsl:for-each></programlisting>
+ </answer>
+ </qandaentry>
+
+ <qandaentry xml:id="example_avoid_xsl_if">
+ <question>
+ <label>Avoiding xsl:if</label>
+
+ <para>In <xref linkend="programlisting_memo_export_sql"/> we
+ used the <abbrev
+ xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev> value
+ <quote>from|to</quote> to select the desired sender and
+ recipient nodes. Inside the <tag
+ class="element">xsl:for-each</tag> block we permitted only
+ those nodes which have an <tag class="attribute">id</tag>
+ attribute. These two steps may be combined into a single
+ <abbrev
+ xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev>
+ expression obsoleting the <tag
+ class="element">xsl:if</tag>.</para>
+ </question>
+
+ <answer>
+ <para>We simply need a modified <abbrev
+ xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev> in
+ the <tag class="element">for-each</tag>:</para>
+
+ <programlisting language="none"><xsl:for-each select="<emphasis
+ role="bold">from[@id]|to[@id]</emphasis>">
+ <xsl:text>INSERT INTO Customer (id, name) VALUES ('</xsl:text>
+ <xsl:value-of select="@id"/>
+ <xsl:text>', '</xsl:text>
+ <xsl:value-of select="."/>
+ <xsl:text>')</xsl:text>
+ <xsl:value-of select="$newline"/>
+</xsl:for-each></programlisting>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+
+ <section xml:id="xsl_apply_templates">
+ <title><tag class="starttag">xsl:apply-templates</tag></title>
+
+ <para>We already used <tag class="element">xsl:for-each</tag> to
+ iterate over a list of element nodes. <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> offers a
+ different possibility for this purpose. The idea is to define the
+ formatting rules at a centralized location. So the solution to <xref
+ linkend="example_position_last"/> in an equivalent way:</para>
+
+ <programlisting language="none"><xsl:template match="/">
+ <xsl:apply-templates select="memo/to" <co
+ xml:id="programlisting_apply_templates_apply"/>/>
+</xsl:template>
+
+<xsl:template match="to" <co xml:id="programlisting_apply_templates_match"/>>
+ <xsl:value-of select="."/>
+ <xsl:if test="<emphasis role="bold">position()</emphasis> &lt; <emphasis
+ role="bold">last()</emphasis>">
+ <xsl:text>,</xsl:text>
+ </xsl:if>
+</xsl:template></programlisting>
+
+ <calloutlist>
+ <callout arearefs="programlisting_apply_templates_apply">
+ <para>Definition of the recipient node list. Each element of
+ this list shall be processed further.</para>
+ </callout>
+
+ <callout arearefs="programlisting_apply_templates_match">
+ <para>This template <emphasis>may</emphasis> be used by a XSL
+ processor to format nodes of type <tag
+ class="starttag">to</tag>. Since the processor is asked to do
+ exactly this in <xref
+ linkend="programlisting_apply_templates_apply"/> the current
+ template will <emphasis>really</emphasis> be used in this
+ example.</para>
+ </callout>
+ </calloutlist>
+
+ <para>The procedure outlined above may have the following
+ advantages:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Some elements being central for a DTD may appear at
+ different places. For example a <tag
+ class="starttag">title</tag> element is likely to appear as a
+ child of chapters, sections, tables figures and so on. It may be
+ sufficient to define a single template with a
+ <code>match="title"</code> attribute which contains all rules
+ being required.</para>
+ </listitem>
+
+ <listitem>
+ <para>Sometimes the body of a <tag
+ class="starttag">xsl:for-each</tag> ... <tag
+ class="endtag">xsl:for-each</tag> spans multiple screens thus
+ limiting code readability. Factoring out the body into a
+ template may avoid this obstacle.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>This method is well known from programming languages: If the
+ code inside a loop is needed multiple times or reaches a painful
+ line count <emphasis>good</emphasis> programmers tend to define a
+ separate method. For example:</para>
+
+ <programlisting language="none">for (int i = 0; i < 10; i++){
+ if (a[i] < b[i]){
+ max[i] = b;
+ } else {
+ max[i] = a;
+ }
+ ...
+}</programlisting>
+
+ <para>Inside the loop's body the relative maximum value of two
+ variables gets computed. This may be needed at several locations and
+ thus it is convenient to centralize this code into a method:</para>
+
+ <programlisting language="none">// cf. <xsl:template match="...">
+static int maximum(int a, int b){
+ if (a < b){
+ return b;
+ } else {
+ return a;
+ }
+}
+...
+// cf. <xsl:apply-templates select="..."/>
+for (int i = 0; i < 10; i++){
+ max[i] = maximum(a[i], b[i]);
+}</programlisting>
+
+ <para>So far calling a static method in <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> may be
+ compared to a <tag class="starttag">xsl:apply-templates</tag>. There
+ is however one big difference. In <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> the
+ <quote>method</quote> being called may not exist at all. A <tag
+ class="starttag">xsl:apply-templates</tag> instructs a processor to
+ format a set of nodes. It does not contain information about any
+ rules being defined to do this job:</para>
+
+ <programlisting language="none"><xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="2.0">
+
+ <xsl:output method="text"/>
+
+ <xsl:template match="/memo">
+ <xsl:apply-templates <emphasis role="bold">select="content"</emphasis>/>
+ </xsl:template>
+
+</xsl:stylesheet></programlisting>
+
+ <para>Since no suitable template supplying rules for <tag
+ class="starttag">content</tag> nodes exists a <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> processor uses
+ a default formatting rule instead:</para>
+
+ <programlisting language="none"><computeroutput>Thanks for your excellent work.Our firewall is definitely
+broken! This bug has been reported by the sender.</computeroutput></programlisting>
+
+ <para>We observe that the <code>#PCDATA</code> content strings of
+ the element itself and all (recursive) sub elements get glued
+ together into one string. In most cases this is definitely not
+ intended. Omitting a necessary template is usually a programming
+ error. It is thus good programming practice during style sheet
+ development to define a special template catching forgotten
+ rules:</para>
+
+ <programlisting language="none"><xsl:template match="/memo">
+ <xsl:apply-templates select="content"/>
+</xsl:template>
+
+<xsl:template match="*">
+ <xsl:message>
+ <xsl:text>Error: No template defined matching element '</xsl:text>
+ <xsl:value-of select="name(.)"/>
+ <xsl:text>'</xsl:text>
+ </xsl:message>
+</xsl:template></programlisting>
+
+ <para>The <quote>*</quote> matches any element if there is no <link
+ xlink:href="http://www.w3.org/TR/xslt20/#conflict">better
+ matching</link> rule defined. Since we did not supply any template
+ for <tag class="starttag">content</tag> nodes at all this default
+ template will match nodes of type <tag
+ class="starttag">content</tag>. The function <code>name()</code> is
+ predefined in <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> and returns
+ the element type name of a node. During the formatting process we
+ will now see the following warning message:</para>
+
+ <programlisting language="none"><computeroutput>Error: No template defined matching element 'content'</computeroutput></programlisting>
+
+ <para>We note that for document nodes <tag
+ class="starttag">xyz</tag><code>foo</code><tag
+ class="endtag">xyz</tag> containing only <code>#PCDATA</code> a
+ simple <tag class="emptytag">xsl:apply-templates select="xyz"</tag>
+ is sufficient: A <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> processor uses
+ its default rule and copies the node's content <code>foo</code> to
+ its output.</para>
+
+ <qandaset defaultlabel="qanda" xml:id="example_rdbms_person">
+ <title>Extending the export to a RDBMS</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>We assume that our RDBMS table <code>Customer</code>
+ from <xref linkend="programlisting_memo_export_sql"/> shall
+ be replaced by a table <code>Person</code>. We expect the
+ senders of memo documents to be employees of a given
+ company. Conversely the recipients of memos are expected to
+ be customers. Our <code>Person</code> table shall have a
+ <quote>tag</quote> like column named <code>type</code>
+ having exactly two allowed values <code>customer</code> or
+ <code>employee</code> being controlled by a
+ <code>CHECK</code> constraint, see <xref
+ linkend="table_person"/>. Create a style sheet generating
+ the necessary SQL statements from a memo document instance.
+ Hint: Define two different templates for <tag
+ class="starttag">from</tag> and <tag
+ class="starttag">to</tag> nodes.</para>
+ </question>
+
+ <answer>
+ <para>We define two templates differing only in the static
+ string value for a person's type. The relevant <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev>
+ portion reads:<programlisting language="none"><xsl:template match="/memo">
+ <xsl:apply-templates select="from|to"/>
+</xsl:template>
+
+<xsl:template match="from">
+ <xsl:text>INSERT INTO Person (name, type) VALUES('</xsl:text>
+ <xsl:value-of select="."/>
+ <xsl:text>', <emphasis role="bold">'employee'</emphasis>)</xsl:text>
+ <xsl:value-of select="$newline"/>
+</xsl:template>
+
+ <xsl:template match="to">
+ <xsl:text>INSERT INTO Person (name, type) VALUES('</xsl:text>
+ <xsl:value-of select="."/>
+ <xsl:text>', <emphasis role="bold">'customer'</emphasis>)</xsl:text>
+ <xsl:value-of select="$newline"/>
+</xsl:template></programlisting></para>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+
+ <table xml:id="table_person">
+ <title>The Person table</title>
+
+ <?dbhtml table-width="30%" ?>
+
+ <?dbfo table-width="40%" ?>
+
+ <tgroup cols="2">
+ <colspec colwidth="3*"/>
+
+ <colspec colwidth="2*"/>
+
+ <thead>
+ <row>
+ <entry>name</entry>
+
+ <entry>type</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>Martin Goik</entry>
+
+ <entry>employee</entry>
+ </row>
+
+ <row>
+ <entry>Adam Hacker</entry>
+
+ <entry>customer</entry>
+ </row>
+
+ <row>
+ <entry>Eve intruder</entry>
+
+ <entry>customer</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section xml:id="xsl_choose">
+ <title><tag class="starttag">xsl:choose</tag></title>
+
+ <para>We already described the <tag class="starttag">xsl:if</tag>
+ which can be compared to an <code>if(..){...}</code> statement in
+ many programming languages. The <tag
+ class="starttag">xsl:choose</tag> element can be compared to
+ multiple <code>else</code> conditions including an optional final
+ <code>else</code> block being reached if all boolean tests
+ fail:</para>
+
+ <programlisting language="none">if (condition a){
+...//block 1
+} else if (condition b){
+... //block b
+} ...
+...
+else {
+ ... //code being reached whan all conditions evaluate to false
+}</programlisting>
+
+ <para>We want to generate a list of memo recipient names with roman
+ type numeration up to 10. Higher numbers shall be displayed in
+ ordinary decimal notation:</para>
+
+ <programlisting language="none"><computeroutput>I:Adam Hacker
+II:Eve intruder
+III: ...
+IV: ...
+...</computeroutput></programlisting>
+
+ <para>Though <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> offers <link
+ xlink:href="http://www.w3.org/TR/xslt20/#convert">a better
+ way</link> we may generate these number literals by:</para>
+
+ <programlisting language="none"><xsl:template match="/memo">
+ <xsl:apply-templates select="to"/>
+</xsl:template>
+
+<xsl:template match="to">
+ <xsl:choose>
+ <xsl:when test="1 = position()">I</xsl:when>
+ <xsl:when test="2 = position()">II</xsl:when>
+ <xsl:when test="3 = position()">III</xsl:when>
+ <xsl:when test="4 = position()">IV</xsl:when>
+ <xsl:when test="5 = position()">V</xsl:when>
+ <xsl:when test="6 = position()">VI</xsl:when>
+ <xsl:when test="7 = position()">VII</xsl:when>
+ <xsl:when test="8 = position()">VIII</xsl:when>
+ <xsl:when test="9 = position()">IX</xsl:when>
+ <xsl:when test="10 = position()">X</xsl:when>
+ <xsl:otherwise>
+ <xsl:value-of select="position()"/>
+ </xsl:otherwise>
+ </xsl:choose>
+
+ <xsl:text>:</xsl:text>
+ <xsl:value-of select="."/>
+ <xsl:value-of select="$newline"/>
+</xsl:template></programlisting>
+
+ <para>Note that this conversion is incomplete: If the number in
+ question is larger than 10 it will be formatted in ordinary decimal
+ style according to the <tag class="starttag">xsl:otherwise</tag>
+ clause.</para>
+ </section>
+
+ <section xml:id="section_html_book">
+ <title>A complete HTML formatting example</title>
+
+ <para>We now present a series of exercises showing how to format
+ <tag class="starttag">book</tag> document instances to XHTML. This
+ is done in a step by step manner each time showing correspondent
+ code snippets for our <filename>memo.dtd</filename>.</para>
+
+ <section xml:id="section_memo_to_list">
+ <title>Listing the recipients of a memo</title>
+
+ <para>In order to generate a XHTML <link
+ xlink:href="http://www.w3.org/TR/html401/struct/lists.html#h-10.2">list</link>
+ of all <tag class="starttag">memo</tag> recipients of a memo we
+ have to use <tag class="starttag">xsl:output method="xhtml"</tag>
+ and embed the required HTML tags in our <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> style
+ sheet:</para>
+
+ <programlisting language="none"><xsl:output method="xhtml" indent="yes"/>
+
+<xsl:template match="/memo">
+ <html>
+ <head>
+ <title>Recipient list</title>
+ </head>
+ <body>
+ <ul>
+ <xsl:apply-templates select="to"/>
+ </ul>
+ </body>
+ </html>
+</xsl:template>
+
+<xsl:template match="to">
+ <li>
+ <xsl:value-of select="."/>
+ </li>
+</xsl:template></programlisting>
+
+ <para>Processing this style sheet for a <tag
+ class="starttag">memo</tag> document instance yields:</para>
+
+ <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
+<html>
+ <head>
+ <title>Recipient list</title>
+ </head>
+ <body>
+ <ul>
+ <li>Adam Hacker</li>
+ <li>Eve intruder</li>
+ </ul>
+ </body>
+</html></programlisting>
+
+ <para>The generated Xhtml code does not contain a reference to a
+ DTD. We may supply this reference by modifying our <tag
+ class="emptytag">xsl:output</tag> directive:</para>
+
+ <programlisting language="none"><xsl:output method="xhtml" indent="yes"
+ <emphasis role="bold">doctype-public</emphasis>="-//W3C//DTD XHTML 1.0 Strict//EN"
+ <emphasis role="bold">doctype-system</emphasis>="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"/></programlisting>
+
+ <para>This adds a corresponding header which allows to validate
+ the generated HTML:</para>
+
+ <programlisting language="none"><!DOCTYPE html
+ PUBLIC "<emphasis role="bold">-//W3C//DTD XHTML 1.0 Strict//EN</emphasis>"
+ "<emphasis role="bold">http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd</emphasis>">
+<html><head> ...</programlisting>
+
+ <para>This may be improved further by instructing the XSL
+ formatter to use <uri
+ xlink:href="http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</uri>
+ as default namespace:</para>
+
+ <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet <emphasis role="bold">xmlns="http://www.w3.org/1999/xhtml"</emphasis>
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0">
+
+<xsl:output method="xhtml" indent="yes"
+ doctype-public="-//W3C//DTD XHTML 1.0 Strict//EN"
+ doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"/>
+
+ <xsl:template match="/">
+ <html><head> ...
+ </xsl:template>
+...
+</xsl:stylesheet></programlisting>
+
+ <para>This yields the following output::</para>
+
+ <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html
+ PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+
+<html <emphasis role="bold">xmlns="http://www.w3.org/1999/xhtml"</emphasis>>
+ <head> ...
+</html></programlisting>
+
+ <para>The top level element <tag class="element">html</tag> is now
+ declared to belong to the namespace
+ <code>xmlns="http://www.w3.org/1999/xhtml</code>. This will be
+ inherited by all inner Xhtml elements.</para>
+
+ <qandaset defaultlabel="qanda" xml:id="example_xsl_book_1_dtd">
+ <title>Transforming book instances to Xhtml</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>Create a <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev>
+ style sheet to transform instances of the first version of
+ <link endterm="example_bookDtd"
+ linkend="example_bookDtd">book.dtd</link> (<xref
+ linkend="example_bookDtd"/>) into <uri
+ xlink:href="http://www.w3.org/TR/xhtml1/#a_dtd_XHTML-1.0-Strict">Xhtml
+ 1.0 strict</uri>.</para>
+
+ <para>You should first construct a Xhtml document
+ <emphasis>manually</emphasis> before coding the XSL. After
+ you have a <quote>working</quote> Xhtml example document
+ create a <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev>
+ style sheet which transforms arbitrary
+ <filename>book.dtd</filename> document instances into a
+ corresponding Xhtml file.</para>
+ </question>
+
+ <answer>
+ <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0">
+
+ <xsl:output indent="yes" method="xhtml"/>
+
+ <xsl:template match="/book">
+ <html>
+ <head>
+ <title><xsl:value-of select="title"/></title>
+ </head>
+ <body>
+ <h1><xsl:value-of select="title"/></h1>
+ <xsl:apply-templates select="chapter"/>
+ </body>
+ </html>
+ </xsl:template>
+
+ <xsl:template match="chapter">
+ <h2><xsl:value-of select="title"/></h2>
+ <xsl:apply-templates select="para"/>
+ </xsl:template>
+
+ <xsl:template match="para">
+ <p><xsl:value-of select="."/></p>
+ </xsl:template>
+
+</xsl:stylesheet></programlisting>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+
+ <section xml:id="section_xsl_attribute">
+ <title><tag class="starttag">xsl:attribute</tag></title>
+
+ <para>Sometimes we want to set attribute values in a generated XML
+ document. For example we might want to set the background color
+ <quote>red</quote> if a memo has a priority value of <tag
+ class="attvalue">high</tag>:</para>
+
+ <programlisting language="none"><h1 style="background:red">Firewall problems</h1></programlisting>
+
+ <para>Regarding our memo example this may be achieved by:</para>
+
+ <programlisting language="none"><xsl:template match="/memo">
+ <html>
+ ...
+ <body>
+ <xsl:variable name="<emphasis role="bold">messageColor</emphasis>" <co
+ xml:id="programlisting_priority_lolor_vardef"/>>
+ <xsl:choose>
+ <xsl:when test="@priority = 'low'">green</xsl:when>
+ <xsl:when test="@priority = 'medium'">yellow</xsl:when>
+ <xsl:when test="@priority = 'high'">red</xsl:when>
+ </xsl:choose>
+ </xsl:variable>
+ <h1 style="background:{<emphasis role="bold">$messageColor</emphasis>};" <co
+ xml:id="programlisting_priority_lolor_usevar"/>>
+ <xsl:value-of select="subject"/>
+ </h1>
+ </body>
+ </html>
+</xsl:template></programlisting>
+
+ <calloutlist>
+ <callout arearefs="programlisting_priority_lolor_vardef">
+ <para>Definition of a color name depending on the attribute
+ <tag class="attvalue">priority</tag>'s value. The set off
+ possible attribute values (low,medium,high) is mapped to the
+ color names (green, yellow,red).</para>
+ </callout>
+
+ <callout arearefs="programlisting_priority_lolor_usevar">
+ <para>The color variable is used to compose the attribute <tag
+ class="attribute">style</tag>'s value. The curly
+ <code>{...}</code> braces are part of the <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev>
+ standard's syntax. They are required here to instruct the
+ <abbrev xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev>
+ processor to substitute the local variable
+ <code>messageColor</code>'s value instead of simply copying
+ the literal string <quote><code>$messageColor</code></quote>
+ itself to the output document e.g. generating <tag
+ class="starttag">h1 style =
+ "background:$messageColor;"</tag>.</para>
+ </callout>
+ </calloutlist>
+
+ <para>Instead of constructing an extra variable <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> offers a
+ slightly more compact way for the same purpose. The <tag
+ class="starttag">xsl:attribute</tag> element allows us to define
+ the name of an attribute to be added together with an attribute
+ value specification:</para>
+
+ <programlisting language="none"><xsl:template match="/memo">
+ <html>
+ ...
+ <h1>
+ <xsl:attribute name="<emphasis role="bold">style</emphasis>">
+ <xsl:text>background:</xsl:text>
+ <xsl:choose>
+ <xsl:when test="@priority = 'low'">green</xsl:when>
+ <xsl:when test="@priority = 'medium'">yellow</xsl:when>
+ <xsl:when test="@priority = 'high'">red</xsl:when>
+ </xsl:choose>
+ </xsl:attribute>
+ <xsl:value-of select="subject"/>
+ </h1>
+ </body>
+ </html>
+</xsl:template></programlisting>
+
+ <qandaset defaultlabel="qanda" xml:id="example_book_toc">
+ <title>Adding a table of contents (toc)</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>For larger document instances it is convenient to
+ add a table of contents to the generated Xhtml document.
+ <!-- We
+ demonstrate the desired result as an <uri
+ xlink:href="src/viewlet/bookhtmltoc/bookhtmltoc_viewlet_swf.html">animation</uri>.--></para>
+
+ <para>For this exercise you need a unique string value for
+ each <tag class="starttag">chapter</tag> node. If a <tag
+ class="starttag">chapter</tag>'s <tag
+ class="attribute">id</tag> attribute had been declared as
+ <code>#REQUIRED</code> its value would do this job
+ perfectly. Unfortunately you cannot rely on its existence
+ since it is declared to be <code>#IMPLIED</code> and may
+ thus be absent.</para>
+
+ <para>XSL offers a standard function for this purpose
+ namely <link
+ xlink:href="http://www.w3.org/TR/xslt20/#generate-id">generate-id(...)</link>.
+ In a nutshell this function takes a XML node as an
+ argument (or being called without arguments it uses the
+ context node) and creates a string value being unique with
+ respect to <emphasis>all</emphasis> other nodes in the
+ document. For a given node the function may be called
+ repeatedly and is guaranteed to always return the same
+ value during the <emphasis>same</emphasis> transformation
+ run. So it suffices to add something like <tag
+ class="starttag">a href="#{generate-id(...)}"</tag> or use
+ it in conjunction with <tag
+ class="starttag">xsl:attribute</tag>.</para>
+ </question>
+
+ <answer>
+ <para>We use the <code>generate-id()</code> function to
+ create a unique identity string for each chapter node.
+ Since we also want to define links to the table of
+ contents we need another unique string value. It is
+ tempting to simply use a static value like
+ <quote>__toc__</quote> for this purpose. However we can
+ not be sure that this value coincides with one of the
+ <code>generate-id()</code> function return values.</para>
+
+ <para>A cleaner solution uses the <tag
+ class="starttag">book</tag> node's generated identity
+ string for this purpose. As stated before this value is
+ definitively unique:</para>
+
+ <programlisting language="none"><xsl:template match="/book">
+...
+ <body>
+ <h1><xsl:value-of select="title"/></h1>
+ <h2 id="{generate-id(.)}" <co xml:base=""
+ xml:id="programlisting_book_toc_def_toc"/>>Table of contents</h2>
+ <ul>
+ <xsl:for-each select="chapter">
+ <li>
+ <a href="#{generate-id(.)}" <co xml:base=""
+ xml:id="programlisting_book_toc_ref_chap"/>><xsl:value-of select="title"></xsl:value-of></a>
+ </li>
+ </xsl:for-each>
+ </ul>
+ <xsl:apply-templates select="chapter"/>
+ </body>
+ </html>
+</xsl:template>
+
+<xsl:template match="chapter">
+ <h2 id="{generate-id(.)}" <co xml:base=""
+ xml:id="programlisting_book_toc_def_chap"/>>
+ <a href="#{generate-id(/book)}" <co xml:base=""
+ xml:id="programlisting_book_toc_ref_toc"/>>
+ <xsl:value-of select="title"/>
+ </a>
+ </h2>
+ <xsl:apply-templates select="para"/>
+</xsl:template>
+...</programlisting>
+
+ <calloutlist>
+ <callout arearefs="programlisting_book_toc_def_toc">
+ <para>The current context node is <tag
+ class="starttag">book</tag>. We use it as argument to
+ <code>generate-id()</code> to create a unique identity
+ string.</para>
+ </callout>
+
+ <callout arearefs="programlisting_book_toc_ref_chap">
+ <para>The <tag class="starttag">xsl:for-each</tag>
+ iterates over all <tag class="starttag">chapter</tag>
+ nodes. We reference the corresponding target nodes
+ being created in <xref
+ linkend="programlisting_book_toc_def_chap"/>.</para>
+ </callout>
+
+ <callout arearefs="programlisting_book_toc_def_chap">
+ <para>Each <tag class="starttag">chapter</tag>'s
+ heading is supplied with a unique identity string
+ being referenced from <xref
+ linkend="programlisting_book_toc_ref_chap"/>.</para>
+ </callout>
+
+ <callout arearefs="programlisting_book_toc_ref_toc">
+ <para>Clicking on a chapter's title shall take us back
+ to the table of contents (toc). So we create a
+ hypertext link referencing our toc heading's identity
+ string being defined in <xref
+ linkend="programlisting_book_toc_def_toc"/>.</para>
+ </callout>
+ </calloutlist>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+
+ <section xml:id="section_xsl_mixed">
+ <title>XSL and mixed content</title>
+
+ <para>The subsequent example shows an element <tag
+ class="starttag">content</tag> having a mixed content model
+ possibly containing <tag class="starttag">url</tag> and <tag
+ class="starttag">emphasis</tag> child nodes:</para>
+
+ <programlisting language="none"><content>The <emphasis
+ role="bold"><url href="http://w3.org/XML">XML</url></emphasis> language
+ is <emphasis role="bold"><emphasis>easy</emphasis></emphasis> to learn. However you need
+ some <emphasis role="bold"><emphasis>time</emphasis></emphasis>.</content></programlisting>
+
+ <para>Embedded element nodes have been set to bold style in order
+ to distinguish them from <code>xs:text</code> nodes. A possible
+ <acronym>XHtml</acronym> output might look like:</para>
+
+ <programlisting language="none"><p>The <emphasis role="bold"><a href="http://w3.org/XML">XML</a>language is<em>easy</em></emphasis> to learn. However you
+need some <emphasis role="bold"><em>time</em></emphasis>.</p></programlisting>
+
+ <para>We start with a first version of an <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev>
+ template:</para>
+
+ <programlisting language="none"> <xsl:template match="content">
+ <p>
+ <xsl:value-of select="."/>
+ </p>
+ </xsl:template></programlisting>
+
+ <para>As mentioned earlier all <code>#PCDATA</code> text nodes of
+ the whole subtree are glued together leading to:</para>
+
+ <programlisting language="none"><p>The XML language is easy to learn. However you need some time.</p></programlisting>
+
+ <para>Our next attempt is to define templates to format the
+ elements <tag class="starttag">url</tag> and <tag
+ class="starttag">emphasis</tag>:</para>
+
+ <programlisting language="none">...
+<xsl:template match="content">
+ <p>
+ <xsl:apply-templates select="emphasis|url"/>
+ </p>
+</xsl:template>
+
+<xsl:template match="url">
+ <a href="{@href}"><xsl:value-of select="."/></a>
+</xsl:template>
+
+<xsl:template match="emphasis">
+ <em><xsl:value-of select="."/></em>
+</xsl:template>
+...</programlisting>
+
+ <para>As expected the sub elements are formatted correctly.
+ Unfortunately the <code>#PCDATA</code> text nodes between the
+ element nodes are lost:</para>
+
+ <programlisting language="none"><p>
+ <a href="http://w3.org/XML">XML</a>
+ <em>easy</em>
+ <em>time</em>
+</p></programlisting>
+
+ <para>To correct this transformation script we have to tell the
+ formatting processor to include bare text nodes into the output.
+ The <abbrev xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev>
+ standard defines a function <link
+ xlink:href="http://www.w3.org/TR/xpath#path-abbrev">text()</link>
+ for this purpose. It returns the boolean value <code>true</code>
+ for an argument node of type text:</para>
+
+ <programlisting language="none">...
+<xsl:template match="content">
+ <p>
+ <xsl:apply-templates select="<emphasis role="bold">text()</emphasis>|emphasis|url"/>
+ </p>
+</xsl:template>
+...</programlisting>
+
+ <para>The yields the desired output. The text node result elements
+ are shown in bold style</para>
+
+ <programlisting language="none"><p><emphasis role="bold">The</emphasis> <a href="http://w3.org/XML">XML</a><emphasis
+ role="bold"> language is </emphasis><em>easy</em><emphasis
+ role="bold"> to learn. However
+you need some </emphasis><em>time</em><emphasis role="bold">.</emphasis></p></programlisting>
+
+ <para>Some remarks:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>The <abbrev
+ xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev>
+ expression <code>select="text()|emphasis|url"</code>
+ corresponds nicely to the content model definition in the
+ DTD:</para>
+
+ <programlisting language="none"><!ELEMENT content (#PCDATA|emphasis|url)*></programlisting>
+ </listitem>
+
+ <listitem>
+ <para>In most mixed content models <emphasis>all</emphasis>
+ sub elements of e.g. <tag class="starttag"
+ role="">content</tag> have to be formatted. During development
+ some of the elements defined in a DTD are likely to be omitted
+ by accidence. For this reason the <quote>typical</quote>
+ <abbrev xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev>
+ expression acting on mixed content models is defined to match
+ <emphasis>any</emphasis> sub element nodes:</para>
+
+ <programlisting language="none">select="text()|<emphasis
+ role="bold">*</emphasis>"</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>Regarding <code>select="text()|emphasis|url"</code> we
+ have defined two templates for element nodes <tag
+ class="starttag">emphasis</tag> and <tag
+ class="starttag">url</tag>. What happens to those text nodes
+ being matched by <code>text()</code>? These are subject to a
+ default rule: The content of bare text nodes is written to the
+ output. We may however redefine this default rule by adding a
+ template:</para>
+
+ <programlisting language="none"><xsl:template match="text()">
+ <emphasis role="bold"><span style="color:red">
+ <xsl:value-of select="."/>
+ </span></emphasis>
+</xsl:template></programlisting>
+
+ <para>This yields:</para>
+
+ <programlisting language="none"><p>
+ <emphasis role="bold"><span style="color:red">The </span></emphasis>
+ <a href="http://w3.org/XML">XML</a>
+ <emphasis role="bold"><span style="color:red"> language is </span></emphasis>
+ <em>easy</em>
+ <emphasis role="bold"><span style="color:red"> to learn. However you need some </span></emphasis>
+ <em>time</em>
+ <emphasis role="bold"><span style="color:red">.</span></emphasis>
+</p></programlisting>
+
+ <para>In most cases it is not desired to replace all text
+ nodes throughout the whole document. In the current example we
+ might only format text nodes being
+ <emphasis>immediate</emphasis> children of <tag
+ class="starttag">content</tag>. This may be achieved by
+ restricting the <abbrev
+ xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev>
+ expression to <tag class="starttag">xsl:template
+ match="content/text()"</tag>.</para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section xml:id="section_xsl_functionid">
+ <title>The function <code>id()</code></title>
+
+ <para>In <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> we sometimes
+ want to lookup nodes by an attribute value of type <link
+ xlink:href="???">ID</link>. We consider our product catalog from
+ <xref linkend="sectSchemaProductCatalog"/>. The following <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> may be used
+ to create <acronym>XHtml</acronym>l documents from <tag
+ class="starttag">catalog</tag> instances:</para>
+
+ <programlisting language="none" xml:lang=""><xsl:template match="/catalog">
+ <html>
+ <head><title>Product catalog</title></head>
+ <body>
+ <h1>List of Products</h1>
+ <xsl:apply-templates select="product"/>
+ </body>
+ </html>
+</xsl:template>
+
+<xsl:template match="product">
+ <h2 id="{@id}" <co xml:base=""
+ xml:id="programlisting_catalog2html_v1_defid"/>><xsl:value-of select="title"/></h2>
+ <xsl:apply-templates select="para"/>
+</xsl:template>
+
+<xsl:template match="para">
+ <p><xsl:apply-templates select="text()|*" <co
+ xml:id="programlisting_catalog2html_v1_mixed"/>/></p>
+</xsl:template>
+
+<xsl:template match="link">
+ <a href="#{@ref}" <co xml:id="programlisting_catalog2html_v1_refid"/>><xsl:value-of select="."/></a>
+</xsl:template></programlisting>
+
+ <calloutlist>
+ <callout arearefs="programlisting_catalog2html_v1_defid">
+ <para>The <code>ID</code> attribute <tag
+ class="starttag">product id="foo"</tag> is unique within the
+ document instance. We may thus use it as an unique string
+ value in the generated Xhtml, too.</para>
+ </callout>
+
+ <callout arearefs="programlisting_catalog2html_v1_mixed">
+ <para>Mixed content consisting of text and <tag
+ class="starttag">link</tag> nodes.</para>
+ </callout>
+
+ <callout arearefs="programlisting_catalog2html_v1_refid">
+ <para>We define a file local Xhtml reference to a
+ product.</para>
+ </callout>
+ </calloutlist>
+
+ <para>The <tag class="starttag">para</tag> element from the
+ example document instance containing a <tag class="starttag">link
+ ref="homeTrainer"</tag> reference will be formatted as:</para>
+
+ <programlisting language="none"><p>If you hate rain look <a href="#homeTrainer">here</a>.</p></programlisting>
+
+ <para>Now suppose we want to add the product's title
+ <emphasis>Home trainer</emphasis> here to give the reader an idea
+ about the product without clicking the hypertext link:</para>
+
+ <programlisting language="none"><p>If you hate rain look <a href="#homeTrainer">here</a> <emphasis
+ role="bold">(Home trainer)</emphasis>.</p></programlisting>
+
+ <para>This title text node is part of the <tag
+ class="starttag">product</tag>node being referenced from the
+ current <tag class="starttag">para</tag>:</para>
+
+ <figure xml:id="linkIdrefProduct">
+ <title>A graphical representation of our <tag
+ class="starttag">catalog</tag>.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/xsl_id.fig"/>
+ </imageobject>
+
+ <caption>
+ <para>The dashed line shows the <code>IDREF</code> based
+ reference from the <tag class="starttag">link</tag> to the
+ <tag class="starttag">product</tag> node.</para>
+ </caption>
+ </mediaobject>
+ </figure>
+
+ <para>In <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> we may
+ follow <code>ID</code> reference by means of the built in function
+ <link
+ xlink:href="http://www.w3.org/TR/xpath#function-id">id(...)</link>:</para>
+
+ <programlisting language="none"><xsl:template match="link">
+ <a href="#{@ref}"><xsl:value-of select="."/></a>
+ <xsl:text> (</xsl:text>
+ <xsl:value-of select="<emphasis role="bold">id(@ref)</emphasis>/title" <co
+ xml:id="programlisting_xsl_id_follow"/>/>
+ <xsl:text>)</xsl:text>
+</xsl:template></programlisting>
+
+ <para>Evaluating <code>id(@ref)</code> at <xref
+ linkend="programlisting_xsl_id_follow"/> returns the first <tag
+ class="starttag">product</tag> <emphasis>node</emphasis>. We
+ simply take its <tag class="starttag">title</tag> value and embed
+ it into a pair of braces. This way the desired text portion
+ <emphasis role="bold">(Home trainer)</emphasis> gets added after
+ the hypertext link.</para>
+
+ <qandaset defaultlabel="qanda" xml:id="example_book_xsl_mixed">
+ <title>Extending the memo style sheet by mixed content and
+ itemized lists</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>In <xref linkend="example_book.dtd_v5"/> we
+ constructed a DTD allowing itemized lists an mixed content
+ for <tag class="starttag">book</tag> instances. This DTD
+ also allowed to define <tag
+ class="starttag">emphasis</tag>, <tag
+ class="starttag">table</tag> and <tag
+ class="starttag">link</tag> elements being part of a mixed
+ content definition. Extend the current book2html.xsl to
+ account for these extensions.</para>
+
+ <para
+ xlink:href="http://www.w3.org/TR/xslt20/#element-copy-of">As
+ we already saw in our memo example itemized lists in Xhtml
+ are represented by the element <tag
+ class="starttag">ul</tag> containing <tag
+ class="starttag">li</tag> elements. Since <tag
+ class="starttag">p</tag> elements are also allowed to
+ appear as children our itemized lists can be easily mapped
+ to Xhtml tags. A<tag class="starttag">link</tag> node may
+ be transformed into <tag class="starttag">a
+ href="..."</tag> Xhtml node.</para>
+
+ <para>The table model is a simplified version of the Xhtml
+ table model. Read the <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev>
+ documentation of the element <tag
+ class="emptytag">xsl:copy-of</tag> at <link
+ xlink:href="http://www.w3.org/TR/xslt20/#element-copy-of">copy-of</link>
+ for processing tables.</para>
+ </question>
+
+ <answer>
+ <para>The full source code of the solution is available at
+ <link
+ xlink:href="Ref/src/Dtd/book/v5/book2html.1.xsl">(Online
+ HTML version) ... book2html.1.xsl</link>. We discuss some
+ important aspects. The following table provides mapping
+ rules from <filename>book.dtd</filename> to Xhtml:</para>
+
+ <table xml:id="table_book2xhtml_element_mappings">
+ <title>Mapping elements from
+ <filename>book.dtd</filename> to Xhtml</title>
+
+ <?dbhtml table-width="50%" ?>
+
+ <?dbfo table-width="50%" ?>
+
+ <tgroup cols="2">
+ <colspec colwidth="3*"/>
+
+ <colspec colwidth="2*"/>
+
+ <thead>
+ <row>
+ <entry>book.dtd</entry>
+
+ <entry>Xhtml</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><tag class="starttag">book</tag>/<tag
+ class="starttag">title</tag></entry>
+
+ <entry><tag class="starttag">h1</tag></entry>
+ </row>
+
+ <row>
+ <entry><tag class="starttag">chapter</tag>/<tag
+ class="starttag">title</tag></entry>
+
+ <entry><tag class="starttag">h2</tag></entry>
+ </row>
+
+ <row>
+ <entry><tag class="starttag">para</tag> (mixed
+ content)</entry>
+
+ <entry><tag class="starttag">p</tag></entry>
+ </row>
+
+ <row>
+ <entry><tag class="starttag">link
+ href="foo"</tag></entry>
+
+ <entry><tag class="starttag">a
+ href="foo"</tag></entry>
+ </row>
+
+ <row>
+ <entry><tag class="starttag">emphasis</tag></entry>
+
+ <entry><tag class="starttag">em</tag></entry>
+ </row>
+
+ <row>
+ <entry><tag
+ class="starttag">itemizedlist</tag></entry>
+
+ <entry><tag class="starttag">ul</tag></entry>
+ </row>
+
+ <row>
+ <entry><tag class="starttag">listitem</tag></entry>
+
+ <entry><tag class="starttag">li</tag></entry>
+ </row>
+
+ <row>
+ <entry><tag class="starttag">table</tag>, <tag
+ class="starttag">caption</tag>,<tag
+ class="starttag">tr</tag>, <tag
+ class="starttag">td</tag> along with all
+ attributes</entry>
+
+ <entry>Identity copy</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>Since our table model is a subset of the HTML table
+ model we may simply copy corresponding nodes to the
+ output:</para>
+
+ <programlisting language="none"><xsl:template match="table">
+ <xsl:copy-of select="."/>
+</xsl:template></programlisting>
+
+ <para>Next we need rules for itemized lists and
+ paragraphs. Our model already implements lists in a way
+ that closely resembles XHTML lists. Since the structure
+ are compatible we only have to provide a mapping:</para>
+
+ <programlisting language="none"><xsl:template match="para">
+ <p id="{generate-id(.)}"><xsl:apply-templates select="text()|*" /></p>
+</xsl:template>
+
+<xsl:template match="itemizedlist">
+ <ul><xsl:apply-templates select="listitem"/></ul>
+</xsl:template>
+
+<xsl:template match="listitem">
+ <li><xsl:apply-templates select="*"/></li>
+</xsl:template></programlisting>
+
+ <para>Since <emphasis>all</emphasis> chapters are
+ reachable via hypertext links from the table of contents
+ we <emphasis>must</emphasis> supply a unique
+ <code>id</code> value <xref
+ linkend="programlisting_book2html_single_chapterid"/> for
+ <emphasis>all</emphasis> of them. Chapters and paragraphs
+ may be referenced by <tag class="starttag">link</tag>
+ elements and thus <emphasis>both</emphasis> need a unique
+ identity value. For simplicity we create both of them via
+ <code>generate-id()</code>. In a more sophisticated
+ solution the strategy would be slightly different:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>If a <tag class="starttag">chapter</tag> node
+ does have an <code>id</code> attribute defined then
+ take its value.</para>
+ </listitem>
+
+ <listitem>
+ <para>If a <tag class="starttag">chapter</tag> node
+ does <emphasis>not</emphasis> have an <code>id</code>
+ attribute defined then use
+ <code>generate-id()</code>.</para>
+ </listitem>
+
+ <listitem>
+ <para><tag class="starttag">para</tag> nodes only get
+ values in XHTML if they do have an <code>id</code>
+ attribute defined. This is consistent since these
+ nodes are never referenced from the table of contents.
+ Thus an identity is only required if the <tag
+ class="starttag">para</tag> node is referenced by a
+ <tag class="starttag">link</tag>. If that is a case
+ the <tag class="starttag">para</tag> surely does have
+ a defined identity value.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>We also have to provide a hypertext link <xref
+ linkend="programlisting_book2html_single_toclink"/> to the
+ table of contents:</para>
+
+ <programlisting language="none"><xsl:template match="chapter">
+ <h2 id="{<emphasis role="bold">generate-id(.)</emphasis>}" <co
+ xml:base=""
+ xml:id="programlisting_book2html_single_chapterid"/>>
+ <a href="#{<emphasis role="bold">generate-id(/book)</emphasis>}" <co
+ xml:base=""
+ xml:id="programlisting_book2html_single_toclink"/>><xsl:value-of select="title"/></a>
+ </h2>
+ <xsl:apply-templates select="para|itemizedlist|table"/>
+</xsl:template></programlisting>
+
+ <para>Implementing the <tag class="starttag">link</tag>
+ element is somewhat more complicated. We cannot use the
+ <code>@ref</code> attribute values itself as <tag
+ class="starttag">a href="..."</tag> attribute values since
+ the target's identity string is generated via
+ <code>generate-id()</code>. But we may follow the
+ reference via the <abbrev
+ xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev>
+ <link linkend="section_xsl_functionid">id()</link>
+ function and then use the target's identity value:</para>
+
+ <programlisting language="none"><xsl:template match="link">
+ <a href="#{generate-id(id(@linkend))}">
+ <xsl:value-of select="."/>
+ </a>
+</xsl:template></programlisting>
+
+ <para>The call to <code>id(@linkend)</code> returns either
+ a <tag class="starttag">chapter</tag> or a <tag
+ class="starttag">para</tag> node since according to the
+ DTD attributes of type <code>ID</code> are only defined
+ for these two elements. Using this node as input to
+ <code>generate-id()</code> returns the desired identity
+ value for the generated Xhtml.</para>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+
+ <section xml:id="xslAxis">
+ <title>XSL axis definitions</title>
+
+ <para>XSL allows us to traverse a document instance's graph in
+ different directions. We start with a memo document
+ instance:</para>
+
+ <programlisting language="none"><!DOCTYPE memo SYSTEM "memo.dtd">
+<memo date="9.9.2099">
+ <from>Joe</from>
+ <to>Jack</to>
+ <to>Eve</to>
+ <to>Jude</to>
+ <to>Tolstoi</to>
+ <subject>Ignore me!</subject>
+ <content>
+ <para>Dumb text.</para>
+ </content>
+</memo></programlisting>
+
+ <para>This instance defines four nodes of type <tag
+ class="starttag">to</tag>. For each of these we want to create a
+ line of text showing also the preceding and the following
+ recipients:</para>
+
+ <programlisting language="none"> <----Jack----> Eve Jude Tolstoi <co
+ xml:id="programlisting_axis_jack"/>
+Jack <----Eve----> Jude Tolstoi <co xml:id="programlisting_axis_eve"/>
+Jack Eve <----Jude----> Tolstoi <co xml:id="programlisting_axis_jude"/>
+Jack Eve Jude <----Tolstoi----> <co
+ xml:id="programlisting_axis_tolstoi"/></programlisting>
+
+ <calloutlist>
+ <callout arearefs="programlisting_axis_jack">
+ <para>Jack has no predecessor and 3 successors</para>
+ </callout>
+
+ <callout arearefs="programlisting_axis_eve">
+ <para>Eve has 1 predecessor and 2 successors</para>
+ </callout>
+
+ <callout arearefs="programlisting_axis_jude">
+ <para>Jude has 2 predecessors and 1 successor</para>
+ </callout>
+
+ <callout arearefs="programlisting_axis_tolstoi">
+ <para><personname>Tolstoi</personname> has 3 predecessors and
+ no successor</para>
+ </callout>
+ </calloutlist>
+
+ <para>XSL supports this type of transformation by supplying
+ <acronym xlink:href="http://www.w3.org/TR/xpath">XPath</acronym>
+ axis definitions. We consider a memo document with 9 <tag
+ class="starttag">to</tag> nodes:</para>
+
+ <figure xml:id="memo9recipients">
+ <title>A memo with 9 recipients</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/memofour.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>We marked the 4-th recipient to represent the context node.
+ All three <tag class="starttag">to</tag> nodes to the
+ <quote>left</quote> belong to the <emphasis>set</emphasis> of
+ preceding siblings with respect to the context node. Likewise the
+ 5 neighbours to the right are called following siblings. Returning
+ to our <quote>four recipient</quote> example we may create the
+ desired output by:</para>
+
+ <programlisting language="none"><xsl:template match="/">
+ <xsl:apply-templates select="memo/to"/>
+</xsl:template>
+
+<xsl:template match="to">
+
+ <xsl:for-each select="preceding-sibling::to" <co
+ xml:id="programlisting_memo_four_xsl_preceding"/>>
+ <xsl:value-of select="."/>
+ <xsl:text> </xsl:text>
+ </xsl:for-each>
+
+ <xsl:text> &lt;----</xsl:text>
+ <xsl:value-of select="."/> <co
+ xml:id="programlisting_memo_four_xsl_context"/>
+ <xsl:text>----&gt; </xsl:text>
+
+ <xsl:for-each select="following-sibling::to"> <co
+ xml:id="programlisting_memo_four_xsl_following"/>
+ <xsl:value-of select="."/>
+ <xsl:text> </xsl:text>
+ </xsl:for-each>
+ <xsl:value-of select="$newline"/>
+</xsl:template></programlisting>
+
+ <calloutlist>
+ <callout arearefs="programlisting_memo_four_xsl_preceding">
+ <para>Iterate on the set of recipients <quote>left</quote> of
+ the context node.</para>
+ </callout>
+
+ <callout arearefs="programlisting_memo_four_xsl_context">
+ <para>Taking the context node's value embedded in
+ <code><---- ... ----></code>.</para>
+ </callout>
+
+ <callout arearefs="programlisting_memo_four_xsl_following">
+ <para>Iterate on the set of recipients <quote>right</quote> of
+ the context node.</para>
+ </callout>
+ </calloutlist>
+
+ <para>More formally the set of preceding siblings is defined to be
+ the set of all nodes having the same parent as the context node
+ and appearing <quote>before</quote> the context node. The notion
+ <quote>before</quote> is meant in the sense of a <link
+ xlink:href="http://en.wikipedia.org/wiki/Depth-first_search">depth-first</link>
+ traversal of the document tree. <abbrev
+ xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev> provides
+ different axis definitions, see <uri
+ xlink:href="http://www.w3.org/TR/xpath#axes">http://www.w3.org/TR/xpath#axes</uri>
+ for details. We provide an illustration here:</para>
+
+ <figure xml:id="disjointAxeSets">
+ <title>Disjoint <acronym
+ xlink:href="http://www.w3.org/TR/xpath">XPath</acronym> axis
+ definitions.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/preceding.fig"/>
+ </imageobject>
+
+ <caption>
+ <para>The sets defined by ancestor, descendant, following,
+ preceding and self are disjoint. Their union forms the set
+ of all document nodes.</para>
+ </caption>
+ </mediaobject>
+ </figure>
+
+ <para>Some remarks:<itemizedlist>
+ <listitem>
+ <para>If the context node is already the topmost node i.e.
+ the root node then the sets defined by <code>ancestor</code>
+ and <code>parent</code> are empty.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <code>parent</code> set
+ <emphasis>always</emphasis> contains zero or one
+ node.</para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section xml:id="xslChunking">
+ <title>Splitting documents into chunks</title>
+
+ <para>Sometimes we want to generate multiple output documents from
+ a single XML source. It may for example be a bad idea to transform
+ a book of 200 printed pages into a <emphasis>single</emphasis>
+ online HTML page. Instead we may split each chapter into a
+ separate HTML file and create navigation links between
+ them.</para>
+
+ <para>We consider a memo document instance. We want to generate
+ one text file for each memo recipient containing just the
+ recipient's name using the <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> element
+ <link
+ xlink:href="http://www.w3.org/TR/xslt20/#element-result-document"><xsl:result-document></link>:</para>
+
+ <programlisting language="none"><xsl:template match="/memo">
+ <xsl:apply-templates select="to"/>
+</xsl:template>
+
+<xsl:template match="to">
+ <emphasis role="bold"><xsl:result-document</emphasis>
+ <co xml:id="programlisting_xsl_result_document_main"/>
+ <emphasis role="bold">href="file_{position()}.txt"</emphasis>
+ <co xml:id="programlisting_xsl_result_document_href"/>
+ <emphasis role="bold">method="text"</emphasis>
+ <co xml:id="programlisting_xsl_result_document_method"/>>
+ <xsl:value-of select="."/> <co
+ xml:id="programlisting_xsl_result_document_content"/>
+
+ <emphasis role="bold"></xsl:result-document></emphasis>
+</xsl:template></programlisting>
+
+ <calloutlist>
+ <callout arearefs="programlisting_xsl_result_document_main">
+ <para>The output from all generating <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev>
+ directives will be redirected from standard output to another
+ output channel.</para>
+ </callout>
+
+ <callout arearefs="programlisting_xsl_result_document_href">
+ <para>The output will be written to a file named
+ <filename>file_i.txt</filename> with decimal number
+ <code>i</code> ranging from value 1 up to the number of
+ recipients.</para>
+ </callout>
+
+ <callout arearefs="programlisting_xsl_result_document_method">
+ <para>The <code>method</code> attribute possibly overrides a
+ value being given in the <tag
+ class="starttag">xsl:output</tag> element. We may also
+ redefine <link
+ xlink:href="http://www.w3.org/TR/xslt20/#element-result-document">other
+ attributes</link> from <tag class="starttag">xsl:output</tag>
+ like <code>doctype-{public.system}</code> and the generated
+ file's <code>encoding</code>.</para>
+ </callout>
+
+ <callout arearefs="programlisting_xsl_result_document_content">
+ <para>All output being generated in this region gets
+ redirected to the channel specified in <xref
+ linkend="programlisting_xsl_result_document_href"/>.</para>
+ </callout>
+ </calloutlist>
+
+ <qandaset defaultlabel="qanda" xml:id="example_book_chunk">
+ <title>Splitting book into chapter files</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>Extend your solution of <xref
+ linkend="example_book_xsl_mixed"/> by writing each <tag
+ class="starttag">chapter</tag>'s content into a separate
+ Xhtml file. In addition create a file
+ <filename>index.html</filename> which contains references
+ to the corresponding <tag class="starttag">chapter</tag>
+ documents. Thus for a document instance with two chapters
+ the overall navigation structure is illustrated by <xref
+ linkend="figure_book_navigation"/>.</para>
+
+ <para>Implementing the <tag class="starttag">link</tag>
+ tag may cause a problem: An internal link may reference a
+ <tag class="starttag">para</tag>. You need to identify the
+ <tag class="starttag">chapter</tag> node embedding this
+ para. This may be done by using a suitable <abbrev
+ xlink:href="http://www.w3.org/TR/xpath">XPath</abbrev>
+ axis direction.</para>
+ </question>
+
+ <answer>
+ <para>The full source code of the solution is available at
+ <link
+ xlink:href="Ref/src/Dtd/book/v5/book2chunks.1.xsl">(Online
+ HTML version) ... book2chunks.1.xsl</link>. First we
+ generate the table of contents file
+ <filename>index.html</filename>:</para>
+
+ <programlisting language="none"><xsl:template match="/">
+ <xsl:result-document href="index.html">
+ <xsl:apply-templates select="book"/>
+ </xsl:result-document>
+
+ <xsl:for-each select="book/chapter">
+ <xsl:result-document href="{generate-id(.)}.html">
+ <xsl:apply-templates select="."/>
+ </xsl:result-document>
+ </xsl:for-each>
+</xsl:template>
+
+<xsl:template match="book">
+ <html>
+ <head><title><xsl:value-of select="title"/></title></head>
+ <body>
+ <h1><xsl:value-of select="title"/></h1>
+ <h2>Table of contents</h2>
+ <ul>
+ <xsl:for-each select="<emphasis role="bold">chapter</emphasis>">
+ <li><a href="{<emphasis role="bold">generate-id(.)</emphasis>}.html"><xsl:value-of select="title"/></a></li>
+ </xsl:for-each>
+ </ul>
+ </body>
+ </html>
+</xsl:template></programlisting>
+
+ <para>The <tag class="starttag">link ref="..."</tag> may
+ reference a <tag class="starttag">chapter</tag> or a <tag
+ class="starttag">para</tag>. So we may need to <quote>step
+ up</quote> from a paragraph to the corresponding chapter
+ node:</para>
+
+ <programlisting language="none"><xsl:template match="link">
+ <xsl:variable name="reftargetNode" select="id(@linkend)"/>
+ <xsl:variable name="reftargetParentChapter"
+ select="$reftargetNode/ancestor-or-self::chapter"/>
+
+ <a href="{generate-id($reftargetParentChapter)}.html#{
+ generate-id($reftargetNode)}">
+ <xsl:value-of select="."/>
+ </a>
+</xsl:template></programlisting>
+
+ <para>This is consistent since <emphasis>all</emphasis>
+ <tag class="starttag">p</tag> nodes in the generated Xhtml
+ receive a unique <code>id</code> value regardless whether
+ the originating <tag class="starttag">para</tag> node does
+ have one.</para>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+
+ <figure xml:id="figure_book_navigation">
+ <title>A <tag class="starttag">book</tag> document with two
+ chapters</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/booknavigate.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ </section>
+ </section>
+ </chapter>
+
+ <chapter xml:id="xmlApis">
+ <title><abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Api">API</abbrev>s for XML
+ document processing</title>
+
+ <section xml:id="sax">
+ <title>The Simple API for XML</title>
+
+ <section xml:id="saxPrinciple">
+ <title>The principle of a <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym>
+ application</title>
+
+ <para>We are already familiar with transformations of XML document
+ instances to other formats. Sometimes the capabilities being offered
+ by a given transformation approach do not suffice for a given
+ problem. Obviously a general purpose programming language like <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> offers
+ superior means to perform advanced manipulations of XML document
+ trees.</para>
+
+ <para>Before diving into technical details we present an example
+ exceeding the limits of our present transformation capabilities. We
+ want to format an XML catalog document with article descriptions to
+ HTML. The price information however shall resides in a XML document
+ external database namely a RDBMS:</para>
+
+ <figure xml:id="saxRdbmsAccessPrinciple">
+ <title>Generating HTML from a XML document and an RDBMS.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/saxxmlrdbms.fig" scale="65"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Our catalog might look like:</para>
+
+ <figure xml:id="simpleCatalog">
+ <title>A <link linkend="gloss_XML"><abbrev>XML</abbrev></link>
+ based catalog.</title>
+
+ <programlisting language="none"><catalog>
+ <item orderNo="<emphasis role="bold">3218</emphasis>">Swinging headset</item>
+ <item orderNo="<emphasis role="bold">9921</emphasis>">200W Stereo Amplifier</item>
+</catalog></programlisting>
+ </figure>
+
+ <para>The RDBMS may hold some relation with a field
+ <code>orderNo</code> as primary key and a corresponding attribute
+ like <code>price</code>. In a real world application
+ <code>orderNo</code> should probably be an integer typed
+ <code>IDENTITY</code> attribute.</para>
+
+ <figure xml:id="saxRdbmsSchema">
+ <title>A Relation containing price information.</title>
+
+ <programlisting language="none">CREATE TABLE Product (
+ orderNo CHAR(10) PRIMARY KEY
+ ,price Money
+)
+
+INSERT INTO Product VALUES('<emphasis role="bold">3218</emphasis>', 42.57)
+INSERT INTO Product VALUES('<emphasis role="bold">9921</emphasis>', 121.50)</programlisting>
+
+ <caption>
+ <para>Prices are depending on article numbers.</para>
+ </caption>
+ </figure>
+
+ <para>The intended HTML output with order numbers being highlighted
+ looks like:</para>
+
+ <figure xml:id="saxPriceOut">
+ <title>HTML generated output.</title>
+
+ <programlisting language="none"><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+ <html>
+ <head><title>Available products</title></head>
+ <body>
+ <table border="1">
+ <tbody>
+ <tr>
+ <th><emphasis role="bold">Order number</emphasis></th>
+ <th>Price</th>
+ <th>Product</th>
+ </tr>
+ <tr>
+ <td><emphasis role="bold">3218</emphasis></td>
+ <td>42,57</td>
+ <td>Swinging headset</td>
+ </tr>
+ <tr>
+ <td><emphasis role="bold">9921</emphasis></td>
+ <td>121,50</td>
+ <td>200W Stereo Amplifier</td>
+ </tr>
+ </tbody>
+ </table>
+ </body>
+ </html></programlisting>
+
+ <caption>
+ <para>This result HTML document contains content both from our
+ XML document an from the database table
+ <code>Product</code>.</para>
+ </caption>
+ </figure>
+
+ <para>The intended transformation is beyond the XSLT standard's
+ processing capabilities: XSLT does not enable us to RDBMS content.
+ However some XSLT processors provide extensions for this
+ task.</para>
+
+ <para>It is tempting to write a <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> application
+ which might use e.g. <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ for database access. But how do we actually read and parse a XML
+ file? Sticking to the <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> standard we
+ might use a <link
+ xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/java/io/FileInputStream.html">FileInputStream</link>
+ instance to read from <code>catalog.xml</code> and write a XML
+ parser by ourself. Fortunately <orgname>SUN</orgname>'s <trademark
+ xlink:href="http://www.oracle.com/technetwork/java/javase">JDK</trademark>
+ already includes an API denoted <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym>, the
+ <emphasis>S</emphasis>imple <emphasis>A</emphasis>pi for
+ <emphasis>X</emphasis>ml. The<productname
+ xlink:href="http://www.oracle.com/technetwork/java/javase/jdk-7-readme-429198.html">JDK</productname>
+ also includes a corresponding parser implementation. In addition
+ there are third party <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> parser
+ implementations available like <productname
+ xlink:href="http://xerces.apache.org">Xerces</productname> from the
+ <orgname xlink:href="http://www.apache.org">Apache
+ Foundation</orgname>.</para>
+
+ <para>The <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> API is event
+ based and will be illustrated by the relationship between customers
+ and a software vendor company:</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/updateinfo.fig"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>After purchasing software customers are asked to register
+ their software. This way the vendor receives the customer's address.
+ Each time a new release is being completed all registered customers
+ will receive a notification typically including a <quote>special
+ offer</quote> to upgrade their software. From an abstract point of
+ view the following two actions take place:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Registration</term>
+
+ <listitem>
+ <para>The customer registers itself at the company's site
+ indicating it's interest in updated versions.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notification</term>
+
+ <listitem>
+ <para>Upon completion of each new software release (considered
+ to be an <emphasis>event</emphasis>) a message is sent to all
+ registered customers.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The same principle applies to GUI applications in software
+ development. A key press <emphasis>event</emphasis> for example will
+ be forwarded by an application's <emphasis>event handler</emphasis>
+ to a callback function (sometimes called a
+ <emphasis>handler</emphasis> method) being implemented by an
+ application developer. The <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> API works the
+ same way: A parser reads a XML document generating events which
+ <emphasis>may</emphasis> be handled by an application. During
+ document parsing the XML tree structure gets
+ <quote>flattened</quote> to a sequence of events:</para>
+
+ <figure xml:id="saxFlattenEvent">
+ <title>Parsing a XML document creates a corresponding sequence of
+ events.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/saxmodel.pdf"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>An application may register components to the parser:</para>
+
+ <figure xml:id="figureSax">
+ <title><acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym>
+ Principle</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/saxapparch.pdf"/>
+ </imageobject>
+
+ <caption>
+ <para>A <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym>
+ application consists of a <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> parser
+ and an implementation of event handlers being specific to the
+ application. The application is developed by implementing the
+ two handlers.</para>
+ </caption>
+ </mediaobject>
+ </figure>
+
+ <para>An Error Handler is required since the XML stream may contain
+ errors. In order to implement a <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> application we
+ have to:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Instantiate required objects:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Parser</para>
+ </listitem>
+
+ <listitem>
+ <para>Event Handler</para>
+ </listitem>
+
+ <listitem>
+ <para>Error Handler</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>Register handler instances</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>register Event Handler to Parser</para>
+ </listitem>
+
+ <listitem>
+ <para>register Error Handler to Parser</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>Start the parsing process by calling the parser's
+ appropriate method.</para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section xml:id="saxIntroExample">
+ <title>First steps</title>
+
+ <para>Our first <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> toy application
+ <classname>sax.stat.v1.ElementCount</classname> shall simply count
+ the number of elements it finds in an arbitrary XML document. In
+ addition the <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> events shall be
+ written to standard output generating output sketched in <xref
+ linkend="saxFlattenEvent"/>. The application's central
+ implementation reads:</para>
+
+ <figure xml:id="saxElementCount">
+ <title>Counting XML elements.</title>
+
+ <programlisting language="none">package sax.stat.v1;
+...
+
+public class ElementCount {
+
+ public void parse(final String uri) {
+ try {
+ final SAXParserFactory saxPf = SAXParserFactory.newInstance();
+ final SAXParser saxParser = saxPf.newSAXParser();
+ saxParser.parse(uri, eventHandler);
+ } catch (ParserConfigurationException e){
+ e.printStackTrace(System.err);
+ } catch (org.xml.sax.SAXException e) {
+ e.printStackTrace(System.err);
+ } catch (IOException e){
+ e.printStackTrace(System.err);
+ }
+ }
+
+ public int getElementCount() {
+ return eventHandler.getElementCount();
+ }
+ private final MyEventHandler eventHandler = new MyEventHandler();
+}</programlisting>
+
+ <caption>
+ <para>This application works for arbitrary well-formed XML
+ documents.</para>
+ </caption>
+ </figure>
+
+ <para>We now explain this application in detail. The first part
+ deals with the instantiation of a parser:</para>
+
+ <programlisting language="none">try {
+ final SAXParserFactory saxPf = <emphasis role="bold">SAXParserFactory</emphasis>.newInstance();
+ final SAXParser saxParser = saxPf.newSAXParser();
+ saxParser.parse(uri, eventHandler);
+} catch (ParserConfigurationException e){
+ e.printStackTrace(System.err);
+} ...</programlisting>
+
+ <para>In order to keep an application independent from a specific
+ parser implementation the <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> uses the so
+ called <link
+ xlink:href="http://www.dofactory.com/Patterns/PatternAbstract.aspx">Abstract
+ Factory Pattern</link> instead of simply calling a constructor from
+ a vendor specific parser class.</para>
+
+ <para>In order to be useful the parser has to be instructed to do
+ something meaningful when a XML document gets parsed. For this
+ purpose our application supplies an event handler instance:</para>
+
+ <programlisting language="none">public void parse(final String uri) {
+ try {
+ final SAXParserFactory saxPf = SAXParserFactory.newInstance();
+ final SAXParser saxParser = saxPf.newSAXParser();
+ saxParser.parse(uri, <emphasis role="bold">eventHandler</emphasis>);
+ } catch (org.xml.sax.SAXException e) {
+ ...
+ private final MyEventHandler <emphasis role="bold">eventHandler = new MyEventHandler()</emphasis>;
+}</programlisting>
+
+ <para>What does the event handler actually do? It offers methods to
+ the parser being callable during the parsing process:</para>
+
+ <programlisting language="none">package sax.stat.v1;
+...
+public class MyEventHandler extends <classname>org.xml.sax.helpers.DefaultHandler</classname> {
+
+ public void <emphasis role="bold"><emphasis role="bold">startDocument()</emphasis></emphasis><co
+ xml:id="programlisting_eventhandler_startDocument"/> {
+ System.out.println("Opening Document");
+ }
+ public void <emphasis role="bold">endDocument()</emphasis><co
+ xml:id="programlisting_eventhandler_endDocument"/> {
+ System.out.println("Closing Document");
+ }
+ public void <emphasis role="bold">startElement(String namespaceUri, String localName, String rawName,
+ Attributes attrs)</emphasis> <co
+ xml:id="programlisting_eventhandler_startElement"/>{
+ System.out.println("Opening \"" + rawName + "\"");
+ elementCount++;
+ }
+ public void <emphasis role="bold">endElement(String namespaceUri, String localName,
+ String rawName)</emphasis><co
+ xml:id="programlisting_eventhandler_endElement"/>{
+ System.out.println("Closing \"" + rawName + "\"");
+ }
+ public void <emphasis role="bold">characters(char[] ch, int start, int length)</emphasis><co
+ xml:id="programlisting_eventhandler_characters"/>{
+ System.out.println("Content \"" + new String(ch, start, length) + '"');
+ }
+ public int getElementCount() <co
+ xml:id="programlisting_eventhandler_getElementCount"/>{
+ return elementCount;
+ }
+ private int elementCount = 0;
+}</programlisting>
+
+ <calloutlist>
+ <callout arearefs="programlisting_eventhandler_startDocument">
+ <para>This method gets called exactly once namely when opening
+ the XML document as a whole.</para>
+ </callout>
+
+ <callout arearefs="programlisting_eventhandler_endDocument">
+ <para>After successfully parsing the whole document instance
+ this method will finally be called.</para>
+ </callout>
+
+ <callout arearefs="programlisting_eventhandler_startElement">
+ <para>This method gets called each time a new element is parsed.
+ In the given catalog.xml example it will be called three times:
+ First when the <tag class="starttag">catalog</tag> appears and
+ then two times upon each <item ... >. The supplied
+ parameters depend whether or not name space processing is
+ enabled.</para>
+ </callout>
+
+ <callout arearefs="programlisting_eventhandler_endElement">
+ <para>Called each time an element like <tag
+ class="starttag">item ...</tag> gets closed by its counterpart
+ <tag class="endtag">item</tag>.</para>
+ </callout>
+
+ <callout arearefs="programlisting_eventhandler_characters">
+ <para>This method is responsible for the treatment of textual
+ content i.e. handling <code>#PCDATA</code> element content. We
+ will explain its uncommon signature a little bit later.</para>
+ </callout>
+
+ <callout arearefs="programlisting_eventhandler_getElementCount">
+ <para><function>getElementCount()</function> is a getter method
+ to read only access the private field
+ <varname>elementCount</varname> which gets incremented in <coref
+ linkend="programlisting_eventhandler_startElement"/> each time
+ an XML element opens.</para>
+ </callout>
+ </calloutlist>
+
+ <para>The call <code>saxParser.parse(uri, eventHandler)</code>
+ actually initiates the parsing process and tells the parser
+ to:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Open the XML document being referenced by the URI
+ argument.</para>
+ </listitem>
+
+ <listitem>
+ <para>Forward XML events to the event handler instance supplied
+ by the second argument.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>A driver class containing a <code>main(...)</code> method may
+ start the whole process and print out the desired number of elements
+ upon completion of a parsing run:</para>
+
+ <programlisting language="none">package sax.stat.v1;
+
+public class ElementCountDriver {
+ public static void main(String argv[]) {
+ ElementCount xmlStats = new ElementCount();
+ xmlStats.parse("<emphasis role="bold">Input/Sax/catalog.xml</emphasis>");
+ System.out.println("Document contains " + xmlStats.<emphasis role="bold">getElementCount()</emphasis> + " elements");
+ }
+}</programlisting>
+
+ <para>Processing the catalog example instance yields:</para>
+
+ <programlisting language="none">Opening Document
+<emphasis role="bold">Opening "catalog"</emphasis> <co
+ xml:id="programlisting_catalog_output"/>
+Content "
+ "
+<emphasis role="bold">Opening "item"</emphasis> <co
+ xml:id="programlisting_catalog_item1"/>
+Content "Swinging headset"
+Closing "item"
+Content "
+ "
+<emphasis role="bold">Opening "item"</emphasis> <co
+ xml:id="programlisting_catalog_item2"/>
+Content "200W Stereo Amplifier"
+Closing "item"
+Content "
+"
+Closing "catalog"
+Closing Document
+<emphasis role="bold">Document contains 3 elements</emphasis> <co
+ xml:id="programlisting_catalog_elementcount"/></programlisting>
+
+ <calloutlist>
+ <callout arearefs="programlisting_catalog_output">
+ <para>Start parsing element <tag
+ class="starttag">catalog</tag>.</para>
+ </callout>
+
+ <callout arch="" arearefs="programlisting_catalog_item1">
+ <para>Start parsing element <tag class="starttag">item
+ orderNo="3218"</tag>Swinging headset<tag class="endtag"
+ role="">item</tag>.</para>
+ </callout>
+
+ <callout arch="" arearefs="programlisting_catalog_item2">
+ <para>Start parsing element <tag class="starttag">item
+ orderNo="9921"</tag>200W Stereo Amplifier<tag class="endtag"
+ role="">item</tag>.</para>
+ </callout>
+
+ <callout arearefs="programlisting_catalog_elementcount">
+ <para>After the parsing process has completed the application
+ outputs the number of elements being counted so far.</para>
+ </callout>
+ </calloutlist>
+
+ <para>The output contains some lines of <quote>empty</quote>
+ content. This content is due to whitespace being located between
+ elements. For example a newline appears between the the <tag
+ class="starttag">catalog</tag> and the first <tag
+ class="starttag">item</tag> element. The parser encapsulates this
+ whitespace in a call to the <link
+ xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/org/xml/sax/ContentHandler.html#characters(char[],%20int,%20int)">characters</link>
+ method. In an application this call will typically be ignored. XML
+ document instances in a professional context will typically not
+ contain any newline characters at all. Instead the whole document is
+ represented as a single line. This inhibits human readability which
+ is not required if the processing applications work well. In this
+ case empty content as above will not appear.</para>
+
+ <para>The <code>characters(char[] ch, int start, int length)</code>
+ method's signature looks somewhat strange regarding <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> conventions.
+ One might expect <code>characters(String s)</code>. But this way the
+ <acronym xlink:href="http://www.saxproject.org">SAX</acronym> API
+ allows efficient parser implementations: A parser may initially
+ allocate a reasonable large <code>char</code> array of say 128 bytes
+ sufficient to hold 64 (<link
+ xlink:href="http://unicode.org">Unicode</link>) characters. If this
+ buffer gets exhausted the parser might allocate a second buffer of
+ double size thus implementing an <quote>amortized doubling</quote>
+ algorithm:</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/saxcharacter.pdf"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>In this example the first element content fits in the first
+ buffer. The second content <code>200W Stereo Amplifier</code> and
+ the third content <code>Earphone</code> both fit in the second
+ buffer. Subsequent content may require further buffer allocations.
+ Such a strategy minimizes the number of time consuming <code>new
+ </code> <link
+ xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/String.html">String</link>
+ <code>(...)</code> constructor calls being necessary for the more
+ convenient API variant <code>characters(String s)</code>.</para>
+ </section>
+
+ <section xml:id="saxRegistry">
+ <title>Event- and error handler registration</title>
+
+ <para>Our first <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> application
+ suffers from the following deficiencies:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The error handling is very sparse. It completely relies on
+ exceptions being thrown by classes like <link
+ xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/org/xml/sax/SAXException.html">SAXException</link>
+ which frequently do not supply meaningful error
+ information.</para>
+ </listitem>
+
+ <listitem>
+ <para>The application is not aware of namespaces. Thus reading
+ e.g. <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> document
+ instances will not allow to distinguish between elements from
+ different namespaces like HTML.</para>
+ </listitem>
+
+ <listitem>
+ <para>The parser will not validate a document instance against a
+ DTD being present.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>We now incrementally add these features to the <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> parsing
+ process. <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> offers an
+ interface <link
+ xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/org/xml/sax/XMLReader.html">XmlReader</link>
+ to conveniently <emphasis>register</emphasis> event- and error
+ handler instances instead of passing them as a separate argument to
+ the <link
+ xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/javax/xml/parsers/SAXParser.html#parse(java.lang.String,%20org.xml.sax.helpers.DefaultHandler)">parse</link>
+ method. We first code an error handler class by implementing the
+ interface <classname>org.xml.sax.ErrorHandler</classname> being part
+ of the <acronym xlink:href="http://www.saxproject.org">SAX</acronym>
+ API:</para>
+
+ <programlisting language="none">package sax.stat.v2;
+...
+public class MyErrorHandler implements ErrorHandler {
+
+ <emphasis role="bold">public void warning(SAXParseException e)</emphasis> {
+ System.err.println("[Warning]" + getLocationString(e));
+ }
+ <emphasis role="bold">public void error(SAXParseException e)</emphasis> {
+ System.err.println("[Error]" + getLocationString(e));
+ }
+ <emphasis role="bold">public void fatalError(SAXParseException e)</emphasis> throws SAXException{
+ System.err.println("[Fatal Error]" + getLocationString(e));
+ }
+ private String getLocationString(SAXParseException e) {
+ return " line " + e.getLineNumber() +
+ ", column " + e.getColumnNumber()+ ":" + e.getMessage();
+ }
+}</programlisting>
+
+ <para>These three methods represent the
+ <classname>org.xml.sax.ErrorHandler</classname> interface. The
+ method <function>getLocationString</function> is used to supply
+ precise parsing error locations by means of line- and column numbers
+ within a document instance. If errors or warnings are encountered
+ the parser will call one of the appropriate public methods:</para>
+
+ <figure xml:id="saxMissItem">
+ <title>A non well formed document.</title>
+
+ <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
+<catalog>
+ <item orderNo="3218">Swinging headset</item>
+ <item orderNo="9921">200W Stereo Amplifier
+</catalog></programlisting>
+
+ <caption>
+ <para>This document is not well formed since due to a missing a
+ closing <tag class="endtag">item</tag> tag is missing.</para>
+ </caption>
+ </figure>
+
+ <para>Our error handler method gets called yielding an informative
+ message:</para>
+
+ <programlisting language="none">[Fatal Error] line 5, column -1:Expected "</item>" to terminate
+element starting on line 4.</programlisting>
+
+ <para>This error output is achieved by
+ <emphasis>registering</emphasis> an instance of
+ <classname>sax.stat.v2.MyErrorHandler</classname> to the parser
+ prior to starting the parsing process. In the following code snippet
+ we also register a content handler instance to the parser and thus
+ separate the parser's configuration from its invocation:</para>
+
+ <programlisting language="none">package sax.stat.v2;
+...
+public class ElementCount {
+ public ElementCount()
+ throws SAXException, ParserConfigurationException{
+ final SAXParserFactory saxPf = SAXParserFactory.newInstance();
+ final SAXParser saxParser = saxPf.newSAXParser();
+ xmlReader = saxParser.getXMLReader();
+ xmlReader.setContentHandler(eventHandler); <co
+ xml:id="programlisting_assemble_parser_setcontenthandler"/>
+ xmlReader.setErrorHandler(errorHandler); <co
+ xml:id="programlisting_assemble_parser_seterrorhandler"/>
+ }
+ public void parse(final String uri)
+ throws IOException, SAXException{
+ xmlReader.parse(uri); <co
+ xml:id="programlisting_assemble_parser_invokeparse"/>
+ }
+ public int getElementCount() {
+ return eventHandler.getElementCount(); <co
+ xml:id="programlisting_assemble_parser_getelementcount"/>
+ }
+ private final XMLReader xmlReader;
+ private final MyEventHandler eventHandler = new MyEventHandler(); <co
+ xml:id="programlisting_assemble_parser_createeventhandler"/>
+ private final MyErrorHandler errorHandler = new MyErrorHandler(); <co
+ xml:id="programlisting_assemble_parser_createerrorhandler"/>
+}</programlisting>
+
+ <calloutlist>
+ <callout arearefs="programlisting_assemble_parser_setcontenthandler programlisting_assemble_parser_seterrorhandler">
+ <para>Referring to <xref linkend="figureSax" os=""/> these two
+ calls attach the event- and error handler objects to the parser
+ thus implementing the two arrows from the parser to the
+ application's implementation.</para>
+ </callout>
+
+ <callout arearefs="programlisting_assemble_parser_invokeparse">
+ <para>The parser is invoked. Note that in this example we only
+ pass a document's URI but no reference to a handler
+ object.</para>
+ </callout>
+
+ <callout arearefs="programlisting_assemble_parser_getelementcount">
+ <para>The method <function>getElementCount()</function> is
+ needed to allow a calling object to access the private
+ <varname>eventHandler</varname> object's
+ <function>getElementCount()</function> method.</para>
+ </callout>
+
+ <callout arearefs="programlisting_assemble_parser_createeventhandler programlisting_assemble_parser_createerrorhandler">
+ <para>An event handling and an error handling object are created
+ to handle events during the parsing process.</para>
+ </callout>
+ </calloutlist>
+
+ <para>The careful reader might notice a subtle difference between
+ the content- and the error handler implementation: The class
+ <classname>sax.stat.v2.MyErrorHandler</classname> implements the
+ interface <classname>org.xml.sax.ErrorHandler</classname>. But
+ <classname>sax.stat.v2.MyEventHandler</classname> is derived from
+ <classname>org.xml.sax.helpers.DefaultHandler</classname> which
+ itself implements the
+ <classname>org.xml.sax.ContentHandler</classname> interface.
+ Actually one might as well start from the latter interface requiring
+ to implement all of it's 11 methods. In most circumstances this only
+ complicates the application's code since it is unnecessary to react
+ to events belonging for example to processing instructions. For this
+ reason it is good coding practice to use the empty default
+ implementations in
+ <classname>org.xml.sax.helpers.DefaultHandler</classname> and to
+ redefine only those methods corresponding to events actually being
+ handled by the application in question.</para>
+
+ <qandaset defaultlabel="qanda" xml:id="sda1SaxReadAttributes">
+ <title>SAX and attribute values</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <label>Reading an element's set of attributes.</label>
+
+ <para>The example document instance does include <tag
+ class="attribute">orderNo</tag> attribute values for each
+ <tag class="starttag">item</tag> element. The parser does
+ not yet show these attribute keys and their corresponding
+ values. Read the documentation for <classname
+ xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/org/xml/sax/Attributes.html">org.xml.sax.Attributes</classname>
+ and extend the given code to use it.</para>
+ </question>
+
+ <answer>
+ <para>For the given example it would suffice to read the
+ known <tag class="attribute">orderNo</tag> attributes value.
+ A generic solution may ask for the set of all defined
+ attributes and show their values:</para>
+
+ <programlisting language="none">package sax;
+
+public class AttribEventHandler extends DefaultHandler {
+
+ public void startElement(String namespaceUri, String localName,
+ String rawName, Attributes attrs) {
+ System.out.println("Opening Element " + rawName);
+ for (int i = 0; i < attrs.getLength(); i++){
+ System.out.println(attrs.getQName(i) + "=" + attrs.getValue(i) + "\n");
+ }
+ }
+}</programlisting>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+
+ <section xml:id="sda1SecElementLists">
+ <title>The set of element names</title>
+
+ <qandaset defaultlabel="qanda" xml:id="sda1QandaElementNames">
+ <title>Element lists of arbitrary XML documents.</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>We reconsider the simple application reading
+ arbitrary XML documents and providing a list of XML
+ Elements being contained within:</para>
+
+ <programlisting language="none">Opening Document
+<emphasis role="bold">Opening "catalog"</emphasis>
+Content "
+ "
+<emphasis role="bold">Opening "item"</emphasis>
+Content "Swinging headset"
+Closing "item"
+Content " ...</programlisting>
+
+ <para>If an element like e.g. <tag
+ class="starttag">item</tag> appears multiple times it will
+ also be written to standard output multiple times.</para>
+
+ <para>We are now interested to get the list of all
+ elements names being present in an arbitrary XML document.
+ Consider the following example:</para>
+
+ <programlisting language="none"><memo>
+ <from>
+ <name>Martin</name>
+ <surname>Goik</surname>
+ </from>
+ <to>
+ <name>Adam</name>
+ <surname>Hacker</surname>
+ </to>
+ <to>
+ <name>Eve</name>
+ <surname>Intruder</surname>
+ </to>
+ <date year="2005" month="1" day="6"/>
+ <subject>Firewall problems</subject>
+ <content>
+ <para>Thanks for your excellent work.</para>
+ <para>Our firewall is definitely broken!</para>
+ </content>
+</memo></programlisting>
+
+ <para>The elements <tag class="starttag">to</tag> , <tag
+ class="starttag">name</tag>, <tag
+ class="starttag">surname</tag> and <tag
+ class="starttag">para</tag> both appear multiple times.
+ Write a SAX application which processes arbitrary XML
+ documents and creates an alphabetically sorted list of
+ elements being contained <emphasis role="bold">excluding
+ duplicates</emphasis>. The intended output for the above
+ example is:</para>
+
+ <programlisting language="none">List of elements: {content date from memo name para subject surname to }</programlisting>
+
+ <para>The corresponding handler should be implemented in a
+ re-usable way. Thus if different XML documents are being
+ handled in succession the list of elements should be
+ erased prior to processing the current document.
+ Hints:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Use a <classname>java.util.SortedSet</classname>
+ instance to collect element names thereby excluding
+ duplicates.</para>
+ </listitem>
+
+ <listitem>
+ <para>The method
+ <methodname>sax.count.ListTagNamesHandler.startDocument()</methodname>
+ may be used to initialize your handler.</para>
+ </listitem>
+ </itemizedlist>
+ </question>
+
+ <answer>
+ <para>A suitable handler reads:</para>
+
+ <programlisting language="none">package sax.count;
+
+import java.util.SortedSet;
+import java.util.TreeSet;
+
+import org.xml.sax.Attributes;
+import org.xml.sax.SAXException;
+import org.xml.sax.helpers.DefaultHandler;
+
+/** Reading attributes from element events */
+public class ListTagNamesHandler extends DefaultHandler {
+
+ // A SortedSet by definition does not contain any duplicates.
+ private SortedSet<String> elementNames = new TreeSet<>();
+
+ @Override
+ public void startDocument() throws SAXException {
+ elementNames.clear(); // May contain elements from a previous run.
+ }
+
+ public void startElement(String namespaceUri, String localName,
+ String rawName, Attributes attrs) {
+ // In case the current element name has already been inserted
+ // this method call will be silently ignored.
+ elementNames.add(rawName);
+ }
+
+ /**
+ * @return A sorted list of element names of he currently processed XML
+ * document without duplicates.
+ */
+ public String[] getTagNames() {
+ return elementNames.toArray(new String[0]);
+ }
+}</programlisting>
+
+ <para>A complete application requires a driver:</para>
+
+ <programlisting language="none">package sax.count;
+
+import javax.xml.parsers.SAXParser;
+import javax.xml.parsers.SAXParserFactory;
+
+import org.xml.sax.XMLReader;
+
+import sax.stat.v2.MyErrorHandler;
+
+public class Driver {
+
+ public static void main(String argv[]) throws Exception {
+
+ final SAXParserFactory saxPf = SAXParserFactory.newInstance();
+ final SAXParser saxParser = saxPf.newSAXParser();
+ final XMLReader xmlReader = saxParser.getXMLReader();
+ final ListTagNamesHandler handler = new ListTagNamesHandler();
+ xmlReader.setContentHandler(handler);
+ xmlReader.setErrorHandler(new MyErrorHandler());
+ xmlReader.parse("Input/Xml/Memo/message.xml");
+
+ System.out.print("List of elements: {");
+ for (String elementName : handler.getTagNames()) {
+ System.out.print(elementName + " ");
+ }
+ System.out.println("}");
+ }
+}</programlisting>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+
+ <section xml:id="sda1SaxView">
+ <title>A limited view on a given XML document instance</title>
+
+ <qandaset defaultlabel="qanda" xml:id="sda1QandamemoView">
+ <title>A specific view on memo documents</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>We reconsider the following memo instance:</para>
+
+ <programlisting language="none"><memo>
+ <from>
+ <name>Martin</name>
+ <surname>Goik</surname>
+ </from>
+ <to>
+ <name>Adam</name>
+ <surname>Hacker</surname>
+ </to>
+ <to>
+ <name>Eve</name>
+ <surname>Intruder</surname>
+ </to>
+ <date year="2005" month="1" day="6"/>
+ <subject>Firewall problems</subject>
+ <content>
+ <para>Thanks for your excellent work.</para>
+ <para>Our firewall is definitely broken!</para>
+ </content>
+</memo></programlisting>
+
+ <para>Every memo instance does have exactly one sender and
+ one subject. Write a SAX application to achieve the
+ following output:</para>
+
+ <programlisting language="none">Sender: Martin Goik
+Subject: Firewall problems</programlisting>
+
+ <para>Hint: The callback implementation of
+ <methodname>org.xml.sax.helpers.DefaultHandler.characters(char[],int,int)</methodname>
+ may be used to filter the desired output. You have to
+ limit its output to <tag class="starttag">from</tag> and
+ <tag class="starttag">subject</tag> descendant content.
+ Taking the <tag class="starttag">subject</tag>Firewall
+ problems<tag class="endtag">subject</tag> element as an
+ example the corresponding event sequence reads:</para>
+
+ <informaltable border="1">
+ <tr>
+ <th>Event</th>
+
+ <th>Corresponding callback</th>
+ </tr>
+
+ <tr>
+ <td>...</td>
+
+ <td>...</td>
+ </tr>
+
+ <tr>
+ <td>Opening <tag class="starttag">subject</tag>
+ element</td>
+
+ <td>startElement(...)</td>
+ </tr>
+
+ <tr>
+ <td>Firewall problems</td>
+
+ <td>characters(...)</td>
+ </tr>
+
+ <tr>
+ <td>Closing <tag class="endtag">subject</tag>
+ element</td>
+
+ <td>endElement(...)</td>
+ </tr>
+
+ <tr>
+ <td>...</td>
+
+ <td>...</td>
+ </tr>
+ </informaltable>
+
+ <para>Limiting output of our
+ <methodname>org.xml.sax.helpers.DefaultHandler.characters(char[],int,int)</methodname>
+ callback method can be achieved by introducing instance
+ scope boolean variables being set to true or false inside
+ your
+ <methodname>org.xml.sax.helpers.DefaultHandler.startElement(String
+ uri,String localName,String qName,org.xml.sax.Attributes
+ attributes)</methodname> and
+ <methodname>org.xml.sax.helpers.DefaultHandler.endElement(String
+ uri, String localName, String qName)</methodname>
+ implementations accordingly to keep track of the current
+ event state.</para>
+ </question>
+
+ <answer>
+ <programlisting language="none">package sax.view;
+...
+/** A view on memo documents restricting to sender name an subject. */
+public class MemoViewHandler extends DefaultHandler {
+
+ // These variables help us to keep track of the current event state spanning
+ // each startElement(...) -- character(...) -- endElement(...) event sequence
+ boolean inFromContext = false,
+ inSubjectContext = false;
+
+ public void startElement(String namespaceUri, String localName,
+ String rawName, Attributes attrs) {
+ switch(rawName) {
+ case "from":
+ inFromContext = true;
+ System.out.print("Sender: ");
+ break;
+ case "subject":
+ inSubjectContext = true;
+ System.out.print("Subject: ");
+ break;
+ case "surname":
+ if (inFromContext) {
+ System.out.print(" "); // Adding additional space between <name> and <surname> content.
+ }
+ break;
+ }
+ }
+
+ @Override
+ public void endElement(String uri, String localName, String rawName)
+ throws SAXException {
+ switch(rawName) {
+ case "from":
+ inFromContext = false;
+ System.out.println();
+ break;
+ case "subject":
+ inSubjectContext = false;
+ System.out.println();
+ break;
+ }
+ }
+
+ @Override
+ public void characters(char[] ch, int start, int length) throws SAXException {
+ if (inFromContext || inSubjectContext) {
+ System.out.print(new String(ch, start, length));
+ }
+ }
+}</programlisting>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+ </section>
+
+ <section xml:id="saxValidate">
+ <title><acronym xlink:href="http://www.saxproject.org">SAX</acronym>
+ validation</title>
+
+ <para>So far we only parsed well formed document instances. Our
+ current parser may operate on valid XML instances:</para>
+
+ <figure xml:id="saxNotValid">
+ <title>An invalid XML document.</title>
+
+ <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE catalog [
+ <!ELEMENT catalog (item) >
+ <!ELEMENT item (#PCDATA) >
+<!ATTLIST item orderNo NMTOKEN #REQUIRED >
+]>
+<catalog>
+ <item orderNo="3218">Swinging headset</item>
+ <item orderNo="9921">200W Stereo Amplifier</item>
+</catalog></programlisting>
+
+ <caption>
+ <para>In contrast to <xref linkend="saxMissItem"/> this document
+ is well formed. But it is not <emphasis
+ role="bold">valid</emphasis> with respect to the DTD grammar
+ since more than one <tag class="starttag">item</tag> elements
+ are present.</para>
+ </caption>
+ </figure>
+
+ <para>This document instance is well-formed but not valid. The
+ parser will not report any error or warning. In order to enable
+ validation we need to configure our parser:</para>
+
+ <programlisting language="none">xmlReader.setFeature("http://xml.org/sax/features/validation", true);</programlisting>
+
+ <para>The string <code>http://xml.org/sax/features/validation</code>
+ serves as a key. Since this is an ordinary string value a parser may
+ or may not implement it. The <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> standard
+ defines two exception classes for dealing with feature related
+ errors:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><link
+ xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/org/xml/sax/SAXNotRecognizedException.html">SAXNotRecognizedException</link></term>
+
+ <listitem>
+ <para>The feature is not known to the parser.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><link
+ xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/org/xml/sax/SAXNotSupportedException.html">SAXNotSupportedException</link></term>
+
+ <listitem>
+ <para>The feature is known to the parser but the parser does
+ not support it or it does not support a specific value being
+ set as a value.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Though not strictly required SAX validation may need DTD
+ related (Entity) resolving. Having just SYSTEM identifier pointing
+ to remote network addresses like <code>... SYSTEM
+ "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd
+ ..."</code> may take a long time for download or even fail
+ completely. So XML catalog files are in order for validation being
+ based on locally available schemes or DTDs.</para>
+
+ <para>The <productname
+ xlink:href="http://projects.apache.org/projects/xml_commons_resolver.html">xml-commons
+ resolver project </productname>offers an implementation being able
+ to process various catalog file formats. Maven based project allow
+ the corresponding library import by adding the following
+ dependency:</para>
+
+ <programlisting language="none"><dependency>
+ <groupId>xml-resolver</groupId>
+ <artifactId>xml-resolver</artifactId>
+ <version>1.2</version>
+</dependency></programlisting>
+
+ <para>We need a properties file <link
+ xlink:href="http://xerces.apache.org/xml-commons/components/resolver/tips.html">CatalogManager.properties</link>
+ defining XML catalogs to be used and additional parameters:</para>
+
+ <programlisting language="none"># Catalogs are relative to this properties file
+relative-catalogs=false
+# Catalog list
+
+catalogs=\
+/usr/share/eclipse/dropins/oxygenxml.oxygen_14.2/plugins/com.oxygenxml.editor_14.2.0.v2013021115/frameworks/xhtml/dtd/xhtmlcatalog.xml;\
+/usr/share/eclipse/dropins/oxygenxml.oxygen_14.2/plugins/com.oxygenxml.editor_14.2.0.v2013021115/frameworks/xhtml11/dtd/xhtmlcatalog.xml
+# PUBLIC in favour of SYSTEM
+prefer=public</programlisting>
+
+ <para>This configuration uses some catalogs from the
+ <trademark>Oxygen</trademark> <trademark>Eclipse</trademark> plugin.
+ We may now add a resolver to our SAX application by referencing the
+ above configuration file <coref linkend="resolverPropertyFile"/> and
+ registering the resolver to our SAX parser instance <coref
+ linkend="resolverRegister"/>:</para>
+
+ <programlisting language="none">xmlReader = saxParser.getXMLReader();
+
+ // Set up resolving PUBLIC identifier
+ final CatalogManager cm = new CatalogManager("<emphasis role="bold">CatalogManager.properties</emphasis>" <co
+ xml:id="resolverPropertyFile"/> );
+ final CatalogResolver resolver = new CatalogResolver(cm);
+ xmlReader.setEntityResolver(resolver) <co xml:id="resolverRegister"/>;</programlisting>
+ </section>
+
+ <section xml:id="saxNamespace">
+ <title>Namespaces</title>
+
+ <para>In order to make a <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> parser
+ application namespace aware we have to activate two <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> parsing
+ features:</para>
+
+ <programlisting language="none">xmlReader = saxParser.getXMLReader();
+xmlReader.setFeature("http://xml.org/sax/features/namespaces", true);
+xmlReader.setFeature("http://xml.org/sax/features/namespace-prefixes", true);</programlisting>
+
+ <para>This instructs the parser to pass the namespace's name for
+ each element. Namespace prefixes like <code>xsl</code> in <tag
+ class="starttag">xsl:for-each</tag> are also passed and may be used
+ by an application:</para>
+
+ <programlisting language="none">package sax;
+...
+public class NamespaceEventHandler extends DefaultHandler {
+...
+ public void startElement(String <emphasis role="bold">namespaceUri</emphasis>, String localName,
+ String rawName, Attributes attrs) {
+ System.out.println("Opening Element rawName='" + rawName + "'\n"
+ + "namespaceUri='" + <emphasis role="bold">namespaceUri</emphasis> + "'\n"
+ + "localName='" + localName
+ + "'\n--------------------------------------------");
+}</programlisting>
+
+ <para>As an example we take a XSLT script:</para>
+
+ <programlisting language="none"><?xml version="1.0" encoding="utf-8"?>
+<xsl:stylesheet version="1.0"
+ xmlns:xsl='http://www.w3.org/1999/XSL/Transform'
+ xmlns:fo='http://www.w3.org/1999/XSL/Format'>
+
+ <xsl:template match="/">
+ <fo:block>A block</fo:block>
+ <HTML/>
+ </xsl:template>
+
+</xsl:stylesheet></programlisting>
+
+ <para>This XSLT script being conceived as a XML document instance
+ contains elements belonging to two different namespaces namely
+ <code>http://www.w3.org/1999/XSL/Transform</code> and
+ <code>http://www.w3.org/1999/XSL/Format</code>. The script also
+ contains a <quote>raw</quote> <tag audience=""
+ class="emptytag">HTML</tag> element being introduced only for
+ demonstration purposes belonging to the default namespace. The
+ result reads:</para>
+
+ <programlisting language="none">Opening Element rawName='xsl:stylesheet'
+namespaceUri='http://www.w3.org/1999/XSL/Transform'
+localName='stylesheet'
+--------------------------------------------
+Opening Element rawName='xsl:template'
+namespaceUri='http://www.w3.org/1999/XSL/Transform'
+localName='template'
+--------------------------------------------
+Opening Element rawName='fo:block'
+namespaceUri='http://www.w3.org/1999/XSL/Format'
+localName='block'
+--------------------------------------------
+Opening Element rawName='HTML'
+namespaceUri=''
+localName='HTML'</programlisting>
+
+ <para>Now the parser tells us to which namespace a given element
+ node belongs to. A XSLT engine for example uses this information to
+ build two classes of elements:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Elements belonging to the namespace
+ <code>http://www.w3.org/1999/XSL/Transform</code> like <tag
+ class="emptytag">xsl:value-of select="..."</tag> have to be
+ interpreted as instructions by the processor.</para>
+ </listitem>
+
+ <listitem>
+ <para>Elements <emphasis role="bold">not</emphasis> belonging to
+ the namespace <code>http://www.w3.org/1999/XSL/Transform</code>
+ like <tag class="emptytag">html</tag> or <tag
+ class="starttag">fo:block</tag> are copied <quote>as is</quote>
+ to the output.</para>
+ </listitem>
+ </itemizedlist>
+
+ <qandaset defaultlabel="qanda" xml:id="quandaentry_SqlFromXml">
+ <title>Generating SQL INSERT statements from XML data</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>Consider the following DTD + document instance
+ example:</para>
+
+ <figure xml:id="catalogProductDescriptionsExample">
+ <title>A sample catalog containing products and
+ corresponding descriptions.</title>
+
+ <programlisting language="none"><!DOCTYPE catalog [
+ <!ELEMENT catalog (product*)>
+ <!ELEMENT product (name, description*, age?)>
+ <!ATTLIST product id ID #REQUIRED>
+ <!ELEMENT name (#PCDATA)>
+ <!ELEMENT description (#PCDATA)>
+ <!ELEMENT age (#PCDATA)>
+]>
+<catalog>
+ <product id="mpt">
+ <name>Monkey Picked Tea</name>
+ <description>Rare wild Chinese tea</description>
+ <description>Picked only by specially trained monkeys</description>
+ </product>
+ <product id="instantTent">
+ <name>4-Person Instant Tent</name>
+ <description>4-person, 1-room tent</description>
+ <description>Pre-attached tent poles</description>
+ <description>Exclusive WeatherTec system.</description>
+ <age>15</age>
+ </product>
+</catalog></programlisting>
+ </figure>
+
+ <para>Data being contained in catalog instances shall be
+ transferred to a relational database system. Implement and
+ test a <link linkend="gloss_SAX"><abbrev>SAX</abbrev></link>
+ application by following the subsequently described
+ steps:</para>
+
+ <glosslist>
+ <glossentry>
+ <glossterm>Database schema</glossterm>
+
+ <glossdef>
+ <para>Create a database schema matching a product of
+ your choice (<productname>Mysql</productname>,
+ <productname>Oracle</productname>, ...). Your schema
+ should map type and integrity constraints of the given
+ DTD. In particular:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The element <tag class="starttag">age</tag> is
+ optional and always expected to be of integer
+ type.</para>
+ </listitem>
+
+ <listitem>
+ <para>description elements are being composed in
+ <product> elements and should thus be modeled
+ as a 1:n relation. Thus you need a suitable foreign
+ key.</para>
+ </listitem>
+ </itemizedlist>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>SAX Application</glossterm>
+
+ <glossdef>
+ <para>The order of appearance of the XML elements <tag
+ class="starttag">product</tag>, <tag
+ class="starttag">name</tag> and <tag
+ class="starttag">age</tag> does not permit a linear
+ generation of suitable SQL <code>INSERT</code>
+ statements by a <link
+ linkend="gloss_SAX"><abbrev>SAX</abbrev></link>
+ content handler. Instead you will have to keep copies
+ of local element values when implementing
+ <methodname>org.xml.sax.ContentHandler.startElement(String,String,String,org.xml.sax.Attributes)</methodname>
+ and related callback methods. The following sequence
+ of insert statements corresponds to the XML data being
+ contained in <xref
+ linkend="catalogProductDescriptionsExample"/>. You may
+ use these statements as a blueprint to be generated by
+ your <link
+ linkend="gloss_SAX"><abbrev>SAX</abbrev></link>
+ application:</para>
+
+ <programlisting language="none"><emphasis role="bold">INSERT INTO Product VALUES ('mpt', 'Monkey picked tea', NULL);</emphasis>
+INSERT INTO Description VALUES('mpt', 'Picked only by specially trained monkeys');
+INSERT INTO Description VALUES('mpt', 'Rare wild Chinese tea');
+
+<emphasis role="bold">INSERT INTO Product VALUES ('instantTent', '4-person instant tent', 15);</emphasis>
+INSERT INTO Description VALUES('instantTent', 'Exclusive WeatherTec system.');
+INSERT INTO Description VALUES('instantTent', '4-person, 1-room tent');
+INSERT INTO Description VALUES('instantTent', 'Pre-attached tent poles');</programlisting>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+ </question>
+
+ <answer>
+ <itemizedlist>
+ <listitem>
+ <para><classname>sax.context.Catalog2SqlDriver</classname></para>
+ </listitem>
+
+ <listitem>
+ <para><classname>sax.context.Catalog2Sql</classname></para>
+ </listitem>
+
+ <listitem>
+ <para><classname>sax.context.ImportHandler</classname></para>
+ </listitem>
+ </itemizedlist>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+
+ <qandaset defaultlabel="qanda" xml:id="quandaentry_NumElemByNs">
+ <title>Counting element names grouped by namespaces</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>We want to extend the SAX examples counting <link
+ linkend="saxElementCount">elements</link> and <link
+ linkend="exercise_saxAttrib">attributes</link> of arbitrary
+ document instances. Consider the following <link
+ linkend="gloss_XHTML">XHTML</link> + <link
+ linkend="gloss_SVG">SVG</link> + <link
+ linkend="gloss_MathML">MathML</link> sample document:</para>
+
+ <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN"
+ "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd" >
+<html xmlns="<emphasis role="bold">http://www.w3.org/1999/xhtml</emphasis>" <co
+ xml:id="xhtmlCombinedNs_Xhtml"/>
+ xmlns:svg="<emphasis role="bold">http://www.w3.org/2000/svg</emphasis>"> <co
+ xml:id="xhtmlCombinedNs_Svg"/>
+ <head>
+ <title>Sample XHTML with Equations</title>
+ </head>
+ <body>
+ <h1>Sample MathML:</h1>
+ <math <emphasis role="bold">xmlns="http://www.w3.org/1998/Math/MathML</emphasis>"> <co
+ xml:id="xhtmlCombinedNs_Mathml"/>
+ <mstyle displaystyle="false" scriptlevel="0">
+ <mrow>
+ <mfrac>
+ <mrow>
+ <mi mathcolor="gray">sin</mi>
+ <mo rspace="verythinmathspace">â¡</mo>
+ <mi>θ</mi>
+ </mrow>
+ <mi>Ï€</mi>
+ </mfrac>
+ </mrow>
+ </mstyle>
+ </math>
+ <h1>Sample SVG:</h1>
+ <svg:svg version="1.1" baseProfile="full" width="300px" height="200px">
+ <svg:circle cx="150px" cy="100px" r="50px" fill="#ff0000"
+ stroke="#000000" stroke-width="5px"/>
+ </svg:svg>
+ </body>
+</html></programlisting>
+
+ <para>This document does define three different namespaces
+ <coref linkend="xhtmlCombinedNs_Xhtml"/>, <coref
+ linkend="xhtmlCombinedNs_Svg"/> and <coref
+ linkend="xhtmlCombinedNs_Mathml"/> corresponding to the
+ three XML application components.</para>
+
+ <para>Implement a <link linkend="gloss_SAX">SAX</link>
+ application being able to group elements of arbitrary XML
+ documents by namespaces along with their corresponding
+ frequencies of occurrence. The intended output corresponding
+ to the previous <link linkend="gloss_XHTML">XHTM</link>L
+ example might look like:</para>
+
+ <programlisting language="none">Namespace '<emphasis
+ role="bold">http://www.w3.org/1998/Math/MathML</emphasis>' contains:
+<math> (1 occurrence)
+<mo> (1 occurrence)
+<mrow> (2 occurrences)
+<mfrac> (1 occurrence)
+<mi> (3 occurrences)
+<mstyle> (1 occurrence)
+
+Namespace '<emphasis role="bold">http://www.w3.org/1999/xhtml</emphasis>' contains:
+<body> (1 occurrence)
+<title> (1 occurrence)
+<html> (1 occurrence)
+<h1> (2 occurrences)
+<head> (1 occurrence)
+
+Namespace '<emphasis role="bold">http://www.w3.org/2000/svg</emphasis>' contains:
+<svg> (1 occurrence)
+<circle> (1 occurrence)</programlisting>
+
+ <para>Hints:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Counting frequencies and grouping by namespaces
+ may be achieved by using standard Java container
+ implementations of <classname>java.util.Map</classname>.
+ You may for example define sets of related XML elements
+ and group them by their corresponding namespaces.</para>
+ </listitem>
+
+ <listitem>
+ <para>Enabling validation may require an entity resolver
+ as being described in <xref linkend="saxValidate"/>.
+ Otherwise you may experience long parsing times due to
+ downloading of referenced DTD components.</para>
+ </listitem>
+ </itemizedlist>
+ </question>
+
+ <answer>
+ <itemizedlist>
+ <listitem>
+ <para><classname>sax.ns.stat.ElementFrequencyDriver</classname></para>
+ </listitem>
+
+ <listitem>
+ <para><classname>sax.ns.stat.ElementFrequency</classname></para>
+ </listitem>
+
+ <listitem>
+ <para><classname>sax.ns.stat.ElementcountByName</classname></para>
+ </listitem>
+
+ <listitem>
+ <para><classname>sax.ns.stat.FrequencyGatherer</classname></para>
+ </listitem>
+ </itemizedlist>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+ </section>
+
+ <section xml:id="dom">
+ <title>The Document Object Model (<acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym>)</title>
+
+ <titleabbrev><acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym></titleabbrev>
+
+ <section xml:id="domBase">
+ <title>Language independent specification</title>
+
+ <titleabbrev>Language independence</titleabbrev>
+
+ <para>XML documents allow for automated content processing. We
+ already discussed the <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> API to access
+ XML documents by <link
+ linkend="gloss_Java"><trademark>Java</trademark></link>
+ applications. There are however situations where <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> is not
+ appropriate:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> is event
+ based. XML node elements are passed to handler methods.
+ Sometimes we want to access neighbouring nodes from a context
+ node in our handler methods for example a <tag
+ class="starttag">title</tag> following a <tag
+ class="starttag">chapter</tag> node. <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> does not
+ offer any support for this. If we need references to
+ neighbouring nodes we have to create them ourselves during a
+ <acronym xlink:href="http://www.saxproject.org">SAX</acronym>
+ parsing run. This is tedious and leads to code being hard to
+ understand.</para>
+ </listitem>
+
+ <listitem>
+ <para>Some applications may want to select node sets by <acronym
+ xlink:href="http://www.w3.org/TR/xpath">XPath</acronym>
+ expressions which is completely impossible in a <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym>
+ application.</para>
+ </listitem>
+
+ <listitem>
+ <para>We may want to move subtrees within a document itself (for
+ example exchanging two <tag class="starttag">chapter</tag>
+ nodes) or even transferring them to a different document.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The greatest deficiency of the <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> is the fact
+ that an XML instance is not represented as a tree like structure but
+ as a succession of events. The <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> allows us to
+ represent XML document instances as tree like structures and thus
+ enables navigational operations between nodes.</para>
+
+ <para>In order to achieve language <emphasis>and</emphasis> software
+ vendor independence the <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> approach uses two
+ stages:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> is formulated
+ in an Interface Definition Language (<abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Interface_description_language">IDL</abbrev>)</para>
+ </listitem>
+
+ <listitem>
+ <para>In order to use the <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> API by a
+ concrete programming language a so called <emphasis>language
+ binding</emphasis> is required. In languages like <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> the
+ language binding will still be a set of (<link
+ linkend="gloss_Java"><trademark>Java</trademark></link>)
+ interfaces. Thus for actually coding an application an
+ implementation of these interfaces is needed</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>So what exactly may an <abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Interface_description_language">IDL</abbrev>
+ be? The programming language <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> already
+ allows pure interface definitions without any implementation. In C++
+ the same result can be achieved by so called <emphasis>pure virtual
+ classes</emphasis>. An <abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Interface_description_language">IDL</abbrev>
+ offers extended features to describe such interfaces. For <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> the <productname
+ xlink:href="http://www.omg.org/gettingstarted/corbafaq.htm">CORBA
+ 2.2</productname> <abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Interface_description_language">IDL</abbrev>
+ had been chosen to describe an XML document programming interface.
+ As a first example we take an excerpt from the <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym>'s <link
+ xlink:href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#ID-1950641247">Node</link>
+ interface definition:</para>
+
+ <programlisting language="none">interface Node {
+ // NodeType
+ const unsigned short ELEMENT_NODE = 1;
+ const unsigned short ATTRIBUTE_NODE = 2;
+ const unsigned short TEXT_NODE = 3;
+ ...
+
+ readonly attribute DOMString nodeName;
+ attribute DOMString nodeValue;
+ // raises(DOMException) on setting
+ // raises(DOMException) on retrieval
+ readonly attribute unsigned short nodeType;
+ readonly attribute Node parentNode;
+ ...
+ readonly attribute NodeList childNodes;
+ readonly attribute Node firstChild;
+ ...
+ Node insertBefore(in Node newChild,
+ in Node refChild)
+ raises(DOMException);
+ ...</programlisting>
+
+ <para>If we want to implement the <abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Interface_description_language">IDL</abbrev>
+ <classname>org.w3c.dom.Node</classname> specification in e.g. <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> a language
+ binding has to be defined. This means writing <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> code which
+ closely resembles the <abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Interface_description_language">IDL</abbrev>
+ specification. Obviously this task depends on and is restricted by
+ the constructs being offered by the target programming language. The
+ W3C <link
+ xlink:href="http://www.w3.org/TR/DOM-Level-3-Core/java-binding.html">defines</link>
+ the <link linkend="gloss_Java"><trademark>Java</trademark></link>
+ <classname>org.w3c.dom.Node</classname> interface by:</para>
+
+ <programlisting language="none">package org.w3c.dom;
+
+public interface Node {
+ public static final short ELEMENT_NODE = 1; // Node Types
+ public static final short ATTRIBUTE_NODE = 2;
+ public static final short TEXT_NODE = 3;
+ ...
+ 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 insertBefore(Node newChild,
+ Node refChild)
+ throws DOMException;
+ ...
+ }</programlisting>
+
+ <para>We take
+ <methodname>org.w3c.dom.Node.getChildNodes()</methodname> as an
+ example:</para>
+
+ <figure xml:id="domRetrieveChildren">
+ <title>Retrieving child nodes of a given context node</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/domtree.fig" scale="65"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The <classname>org.w3c.dom.Node</classname> interface offers a
+ set of common operations for objects being part of a XML document.
+ But a XML document tree contains different types of nodes such
+ as:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Elements</para>
+ </listitem>
+
+ <listitem>
+ <para>Attributes</para>
+ </listitem>
+
+ <listitem>
+ <para>Entities</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>An XML API may address this issue by offering data types to
+ represent these different kinds of nodes. The <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> Binding
+ defines an inheritance hierarchy of interfaces for this
+ purpose:</para>
+
+ <figure xml:id="domJavaNodeInterfaces">
+ <title>Inheritance interface hierarchy in the <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> <link
+ linkend="gloss_Java"><trademark>Java</trademark></link>
+ binding</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/nodeHierarchy.svg"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Two commonly used <link
+ linkend="gloss_Java"><trademark>Java</trademark></link>
+ implementations of these interfaces are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Xerces</term>
+
+ <listitem>
+ <para><orgname
+ xlink:href="http://xml.apache.org/xerces2-j">Apache Software
+ foundation</orgname></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Jaxp</term>
+
+ <listitem>
+ <para><orgname xlink:href="http://java.sun.com/xml/jaxp">Sun
+ microsystems</orgname></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Both implementations offer additional interfaces beyond the
+ <acronym xlink:href="http://www.w3.org/DOM">DOM</acronym>'s
+ scope.</para>
+
+ <para>Going back to the <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> itself the
+ specification is divided into <link
+ xlink:href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/introduction.html#DOMArchitecture-h2">modules</link>:</para>
+
+ <figure xml:id="figureDomModules">
+ <title><acronym xlink:href="http://www.w3.org/DOM">DOM</acronym>
+ modules.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Screen/dom-architecture.screen.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+
+ <section xml:id="domCreate">
+ <title>Creating a new document from scratch</title>
+
+ <titleabbrev>New document</titleabbrev>
+
+ <para>If we want to export non-XML content (e.g. from a RDBMS) into
+ XML we may achieve this by the following recipe:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Create a document builder instance.</para>
+ </listitem>
+
+ <listitem>
+ <para>Create an empty <link
+ xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/org/w3c/dom/Document.html">Document</link>
+ instance.</para>
+ </listitem>
+
+ <listitem>
+ <para>Fill in the desired Elements and Attributes.</para>
+ </listitem>
+
+ <listitem>
+ <para>Create a serializer.</para>
+ </listitem>
+
+ <listitem>
+ <para>Serialize the resulting tree to a stream.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>An introductory piece of code illustrates these steps:</para>
+
+ <figure xml:id="simpleDomCreate">
+ <title>Creation of a XML document instance from scratch.</title>
+
+ <programlisting language="none">package dom;
+...
+public class CreateDoc {
+ public static void main(String[] args) throws Exception {
+
+ // Create the root element
+ <emphasis role="bold">final Element titel = new Element("titel");
+</emphasis>
+ //Set a date
+ <emphasis role="bold">titel.setAttribute("date", "23.02.2000");</emphasis>
+
+ // Append a text node as child
+ <emphasis role="bold">titel.addContent(new Text("Versuch 1"));</emphasis>
+
+
+ // Set formatting for the XML output
+ <emphasis role="bold">final Format outFormat = Format.getPrettyFormat();</emphasis>
+
+ // Serialize to console
+ <emphasis role="bold">final XMLOutputter printer = new XMLOutputter(outFormat);
+ printer.output(titel, System.out);</emphasis>
+ }
+}</programlisting>
+ </figure>
+
+ <para>We get the following result:</para>
+
+ <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
+<titel date="23.02.2000">Versuch 1</titel></programlisting>
+ </section>
+
+ <section xml:id="domCreateExercises">
+ <title>Exercises</title>
+
+ <qandaset defaultlabel="qanda" xml:id="createDocModify">
+ <title>A sub structured <tag class="starttag">title</tag></title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <label>Creation of an extended XML document instance</label>
+
+ <para>In order to run the examples given during the lecture
+ the <filename
+ xlink:href="http://www.jdom.org/downloads">jdom2.jar</filename>
+ library must be added to the
+ <envar>CLASSPATH</envar>.</para>
+
+ <para>The <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> creating
+ example given before may be used as a starting point. Extend
+ the <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> tree
+ created in <xref linkend="simpleDomCreate"/> to produce an
+ extended XML document:</para>
+
+ <programlisting language="none"><title>
+ <long>The long version of this title</long>
+ <short>Short version</short>
+</title></programlisting>
+ </question>
+
+ <answer>
+ <programlisting language="none">package dom;
+...
+public class CreateExtended {
+ /**
+ * @param args
+ * @throws IOException
+ */
+ public static void main(String[] args) throws IOException {
+
+ final Element titel = new Element("titel"),
+ tLong = new Element("long"),
+ tShort = new Element("short");
+
+ <emphasis role="bold">// Append <long> and <short> to parent <title></emphasis>
+ titel.addContent(tLong).addContent(tShort);
+
+ <emphasis role="bold">// Append text to <long> and <short></emphasis>
+ tLong.addContent(new Text("The long version of this title"));
+ tShort.addContent(new Text("Short version"));
+
+ <emphasis role="bold">// Set formatting for the XML output</emphasis>
+ Format outFormat = Format.getPrettyFormat();
+
+ <emphasis role="bold">// Serialize to console</emphasis>
+ final XMLOutputter printer = new XMLOutputter(outFormat);
+ printer.output(titel, System.out);
+ }
+}</programlisting>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+
+ <section xml:id="domParse">
+ <title>Parsing existing XML documents</title>
+
+ <titleabbrev>Parsing</titleabbrev>
+
+ <para>We already used a <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> to parse an XML
+ document. Rather than handling <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> events
+ ourselves these events may be used to construct a <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> representation of
+ our document. This work is done by an instance of. We use our
+ catalog example from <xref linkend="simpleCatalog"/> as an
+ introductory example.</para>
+
+ <para>We already noticed the need for an
+ <classname>org.xml.sax.ErrorHandler</classname> object during
+ <acronym xlink:href="http://www.saxproject.org">SAX</acronym>
+ processing. A <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> Parser requires a
+ similar type of Object in order to react to parsing errors in a
+ meaningful way. In principle a <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> parser implementor
+ is free to choose his implementation but most implementations are
+ based on top of a <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> parser. For
+ this reason it was natural to choose a <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> error handling
+ interface which is similar to a <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym>
+ <classname>org.xml.sax.ErrorHandler</classname>. The following code
+ serves the needs described before:</para>
+
+ <figure xml:id="domTreeTraversal">
+ <title>Accessing a XML Tree purely by <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> methods.</title>
+
+ <programlisting language="none">package dom;
+...
+public class ArticleOrder {
+
+<emphasis role="bold"> // Though we are playing DOM here, a <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> parser still
+ // assembles our DOM tree.</emphasis>
+ private SAXBuilder builder = new SAXBuilder();
+
+ public ArticleOrder() {
+ <emphasis role="bold">// Though an ErrorHandler is not strictly required it allows
+ // for easierlocalization of XML document errors</emphasis>
+ builder.setErrorHandler(new MySaxErrorHandler(System.out));<co
+ linkends="domSetSaxErrorHandler-co"
+ xml:id="domSetSaxErrorHandler"/>
+ }
+
+ /** Descending a catalog till its <item> elements. For each product
+ * its name and order number are being written to the output.
+ * @throws ...
+ */
+ public void process(final String filename) throws JDOMException, IOException {
+
+ <emphasis role="bold">// Parsing our XML file</emphasis>
+ final Document docInput = builder.build(filename);
+
+ <emphasis role="bold">// Accessing the document's root element</emphasis>
+ final Element docRoot = docInput.getRootElement();
+
+ <emphasis role="bold">// Accessing the <item> children of parent element <catalog></emphasis>
+ final List<Element> items = docRoot.getChildren(); // Element nodes only
+ for (final Element item : items) {
+ System.out.println("Article: " + item.getText()
+ + ", order number: " + item.getAttributeValue("orderNo"));
+ } ...</programlisting>
+
+ <para>Note <coref linkend="domSetSaxErrorHandler"
+ xml:id="domSetSaxErrorHandler-co"/>: This is our standard <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym> error handler
+ implementing the <classname>org.xml.sax.ErrorHandler</classname>
+ interface.</para>
+ </figure>
+
+ <para>Executing this method needs a driver instance providing an
+ input XML filename:</para>
+
+ <programlisting language="none">package dom;
+...
+public class ArticleOrderDriver {
+ public static void main(String[] argv) throws Exception {
+ final ArticleOrder ao = new ArticleOrder();
+ ao.process("<emphasis role="bold">Input/article.xml</emphasis>");
+ }
+}</programlisting>
+
+ <para>This yields:</para>
+
+ <programlisting language="none">Article: Swinging headset, order number: 3218
+Article: 200W Stereo Amplifier, order number: 9921</programlisting>
+
+ <para>To illustrate the internal processes we take a look at the
+ sequence diagram:</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/sequenceDomParser.svg"/>
+ </imageobject>
+ </mediaobject>
+
+ <qandaset defaultlabel="qanda" xml:id="exercise_domHtmlSimple">
+ <title>Creating HTML output</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <label>Simple HTML output</label>
+
+ <para>Instead exporting simple text output in <xref
+ linkend="domTreeTraversal"/> we may also create HTML pages
+ like:</para>
+
+ <programlisting language="none"><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+ <head>
+ <title>Available articles</title>
+ </head>
+ <body>
+ <h1>Available articles</h1>
+ <table>
+ <tbody>
+ <tr>
+ <th align="left">Article Description</th><th>Order Number</th>
+ </tr>
+ <tr>
+ <td align="left"><emphasis role="bold">Swinging headset</emphasis></td><td><emphasis
+ role="bold">3218</emphasis></td>
+ </tr>
+ <tr>
+ <td align="left"><emphasis role="bold">200W Stereo Amplifier</emphasis></td><td><emphasis
+ role="bold">9921</emphasis></td>
+ </tr>
+ </tbody>
+ </table>
+ </body>
+</html></programlisting>
+
+ <para>Instead of simply writing
+ <code>...println(<html>\n\t<head>...)</code>
+ statements you are expected to code a more sophisticated
+ solution. We may combine<xref linkend="createDocModify"/>
+ and <xref linkend="createDocModify"/>. The idea is reading
+ the XML catalog instance as a <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> as before.
+ Then construct a <emphasis>second</emphasis> <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> tree for
+ the desired HTML output and fill in the article information
+ from the first <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> tree
+ accordingly.</para>
+ </question>
+
+ <answer>
+ <para>We introduce a class
+ <classname>solve.dom.HtmlTree</classname>:</para>
+
+ <programlisting language="none">package solve.dom;
+...
+package solve.dom;
+
+import java.io.IOException;
+import java.io.PrintStream;
+
+import org.jdom2.DocType;
+import org.jdom2.Document;
+import org.jdom2.Element;
+import org.jdom2.Text;
+import org.jdom2.output.Format;
+import org.jdom2.output.XMLOutputter;
+
+/**
+ * Holding a HTML DOM to produce output.
+ * @author goik
+ */
+public class HtmlTree {
+
+ private Document htmlOutput;
+ private Element tableBody;
+
+ public HtmlTree(final String titleText,
+ final String[] tableHeaderFields) { <co
+ linkends="programlisting_catalog2html_htmlskel_co"
+ xml:id="programlisting_catalog2html_htmlskel"/>
+
+ DocType doctype = new DocType("html",
+ "-//W3C//DTD XHTML 1.0 Strict//EN",
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd");
+
+ final Element htmlRoot = new Element("html"); <co
+ linkends="programlisting_catalog2html_tablehead_co"
+ xml:id="programlisting_catalog2html_tablehead"/>
+ htmlOutput = new Document(htmlRoot);
+ htmlOutput.setDocType(doctype);
+
+ // We create a HTML skeleton including an "empty" table
+ final Element head = new Element("head"),
+ body = new Element("body"),
+ table = new Element("table");
+
+ htmlRoot.addContent(head).addContent(body);
+
+ head.addContent(new Element("title").addContent(new Text(titleText)));
+
+ body.addContent(new Element("h1").addContent(new Text(titleText)));
+
+ body.addContent(table);
+
+
+ tableBody = new Element("tbody");
+ table.addContent(tableBody);
+
+ final Element tr = tableBody.addContent(new Element("tr"));
+ for (final String headerField: tableHeaderFields) {
+ tr.addContent(new Element("th").addContent(new Text(headerField)));
+ }
+ }
+
+ public void appendItem(final String itemName, final String orderNo) {<co
+ linkends="programlisting_catalog2html_insertproduct_co"
+ xml:id="programlisting_catalog2html_insertproduct"/>
+ final Element tr = new Element("tr");
+ tableBody.addContent(tr);
+ tr.addContent(new Element("td").addContent(new Text(itemName)));
+ tr.addContent(new Element("td").addContent(new Text(orderNo)));
+ }
+ public void serialize(PrintStream out){
+
+ // Set formatting for the XML output
+ final Format outFormat = Format.getPrettyFormat();
+
+ // Serialize to console
+ final XMLOutputter printer = new XMLOutputter(outFormat);
+ try {
+ printer.output(htmlOutput, System.out);
+ } catch (IOException e) {
+ e.printStackTrace();
+ System.exit(1);
+ }
+ }
+ /**
+ * @return the table's <tbody> element
+ */
+ public Element getTable() {
+ return tableBody;
+ }
+}
+
+ </programlisting>
+
+ <calloutlist>
+ <callout arearefs="programlisting_catalog2html_htmlskel"
+ xml:id="programlisting_catalog2html_htmlskel_co">
+ <para>A basic HTML skeleton is is being created:</para>
+
+ <programlisting language="none"><?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <title>Available articles</title>
+ </head>
+ <body>
+ <h1>Available articles</h1>
+ <table>
+ <emphasis role="bold"><tbody></emphasis> <!-- Data to be inserted here in next step -->
+ <emphasis role="bold"></tbody></emphasis>
+ </table>
+ </body>
+</html></programlisting>
+
+ <para>The table containing the product's data is empty
+ at this point and thus invalid.</para>
+ </callout>
+
+ <callout arearefs="programlisting_catalog2html_tablehead"
+ xml:id="programlisting_catalog2html_tablehead_co">
+ <para>The table's header is appended but the actual data
+ from our two products is still missing:</para>
+
+ <programlisting language="none">... <h1>Available articles</h1>
+ <table>
+ <tbody>
+ <tr>
+ <th>Article Description</th>
+ <th>Order Number</th>
+ <emphasis role="bold"></tr></emphasis><!-- Data to be appended after this row in next step -->
+ <emphasis role="bold"></tbody></emphasis>
+ </table> ...</programlisting>
+ </callout>
+
+ <callout arearefs="programlisting_catalog2html_insertproduct"
+ xml:id="programlisting_catalog2html_insertproduct_co">
+ <para>Calling
+ <methodname>solve.dom.HtmlTree.appendItem(String,String)</methodname>
+ once per product completes the creation of our HTML DOM
+ tree:</para>
+
+ <programlisting language="none">... </tr>
+ <tr>
+ <td>Swinging headset</td>
+ <td>3218</td>
+ </tr>
+ <tr>
+ <td>200W Stereo Amplifier</td>
+ <td>9921</td>
+ </tr>
+ </tbody> ...</programlisting>
+ </callout>
+ </calloutlist>
+
+ <para>The class
+ <classname>solve.dom.Article2Html</classname> reads the
+ catalog data:</para>
+
+ <programlisting language="none">package solve.dom;
+...
+public class Article2Html {
+
+ private final SAXBuilder builder = new SAXBuilder();
+ private final HtmlTree htmlResult;
+
+ public Article2Html() {
+
+ builder.setErrorHandler(new MySaxErrorHandler(System.out));
+
+ htmlResult = new HtmlTree("Available articles", new String[] { <co
+ linkends="programlisting_catalog2html_glue_createhtmldom_co"
+ xml:id="programlisting_catalog2html_glue_createhtmldom"/>
+ "Article Description", "Order Number" });
+ }
+
+ /** Read an Xml catalog instance and insert product names among with their
+ * order numbers into the HTML DOM. Then serialize HTML tree to a stream.
+ *
+ * @param
+ * filename of the Xml source.
+ * @param out
+ * The output stream for HTML serialization.
+ * @throws IOException
+ * @throws JDOMException
+ */
+ public void process(final String filename, final PrintStream out) throws JDOMException, IOException{
+ final List<Element> items =
+ builder.build(filename).getRootElement().getChildren();
+
+ for (final Element item : items) { <co
+ linkends="programlisting_catalog2html_glue_prodloop_co"
+ xml:id="programlisting_catalog2html_glue_prodloop"/>
+ htmlResult.appendItem(item.getText(), item.getAttributeValue("orderNo")); <co
+ linkends="programlisting_catalog2html_glue_insertprod_co"
+ xml:id="programlisting_catalog2html_glue_insertprod"/>
+ }
+ htmlResult.serialize(out); <co
+ linkends="programlisting_catalog2html_glue_serialize_co"
+ xml:id="programlisting_catalog2html_glue_serialize"/>
+ }
+}</programlisting>
+
+ <calloutlist>
+ <callout arearefs="programlisting_catalog2html_glue_createhtmldom"
+ xml:id="programlisting_catalog2html_glue_createhtmldom_co">
+ <para>Create an instance holding a HTML <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> with a
+ table header containing the strings <emphasis>Article
+ Description</emphasis> and <emphasis>Order
+ Number</emphasis>.</para>
+ </callout>
+
+ <callout arearefs="programlisting_catalog2html_glue_prodloop"
+ xml:id="programlisting_catalog2html_glue_prodloop_co">
+ <para>Iterate over all product nodes.</para>
+ </callout>
+
+ <callout arearefs="programlisting_catalog2html_glue_insertprod"
+ xml:id="programlisting_catalog2html_glue_insertprod_co">
+ <para>Insert the product's name an order number into the
+ HTML <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym>.</para>
+ </callout>
+
+ <callout arearefs="programlisting_catalog2html_glue_serialize"
+ xml:id="programlisting_catalog2html_glue_serialize_co">
+ <para>Serialize the completed HTML <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> tree to
+ the output stream.</para>
+ </callout>
+ </calloutlist>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+
+ <section xml:id="domJavaScript">
+ <title>Using <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> with
+ HTML/Javascript</title>
+
+ <para>Due to script language support in a variety of browsers we may
+ also use the <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> to implement client
+ side event handling. As an example we <link
+ xlink:href="Ref/src/tablesort.html">demonstrate</link> how a HTML
+ table can be made sortable by clicking on a header's column. The
+ example code along with the code description can be found at <uri
+ xlink:href="http://www.kryogenix.org/code/browser/sorttable">http://www.kryogenix.org/code/browser/sorttable</uri>.</para>
+
+ <para>Quite remarkably there are only few ingredients required to
+ enrich an ordinary static HTML table with this functionality:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>An external Javascript library has to be included via
+ <code><script type="text/javascript"
+ src="sorttable.js"></code></para>
+ </listitem>
+
+ <listitem>
+ <para>Each sortable HTML table needs:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>A unique <code>id</code> attribute</para>
+ </listitem>
+
+ <listitem>
+ <para>A <code>class="sortable"</code> attribute</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section xml:id="domXpath">
+ <title>Using <acronym
+ xlink:href="http://www.w3.org/TR/xpath">XPath</acronym></title>
+
+ <para><xref linkend="domTreeTraversal"/> demonstrated the
+ possibility to traverse trees solely by using <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> Method calls.
+ Though this approach is possible it will in general not lead to
+ stable applications. Real world examples are often based on large
+ XML documents with complex hierarchical structures. Thus using this
+ rather primitive approach deeply nested method calls are necessary
+ to access desired sets of nodes. In addition changing a DTD will
+ require rewriting large code portions..</para>
+
+ <para>As we already know from <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev>
+ transformations <code>Xpath</code> allows to address node sets
+ inside a XML tree. The role of <acronym
+ xlink:href="http://www.w3.org/TR/xpath">XPath</acronym> can be
+ compared to SQL queries when working with relational databases.
+ <acronym xlink:href="http://www.w3.org/TR/xpath">XPath</acronym> may
+ also be used within <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> code. As a
+ first example we show an image filename extracting application
+ operating on XHTML documents. The following example contains three
+ <tag class="starttag">img</tag> elements:</para>
+
+ <figure xml:id="htmlGallery">
+ <title>A HTML document containing <code>IMG</code> tags.</title>
+
+ <programlisting language="none"><?xml version="1.0"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html>
+ <head>
+ <title>Picture gallery</title>
+ </head>
+ <body>
+ <h1>Picture gallery</h1>
+ <p>Images may appear inline:<emphasis role="bold"><img src="inline.gif" alt="none"/></emphasis></p>
+ <table>
+ <tbody>
+ <tr>
+ <td>Number one:</td>
+ <td><emphasis role="bold"><img src="one.gif" alt="none"/></emphasis></td>
+ </tr>
+ <tr>
+ <td>Number two:</td>
+ <td><emphasis role="bold"><img src="http://www.hdm-stuttgart.de/favicon.ico" alt="none"/></emphasis></td>
+ </tr>
+ </tbody>
+ </table>
+ </body>
+</html>
+</programlisting>
+ </figure>
+
+ <para>A given HTML document may contain <tag
+ class="starttag">img</tag> elements at
+ <emphasis>arbitrary</emphasis> positions. It is sometimes desirable
+ to check for existence and accessibility of such external objects
+ being necessary for the page's correct rendering. A simple XSL
+ script will do first part the job namely extracting the <tag
+ class="starttag">img</tag> elements:</para>
+
+ <figure xml:id="gallery2imagelist">
+ <title>A <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> script for
+ image name extraction.</title>
+
+ <programlisting language="none"><xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ xmlns:html="http://www.w3.org/1999/xhtml">
+ <xsl:output method="text"/>
+
+ <xsl:template match="/">
+ <xsl:for-each select="//html:img">
+ <xsl:value-of select="@src"/>
+ <xsl:text> </xsl:text>
+ </xsl:for-each>
+ </xsl:template>
+
+</xsl:stylesheet></programlisting>
+ </figure>
+
+ <para>Note the necessity for <code>html</code> namespace inclusion
+ into the <acronym
+ xlink:href="http://www.w3.org/TR/xpath">XPath</acronym> expression
+ in <code><xsl:for-each select="//html:img"></code>. A simple
+ <code>select="//img"></code> results in an empty node set.
+ Executing the <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> script yields
+ a list of image filenames being contained in the HTML page i.e.
+ <code>inline.gif one.gif two.gif</code>.</para>
+
+ <para>Now we want to write a <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> application
+ which allows to check whether these referenced image files do exist
+ and have sufficient permissions to be accessed. A simple approach
+ may pipe the <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> output to our
+ application which then executes the readability checks. Instead we
+ want to incorporate the <acronym
+ xlink:href="http://www.w3.org/TR/xpath">XPath</acronym> based search
+ into the application. Ignoring Namespaces and trying to resemble the
+ <abbrev xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev>
+ actions as closely as possible our application will have to search
+ for <link
+ xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/org/w3c/dom/Element.html">Element</link>
+ Nodes by the <acronym
+ xlink:href="http://www.w3.org/TR/xpath">XPath</acronym> expression
+ <code>//html:img</code>:</para>
+
+ <figure xml:id="domFindImages">
+ <title>Extracting <tag class="emptytag">img</tag> element image
+ references from a HTML document.</title>
+
+ <programlisting language="none">package dom.xpath;
+...
+public class DomXpath {
+ private final SAXBuilder builder = new SAXBuilder();
+
+ public DomXpath() {
+ builder.setErrorHandler(new MySaxErrorHandler(System.err));
+ }
+ public void process(final String xhtmlFilename) throws JDOMException, IOException {
+
+ final Document htmlInput = builder.build(xhtmlFilename);<co
+ linkends="programlisting_java_searchimg_parse_co"
+ xml:id="programlisting_java_searchimg_parse"/>
+ final XPathExpression<Object> xpath = XPathFactory.instance().compile( "//img" ); <co
+ linkends="programlisting_java_searchimg_pf_co"
+ xml:id="programlisting_java_searchimg_pf"/> <co
+ linkends="programlisting_java_searchimg_newxpath_co"
+ xml:id="programlisting_java_searchimg_newxpath"/>
+ final List<Object> images = xpath.evaluate(htmlInput);<co
+ linkends="programlisting_java_searchimg_execquery_co"
+ xml:id="programlisting_java_searchimg_execquery"/>
+
+ for (Object o: images) { <co
+ linkends="programlisting_java_searchimg_loop_co"
+ xml:id="programlisting_java_searchimg_loop"/>
+ final Element image = (Element ) o;<co
+ linkends="programlisting_java_searchimg_cast_co"
+ xml:id="programlisting_java_searchimg_cast"/>
+ System.out.print(image.getAttribute("src") + " ");
+ }
+ }
+}</programlisting>
+
+ <caption>
+ <para>This application searches for <tag
+ class="emptytag">img</tag> elements and shows their
+ <code>src</code> attribute value.</para>
+ </caption>
+ </figure>
+
+ <calloutlist>
+ <callout arearefs="programlisting_java_searchimg_parse"
+ xml:id="programlisting_java_searchimg_parse_co">
+ <para>Parse a XHTML document instance into a DOM tree.</para>
+ </callout>
+
+ <callout arearefs="programlisting_java_searchimg_pf"
+ xml:id="programlisting_java_searchimg_pf_co">
+ <para>Create a <acronym
+ xlink:href="http://www.w3.org/TR/xpath">XPath</acronym>
+ factory.</para>
+ </callout>
+
+ <callout arearefs="programlisting_java_searchimg_newxpath"
+ xml:id="programlisting_java_searchimg_newxpath_co">
+ <para>Create a <acronym
+ xlink:href="http://www.w3.org/TR/xpath">XPath</acronym> query
+ instance. This may be used to search for a set of nodes starting
+ from a context node.</para>
+ </callout>
+
+ <callout arearefs="programlisting_java_searchimg_execquery"
+ xml:id="programlisting_java_searchimg_execquery_co">
+ <para>Using the document's root node as the context node we
+ search for <tag class="starttag">img</tag> elements appearing at
+ arbitrary positions in our document.</para>
+ </callout>
+
+ <callout arearefs="programlisting_java_searchimg_loop"
+ xml:id="programlisting_java_searchimg_loop_co">
+ <para>We iterate over the retrieved list of images.</para>
+ </callout>
+
+ <callout arearefs="programlisting_java_searchimg_cast"
+ xml:id="programlisting_java_searchimg_cast_co">
+ <para>Casting to the correct type.</para>
+ </callout>
+ </calloutlist>
+
+ <para>The result is a list of image filename references:</para>
+
+ <programlisting language="none">inline.gif one.gif http://www.hdm-stuttgart.de/favicon.ico </programlisting>
+
+ <qandaset defaultlabel="qanda" xml:id="quandaentry_CastAlwaysLegal">
+ <title>Legal casting?</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>Why is the cast in <coref
+ linkend="programlisting_java_searchimg_cast"/> in <xref
+ linkend="domFindImages"/> guaranteed to never cause a
+ <classname>java.lang.ClassCastException</classname>?</para>
+ </question>
+
+ <answer>
+ <para>The <acronym
+ xlink:href="http://www.w3.org/TR/xpath">XPath</acronym>
+ <code>//img</code> expression is guaranteed to return only
+ <tag class="starttag">img</tag> elements. Thus within our
+ <link
+ linkend="gloss_Java"><trademark>Java</trademark></link>
+ context we are sure to find only
+ <classname>org.jdom2.Element</classname> instances.</para>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+
+ <qandaset defaultlabel="qanda" xml:id="exercise_htmlImageVerify">
+ <title>Verification of referenced images readability</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>We want to extend the example given in <xref
+ linkend="domFindImages"/> by testing the existence and
+ checking for readability of referenced images. The following
+ HTML document contains <quote>dead</quote> image
+ references:</para>
+
+ <programlisting language="none"
+ xml:id="domCheckImageAccessibility"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml"> ...
+ <body>
+ <h1>External Pictures</h1>
+ <p>A local image reference:<img src="inline.gif" alt="none"/></p>
+ <table>
+ <tbody>
+ <tr>
+ <td>An existing picture:</td>
+ <td><img
+ src="http://www.hdm-stuttgart.de/bilder_navigation/laptop.gif"
+ alt="none"/></td>
+ </tr>
+ <tr>
+ <td>A non-existing picture:</td>
+ <td><img src="<emphasis role="bold">http://www.hdm-stuttgart.de/rotfl.gif</emphasis>" alt="none"/></td>
+ </tr>
+ </tbody>
+ </table>
+ </body>
+</html></programlisting>
+
+ <para>Write an application which checks for readability of
+ <abbrev
+ xlink:href="http://www.ietf.org/rfc/rfc1738.txt">URL</abbrev>
+ image references to <emphasis>external</emphasis> Servers
+ starting either with <code>http://</code> or
+ <code>ftp://</code> ignoring other protocol types. Internal
+ image references referring to the <quote>current</quote>
+ server typically look like <code><img
+ src="/images/test.gif"</code>. So in order to distinguish
+ these two types of references we may use the XSL built in
+ function <link
+ xlink:href="http://www.cafeconleche.org/books/bible2/chapters/ch17.html">starts-with()</link>
+ testing for the <code>http</code> or <code>ftp</code>
+ protocol definition part of an <abbrev
+ xlink:href="http://www.ietf.org/rfc/rfc1738.txt">URL</abbrev>.
+ A possible output for the example being given is:</para>
+
+ <programlisting language="none">Received 'sun.awt.image.URLImageSource' from
+ http://www.hdm-stuttgart.de/bilder_navigation/laptop.gif
+Unable to open 'http://www.hdm-stuttgart.de/rotfl.gif'</programlisting>
+
+ <para>The following code snippet shows a helpful class
+ method to check for both correctness of <abbrev
+ xlink:href="http://www.ietf.org/rfc/rfc1738.txt">URL</abbrev>'s
+ and accessibility of referenced objects:</para>
+
+ <programlisting language="none">package dom.xpath;
+...
+public class CheckUrl {
+ public static void checkReadability(final String urlRef) {
+ try {
+ final URL url = new URL(urlRef);
+ try {
+ final Object imgCandidate = url.getContent();
+ if (null == imgCandidate) {
+ System.err.println("Unable to open '" + urlRef + "'");
+ } else {
+ System.out.println("Received '"
+ + imgCandidate.getClass().getName() + "' from "
+ + urlRef);
+ }
+ } catch (IOException e) {
+ System.err.println("Unable to open '" + urlRef + "'");
+ }
+ } catch (MalformedURLException e) {
+ System.err.println("Adress '" + urlRef + "' is malformed");
+ }
+ }
+}</programlisting>
+ </question>
+
+ <answer>
+ <para>We are interested in the set of images within a given
+ HTML document containing an <link
+ xlink:href="http://www.w3.org/Addressing">URL</link>
+ reference starting either with <code>http://</code> or
+ <code>ftp://</code>. This is achieved by the following
+ <acronym
+ xlink:href="http://www.w3.org/TR/xpath">XPath</acronym>
+ expression:</para>
+
+ <programlisting language="none">//html:img[starts-with(@src, 'http://') or starts-with(@src, 'ftp://')]</programlisting>
+
+ <para>The application only needs to pass the corresponding
+ <abbrev
+ xlink:href="http://www.ietf.org/rfc/rfc1738.txt">URL</abbrev>'s
+ to the method <link
+ xlink:href="domCheckUrlObjectExistence">CheckUrl.checkReadability()</link>.
+ The rest of the code is identical to the <link
+ linkend="domFindImages">introductory example</link>:</para>
+
+ <informalfigure xml:id="solutionFintExtImgRef">
+ <programlisting language="none">package dom.xpath;
+...
+public class CheckExtImage {
+ private final SAXBuilder builder = new SAXBuilder();
+
+ public CheckExtImage() {
+ builder.setErrorHandler(new MySaxErrorHandler(System.err));
+ }
+ public void process(final String xhtmlFilename) throws JDOMException, IOException {
+
+ final Document htmlInput = builder.build(xhtmlFilename);
+ final XPathExpression<Object> xpath = XPathFactory.instance().compile(
+ "<emphasis role="bold">//img[starts-with(@src, 'http://') or starts-with(@src, 'ftp://')]</emphasis>");
+ final List<Object> images = xpath.evaluate(htmlInput);
+
+ for (Object o: images) {
+ final Element image = (Element ) o;
+ <emphasis role="bold">CheckUrl.checkReadability(image.getAttributeValue("src"));</emphasis>
+ }
+ }
+}</programlisting>
+ </informalfigure>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+
+ <section xml:id="domXsl">
+ <title><acronym xlink:href="http://www.w3.org/DOM">DOM</acronym> and
+ <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev></title>
+
+ <para><link linkend="gloss_Java"><trademark>Java</trademark></link>
+ based <link linkend="gloss_XML"><abbrev>XML</abbrev></link>
+ applications may use XSL style sheets for processing. A <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> tree may for
+ example be transformed into another tree. The package <link
+ xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/javax/xml/transform/package-frame.html">javax.xml.transform</link>
+ provides interfaces and classes for this purpose. We consider the
+ following product catalog example:</para>
+
+ <figure xml:id="climbingCatalog">
+ <title>A simplified <link
+ linkend="gloss_XML"><abbrev>XML</abbrev></link> product
+ catalog</title>
+
+ <programlisting language="none"><catalog xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="catalog.xsd">
+ <title>Outdoor products</title>
+ <introduction>
+ <para>We offer a great variety of basic stuff for mountaineering
+ such as ropes, harnesses and tents.</para>
+ <para>Our shop is proud for its large number of available
+ sleeping bags.</para>
+ </introduction>
+ <product id="x-223">
+ <title>Multi freezing bag Nightmare camper</title>
+ <description>
+ <para>You will feel comfortable till minus 20 degrees - At
+ least if you are a penguin or a polar bear.</para>
+ </description>
+ </product>
+ <product id="r-334">
+ <title>Rope 40m</title>
+ <description>
+ <para>Excellent for indoor climbing.</para>
+ </description>
+ </product>
+</catalog></programlisting>
+
+ <para>A corresponding schema file <filename>catalog.xsd</filename>
+ is straightforward:</para>
+
+ <programlisting language="none"><xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+ xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning" elementFormDefault="qualified"
+ vc:minVersion="1.0" vc:maxVersion="1.1">
+
+ <xs:simpleType name="money">
+ <xs:restriction base="xs:decimal">
+ <xs:fractionDigits value="2"/>
+ </xs:restriction>
+ </xs:simpleType>
+
+ <xs:element name="title" type="xs:string"/>
+ <xs:element name="para" type="xs:string"/>
+
+ <xs:element name="description" type="paraSequence"/>
+ <xs:element name="introduction" type="paraSequence"/>
+
+ <xs:complexType name="paraSequence">
+ <xs:sequence>
+ <xs:element ref="para" minOccurs="1" maxOccurs="unbounded"/>
+ </xs:sequence>
+ </xs:complexType>
+
+ <xs:element name="product">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element ref="title"/>
+ <xs:element ref="description"/>
+ </xs:sequence>
+ <xs:attribute name="id" type="xs:ID" use="required"/>
+ <xs:attribute name="price" type="money" use="optional"/>
+ </xs:complexType>
+ </xs:element>
+
+ <xs:element name="catalog">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element ref="title"/>
+ <xs:element ref="introduction"/>
+ <xs:element ref="product" minOccurs="1" maxOccurs="unbounded"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+
+</xs:schema>
+</programlisting>
+ </figure>
+
+ <para>A <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> style sheet
+ may be used to transform this document into the HTML Format:</para>
+
+ <figure xml:id="catalog2html">
+ <title>A <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> style sheet
+ for catalog transformation to HTML.</title>
+
+ <programlisting language="none"><?xml version="1.0" encoding="utf-8"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="2.0" xmlns="http://www.w3.org/1999/xhtml">
+
+ <xsl:template match="/catalog">
+ <html>
+ <head><title><xsl:value-of select="title"/></title></head>
+ <body style="background-color:#FFFFFF">
+ <h1><xsl:value-of select="title"/></h1>
+ <xsl:apply-templates select="product"/>
+ </body>
+ </html>
+ </xsl:template>
+
+ <xsl:template match="product">
+ <h3><xsl:value-of select="title"/></h3>
+ <xsl:for-each select="description/para">
+ <p><xsl:value-of select="."/></p>
+ </xsl:for-each>
+ <xsl:if test="price">
+ <p>
+ <xsl:text>Price:</xsl:text>
+ <xsl:value-of select="price/@value"/>
+ </p>
+ </xsl:if>
+ </xsl:template>
+</xsl:stylesheet></programlisting>
+ </figure>
+
+ <para>As a preparation for <xref linkend="exercise_catalogRdbms"/>
+ we now demonstrate the usage of <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> within a <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> application.
+ This is done by a <link
+ xlink:href="http://java.sun.com/j2se/1.5.0/docs/api/javax/xml/transform/Transformer.html">Transformer</link>
+ instance:</para>
+
+ <figure xml:id="xml2xml">
+ <title>Transforming an XML document instance to HTML by a XSL
+ style sheet.</title>
+
+ <programlisting language="none">package dom.xsl;
+...
+public class Xml2Html {
+ private final SAXBuilder builder = new SAXBuilder();
+
+ final XSLTransformer transformer;
+
+ public Xml2Html(final String xslFilename) throws XSLTransformException {
+ builder.setErrorHandler(new MySaxErrorHandler(System.err));
+ transformer = new XSLTransformer(xslFilename);
+ }
+ public void transform(final String xmlInFilename,
+ final String resultFilename) throws JDOMException, IOException {
+
+ final Document inDoc = builder.build(xmlInFilename);
+ Document result = transformer.transform(inDoc);
+
+ // Set formatting for the XML output
+ final Format outFormat = Format.getPrettyFormat();
+
+ // Serialize to console
+ final XMLOutputter printer = new XMLOutputter(outFormat);
+ printer.output(result.getDocument(), System.out);
+
+ }
+}</programlisting>
+ </figure>
+
+ <para>A corresponding driver file is needed to invoke a
+ transformation:</para>
+
+ <figure xml:id="xml2xmlDriver">
+ <title>A driver class for the xml2xml transformer.</title>
+
+ <programlisting language="none">package dom.xsl;
+...
+public class Xml2HtmlDriver {
+...
+ public static void main(String[] args) {
+ final String
+ inFilename = "Input/Dom/climbing.xml",
+ xslFilename = "Input/Dom/catalog2html.xsl",
+ htmlOutputFilename = "Input/Dom/climbing.html";
+ try {
+ final Xml2Html converter = new Xml2Html(xslFilename);
+ converter.transform(inFilename, htmlOutputFilename);
+ } catch (Exception e) {
+ System.err.println("The conversion of '" + inFilename
+ + "' by stylesheet '" + xslFilename
+ + "' to output HTML file '" + htmlOutputFilename
+ + "' failed with the following error:" + e);
+ e.printStackTrace();
+ }
+ }
+}</programlisting>
+ </figure>
+
+ <qandaset defaultlabel="qanda" xml:id="exercise_catalogRdbms">
+ <title>HTML from XML and relational data</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <label>Catalogs and RDBMS</label>
+
+ <para>We want to extend the transformation being described
+ before in <xref linkend="xml2xml"/> by reading price
+ information from a RDBMS. Consider the following schema and
+ <code>INSERT</code>s:</para>
+
+ <programlisting language="none">CREATE TABLE Product(
+ orderNo CHAR(10)
+ ,price NUMERIC(10,2)
+);
+
+INSERT INTO Product VALUES('x-223', 330.20);
+INSERT INTO Product VALUES('w-124', 110.40);</programlisting>
+
+ <para>Adding prices may be implemented the following
+ way:</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/xml2html.fig"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>You may implement this by following these
+ steps:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>You may reuse class
+ <classname>sax.rdbms.RdbmsAccess</classname> from <xref
+ linkend="saxRdbms"/>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Use the previous class to modify <xref
+ linkend="xml2xml"/> by introducing a new method
+ <code>addPrices(final Document catalog)</code> which
+ adds prices to the <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> tree
+ accordingly. The insertion points may be reached by an
+ <acronym
+ xlink:href="http://www.w3.org/TR/xpath">XPath</acronym>
+ expression.</para>
+ </listitem>
+ </orderedlist>
+ </question>
+
+ <answer>
+ <para>The additional functionality on top of <xref
+ linkend="xml2xml"/> is represented by a method
+ <methodname>dom.xsl.XmlRdbms2Html.addPrices()</methodname>.
+ This method modifies the <acronym
+ xlink:href="http://www.w3.org/DOM">DOM</acronym> input tree
+ prior to applying the XSL. Prices are being inserting based
+ on data received from an RDBMS via <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>:</para>
+
+ <programlisting language="none">package dom.xsl;
+...
+public class XmlRdbms2Html {
+ private final SAXBuilder builder = new SAXBuilder();
+
+ DbAccess db = new DbAccess();
+
+ final XSLTransformer transformer;
+ Document catalog;
+
+ final org.jdom2.xpath.XPathExpression<Object> selectProducts =
+ XPathFactory.instance().compile("/catalog/product");
+
+ /**
+ * @param xslFilename the stylesheet being used for subsequent
+ * transformations by {@link #transform(String, String)}.
+ *
+ * @throws XSLTransformException
+ */
+ public XmlRdbms2Html(final String xslFilename) throws XSLTransformException {
+ builder.setErrorHandler(new MySaxErrorHandler(System.err));
+ transformer = new XSLTransformer(xslFilename);
+ }
+
+ /**
+ * The actual workhorse carrying out the transformation
+ * and adding prices from the database table.
+ *
+ * @param xmlInFilename input file to be transformed
+ * @param resultFilename the result file holding the generated HTML document
+ * @throws JDOMException The transformation may fail for various reasons.
+ * @throws IOException
+ */
+ public void transform(final String xmlInFilename,
+ final String resultFilename) throws JDOMException, IOException {
+
+ catalog = builder.build(xmlInFilename);
+
+ addPrices();
+
+ final Document htmlResult = transformer.transform(catalog);
+
+ // Set formatting for the XML output
+ final Format outFormat = Format.getPrettyFormat();
+
+ // Serialize to console
+ final XMLOutputter printer = new XMLOutputter(outFormat);
+ printer.output(htmlResult, System.out);
+
+ }
+ private void addPrices() {
+ final List<Object> products = selectProducts.evaluate(catalog.getRootElement());
+
+ db.connect("jdbc:mysql://localhost:3306/hdm", "hdmuser", "XYZ");
+ for (Object p: products) {
+ final Element product = (Element ) p;
+ final String productId = product.getAttributeValue("id");
+ product.setAttribute("price", db.readPrice(productId));
+ }
+ db.close();
+ }
+}</programlisting>
+
+ <para>The method <code>addPrices(...)</code> utilizes our
+ RDBMS access class:</para>
+
+ <programlisting language="none">package dom.xsl;
+...
+public class DbAccess {
+ public void connect(final String jdbcUrl,
+ final String userName, final String password) {
+ try {
+ conn = DriverManager.getConnection(jdbcUrl, userName, password);
+ priceQuery = conn.prepareStatement(sqlPriceQuery);
+ } catch (SQLException e) {
+ System.err.println("Unable to open connection to database:" + e);}
+ }
+ public String readPrice(final String articleNumber) {
+ String result;
+ try {
+ priceQuery.setString(1, articleNumber);
+ final ResultSet rs = priceQuery.executeQuery();
+ if (rs.next()) {
+ result = rs.getString("price");
+ } else {
+ result = "No price available for article '" + articleNumber + "'";
+ }
+ } catch (SQLException e) {
+ result = "Error reading price for article '" + articleNumber + "':" + e;
+ }
+ return result;
+ }
+ ...
+}</programlisting>
+
+ <para>Of course the connection details should be moved to a
+ configuration file.</para>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+ </section>
+ </chapter>
+
+ <chapter xml:id="introPersistence">
+ <title>Accessing Relational Data</title>
+
+ <section xml:id="persistence">
+ <title>Persistence in Object Oriented languages</title>
+
+ <para>Following <xref linkend="Bauer05"/> we may define persistence
+ by:</para>
+
+ <blockquote>
+ <para>persistence allows an object to outlive the process that
+ created it. The state of the object may be stored to disk and an
+ object with the same state re-created at some point in the
+ future.</para>
+ </blockquote>
+
+ <para>The notion of <quote>process</quote> refers to operating
+ systems. Let us start wit a simple example assuming a <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> class
+ User:</para>
+
+ <programlisting language="none">public class User {
+ String cname; //The user's common name e.g. 'Joe Bix'
+ String uid; //The user's unique system ID (login name) e.g. 'bix'
+
+// getters, setters and other stuff
+ ...
+}</programlisting>
+
+ <para>A relational implementation might look like:</para>
+
+ <programlisting language="none">CREATE TABLE User(
+ CHAR(80) cname
+ ,CHAR(10) uid PRIMARY KEY
+)</programlisting>
+
+ <para>Now a <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> application
+ may create instances of class <code>User</code> and save these to a
+ database:</para>
+
+ <figure xml:id="processObjPersist">
+ <title>Persistence across process boundaries</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/persistence.fig" scale="65"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Both the <trademark
+ xlink:href="http://www.oracle.com/technetwork/java/javase">JRE</trademark>
+ instances and the RDBMS database server are processes (or sets of
+ processes) typically existing in different address spaces. The two
+ <trademark
+ xlink:href="http://www.oracle.com/technetwork/java/javase">JRE</trademark>
+ processes mentioned here may as well be started in disjoint address
+ spaces. In fact we might even run two entirely different applications
+ implemented in different programming languages like <abbrev
+ xlink:href="http://www.php.net">PHP</abbrev>.</para>
+
+ <para>It is important to mention that the two arrows
+ Â <quote>save</quote> and <quote>load</quote> thus typically denote a
+ communication across machine boundaries.</para>
+ </section>
+
+ <section xml:id="jdbcIntro">
+ <title>Introduction to <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark></title>
+
+ <section xml:id="jdbcWrite">
+ <title>Write access, principles</title>
+
+ <para>Connecting an application to a database means to establish a
+ connection from a client to a database server:</para>
+
+ <figure xml:id="jdbcClientServer">
+ <title>Networking between clients and database servers</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/clientserv.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>So <trademark
+ xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc">JDBC</trademark>
+ is just one among a whole bunch of protocol implementations
+ connecting database servers and applications. Consequently
+ <trademark
+ xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc">JDBC</trademark>
+ is expected to appear in the lower layer of multi-tier applications.
+ We take a three-tier application as a starting point:</para>
+
+ <figure xml:id="jdbcThreeTier">
+ <title>The role of <trademark
+ xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc">JDBC</trademark>
+ in a three-tier application</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/jdbcThreeTier.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>We may add an additional layer. Web applications are typically
+ being build on top of an application server (<productname
+ xlink:href="http://www.ibm.com/software/de/websphere/">WebSphere</productname>,
+ <productname
+ xlink:href="http://glassfish.java.net">Glassfish</productname>,
+ <productname
+ xlink:href="http://www.jboss.org/jbossas">Jboss</productname>,...)
+ providing additional services:</para>
+
+ <figure xml:id="jdbcFourTier">
+ <title><trademark
+ xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc">JDBC</trademark>
+ connecting application server and database.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/jdbcFourTier.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>So what is actually required to connect to a database server?
+ A client requires the following parameter values to open a
+ connection:</para>
+
+ <orderedlist>
+ <listitem xml:id="ItemJdbcProtocol">
+ <para>The type of database server i.e. <productname
+ xlink:href="http://www.oracle.com/us/products/database">Oracle</productname>,
+ <productname
+ xlink:href="www.ibm.com/software/data/db2">DB2</productname>,
+ <productname
+ xlink:href="http://www-01.ibm.com/software/data/informix">Informix</productname>,
+ <productname
+ xlink:href="http://www.mysql.com">Mysql</productname> etc. This
+ information is needed because of vendor dependent <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ protocol implementations.</para>
+ </listitem>
+
+ <listitem>
+ <para>The server's <link
+ xlink:href="http://en.wikipedia.org/wiki/Domain_Name_System">DNS</link>
+ name or IP number</para>
+ </listitem>
+
+ <listitem>
+ <para>The database service's port number at the previously
+ defined host. The database server process listens for
+ connections to this port number.</para>
+ </listitem>
+
+ <listitem xml:id="itemJdbcDatabaseName">
+ <para>The database name within the given database server</para>
+ </listitem>
+
+ <listitem>
+ <para>Optional: A database user's account name and
+ password.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>Items <xref linkend="ItemJdbcProtocol"/> - <xref
+ linkend="itemJdbcDatabaseName"/> will be encapsulated into a so
+ called <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ <link
+ xlink:href="http://en.wikipedia.org/wiki/Uniform_Resource_Locator">URL</link>.
+ We consider a typical example corresponding to the previous
+ parameter list:</para>
+
+ <figure xml:id="jdbcUrlComponents">
+ <title>Components of a <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ URL</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/jdbcurl.fig" scale="65"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>In fact this <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ URL example closely resembles other types of URL strings as being
+ defined in <uri
+ xlink:href="http://www.ietf.org/rfc/rfc2396.txt">http://www.ietf.org/rfc/rfc2396.txt</uri>.
+ Look for <code>opaque_part</code> to understand the second
+ <quote>:</quote> in the protocol definition part of a <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ URL. Common example for <abbrev
+ xlink:href="http://www.ietf.org/rfc/rfc1738.txt">URL</abbrev>s
+ are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><code>http://www.hdm-stuttgart.de/aaa</code></para>
+ </listitem>
+
+ <listitem>
+ <para><code>http://someserver.com:8080/someResource</code></para>
+ </listitem>
+
+ <listitem>
+ <para><code>ftp://mirror.mi.hdm-stuttgart.de/Firmen</code></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>We notice the explicit mentioning of a port number 8080 in the
+ second example; The default <abbrev
+ xlink:href="http://www.w3.org/Protocols">http</abbrev> protocol port
+ number is 80. So if a web server accepts connections at port 80 we
+ do not have to specify this value. A web browser will automatically
+ use this default port.</para>
+
+ <para>Actually the notion <quote><code>jdbc:mysql</code></quote>
+ denotes a sub protocol implementation namely<orgname>
+ Mysql</orgname>'s implementation of <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>.
+ Connecting to an IBM DB2 server would require jdbc:db2 for this
+ protocol part.</para>
+
+ <para>In contrast to <abbrev
+ xlink:href="http://www.w3.org/Protocols">http</abbrev> no standard
+ ports are <quote>officially</quote> assigned for <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ protocol variants. Due to vendor specific implementations this does
+ not make any sense. Thus we <emphasis role="bold">always</emphasis>
+ have to specify the port number when opening <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ connections.</para>
+
+ <para>Writing <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ based applications follows a simple scheme:</para>
+
+ <figure xml:id="jdbcArchitecture">
+ <title>Architecture of JDBC</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/jdbcarch.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>From a programmer's point of view the
+ <classname>java.sql.DriverManager</classname> is a bootstrapping
+ object: Other objects like Statement instances are created from this
+ central and unique object.</para>
+
+ <para>The first instance being created by the
+ <classname>java.sql.DriverManager</classname> is an object of type
+ <classname>java.sql.Connection</classname>. In <xref
+ linkend="exerciseJdbcWhyInterface"/> we discuss the way vendor
+ specific implementation details are hidden by Interfaces. We can
+ distinguish between:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Vendor neutral specific parts of a <trademark
+ xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc">JDBC</trademark>
+ environment. These are those components being shipped by Oracle
+ or other organizations providing <link
+ linkend="gloss_Java"><trademark>Java</trademark></link>
+ runtimes. The class
+ <classname>java.sql.DriverManager</classname> belongs to this
+ domain.</para>
+ </listitem>
+
+ <listitem>
+ <para>Vendor specific parts. In <xref
+ linkend="jdbcArchitecture"/> this starts with the
+ <classname>java.sql.Connection</classname> object.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>The <classname>java.sql.Connection</classname> object thus
+ marks the boundary between a <trademark
+ xlink:href="http://www.oracle.com/technetwork/java/javase">JDK</trademark>
+ / <trademark
+ xlink:href="http://www.oracle.com/technetwork/java/javase">JRE</trademark>
+ and a <trademark
+ xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc">JDBC</trademark>
+ Driver implementation from e.g. Oracle or other institutions.</para>
+
+ <para><xref linkend="jdbcArchitecture"/> does not show details about
+ the relations between <classname>java.sql.Connection</classname>,
+ <classname>java.sql.Statement</classname> and
+ <classname>java.sql.ResultSet</classname> objects. We start by
+ giving a rough description of the tasks and responsibilities these
+ three types have:</para>
+
+ <glosslist>
+ <glossentry>
+ <glossterm><classname>java.sql.Connection</classname></glossterm>
+
+ <glossdef>
+ <para>Holding a permanent connection to a database server.
+ Both client and server can contact each other. The database
+ server may for example terminate a transaction if problems
+ like deadlocks occur.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm><classname>java.sql.Statement</classname></glossterm>
+
+ <glossdef>
+ <para>We have two distinct classes of actions:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Instructions to modify data on the database server.
+ These include <code>INSERT</code>, <code>UPDATE</code> and
+ <code>DELETE</code> operations as far as
+ <abbrev>SQL-DML</abbrev> is concerned. <trademark
+ xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc">JDBC</trademark>
+ acts as a means of transport and merely returns integer
+ values back to the client like the number of rows being
+ affected by an UPDATE.</para>
+ </listitem>
+
+ <listitem>
+ <para>Instructions reading data from the server. This is
+ done by sending SELECT statements. It is not sufficient to
+ just return integer values: Instead <trademark
+ xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc">JDBC</trademark>
+ needs to copy complete datasets back to the client to fill
+ containers being accessible by applications. This is being
+ discussed in <xref linkend="jdbcRead"/>.</para>
+ </listitem>
+ </orderedlist>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+
+ <para>We shed some light on the relationship between these important
+ <trademark
+ xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc">JDBC</trademark>
+ components and their respective creation:<figure
+ xml:id="jdbcObjectCreation">
+ <title>Important <trademark
+ xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc">JDBC</trademark>
+ instances and relationships.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/jdbcObjectRelation.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure></para>
+ </section>
+
+ <section xml:id="writeAccessCoding">
+ <title>Write access, coding!</title>
+
+ <para>So how does it actually work with respect to coding? You may
+ want to read <xref linkend="toolingConfigJdbc"/> before starting
+ your exercises. We first prepare a database table using Eclipse's
+ database tools:</para>
+
+ <figure xml:id="figSchemaPerson">
+ <title>A relation <code>Person</code> containing names and email
+ addresses</title>
+
+ <programlisting language="none"><emphasis role="strong">CREATE</emphasis> <emphasis
+ role="strong">TABLE</emphasis> Person (
+ name CHAR(20)
+ ,email CHAR(20) <emphasis>UNIQUE</emphasis>)</programlisting>
+ </figure>
+
+ <para>Our actual (toy) <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ application will insert a single object ('Jim', 'jim@foo.org') into
+ the <code>Person</code> relation. This is simpler than reading data
+ since no client <classname>java.sql.ResultSet</classname> container
+ is needed:</para>
+
+ <figure xml:id="figJdbcSimpleWrite">
+ <title>A simple <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ application inserting data into a relational table.</title>
+
+ <programlisting language="none">01 package sda.jdbc.intro.v1;
+02
+03 import java.sql.Connection;
+04 import java.sql.DriverManager;
+05 import java.sql.SQLException;
+06 import java.sql.Statement;
+07
+08 public class SimpleInsert {
+09
+10 public static void main(String[] args) throws SQLException {
+11 // Step 1: Open a connection to the database server
+12 final Connection conn = DriverManager.getConnection(
+13 "jdbc:mysql://localhost:3306/hdm", "hdmuser", "XYZ");
+14 // Step 2: Create a Statement instance
+15 final Statement stmt = conn.createStatement();
+16 // Step 3: Execute the desired INSERT
+17 final int updateCount = stmt.executeUpdate(
+18 "INSERT INTO Person VALUES('Jim', 'jim@foo.org')");
+19 // Step 4: Give feedback to the enduser
+20 System.out.println("Successfully inserted " + updateCount + " dataset(s)");
+21 }
+22 }</programlisting>
+ </figure>
+
+ <para>Looks simple? Unfortunately it does not (yet) work:</para>
+
+ <programlisting language="none">Exception in thread "main" java.sql.SQLException: <emphasis
+ role="bold">
+ No suitable driver found for jdbc:mysql://localhost:3306/hdm</emphasis>
+ at java.sql.DriverManager.getConnection(DriverManager.java:604)
+ at java.sql.DriverManager.getConnection(DriverManager.java:221)
+ at sda.jdbc.intro.SimpleInsert.main(SimpleInsert.java:12)</programlisting>
+
+ <para>What's wrong here? In <xref linkend="figureConfigJdbcDriver"/>
+ we needed a <productname
+ xlink:href="http://www.mysql.com">Mysql</productname> <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ Driver implementation <filename>mysql-connector-java.jar</filename>
+ as a prerequisite to open connections to a database server. This
+ implementation is mandatory for our toy application as well. All we
+ have to do is adding <filename>mysql-connector-java.jar</filename>
+ to our <link linkend="gloss_Java"><trademark>Java</trademark></link>
+ <varname>CLASSPATH</varname> at <emphasis
+ role="bold">runtime</emphasis>.</para>
+
+ <para>Depending on our <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> environment
+ this will be achieved by different means. Eclipse requires the
+ definition of a run configuration as being described in <uri
+ xlink:href="http://help.eclipse.org/juno/index.jsp?topic=/org.eclipse.jdt.doc.user/tasks/tasks-java-local-configuration.htm">http://help.eclipse.org/juno/index.jsp?topic=/org.eclipse.jdt.doc.user/tasks/tasks-java-local-configuration.htm</uri>.
+ When configuring a run-time configuration for
+ <classname>sda.jdbc.intro.SimpleInsert</classname> we have to add
+ <filename>mysql-connector-java.jar</filename> to the
+ <varname>Classpath</varname> tab. The following screen shot shows a
+ working configuration:</para>
+
+ <figure xml:id="figureConfigRunExtJar">
+ <title>Creating an Eclipse run time configuration containing a
+ <productname xlink:href="http://www.mysql.com">Mysql</productname>
+ <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ Driver Jar marked red.</title>
+
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Screen/runConfigJarAnnot.screen.png"
+ scale="70"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+ </figure>
+
+ <para>This time execution works as expected:</para>
+
+ <programlisting language="none">Successfully inserted 1 dataset(s)</programlisting>
+
+ <qandaset defaultlabel="qanda" xml:id="quandaentry_DupInsert">
+ <title>Exception on inserting objects</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>A second invocation of
+ <classname>sda.jdbc.intro.v1.SimpleInsert</classname> yields
+ the following runtime error:</para>
+
+ <programlisting language="none">Exception in thread "main"
+ com.mysql.jdbc.exceptions.jdbc4.MySQLIntegrityConstraintViolationException:
+ <emphasis role="bold">Duplicate entry 'jim@foo.org' for key 'email'</emphasis>
+...
+ at com.mysql.jdbc.StatementImpl.executeUpdate(StatementImpl.java:1617)
+ at sda.jdbc.intro.SimpleInsert.main(SimpleInsert.java:17)</programlisting>
+ </question>
+
+ <answer>
+ <para>This expected error is easy to understand: The
+ exception's message text <emphasis role="bold">Duplicate
+ entry 'Jim' for key 'PRIMARY'</emphasis> informs us about a
+ UNIQUE key constraint violation with respect to the
+ attribute <code>email</code> in our schema definition in
+ <xref linkend="figSchemaPerson"/>. We cannot add a second
+ entry with the same value <code>'jim@foo.org'</code>.</para>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+
+ <para>It is worth to mention that the <productname
+ xlink:href="http://www.mysql.com">Mysql</productname> driver
+ implementation does not have to be available at compile time.
+ <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ defines interfaces in favour of (concrete) classes. The latter are
+ only required at runtime.</para>
+
+ <para>When working with eclipse we need a separate runtime
+ configuration for each runnable <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> application
+ to add the <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ driver implementation to the runtime <envar>CLASSPATH</envar>. This
+ may become tedious. Judging the pros and cons you may simply add
+ <filename>mysql-connector-java.jar</filename> to your compile time
+ <envar>CLASSPATH as well</envar>. As a drawback all <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ implementing classes will now become visible wen e.g. hitting
+ auto-completion.</para>
+
+ <para>We now discuss some important methods being defined in the
+ <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ interfaces:</para>
+
+ <glosslist>
+ <glossentry>
+ <glossterm><classname>java.sql.Connection</classname></glossterm>
+
+ <glossdef>
+ <itemizedlist>
+ <listitem>
+ <para><link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#createStatement()">createStatement()</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#setAutoCommit(boolean)">setAutoCommit()</link>,
+ <link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#getAutoCommit()">getAutoCommit()</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#getWarnings()">getWarnings()</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#isClosed()">isClosed()</link>,
+ <link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#isValid(int)">isValid(int
+ timeout)</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#rollback()">rollback()</link>,
+ <link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#commit()">commit()</link>
+ and .</para>
+ </listitem>
+
+ <listitem>
+ <para><link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#close()">close()</link></para>
+ </listitem>
+ </itemizedlist>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm><classname>java.sql.Statement</classname></glossterm>
+
+ <glossdef>
+ <itemizedlist>
+ <listitem>
+ <para><link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Statement.html#executeUpdate(java.lang.String)">executeUpdate(String
+ sql)</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Statement.html#getConnection()">getConnection()</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Statement.html#getResultSet()">getResultSet()</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Statement.html#close()">close()</link>
+ and <link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Statement.html#isClosed()">isClosed()</link></para>
+ </listitem>
+ </itemizedlist>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+
+ <qandaset defaultlabel="qanda" xml:id="quandaentry_AutoCommit">
+ <title><trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ and transactions</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para><link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#setAutoCommit(boolean)">How
+ does the method setAutoCommit()</link> relate to <link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#commit()">commit()</link>
+ and <link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/Connection.html#rollback()">rollback()</link>?</para>
+ </question>
+
+ <answer>
+ <para>A connections default state is <code>autocommit ==
+ true</code>. This means that individual SQL statements are
+ executed as separate transactions.</para>
+
+ <para>If we want to group two or more statements into a
+ transaction we have to:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Call
+ <code>connection.setAutoComit(false)</code></para>
+ </listitem>
+
+ <listitem>
+ <para>From now on subsequent SQL statements will
+ implicitly become part of a transaction till either of
+ the three events happens:</para>
+
+ <orderedlist numeration="loweralpha">
+ <listitem>
+ <para><code>connection.commit()</code></para>
+ </listitem>
+
+ <listitem>
+ <para><code>connection.rollback()</code></para>
+ </listitem>
+
+ <listitem>
+ <para>The transaction gets aborted by the database
+ server. This may for example happen in case of a
+ deadlock conflict with a second transaction.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>Note that the first two events are initiated by
+ our client software. The third possible action is being
+ carried out by the database server.</para>
+ </listitem>
+ </orderedlist>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+
+ <qandaset defaultlabel="qanda" xml:id="quandaentry_Close">
+ <title>Closing <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ connections</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>Why is it very important to call the close() method
+ for <classname>java.sql.Connection</classname> and / or
+ <classname>java.sql.Statement</classname> instances?</para>
+ </question>
+
+ <answer>
+ <para>A <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ connection ties network resources (socket connections).
+ These may be used up if e.g. new connections get established
+ within a loop without being closed.</para>
+
+ <para>The situation is comparable to memory leaks when using
+ programming languages lacking a garbage collector.</para>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+
+ <qandaset defaultlabel="qanda" xml:id="quandaentry_AbortTran">
+ <title>Aborted transactions</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>In the previous exercise we mentioned the possibility
+ of a transaction abort issued by the database server. Which
+ responsibility arises for an application programmer? Hint:
+ How may an implementation become aware of such an abort
+ transaction event?</para>
+ </question>
+
+ <answer>
+ <para>If a database server aborts a transaction a
+ <classname>java.sql.SQLException</classname> will be thrown.
+ An application must be aware of this possibility and thus
+ implement a sensible <code>catch(...)</code> clause
+ accordingly.</para>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+
+ <qandaset defaultlabel="qanda" xml:id="exerciseJdbcWhyInterface">
+ <title>Interfaces and classes in <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark></title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>The <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ standard mostly defines interfaces as
+ <classname>java.sql.Connection</classname> and
+ <classname>java.sql.Statement</classname>. Why are these not
+ being defined as classes? Moreover why is
+ <classname>java.sql.DriverManager</classname> being defined
+ as a class rather than an interface?</para>
+
+ <para>You may want to supply code examples to explain your
+ argumentation.</para>
+ </question>
+
+ <answer>
+ <para>Figure <xref linkend="jdbcArchitecture"/> tells us
+ about the vendor independent architecture of <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>.
+ Oracle for example may implement a class
+ <code>com.oracle.jdbc.OracleConnection</code>:</para>
+
+ <programlisting annotations="nojavadoc" language="java">package com.oracle.jdbc;
+
+import java.sql.Connection;
+import java.sql.Statement;
+import java.sql.SQLException;
+
+public class OracleConnection implements Connection {
+
+...
+
+Statement createStatement(int resultSetType,
+ int resultSetConcurrency)
+ throws SQLException) {
+ // Implementation omitted here due to
+ // limited personal hacking capabilities
+ ...
+}
+...
+}</programlisting>
+
+ <para>If a programmer only uses the <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ interfaces rather than a vendor's classes it is much easier
+ to make the resulting application work with different
+ databases from other vendors. This way a company's
+ implementation is not exposed to our own <link
+ linkend="gloss_Java"><trademark>Java</trademark></link>
+ code.</para>
+
+ <para>Regarding the special role of
+ <classname>java.sql.DriverManager</classname> we notice the
+ need of a starting point: We have to create an initial
+ instance of some class. In theory (<emphasis role="bold">BUT
+ NOT IN PRACTICE!!!</emphasis>) the following (ugly code)
+ might be possible:</para>
+
+ <programlisting language="none">package my.personal.application;
+
+import java.sql.Connection;
+import java.sql.Statement;
+import java.sql.SQLException;
+
+public someClass {
+
+ public void someMethod(){
+
+ Connection conn = <emphasis role="bold">new OracleConnection()</emphasis>; // bad idea!
+ ...
+ }
+ ...
+}</programlisting>
+
+ <para>The problem with this approach is the explicit
+ constructor call: Whenever we want to use another database
+ we have two possibilities:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Rewrite our code.</para>
+ </listitem>
+
+ <listitem>
+ <para>Introduce some sort of switch statement to provide
+ a fixed number of databases beforehand:</para>
+
+ <programlisting language="none">public void someMethod(final String vendor){
+
+ final Connection conn;
+
+ switch(vendor) {
+ case "ORACLE":
+ conn = new OracleConnection();
+ break;
+
+ case "DB2":
+ conn = new Db2Connection();
+ break;
+
+ default:
+ conn = null;
+ break;
+ }
+ ...
+}</programlisting>
+
+ <para>Adding a new database still requires code
+ rewriting.</para>
+ </listitem>
+ </itemizedlist>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+
+ <qandaset defaultlabel="qanda" xml:id="quandaentry_DriverDispatch">
+ <title>Driver dispatch mechanism</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>In exercise <xref linkend="exerciseJdbcWhyInterface"/>
+ we saw a hypothetic way to resolve the interface/class
+ resolution problem by using a switch clause. How is this
+ <code>switch</code> clause's logic actually realized in a
+ <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ based application? (<quote>behind the scenes</quote>)</para>
+
+ <para>Hint: Read the documentation of
+ <classname>java.sql.DriverManager</classname>.</para>
+ </question>
+
+ <answer>
+ <para>Prior to opening a Connection a <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ driver registers itself at the
+ <classname>java.sql.DriverManager</classname> singleton
+ instance. For this purpose the standard defined the method
+ <link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/DriverManager.html#registerDriver(java.sql.Driver)">registerDriver(Driver)</link>.
+ On success the <classname>java.sql.DriverManager</classname>
+ adds the driver to an internal dictionary:</para>
+
+ <informaltable border="1">
+ <col width="20%"/>
+
+ <col width="30%"/>
+
+ <tr>
+ <th>protocol</th>
+
+ <th>driver instance</th>
+ </tr>
+
+ <tr>
+ <td>jdbc:mysql</td>
+
+ <td>mysqlDriver instance</td>
+ </tr>
+
+ <tr>
+ <td>jdbc:oracle</td>
+
+ <td>oracleDriver instance</td>
+ </tr>
+
+ <tr>
+ <td>...</td>
+
+ <td>...</td>
+ </tr>
+ </informaltable>
+
+ <para>So whenever the method <link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/DriverManager.html#getConnection(java.lang.String,%20java.lang.String,%20java.lang.String)">getConnection()</link>
+ is being called the
+ <classname>java.sql.DriverManager</classname> will scan the
+ <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ URL and isolate the protocol part. If we start with
+ <code>jdbc:mysql://someserver.com:3306/someDatabase</code>
+ this is just <code>jdbc:mysql</code>. The value is then
+ being looked up in the above table of registered drivers to
+ choose an appropriate instance or null otherwise. This way
+ our hypothetic switch including the default value null is
+ actually implemented.</para>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+
+ <section xml:id="propertiesFile">
+ <title>Connection properties</title>
+
+ <para>So far our application depicted in <xref
+ linkend="figJdbcSimpleWrite"/> suffers both from missing error
+ handling and hard-coded parameters.</para>
+
+ <para>Professional applications must be configurable. Changing the
+ password currently requires source code modification and
+ recompilation. <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> offers a
+ standard procedure to externalize parameters like
+ <varname>username</varname>, <varname>password</varname> an
+ <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ connection URL as being present in <xref
+ linkend="figJdbcSimpleWrite"/>: We may externalize these parameters
+ to external so called properties files:</para>
+
+ <figure xml:id="propertyExternalization">
+ <title>Externalize a single string <code>"User name"</code> to a
+ separate file <filename>message.properties</filename>.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/externalize.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The current figure shows the externalization of just a single
+ property. The file <filename>message.properties</filename> contains
+ key-value pairs. The key <code>PropHello.uname</code> contains the
+ value <code>User name</code>. Multiple strings may be externalized
+ to the same properties file.</para>
+
+ <para>Eclipse does have tool support for externalization. Simply hit
+ Source --> Externalize Strings from the context menu. This
+ activates a wizard to define property keys, renaming the generated
+ helper class' name and finally create the actual
+ <filename>message.properties</filename> file.</para>
+
+ <qandaset defaultlabel="qanda" xml:id="quandaentry_WritProps">
+ <title>Moving <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ <abbrev
+ xlink:href="http://www.ietf.org/rfc/rfc1738.txt">URL</abbrev> and
+ credentials to a property file</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>Start executing the code given in <xref
+ linkend="figJdbcSimpleWrite"/>. Then extend this example by
+ externalizing all <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ related connection parameters to a
+ <filename>jdbc.properties</filename> file like:</para>
+
+ <programlisting language="none">SimpleInsert.jdbcUrl=jdbc:mysql://localhost:3306/hdm
+SimpleInsert.password=XYZ
+SimpleInsert.username=hdmuser</programlisting>
+
+ <para>As being stated earlier the eclipse wizard assists you
+ by generating both the properties file and a helper class
+ reading that file at runtime.</para>
+ </question>
+
+ <answer>
+ <para>The current exercise is mostly related to tooling.
+ From our <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> code
+ the context menu allows us to choose the desired
+ wizard:</para>
+
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Screen/externalize.screen.png"/>
+ </imageobject>
+ </mediaobject>
+ </informalfigure>
+
+ <para>We may now:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Select the strings to be externalized.</para>
+ </listitem>
+
+ <listitem>
+ <para>Supply key names. In the subsequent screenshot
+ this task has already been started by manually replacing
+ the default <code>SimpleInsert.1</code> by
+ <code>Simpleinsert.jdbc</code>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Redefine other parameters like prefix, properties
+ file name etc. In the following screenshot only the
+ first of three keys has been manually renamed to the
+ sensible value
+ <varname>SimpleInsert.jdbc</varname>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Screen/externalize2.screen.png"/>
+ </imageobject>
+ </mediaobject>
+ </informalfigure>
+
+ <para>The wizard also generates a class
+ <classname>sda.jdbc.intro.v1.DbProps</classname> to actually
+ access our properties:</para>
+
+ <programlisting language="none">package sda.jdbc.intro.v1;
+...
+public class DbProps {
+ private static final String BUNDLE_NAME = "sda.jdbc.intro.v1.database";
+
+ private static final ResourceBundle RESOURCE_BUNDLE = ResourceBundle
+ .getBundle(BUNDLE_NAME);
+
+ private DbProps() {
+ }
+
+ public static String getString(String key) {
+ try {
+ return RESOURCE_BUNDLE.getString(key);
+ } catch (MissingResourceException e) {
+ return '!' + key + '!';
+ }
+ }
+}</programlisting>
+
+ <para>Our <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ related code now contains three references to external
+ properties:</para>
+
+ <programlisting language="none">package sda.jdbc.intro.v1;
+...
+public class SimpleInsert {
+
+
+ public static void main(String[] args) throws SQLException {
+ // Step 1: Open a connection to the database server
+ final Connection conn = DriverManager.getConnection (
+ <emphasis role="bold">DbProps.getString("PersistenceHandler.jdbcUrl"), </emphasis>
+ <emphasis role="bold">DbProps.getString("PersistenceHandler.username")</emphasis>,
+ <emphasis role="bold">DbProps.getString("PersistenceHandler.password")</emphasis>);
+ // Step 2: Create a Statement instance
+ final Statement stmt = conn.createStatement();
+ // Step 3: Execute the desired INSERT
+ final int updateCount = stmt.executeUpdate(
+ "INSERT INTO Person VALUES('Jim', 'jim@foo.org')");
+ // Step 4: Give feedback to the enduser
+ System.out.println("Successfully inserted " + updateCount + " dataset(s)");
+ }
+}</programlisting>
+
+ <para>The current base name
+ <classname>sda.jdbc.intro.v1.PersistenceHandler</classname>
+ is related to a later exercise.</para>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+
+ <section xml:id="sectSimpleInsertGui">
+ <title>A first GUI sketch</title>
+
+ <para>So far all data records being transferred to the database
+ server are still hard-coded in our application. In practice a user
+ wants to enter data of persons to be submitted to the
+ database.</para>
+
+ <para>We now guide you to develop a first version of a simple GUI
+ for this tasks. A more <link linkend="figureDataInsert2">elaborate
+ version</link> will be presented in a follow-up exercise. The
+ screenshot illustrates the intended application behaviour:</para>
+
+ <figure xml:id="simpleInsertGui">
+ <title>A simple GUI to insert data into a database server.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Screen/simpleInsertGui.screen.png"/>
+ </imageobject>
+
+ <caption>
+ <para>After clicking <quote>Insert</quote> a message is being
+ presented to the user. This message may as well indicate a
+ failure.</para>
+ </caption>
+ </mediaobject>
+ </figure>
+
+ <para>Implementing Swing GUI applications requires knowledge as
+ being taught in e.g. <link
+ xlink:href="http://www.hdm-stuttgart.de/studenten/stundenplan/vorlesungsverzeichnis/vorlesung_detail?vorlid=5212221">113300
+ Entwicklung von Web-Anwendungen</link>. If you do not (yet) feel
+ comfortable writing <productname
+ xlink:href="http://docs.oracle.com/javase/tutorial/uiswing/index.html">Swing</productname>
+ applications you may want to read <uri
+ xlink:href="http://www.javamex.com/tutorials/swing">http://www.javamex.com/tutorials/swing</uri>
+ and <emphasis role="bold">really</emphasis> understand the examples
+ being presented therein.</para>
+
+ <qandaset defaultlabel="qanda" xml:id="quandaentry_GuiDb">
+ <title>GUI for inserting Person data to a database server</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>Write a GUI application as being outlined in <xref
+ linkend="simpleInsertGui"/>. You may proceed as
+ follows:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Write a dummy GUI without any database
+ functionality. Only present the two labels an input
+ fields and the Insert button.</para>
+ </listitem>
+
+ <listitem>
+ <para>Add an
+ <classname>java.awt.event.ActionListener</classname>
+ which generates a SQL INSERT Statement when clicking the
+ Insert button. Return this string to the user as being
+ shown in the message window of <xref
+ linkend="simpleInsertGui"/>.</para>
+
+ <para>At this point you still do not need a database
+ connection. The message shown to the user is just a
+ fake, so the GUI <emphasis
+ role="bold">appears</emphasis> to be working.</para>
+ </listitem>
+
+ <listitem>
+ <para>Establish a
+ <classname>java.sql.Connection</classname> and create a
+ <classname>java.sql.Statement</classname> instance when
+ launching your application. Use the latter in your
+ <classname>java.awt.event.ActionListener</classname> to
+ actually insert datasets into your database.</para>
+ </listitem>
+ </orderedlist>
+ </question>
+
+ <answer>
+ <para>The complete implementation resides in
+ <classname>sda.jdbc.intro.v01.InsertPerson</classname>:</para>
+
+ <programlisting language="none">package sda.jdbc.intro.v01;
+
+import ...
+
+public class InsertPerson extends JFrame {
+
+ ...
+
+ public InsertPerson () throws SQLException{
+ super ("Add a person's data");
+
+ setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
+
+ final JPanel databaseFieldPanel = new JPanel();
+ databaseFieldPanel.setLayout(new GridLayout(0,2));
+ add(databaseFieldPanel, BorderLayout.CENTER);
+
+ databaseFieldPanel.add(new JLabel("Name:"));
+ final JTextField nameField = new JTextField(15);
+ databaseFieldPanel.add(nameField);
+
+ databaseFieldPanel.add(new JLabel("E-mail:"));
+ final JTextField emailField = new JTextField(15);
+ databaseFieldPanel.add(emailField);
+
+ final JButton insertButton = new JButton("Insert");
+ add(insertButton, BorderLayout.SOUTH);
+
+ final Connection conn = DriverManager.getConnection(
+ "jdbc:mysql://localhost:3306/hdm", "hdmuser", "XYZ");
+ final Statement stmt = conn.createStatement();
+
+ insertButton.addActionListener(new ActionListener() {
+ // Linking the GUI to the database server. We assume an open
+ // connection and a correctly initialized Statement instance
+ @Override
+ public void actionPerformed(ActionEvent event) {
+ final String sql = "INSERT INTO Person VALUES('" + nameField.getText()+ "', '"
+ + emailField.getText() + "')";
+ // We have to catch this Exception because an ActionListener's signature
+ // prohibits the existence of a "throws" clause.
+ try {
+ final int updateCount = stmt.executeUpdate(sql);
+ JOptionPane.showMessageDialog(null, "Successfully executed \n'" + sql + "'\nand inserted "
+ + updateCount + " dataset");
+ } catch (SQLException e) {
+ e.printStackTrace();
+ }
+ }
+ });
+ pack();
+ }
+}</programlisting>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+
+ <section xml:id="jdbcExceptions">
+ <title>Handling possible exceptions</title>
+
+ <para>Our current code lacks any kind of error handling: Exceptions
+ will not be caught at all and invariably lead to program
+ termination. This is of course inadequate regarding professional
+ software. In case of problems we have to:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Gracefully recover or shut down our application. We may
+ for example show a pop up window <quote>Terminating due to an
+ internal error</quote>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Enable the customer to supply the development team with
+ helpful information. The user may for example be asked to submit
+ a log file in case of errors.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>In addition the solution
+ <classname>sda.jdbc.intro.v01.InsertPerson</classname> contains an
+ ugly mix of GUI components and database related code. We take a
+ first step to decouple these two distinct concerns:</para>
+
+ <qandaset defaultlabel="qanda" xml:id="quandaentry_DbLayer">
+ <title>Handling the database layer</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>Implement a class <code>PersistenceHandler</code> to
+ be later used as a component of our next step GUI
+ application prototype. This class should have the following
+ methods:</para>
+
+ <programlisting language="none">...
+/**
+ * Handle database communication. There are two
+ * distinct internal states <q>disconnected</q> and <q>connected</q>, see
+ * {@link #isConnected()}. These two states may be toggled by invoking
+ * {@link #connect()} and {@link #disconnect()} respectively.
+ *
+ * The following snippet illustrates the intended usage:
+ * <pre> public static void main(String[] args) {
+ final PersistenceHandler ph = new PersistenceHandler();
+ if (ph.connect()) {
+ if (!ph.add("Jim", "jim@foo.com")) {
+ System.err.println("Insert Error:" + ph.getErrorMessage());
+ }
+ } else {
+ System.err.println("Connect error:" + ph.getErrorMessage());
+ }
+ }</pre>
+ *
+ * @author goik
+ */
+public class PersistenceHandler {
+ ...
+ /**
+ * Instance in <q>disconnected</q> state. See {@link #isConnected()}
+ */
+ public PersistenceHandler() {/* only present here to supply Javadoc comment */}
+
+ /**
+ * Inserting a (name, email) record into the database server. In case of
+ * errors corresponding messages may subsequently be retrieved by calling
+ * {@link #getErrorMessage()}.
+ *
+ * <dt><b>Precondition:</b></dt> <dd>must be in
+ * <q>connected</q> state, see {@link #isConnected()}</dd>
+ *
+ * @param name
+ * A person's name
+ * @param email
+ * A person's email address
+ *
+ * @return true if the current data record has been successfully inserted
+ * into the database server. false in case of error(s).
+ */
+ public boolean add(final String name, final String email){
+ ...
+ }
+
+ /**
+ * Retrieving error messages in case a call to {@link #add(String, String)},
+ * {@link #connect()}, or {@link #disconnect()} yields an error.
+ *
+ * @return the error explanation corresponding to the latest failed
+ * operation, null if no error yet occurred.
+ */
+ public String getErrorMessage() {
+ return ...;
+ }
+
+ /**
+ * Open a connection to a database server.
+ *
+ * <dt><b>Precondition:</b><dd>
+ * <dd>must be in <q>disconnected</q> state, see {@link #isConnected()}</dd>
+ *
+ * <dt><b>Precondition:</b><dd>
+ * <dd>The following properties must be set:
+ * <pre>PersistenceHandler.jdbcUrl=jdbc:mysql://localhost:3306/hdm
+PersistenceHandler.password=XYZ
+PersistenceHandler.username=foo</pre>
+ * </dd>
+ *
+ * @return true if connecting was successful
+ */
+ public boolean connect () {
+ ...
+ }
+
+ /**
+ * Close a connection to a database server and clean up JDBC related resources
+ *
+ * Error messages in case of failure may subsequently be retrieved by
+ * calling {@link #getErrorMessage()}.
+ *
+ * <dt><b>Precondition:</b></dt>
+ * <dd>must be in <q>connected</q> state, see {@link #isConnected()}</dd>
+ *
+ * @return true if disconnecting was successful, false in case error(s) occur.
+ */
+ public boolean disconnect() {
+ ...
+ }
+
+ /**
+ * An instance can either be in <q>connected</q> or <q>disconnected</q> state. The
+ * state can be toggled by invoking {@link #connect()} or
+ * {@link #disconnect()} respectively.
+ *
+ * @return true if connected, false otherwise
+ */
+ public boolean isConnected() {
+ return ...;
+ }
+}</programlisting>
+
+ <para>Notice the two internal states
+ <quote>disconnected</quote> and
+ <quote>connected</quote>:</para>
+
+ <figure xml:id="figPersistenceHandlerStates">
+ <title>Possible states and transitions for instances of
+ <code>PersistenceHandler</code>.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/persistHandlerStates.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>According to the above documentation a newly created
+ <code>PersistenceHandler</code> instance should be in
+ disconnected state. As being shown in the <link
+ linkend="gloss_Java"><trademark>Java</trademark></link>
+ class description you may test your implementation without
+ any GUI code. If you are already familiar with unit testing
+ this might be a good start as well.</para>
+ </question>
+
+ <answer>
+ <para>We show a possible implementation of
+ <classname>sda.jdbc.intro.v1.PersistenceHandler</classname>:</para>
+
+ <programlisting language="none">package sda.jdbc.intro.v1;
+...
+
+public class PersistenceHandler {
+
+ Connection conn = null;
+ Statement stmt = null;
+
+ String errorMessage = null;
+
+ /**
+ * New instances are in <q>disconnected</q> state. See {@link #isConnected()}
+ */
+ public PersistenceHandler() {/* only present here to supply Javadoc comment */}
+
+ /**
+ * Inserting a (name, email) record into the database server. In case of
+ * errors corresponding messages may subsequently be retrieved by calling
+ * {@link #getErrorMessage()}.
+ *
+ * <dt><b>Precondition:</b></dt> <dd>must be in
+ * <q>connected</q> state, see {@link #isConnected()}</dd>
+ *
+ * @param name
+ * A person's name
+ * @param email
+ * A person's email address
+ *
+ * @return true if the current data record has been successfully inserted
+ * into the database server. false in case of error(s).
+ */
+ public boolean add(final String name, final String email){
+ final String sql = "INSERT INTO Person VALUES('" + name + "', '" +
+ email + "')";
+ try {
+ stmt.executeUpdate(sql);
+ return true;
+ } catch (SQLException e) {
+ errorMessage = "Unable to execute '" + sql + "': '" + e.getMessage() + "'";
+ return false;
+ }
+ }
+
+ /**
+ * Retrieving error messages in case a call to {@link #add(String, String)},
+ * {@link #connect()}, or {@link #disconnect()} yields an error.
+ *
+ * @return the error explanation corresponding to the latest failed
+ * operation, null if no error yet occurred.
+ */
+ public String getErrorMessage() {
+ return errorMessage;
+ }
+
+ /**
+ * Open a connection to a database server.
+ *
+ * <dt><b>Precondition:</b><dd>
+ * <dd>must be in <q>disconnected</q> state, see {@link #isConnected()}</dd>
+ *
+ * <dt><b>Precondition:</b><dd>
+ * <dd>The following properties must be set:
+ * <pre>PersistenceHandler.jdbcUrl=jdbc:mysql://localhost:3306/hdm
+PersistenceHandler.password=XYZ
+PersistenceHandler.username=foo</pre>
+ * </dd>
+ *
+ * @return true if connecting was successful
+ */
+ public boolean connect () {
+ try {
+ conn = DriverManager.getConnection(
+ DbProps.getString("PersistenceHandler.jdbcUrl"),
+ DbProps.getString("PersistenceHandler.username"),
+ DbProps.getString("PersistenceHandler.password"));
+ try {
+ stmt = conn.createStatement();
+ return true;
+ } catch (SQLException e) {
+ errorMessage = "Connection opened but Statement creation failed:\"" + e.getMessage() + "\".";
+ try {
+ conn.close();
+ } catch (SQLException ee) {
+ errorMessage += "Closing connection failed:\"" + e.getMessage() + "\".";
+ }
+ conn = null;
+ }
+
+ } catch (SQLException e) {
+ errorMessage = "Unable to open connection:\"" + e.getMessage() + "\".";
+ }
+ return false;
+ }
+
+ /**
+ * Close a connection to a database server and clean up JDBC related resources
+ *
+ * Error messages in case of failure may subsequently be retrieved by
+ * calling {@link #getErrorMessage()}.
+ *
+ * <dt><b>Precondition:</b></dt>
+ * <dd>must be in <q>connected</q> state, see {@link #isConnected()}</dd>
+ *
+ * @return true if disconnecting was successful, false in case error(s) occur.
+ */
+ public boolean disconnect() {
+ boolean resultStatus = true;
+ final StringBuffer messageCollector = new StringBuffer();
+ try {
+ stmt.close();
+ } catch (SQLException e) {
+ resultStatus = false;
+ messageCollector.append("Unable to close Statement:\"" + e.getMessage() + "\".");
+ }
+ stmt = null;
+ try {
+ conn.close();
+ } catch (SQLException e) {
+ resultStatus = false;
+ messageCollector.append("Unable to close connection:\"" + e.getMessage() + "\".");
+ }
+ conn = null;
+ if (!resultStatus) {
+ errorMessage = messageCollector.toString();
+ }
+ return resultStatus;
+ }
+
+ /**
+ * An instance can either be in <q>connected</q> or <q>disconnected</q> state. The
+ * state can be toggled by invoking {@link #connect()} or
+ * {@link #disconnect()} respectively.
+ *
+ * @return true if connected, false otherwise
+ */
+ public boolean isConnected() {
+ return null != conn;
+ }
+}</programlisting>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+
+ <para>We may now complete the next enhancement step of our GUI
+ database client.</para>
+
+ <qandaset defaultlabel="qanda" xml:id="exerciseGuiWriteTakeTwo">
+ <title>Connection on user action</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <label>An application writing records to a database
+ server</label>
+
+ <para>Our aim is to enhance the first GUI prototype being
+ described in <xref linkend="simpleInsertGui"/>. The
+ application shall start being disconnected from the database
+ server. Prior to entering data the user shall be guided to
+ open a connection. The following video illustrates the
+ desired user interface:</para>
+
+ <figure xml:id="figureDataInsert2">
+ <title>A GUI frontend for adding personal data to a
+ server.</title>
+
+ <mediaobject>
+ <videoobject>
+ <videodata fileref="Ref/Video/dataInsert.mp4"/>
+ </videoobject>
+ </mediaobject>
+ </figure>
+
+ <para>In case a user closes the main window while still
+ being connected a disconnect from the database server shall
+ be enforced. For this purpose we must handle the event when
+ the user clicks on the closing button within the window
+ decoration. An exit handler method is being required to
+ terminate a potentially open database connection.</para>
+ </question>
+
+ <answer>
+ <para>Our implementation uses the class
+ <classname>sda.jdbc.intro.v1.PersistenceHandler</classname>
+ for handling all database communication. The GUI needs to
+ visualize the two different states
+ <quote>disconnected</quote> and <quote>connected</quote>. In
+ <quote>disconnected</quote> state the whole input pane for
+ entering datasets and clicking the <quote>Insert</quote>
+ button is locked. So the user is forced to actively open a
+ database connection.</para>
+
+ <para>Notice also the
+ <classname>java.awt.event.WindowAdapter</classname>
+ implementation being executed when closing the application's
+ main window. The
+ <methodname>java.awt.event.WindowAdapter.windowClosing(java.awt.event.WindowEvent)</methodname>
+ method disconnects any existing database connection thus
+ freeing resources.</para>
+
+ <programlisting language="none">package sda.jdbc.intro.v1;
+
+import ...
+
+public class InsertPerson extends JFrame {
+
+ private static final long serialVersionUID = 6815975741605247675L;
+
+ final PersistenceHandler persistenceHandler = new PersistenceHandler();
+
+ final JTextField nameField = new JTextField(15),
+ emailField = new JTextField(20);
+
+ final JButton toggleConnectButton = new JButton(),
+ insertButton = new JButton("Insert");
+
+ final JPanel databaseFieldPanel = new JPanel();
+
+ private void setGuiConnectionState(final boolean state) {
+ if (state) {
+ toggleConnectButton.setText("Disconnect");
+ } else {
+ toggleConnectButton.setText("Connect");
+ }
+ for (final Component c: databaseFieldPanel.getComponents()){
+ c.setEnabled(state);
+ }
+ }
+
+ public static void main(String[] args) throws SQLException {
+ InsertPerson app = new InsertPerson();
+ app.setVisible(true);
+ }
+
+ public InsertPerson (){
+ super ("Add a person's data");
+
+ setSize(500, 500);
+
+ addWindowListener(new WindowAdapter() {
+ // In case a user closes our application window while still being connected
+ // we have to close the database connection.
+ @Override
+ public void windowClosing(WindowEvent e) {
+ super.windowClosing(e);
+ if (persistenceHandler.isConnected() && !persistenceHandler.disconnect()) {
+ System.exit(1);
+ } else {
+ System.exit(0);
+ }
+ });
+ Box top = Box.createHorizontalBox();
+ add(top, BorderLayout.NORTH);
+ top.add(toggleConnectButton);
+
+ toggleConnectButton.addActionListener(new ActionListener() {
+
+ @Override
+ public void actionPerformed(ActionEvent e) {
+ if (persistenceHandler.isConnected()) {
+ if (persistenceHandler.disconnect()){
+ setGuiConnectionState(false);
+ } else {
+ JOptionPane.showMessageDialog(null, persistenceHandler.getErrorMessage());
+ }
+ } else {
+ if (persistenceHandler.connect()){
+ setGuiConnectionState(true);
+ } else {
+ JOptionPane.showMessageDialog(null, persistenceHandler.getErrorMessage());
+ }
+ }
+ }
+ });
+
+ databaseFieldPanel.setLayout(new GridLayout(0,2));
+ add(databaseFieldPanel);
+
+ databaseFieldPanel.add(new JLabel("Name:"));
+ databaseFieldPanel.add(nameField);
+
+ databaseFieldPanel.add(new JLabel("E-mail:"));
+ databaseFieldPanel.add(emailField);
+
+ insertButton.addActionListener(new ActionListener() {
+ @Override
+ public void actionPerformed(ActionEvent e) {
+ if (persistenceHandler.add(nameField.getText(), emailField.getText())) {
+ nameField.setText("");
+ emailField.setText("");
+ JOptionPane.showMessageDialog(null, "Succesfully inserted dataset");
+ } else {
+ JOptionPane.showMessageDialog(null, persistenceHandler.getErrorMessage());
+ }
+ }
+ });
+ databaseFieldPanel.add(Box.createGlue());
+ databaseFieldPanel.add(insertButton);
+ setGuiConnectionState(false);
+ pack();
+ }
+}</programlisting>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+
+ <section xml:id="jdbcSecurity">
+ <title><trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ and security</title>
+
+ <section xml:id="jdbcSecurityNetwork">
+ <title>Network sniffing</title>
+
+ <para>Sniffing <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ network traffic is one possibility for intruders to compromise
+ database applications. This requires physical access to either
+ of:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Server host</para>
+ </listitem>
+
+ <listitem>
+ <para>Client host</para>
+ </listitem>
+
+ <listitem>
+ <para>intermediate hub, switch or router.</para>
+ </listitem>
+ </itemizedlist>
+
+ <figure xml:id="figJdbcSniffing">
+ <title>Sniffing a <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ connection by an intruder.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/jdbcSniffing.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>We demonstrate a possible attack by analyzing the network
+ traffic between our application shown in <xref
+ linkend="figJdbcSimpleWrite"/> and the <productname
+ xlink:href="http://www.mysql.com">Mysql</productname> database
+ server. Prior to starting the application we set up <productname
+ xlink:href="http://www.wireshark.org">Wireshark</productname> for
+ filtered capturing:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Connecting to the <varname>loopback</varname> (lo)
+ interface only. This is sufficient since our client connects
+ to <varname>localhost</varname>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Filtering packets if not of type <acronym
+ xlink:href="http://en.wikipedia.org/wiki/Transmission_Control_Protocol">TCP</acronym>
+ and having port number 3306</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>This yields the following capture being shortened for the
+ sake of brevity:</para>
+
+ <programlisting language="none">[...
+5.5.24-0ubuntu0.12.04.1.%...X*e?I1ZQ...................e,F[yoA5$T[N.mysql_native_password.
+ A...........!.......................hdmuser <co xml:id="tcpCaptureUsername"/>......U.>S.%..~h...!.xhdm............j..../*
+
+ ... INSERT INTO Person VALUES('Jim', 'jim@foo.org') <co
+ xml:id="tcpCaptureSqlInsert"/>6...
+ .&.#23000Duplicate entry 'jim@foo.org' for key 'email' <co
+ xml:id="tcpCaptureErrmsg"/></programlisting>
+
+ <calloutlist>
+ <callout arearefs="tcpCaptureUsername">
+ <para>The <varname>username</varname> initiating the
+ connection to the database server.</para>
+ </callout>
+
+ <callout arearefs="tcpCaptureSqlInsert">
+ <para>The <code>INSERT ...</code> statement.</para>
+ </callout>
+
+ <callout arearefs="tcpCaptureErrmsg">
+ <para>The resulting error message being sent back to the
+ client.</para>
+ </callout>
+ </calloutlist>
+
+ <para>Something seems to be missing here: The user's password. Our
+ code in <xref linkend="figJdbcSimpleWrite"/> contains the password
+ <quote><varname>XYZ</varname></quote> in clear text. But even
+ using the search function of <productname
+ xlink:href="http://www.wireshark.org">Wireshark</productname> does
+ not show any such string within the above capture. The
+ <productname xlink:href="http://www.mysql.com">Mysql</productname>
+ documentation however <link
+ xlink:href="http://dev.mysql.com/doc/refman/5.0/en/security-against-attack.html">reveals</link>
+ that everything but the password is transmitted in clear text. So
+ all we might identify is a hash of <code>XYZ</code>.</para>
+
+ <para>So regarding our (current) <productname
+ xlink:href="http://www.mysql.com">Mysql</productname>
+ implementation the impact of this attack type is somewhat limited
+ but still severe: All data being transmitted between client and
+ server may be disclosed. This typically comprises sensible data as
+ well. Possible solutions:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Create an encrypted tunnel between client and server
+ like e.g. <link
+ xlink:href="http://www.debianadmin.com/howto-use-ssh-local-and-remote-port-forwarding.html">ssh
+ port forwarding</link> or <link
+ xlink:href="http://de.wikipedia.org/wiki/Virtual_Private_Network">VPN</link>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Many database vendors <link
+ xlink:href="http://dev.mysql.com/doc/refman/5.1/de/connector-j-reference-using-ssl.html">supply
+ SSL</link> or similar <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ protocol encryption extensions. This requires additional
+ configuration procedures like setting up server side
+ certificates. Moreover similar to the http/https protocols
+ encryption generally slows down data traffic.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Of course this is only relevant if the transport layer is
+ considered to be insecure. If both server and client reside within
+ the same trusted infrastructure no action has to be taken. We also
+ note that this kind of problem is not limited to <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>.
+ In fact all protocols lacking encryption are subject to this type
+ of attack.</para>
+ </section>
+
+ <section xml:id="sqlInjection">
+ <title>SQL injection</title>
+
+ <para>Before diving into technical details we shed some light on
+ the possible impact of this common attack type being described in
+ this chapter. Our example is the well known Heartland Payment
+ Systems data breach:</para>
+
+ <figure xml:id="figHeartlandSecurityBreach">
+ <title>Summary about possible SQL injection impact based on the
+ Heartland security breach</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/heartland.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Why should we be concerned with SQL injection? In the
+ introduction of <xref linkend="bibClarke09"/> a compelling
+ argument is being given:</para>
+
+ <blockquote>
+ <para>Many people say they know what SQL injection is, but all
+ they have heard about or experienced are trivial examples. SQL
+ injection is one of the most devastating vulnerabilities to
+ impact a business, as it can lead to exposure of all of the
+ sensitive information stored in an application's database,
+ including handy information such as usernames, passwords, names,
+ addresses, phone numbers, and credit card details.</para>
+ </blockquote>
+
+ <para>In this lecture due to limited resources we only deal with
+ trivial examples mentioned above. One possible way SQL injection
+ attacks work is by inserting SQL code into fields being designed
+ for end user input:</para>
+
+ <figure xml:id="figSqlInject">
+ <title>SQL injection triggered by ordinary user input.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/sqlinject.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <qandaset defaultlabel="qanda" xml:id="sqlInjectDropTable">
+ <title>Attack from the dark side</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>Use the application from <xref
+ linkend="exerciseGuiWriteTakeTwo"/> and <xref
+ linkend="figSqlInject"/> to launch a SQL injection attack.
+ We provide some hints:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>The <productname
+ xlink:href="http://www.mysql.com">Mysql</productname>
+ <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ driver implementation already provides precautions to
+ hamper SQL injection attacks. In its default
+ configuration a sequence of SQL commands separated by
+ semicolons (<quote>;</quote>) will not be executed but
+ flagged as a SQL syntax error. We take an
+ example:</para>
+
+ <programlisting language="none">INSERT INTO Person VALUES (...);DROP TABLE Person</programlisting>
+
+ <para>In order to execute these so called multi user
+ queries we explicitly have to enable a <productname
+ xlink:href="http://www.mysql.com">Mysql</productname>
+ property. This may be achieved by extending our
+ <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ URL:</para>
+
+ <programlisting language="none">jdbc:mysql://localhost:3306/hdm?<emphasis
+ role="bold">allowMultiQueries=true</emphasis></programlisting>
+
+ <para>The <productname
+ xlink:href="http://www.mysql.com">Mysql</productname>
+ manual <link
+ xlink:href="http://dev.mysql.com/doc/refman/5.1/en/connector-j-reference-configuration-properties.html">contains
+ </link>a remark regarding this parameter:</para>
+
+ <remark>Notice that this has the potential for SQL
+ injection if using plain java.sql.Statements and your
+ code doesn't sanitize input correctly.</remark>
+
+ <para>In other words: You have been warned!</para>
+ </listitem>
+
+ <listitem>
+ <para>You may now use either of the two input fields
+ <quote>name</quote> or <quote>email</quote> to inject
+ arbitrary SQL code.</para>
+ </listitem>
+ </orderedlist>
+ </question>
+
+ <answer>
+ <para>We construct a suitable string being injected to
+ drop our <code>Person</code> table:</para>
+
+ <programlisting language="none">Jim', 'jim@c.com');DROP TABLE Person;INSERT INTO Person VALUES('Joe</programlisting>
+
+ <para>This being entered into the name field kills our
+ <code>Table</code> relation effectively. As the error
+ message shows two INSERT statements are separated by a
+ DROP TABLE statement. So after executing the first INSERT
+ our database server drops the whole table. At last the
+ second INSERT statement fails giving rise to an error
+ message no end user will ever understand:</para>
+
+ <figure xml:id="figSqlInjectDropPerson">
+ <title>Dropping the <code>Person</code> table by SQL
+ injection</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Screen/sqlInject.screen.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>According to the message text the table
+ <code>Person</code> gets dropped as expected. Thus the
+ subsequent (second) <code>INSERT</code> action is bound to
+ fail.</para>
+
+ <para>In practice this result my be avoided. The database
+ user will (hopefully!) not have sufficient permissions to
+ drop the whole table. Malicious modifications by INSERT,
+ UPDATE or DELETE statements are still possible.</para>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+
+ <section xml:id="sanitizeUserInput">
+ <title>Sanitizing user input</title>
+
+ <para>There are at least two general ways to deal with the
+ disastrous result of <xref linkend="sqlInjectDropTable"/>:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Keep the database server from interpreting user input
+ completely. This is probably the best way and will be
+ discussed in <xref linkend="sectPreparedStatements"/>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Let the application check and process user input.
+ Dangerous user input may be modified prior to being embedded
+ in SQL statements or being rejected completely.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The first method is definitely superior in most cases. There
+ are however cases where the restrictions being implied are too
+ severe. We may for example choose dynamically which tables shall
+ be accessed. So an SQL statement's structure rather than just its
+ predicates is affected by user input. There are at least two
+ standard procedures dealing with this problem:</para>
+
+ <glosslist>
+ <glossentry>
+ <glossterm>Input Filtering</glossterm>
+
+ <glossdef>
+ <para>In the simplest case we check a user's input by
+ regular expressions. An example is an input field in a login
+ window representing a system user name. Legal input may
+ allows letters and digits only. Special characters,
+ whitespace etc. are typically prohibited. The input does
+ have a minimum length of one character. A maximum length may
+ be imposed as well. So we may choose the regular expression
+ <code>[A-Za-z0-9]+</code> to check valid user names.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm><foreignphrase>Whitelisting</foreignphrase></glossterm>
+
+ <glossdef>
+ <para>In many cases Input fields only allow a restricted set
+ of values. Consider an input field for names of planets. An
+ application may keep a dictionary table to validate user
+ input:</para>
+
+ <informaltable border="1">
+ <col width="10%"/>
+
+ <col width="5%"/>
+
+ <tr>
+ <td>Mercury</td>
+
+ <td>1</td>
+ </tr>
+
+ <tr>
+ <td>Venus</td>
+
+ <td>2</td>
+ </tr>
+
+ <tr>
+ <td>Earth</td>
+
+ <td>3</td>
+ </tr>
+
+ <tr>
+ <td>...</td>
+
+ <td>...</td>
+ </tr>
+
+ <tr>
+ <td>Neptune</td>
+
+ <td>9</td>
+ </tr>
+
+ <tr>
+ <td><emphasis role="bold">Default:</emphasis></td>
+
+ <td><emphasis role="bold">0</emphasis></td>
+ </tr>
+ </informaltable>
+
+ <para>So if a user enters a valid planet name a
+ corresponding number representing this particular planet
+ will be sent to the database. If the user enters an invalid
+ string an error message may be raised.</para>
+
+ <para>In a GUI in many situations this may be better
+ accomplished by presenting the list of planets to choose
+ from. In this case a user has no chance to enter invalid or
+ even malicious code.</para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+
+ <para>So we have an <quote>interceptor</quote> sitting between
+ user input fields and SQL generating code:</para>
+
+ <figure xml:id="figInputFiltering">
+ <title>Validating user input prior to dynamically composing SQL
+ statements.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/filtering.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <qandaset defaultlabel="qanda" xml:id="quandaentry_RegexpUse">
+ <title>Using regular expressions in <link
+ linkend="gloss_Java"><trademark>Java</trademark></link></title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>This exercise is a preparation for <xref
+ linkend="exercisefilterUserInput"/>. The aim is to deal
+ with regular expressions and to use them in <link
+ linkend="gloss_Java"><trademark>Java</trademark></link>.
+ If you don't know yet about regular expressions / pattern
+ matching you may want to read either of:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><link
+ xlink:href="http://www.aivosto.com/vbtips/regex.html">Regular
+ expressions - An introduction</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link
+ xlink:href="http://www.codeproject.com/Articles/939/An-Introduction-to-Regular-Expressions">An
+ Introduction to Regular Expressions</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link
+ xlink:href="http://www.regular-expressions.info/tutorial.html">Regular
+ Expression Tutorial</link></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Complete the implementation of the following
+ skeleton:</para>
+
+ <programlisting language="none">...
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+public static void main(String[] args) {
+ final String [] wordList = new String [] {"Eric", "126653BBb", "_login","some text"};
+ final String [] regexpList = new String[] {"[A-K].*", "[^0-9]+.*", "_[a-z]+", ""};
+
+ for (final String word: wordList) {
+ for (final String regexp: regexpList) {
+ testMatch(word, regexp);
+ }
+ }
+}
+
+/**
+ * Matching a given word by a regular expression. A log message is being
+ * written to stdout.
+ *
+ * Hint: The implementation is based on the explanation being given in the
+ * introduction to {@link Pattern}
+ *
+ * @param word This string will be matched by the subsequent argument.
+ * @param regexp The regular expression tested to match the previous argument.
+ * @return true if regexp matches word, false otherwise.
+ */
+public static boolean testMatch(final String word, final String regexp) {
+.../* to be implemented by <emphasis role="bold">**YOU**</emphasis> */
+}</programlisting>
+
+ <para>As being noted in the <link
+ linkend="gloss_Java"><trademark>Java</trademark></link>
+ above you may want to read the documentation of class
+ <classname>java.util.regex.Pattern</classname>. The
+ intended output of the above application is:</para>
+
+ <programlisting language="none">The expression '[A-K].*' matches 'Eric'
+The expression '[^0-9]+.*' ...
+...</programlisting>
+ </question>
+
+ <answer>
+ <para>A possible implementation is given by
+ <classname>sda.regexp.RegexpPrimer</classname>.</para>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+
+ <qandaset defaultlabel="qanda" xml:id="exercisefilterUserInput">
+ <title>Input validation by regular expressions</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>The application of <xref
+ linkend="sqlInjectDropTable"/> proved to be vulnerable to
+ SQL injection. Sanitize the two user input field's values
+ to prevent such behaviour.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Find appropriate regular expressions to check
+ both username and email. Some hints:</para>
+
+ <glosslist>
+ <glossentry>
+ <glossterm>username</glossterm>
+
+ <glossdef>
+ <para>Regarding SQL injection the <quote>;</quote>
+ character is among the most critical. You may want
+ to exclude certain special characters. This doesn't
+ harm since their presence in a user's name is likely
+ to be a typo rather then any sensitive input.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>email</glossterm>
+
+ <glossdef>
+ <para>There are tons of <quote>ultimate</quote>
+ regular expressions available to check email
+ addresses. Remember that rather avoiding
+ <quote>wrong</quote> email addresses the present
+ task is to avoid SQL injection. So find a reasonable
+ one which may be too permissive regarding RFC email
+ syntax rules but sufficient to secure your
+ application.</para>
+
+ <para>A concise definition of an email's syntax is
+ being given in <link
+ xlink:href="http://tools.ietf.org/html/rfc5322#section-3.4.1">RFC5322</link>.
+ Its implementation is beyond scope of the current
+ lecture. Moreover it is questionable whether E-mail
+ clients and mail transfer agents implement strict
+ RFC compliance.</para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+
+ <para>Both regular expressions must cover the whole
+ user input from the beginning to the end. This can be
+ achieved by using <code>^ ... $</code>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <link
+ linkend="gloss_Java"><trademark>Java</trademark></link>
+ standard class
+ <classname>javax.swing.InputVerifier</classname> may
+ help you validating user input.</para>
+ </listitem>
+
+ <listitem>
+ <para>The following screenshot may provide an idea for
+ GUI realization and user interaction in case of
+ errors. Of course the submit button's action should be
+ disabled in case of erroneous input. The user should
+ receive a helpful error message instead.</para>
+
+ <figure xml:id="figInsertValidate">
+ <title>Error message being presented to the
+ user.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Screen/insertValidate.screen.png"/>
+ </imageobject>
+
+ <caption>
+ <para>In the current example the trailing
+ <quote>;</quote> within the E-Mail field is
+ invalid.</para>
+ </caption>
+ </mediaobject>
+ </figure>
+ </listitem>
+ </itemizedlist>
+ </question>
+
+ <answer>
+ <para>Extending
+ <classname>javax.swing.InputVerifier</classname> allows us
+ to build a generic class to filter user text input by
+ arbitrary regular expressions:</para>
+
+ <programlisting language="none">package sda.jdbc.intro.v1.sanitize;
+...
+public class RegexpVerifier extends InputVerifier {
+
+ final Pattern syntaxPattern;
+ final JLabel validationLabel;
+ private boolean inputValid = false;
+ private final String errMsg;
+...
+ public RegexpVerifier (final String regex, final JLabel validationLabel, final String errMsg) {
+ this.validationLabel = validationLabel;
+ this.errMsg = errMsg;
+ syntaxPattern = Pattern.compile(regex);
+ }
+
+ @Override
+ public boolean verify(JComponent input) {
+ if (input instanceof JTextField) {
+ final String userInput = ((JTextField) input).getText();
+ if (syntaxPattern.matcher(userInput).find()) {
+ validationLabel.setText("");
+ inputValid = true;
+ } else {
+ validationLabel.setText(errMsg);
+ inputValid = false;
+ }
+ }
+ return inputValid;
+ }
+ public boolean inputIsValid () {
+ return inputValid;
+ }
+}</programlisting>
+
+ <para>Instances of
+ <classname>sda.jdbc.intro.v1.sanitize.RegexpVerifier</classname>
+ <coref linkend="emailVerifier"/> <coref
+ linkend="nameVerifier"/> may now be used to validate our
+ two input data fields <coref linkend="setNameValidation"/>
+ <coref linkend="setEmailValidation"/>. We put emphasis on
+ the changes with respect to
+ <classname>sda.jdbc.intro.v1.InsertPerson</classname>:</para>
+
+ <programlisting language="none">package sda.jdbc.intro.v1.sanitize;
+...
+public class InsertPerson extends JFrame {
+
+ final JTextField nameField = new JTextField(15);
+ final JLabel nameFieldValidationLabel <co xml:id="nameVerifier"/> = new JLabel();
+ final RegexpVerifier nameFieldVerifier = new RegexpVerifier(
+ "^[^;'\"]+$",
+ nameFieldValidationLabel,
+ "No special characters");
+
+ final JTextField emailField = new JTextField(20);
+ final JLabel emailFieldValidationLabel <co xml:id="emailVerifier"/> = new JLabel();
+ final RegexpVerifier emailFieldVerifier =
+ new RegexpVerifier("^[\\w\\-\\.\\_]+@[\\w\\-\\.]*[a-zA-Z]{2,4}$",
+ emailFieldValidationLabel,
+ "email not valid");
+...
+ public static void main(String[] args) throws SQLException {
+ InsertPerson app = new InsertPerson();
+ app.setVisible(true);
+ }
+ public InsertPerson (){
+...
+ databaseFieldPanel.add(nameField);
+ <emphasis role="bold">nameFieldValidationLabel.setForeground(Color.RED);
+ databaseFieldPanel.add(nameFieldValidationLabel);
+ nameField.setInputVerifier(nameFieldVerifier);</emphasis> <co
+ xml:id="setNameValidation"/>
+
+ databaseFieldPanel.add(new JLabel("E-mail:"));
+ databaseFieldPanel.add(emailField);
+ <emphasis role="bold">databaseFieldPanel.add(emailFieldValidationLabel);
+ emailFieldValidationLabel.setForeground(Color.RED);
+ emailField.setInputVerifier(emailFieldVerifier);</emphasis> <co
+ xml:id="setEmailValidation"/>
+
+ insertButton.addActionListener(new ActionListener() {
+ @Override
+ public void actionPerformed(ActionEvent e) {
+ <emphasis role="bold">if (!nameFieldVerifier.inputIsValid() || !emailFieldVerifier.inputIsValid()) {
+ JOptionPane.showMessageDialog(null, "Invalid input value(s)");
+ }</emphasis> else {
+...</programlisting>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+
+ <section xml:id="sectPreparedStatements">
+ <title><classname>java.sql.PreparedStatement</classname>
+ objects</title>
+
+ <para>Sanitizing user input is an essential means to secure an
+ application. The <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ standard however provides a mechanism being superior regarding the
+ purpose of protecting applications against SQL injection attacks.
+ We shed some light on our current mechanism sending SQL statements
+ to a database server:</para>
+
+ <figure xml:id="sqlTransport">
+ <title>SQL statements in <link
+ linkend="gloss_Java"><trademark>Java</trademark></link>
+ applications get parsed at the database server</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/sqlTransport.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>This architecture raises two questions:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>What happens in case identical SQL statements are
+ executed repeatedly? This may happen inside a loop when
+ thousands of records with identical structure are being sent
+ to a database.</para>
+ </listitem>
+
+ <listitem>
+ <para>Is this architecture adequate with respect to security
+ concerns?</para>
+ </listitem>
+ </orderedlist>
+
+ <para>The first question is related to performance: Parsing
+ statements being identical despite the properties being contained
+ within is a waste of resources. We consider the transfer of
+ records between different databases:</para>
+
+ <programlisting language="none">INSERT INTO Person VALUES ('Jim', 'jim@q.org')
+INSERT INTO Person VALUES ('Eve', 'eve@y.org')
+INSERT INTO Person VALUES ('Pete', 'p@rr.com')
+...</programlisting>
+
+ <para>In this case it does not make sense to repeatedly parse
+ identical SQL statements. Using single <code>INSERT</code>
+ statements with multiple data records may not be an option when
+ the number of records grows.</para>
+
+ <para>The second question is related to our current security
+ topic: The database server's interpreter my be so
+ <quote>kind</quote> to interpret an attacker's malicious code as
+ well.</para>
+
+ <para>Both topics are being addressed by
+ <classname>java.sql.PreparedStatement</classname> objects.
+ Basically these objects allow for separation of an SQL statements
+ structure from parameter values contained within. The scenario
+ given in <xref linkend="sqlTransport"/> may be implemented
+ as:</para>
+
+ <figure xml:id="sqlTransportPrepare">
+ <title>Using <classname>java.sql.PreparedStatement</classname>
+ objects.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/sqlTransportPrepare.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Prepared statements are an example for parameterized SQL
+ statements which exist in various programming languages. When
+ using <classname>java.sql.PreparedStatement</classname> instances
+ we actually have three distinct phases:</para>
+
+ <orderedlist>
+ <listitem>
+ <para xml:id="exerciseGuiWritePrepared">Creating an instance
+ of <classname>java.sql.PreparedStatement</classname>. The SQL
+ statement possibly containing place holders gets
+ parsed.</para>
+ </listitem>
+
+ <listitem>
+ <para>Setting all placeholder values. This does not involve
+ any further SQL syntax parsing.</para>
+ </listitem>
+
+ <listitem>
+ <para>Execute the statement.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>Steps 2. and 3. may be repeated as often as desired without
+ any re-parsing of SQL statements thus saving resources on the
+ database server side.</para>
+
+ <para>Our introductory toy application <xref
+ linkend="figJdbcSimpleWrite"/> may be rewritten using
+ <classname>java.sql.PreparedStatement</classname> objects:</para>
+
+ <programlisting language="none">sda.jdbc.intro.v1;
+...
+public class SimpleInsert {
+
+ public static void main(String[] args) throws SQLException {
+
+ final Connection conn = DriverManager.getConnection (...
+
+ // Step 2: Create a PreparedStatement instance
+ final PreparedStatement pStmt = conn.prepareStatement(
+ "INSERT INTO Person VALUES(<emphasis role="bold">?, ?</emphasis>)");<co
+ xml:id="listPrepCreate"/>
+
+ // Step 3a: Fill in desired attribute values
+ pStmt.setString(1, "Jim");<co xml:id="listPrepSet1"/>
+ pStmt.setString(2, "jim@foo.org");<co xml:id="listPrepSet2"/>
+
+ // Step 3b: Execute the desired INSERT
+ final int updateCount = pStmt.executeUpdate();<co xml:id="listPrepExec"/>
+
+ // Step 4: Give feedback to the enduser
+ System.out.println("Successfully inserted " + updateCount + " dataset(s)");
+ }
+}</programlisting>
+
+ <calloutlist>
+ <callout arearefs="listPrepCreate">
+ <para>An instance of
+ <classname>java.sql.PreparedStatement</classname> is being
+ created. Notice the two question marks representing two place
+ holders for string values to be inserted in the next
+ step.</para>
+ </callout>
+
+ <callout arearefs="listPrepSet1 listPrepSet2">
+ <para>Fill in the two placeholder values being defined at
+ <coref linkend="listPrepCreate"/>.</para>
+
+ <caution>
+ <para>Since half the world of programming folks will index a
+ list of n elements starting from 0 to n-1, <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ apparently counts from 1 to n. Working with <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ would have been too easy otherwise.</para>
+ </caution>
+ </callout>
+
+ <callout arearefs="listPrepExec">
+ <para>Execute the beast! Notice the empty parameter list. No
+ SQL is required since we already prepared it in <coref
+ linkend="listPrepCreate"/>.</para>
+ </callout>
+ </calloutlist>
+
+ <para>The problem of SQL injection disappears completely when
+ using <classname>java.sql.PreparedStatement</classname> instances.
+ An attacker may safely enter offending strings like:</para>
+
+ <programlisting language="none">Jim', 'jim@c.com');DROP TABLE Person;INSERT INTO Person VALUES('Joe</programlisting>
+
+ <para>The above string will be taken <quote>as is</quote> and thus
+ simply becomes part of the database server's content.</para>
+
+ <qandaset defaultlabel="qanda" xml:id="exerciseSqlInjectPrepare">
+ <title>Prepared Statements to keep the barbarians at the
+ gate</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>In <xref linkend="sqlInjectDropTable"/> we found our
+ implementation in <xref
+ linkend="exerciseGuiWriteTakeTwo"/> to be vulnerable with
+ respect to SQL injection. Rather than sanitizing user
+ input you shall use
+ <classname>java.sql.PreparedStatement</classname> objects
+ to secure the application.</para>
+ </question>
+
+ <answer>
+ <para>Due to our separation of GUI and persistence
+ handling we only need to re-implement
+ <classname>sda.jdbc.intro.sqlinject.PersistenceHandler</classname>.
+ We have to replace
+ <classname>java.sql.Statement</classname> by
+ <classname>java.sql.PreparedStatement</classname>
+ instances. A possible implementation is
+ <classname>sda.jdbc.intro.v1.prepare.PersistenceHandler</classname>.
+ We may now safely enter offending strings like:</para>
+
+ <programlisting language="none">Jim', 'jim@c.com');DROP TABLE Person;INSERT INTO Person VALUES('Joe</programlisting>
+
+ <para>This time the input value is taken <quote>as
+ is</quote> and yields the following error message:</para>
+
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Screen/sqlInjectPrepare.screen.png"/>
+ </imageobject>
+ </mediaobject>
+ </informalfigure>
+
+ <para>The offending string exceeds the length of the
+ attribute <code>name</code> within the database table
+ <code>Person</code>. We may enlarge this value to allow
+ the <code>INSERT</code> operation:</para>
+
+ <programlisting language="none">CREATE TABLE Person (
+ name char(<emphasis role="bold">80</emphasis>) <emphasis role="bold">-- a little bit longer --</emphasis>
+ ,email CHAR(20) UNIQUE
+);</programlisting>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+
+ <para>We may have followed the track of test-driven development.
+ In that case we would have written tests before actually
+ implementing our application. In the current lecture we will do
+ this the other way round in the following exercise. The idea is to
+ assure software quality when fixing bugs or extending an
+ application.</para>
+
+ <para>The subsequent exercise requires the <productname
+ xlink:href="http://testng.org/doc/eclipse.html#eclipse-installation">TestNG</productname>
+ plugin for Eclipse to be installed. This should already be the
+ case both in the MI exercise classrooms and in the Virtualbox
+ image provided at <uri
+ xlink:href="ftp://mirror.mi.hdm-stuttgart.de/ubuntu/VirtualBox/lubuntu.vdi">ftp://mirror.mi.hdm-stuttgart.de/ubuntu/VirtualBox/lubuntu.vdi</uri>.
+ If you use a private Eclipse installation you may want to follow
+ <xref linkend="testngInstall"/>.</para>
+
+ <qandaset defaultlabel="qanda"
+ xml:id="quandaentry_DbLayerUnitTest">
+ <title>Testing
+ <classname>sda.jdbc.intro.v1.PersistenceHandler</classname>
+ using <productname
+ xlink:href="http://testng.org">TestNG</productname></title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>Read <xref linkend="chapUnitTesting"/>. Then
+ test:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Proper behaviour when opening and closing
+ connections.</para>
+ </listitem>
+
+ <listitem>
+ <para>Proper behavior when inserting data</para>
+ </listitem>
+
+ <listitem>
+ <para>Expected behaviour when entering duplicate
+ values violating integrity constraints. Look for error
+ messages as well.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>You may write code to initialize the database state
+ appropriately prior to start tests.</para>
+ </question>
+
+ <answer>
+ <para><productname
+ xlink:href="http://testng.org">TestNG</productname> may be
+ directed by
+ <classname>sda.jdbc.intro.v1.prepare.PersistenceHandlerTest</classname>.</para>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+ </section>
+
+ <section xml:id="jdbcRead">
+ <title>Read Access</title>
+
+ <para>So far we've sent records to a database server. Applications
+ however need both directions: Pushing data to a Server and receiving
+ data as well. The overall process looks like:</para>
+
+ <figure xml:id="jdbcReadWrite">
+ <title>Server / client object's life cycle</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/jdbcReadWrite.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>So far we've only covered the second (<code>UPDATE</code>)
+ part of this picture. Reading objects from a database server into a
+ client's (transient) address space requires a container object to
+ hold the data in question. Though <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> offers
+ standard container interfaces like
+ <classname>java.util.List</classname> the <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ standard has created separate specifications like
+ <classname>java.sql.ResultSet</classname>. Instances of
+ <classname>java.sql.ResultSet</classname> will hold transient copies
+ of (database) objects. The next figure outlines the basic
+ approach:</para>
+
+ <figure xml:id="figJdbcRead">
+ <title>Reading data from a database server.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/jdbcread.fig" scale="65"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>We take an example. Suppose our database contains a table of
+ our friends' nicknames and their respective birth dates:</para>
+
+ <table border="1" xml:id="figRelationFriends">
+ <caption>Names and birth dates of friends.</caption>
+
+ <tr>
+ <td><programlisting language="none">CREATE TABLE Friends (
+ id INTEGER NOT NULL PRIMARY KEY
+ ,nickname char(10)
+ ,birthdate DATE
+);</programlisting></td>
+
+ <td><programlisting language="none">INSERT INTO Friends VALUES
+ (1, 'Jim', '1991-10-10')
+ ,(2, 'Eve', '2003-05-24')
+ ,(3, 'Mick','2001-12-30')
+ ;</programlisting></td>
+ </tr>
+ </table>
+
+ <para>Following the outline in <xref linkend="figJdbcRead"/> we may
+ access our data by:</para>
+
+ <figure xml:id="listingJdbcRead">
+ <title>Accessing relational data</title>
+
+ <programlisting language="none">package sda.jdbc.intro;
+...
+public class SimpleRead {
+
+ public static void main(String[] args) throws SQLException {
+
+ // Step 1: Open a connection to the database server
+ final Connection conn = DriverManager.getConnection (
+ DbProps.getString("PersistenceHandler.jdbcUrl"),
+ DbProps.getString("PersistenceHandler.username"),
+ DbProps.getString("PersistenceHandler.password"));
+
+ // Step 2: Create a Statement instance
+ final Statement stmt = conn.createStatement();
+
+ <emphasis role="bold">// Step 3: Creating the client side JDBC container holding our data records</emphasis>
+ <emphasis role="bold">final ResultSet data = stmt.executeQuery("SELECT * FROM Friends");</emphasis> <co
+ linkends="listingJdbcRead-1" xml:id="listingJdbcRead-1-co"/>
+
+ <emphasis role="bold">// Step 4: Dataset iteration
+ while (data.next()) {</emphasis> <co linkends="listingJdbcRead-2"
+ xml:id="listingJdbcRead-2-co"/>
+ <emphasis role="bold">System.out.println(data.getInt("id")</emphasis> <co
+ linkends="listingJdbcRead-3" xml:id="listingJdbcRead-3-co"/>
+ <emphasis role="bold">+ ", " + data.getString("nickname")</emphasis> <co
+ linkends="listingJdbcRead-3" xml:id="listingJdbcRead-4-co"/>
+ <emphasis role="bold">+ ", " + data.getString("birthdate"));</emphasis> <co
+ linkends="listingJdbcRead-3" xml:id="listingJdbcRead-5-co"/>
+ }
+ }
+}</programlisting>
+ </figure>
+
+ <para>The marked code segment above shows difference with respect to
+ our data insertion application
+ <classname>sda.jdbc.intro.SimpleInsert</classname>. Some remarks are
+ in order:</para>
+
+ <calloutlist>
+ <callout arearefs="listingJdbcRead-1-co"
+ xml:id="listingJdbcRead-1">
+ <para>As being mentioned in the introduction to this section the
+ <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ standard comes with its own container interface rather than
+ <classname>java.util.List</classname> or similar.</para>
+ </callout>
+
+ <callout arearefs="listingJdbcRead-2-co"
+ xml:id="listingJdbcRead-2">
+ <para>Calling <link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/ResultSet.html#next()">next()</link>
+ prior to actually accessing data on the client side is
+ mandatory! The <link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/ResultSet.html#next()">next()</link>
+ method places the internal iterator to the first element of our
+ dataset if not empty. Follow the link address and **read** the
+ documentation.</para>
+ </callout>
+
+ <callout arearefs="listingJdbcRead-3-co listingJdbcRead-4-co listingJdbcRead-5-co"
+ xml:id="listingJdbcRead-3">
+ <para>The access methods have to be chosen according to matching
+ types. An overview of database/<link
+ linkend="gloss_Java"><trademark>Java</trademark></link> type
+ mappings is being given in <uri
+ xlink:href="http://docs.oracle.com/javase/1.3/docs/guide/jdbc/getstart/mapping.html">http://docs.oracle.com/javase/1.3/docs/guide/jdbc/getstart/mapping.html</uri>.</para>
+ </callout>
+ </calloutlist>
+
+ <qandaset defaultlabel="qanda"
+ xml:id="quandaentry_JdbcTypeConversion">
+ <title>Getter methods and type conversion</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>Apart from type mappings the <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ access methods like <link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/ResultSet.html#getString(int)">getString()</link>
+ may also be used for type conversion. Modify <xref
+ linkend="listingJdbcRead"/> by:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Read the database attribute <code>id</code> by
+ <link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/ResultSet.html#getString(java.lang.String)">getString(String)</link>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Read the database attribute nickname by <link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/ResultSet.html#getInt(java.lang.String)">getInt(String)</link>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>What do you observe?</para>
+ </question>
+
+ <answer>
+ <para>Modifying our iteration loop:</para>
+
+ <programlisting language="none">// Step 4: Dataset iteration
+while (data.next()) {
+ System.out.println(data.<emphasis role="bold">getString</emphasis>("id") <co
+ linkends="jdbcReadWrongType-1"
+ xml:id="jdbcReadWrongType-1-co"/>
+ + ", " + data.<emphasis role="bold">getInt</emphasis>("nickname") <co
+ linkends="jdbcReadWrongType-2"
+ xml:id="jdbcReadWrongType-2-co"/>
+ + ", " + data.getString("birthdate"));
+}</programlisting>
+
+ <para>We observe:</para>
+
+ <calloutlist>
+ <callout arearefs="jdbcReadWrongType-1-co"
+ xml:id="jdbcReadWrongType-1">
+ <para>Calling <link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/ResultSet.html#getString(int)">getString()</link>
+ for a database attribute of type INTEGER does not cause
+ any trouble: The value gets silently converted to a
+ string value.</para>
+ </callout>
+
+ <callout arearefs="jdbcReadWrongType-2-co"
+ xml:id="jdbcReadWrongType-2">
+ <para>Calling <link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/ResultSet.html#getInt(java.lang.String)">getInt(String)</link>
+ for the database field of type CHAR yields an (expected)
+ Exception:</para>
+ </callout>
+ </calloutlist>
+
+ <programlisting language="none">Exception in thread "main" java.sql.SQLException: Invalid value for getInt() - 'Jim'
+ at com.mysql.jdbc.SQLError.createSQLException(SQLError.java:1073)
+...</programlisting>
+
+ <para>We may however provide <quote>compatible</quote> data
+ records:</para>
+
+ <programlisting language="none">DELETE FROM Friends;
+INSERT INTO Friends VALUES (1, <emphasis role="bold">'31'</emphasis>, '1991-10-10');</programlisting>
+
+ <para>This time our application executes perfectly
+ well:</para>
+
+ <programlisting language="none">1, 31, 1991-10-10</programlisting>
+
+ <para>Conclusion: The <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>
+ driver performs a conversion from a string type to an
+ integer similar like the <link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/lang/Integer.html#parseInt(java.lang.String)">parseInt(String)</link>
+ method.</para>
+
+ <para>The next series of exercises aims on a more powerful
+ implementation of our person data insertion application in
+ <xref linkend="exerciseInsertLoginCredentials"/>.</para>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+
+ <qandaset defaultlabel="qanda" xml:id="quandaentry_HandlingNull">
+ <title>Handling NULL values.</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>The attribute <code>birthday</code> in our database
+ table Friends allows <code>NULL</code> values:</para>
+
+ <programlisting language="none">INSERT INTO Friends VALUES
+ (1, 'Jim', '1991-10-10')
+ ,(2, <emphasis role="bold"> NULL</emphasis>, '2003-5-24')
+ ,(3, 'Mick', '2001-12-30');</programlisting>
+
+ <para>Starting our current application yields:</para>
+
+ <programlisting language="none">1, Jim, 1991-10-10
+2, null, 2003-05-24
+3, Mick, 2001-12-30</programlisting>
+
+ <para>This might be confuses with a person having the
+ nickname <quote>null</quote>. Instead we would like to
+ have:</para>
+
+ <programlisting language="none">1, Jim, 1991-10-10
+2, -Name unknown- , 2003-05-24
+3, Mick, 2001-12-30</programlisting>
+
+ <para>Extend the current code of
+ <classname>sda.jdbc.intro.SimpleRead</classname> to produce
+ the above result in case of nickname <code>NULL</code>
+ values.</para>
+
+ <para>Hint: Read the documentation of <link
+ xlink:href="http://docs.oracle.com/javase/7/docs/api/java/sql/ResultSet.html#wasNull()">wasNull()</link>.</para>
+ </question>
+
+ <answer>
+ <para>A possible implementation is being given in
+ <classname>sda.jdbc.intro.v1.SimpleRead</classname>.</para>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+
+ <qandaset defaultlabel="qanda" xml:id="exerciseInsecureAuth">
+ <title>A user authentication <quote>strategy</quote></title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>Our current application for entering
+ <code>Person</code> records lacks authentication: A user
+ simply connects to the database using credentials being hard
+ coded in a properties file. A programmer suggests to
+ implement authentication based on the following extension of
+ the <code>Person</code> table:</para>
+
+ <programlisting language="none">CREATE TABLE Person (
+ name char(80) NOT NULL
+ ,email CHAR(20) NOT NULL UNIQUE
+ ,login CHAR(10) UNIQUE -- login names must be unique --
+ ,password CHAR(20)
+);</programlisting>
+
+ <para>On clicking <quote>Connect</quote> a user may enter
+ his login name and password, <quote>fred</quote> and
+ <quote>12345678</quote> in the following example:</para>
+
+ <figure xml:id="figLogin">
+ <title>Login credentials for database connection</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Screen/login.screen.png"
+ scale="90"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Based on these input values the following SQL query is
+ being executed by a
+ <classname>java.sql.Statement</classname> object:</para>
+
+ <programlisting language="none">SELECT * FROM Person WHERE login='<emphasis
+ role="bold">fred</emphasis>' and password = '<emphasis
+ role="bold">12345678</emphasis>'</programlisting>
+
+ <para>Since the login attribute is UNIQUE we are sure to
+ receive either 0 or 1 dataset. Our programmer proposes to
+ grant login if the query returns at least one
+ dataset.</para>
+
+ <para>Discuss this implementation sketch with a colleague.
+ Do you think this is a sensible approach? <emphasis
+ role="bold">Write down</emphasis> your results.</para>
+ </question>
+
+ <answer>
+ <para>The approach is essentially unusable due to severe
+ security implications. Since it is based on
+ <classname>java.sql.Statement</classname> rater than on
+ <classname>java.sql.PreparedStatement</classname> objects it
+ is vulnerable to SQL injection attacks. A user my enter the
+ following password value in the GUI:</para>
+
+ <programlisting language="none">sd' OR '1' = '1</programlisting>
+
+ <para>Based on the login name <quote>fred</quote> the
+ following SQL string is being crafted:</para>
+
+ <programlisting language="none">SELECT * FROM Person WHERE login='fred' and password = 'sd' OR <emphasis
+ role="bold">'1' = '1'</emphasis>;</programlisting>
+
+ <para>Since the WHERE clause's last component always
+ evaluates to true, all objects from the <code>Person</code>
+ relation are returned thus permitting login.</para>
+
+ <para>The implementation approach suffers from a second
+ deficiency: The passwords are stored in clear text. If an
+ attacker gains access to the <code>Person</code> table he'll
+ immediately retrieve the passwords of all users. This
+ problem can be solved by storing hash values of passwords
+ rather than the clear text values themselves.</para>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+
+ <qandaset defaultlabel="qanda" xml:id="exerciseHashTraining">
+ <title>Passwords and hash values</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>In exercise <xref linkend="exerciseInsecureAuth"/> we
+ discarded the idea of clear text passwords in favour of
+ password hashes. In order to avoid Rainbow cracking so
+ called salted hashes are superior. You should read <uri
+ xlink:href="https://www.heckrothindustries.co.uk/articles/an-introduction-to-password-hashes">https://www.heckrothindustries.co.uk/articles/an-introduction-to-password-hashes</uri>
+ for overview purposes. The article contains further
+ references on the bottom of the page.</para>
+
+ <para>With respect to an implementation <uri
+ xlink:href="http://stackoverflow.com/questions/2860943/suggestions-for-library-to-hash-passwords-in-java#11038230">http://stackoverflow.com/questions/2860943/suggestions-for-library-to-hash-passwords-in-java</uri>
+ provides a simple example for:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Creating a salted hash from a given password
+ string.</para>
+ </listitem>
+
+ <listitem>
+ <para>Verify if a hash string matches a given clear text
+ password.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The example uses an external library. On <productname
+ xlink:href="http://www.ubuntu.com">Ubuntu</productname>
+ Linux this may be installed by issuing
+ <command>aptitude</command> <option>install</option>
+ <option>libcommons-codec-java</option>. On successful
+ install the file
+ <filename>/usr/share/java/commons-codec-1.5.jar</filename>
+ may be appended to your <envar>CLASSPATH</envar>.</para>
+
+ <para>You may as well use <uri
+ xlink:href="http://crackstation.net/hashing-security.htm#javasourcecode">http://crackstation.net/hashing-security.htm#javasourcecode</uri>
+ as a starting point. This example works standalone without
+ needing an external library. Note: Tis example produces
+ different (incompatible) hash values.</para>
+
+ <para>Create a simple main() method to experiment with the
+ two class methods.</para>
+ </question>
+
+ <answer>
+ <para>Starting from <uri
+ xlink:href="http://stackoverflow.com/questions/2860943/suggestions-for-library-to-hash-passwords-in-java#11038230">http://stackoverflow.com/questions/2860943/suggestions-for-library-to-hash-passwords-in-java</uri>
+ we create a slightly modified class
+ <classname>sda.jdbc.intro.auth.HashProvider</classname>
+ offering both hash providing <coref
+ linkend="hashProviderMethod"/> and verifying <coref
+ linkend="hashVerifyMethod"/> methods:</para>
+
+ <programlisting language="none">package sda.jdbc.intro.auth;
+...
+public class HashProvider {
+...
+ /** Computes a salted PBKDF2 hash of given plaintext password
+ suitable for storing in a database. */
+ public static <emphasis role="bold">String getSaltedHash</emphasis> <co
+ xml:id="hashProviderMethod"/>(char [] password) {
+ byte[] salt;
+ try {
+ salt = SecureRandom.getInstance("SHA1PRNG").generateSeed(saltLen);
+ // store the salt with the password
+ return Base64.encodeBase64String(salt) + "$" + hash(password, salt);
+ } catch (NoSuchAlgorithmException e) {
+ e.printStackTrace();
+ }
+ System.exit(1);
+ return null;
+ }
+
+ /** Checks whether given plaintext password corresponds
+ to a stored salted hash of the password. */
+ public static <emphasis role="bold">boolean check</emphasis> <co
+ xml:id="hashVerifyMethod"/>(char[] password, String stored){
+ String[] saltAndPass = stored.split("\\$");
+ if (saltAndPass.length != 2)
+ return false;
+ String hashOfInput = hash(password, Base64.decodeBase64(saltAndPass[0]));
+ return hashOfInput.equals(saltAndPass[1]);
+ }
+...}</programlisting>
+
+ <para>We may test the two class methods
+ <methodname>sda.jdbc.intro.auth.HashProvider.getSaltedHash(char[])</methodname>(...)
+ and
+ <methodname>sda.jdbc.intro.auth.HashProvider.check(char[],String)</methodname>
+ by a separate driver class. Notice the <quote>$</quote> sign
+ <coref linkend="saltPwhashSeparator"/> separating salt and
+ password hash:</para>
+
+ <programlisting language="none">package sda.jdbc.intro.auth;
+
+public class TestHashProvider {
+
+ public static void main(String [] args) throws Exception {
+ final char [] clearText = {'s', 'e', 'c'};
+ final String hash = <emphasis role="bold">HashProvider.getSaltedHash(clearText)</emphasis>;
+ System.out.println("Hash:" + hash);
+ if (HashProvider.check(clearText, <co
+ xml:id="saltPwhashSeparator"/>
+ "<emphasis role="bold">HwX2DkuYiwp7xogm3AGndza8DKRVvCMntxRvCrCGFPw=</emphasis>$<emphasis
+ role="bold">6Ix11yHNB4uPZuF2IQYxVV/MYragJwTDE33OIFR9a24=</emphasis>")) {
+ System.out.println("hash matches");
+ } else {
+ System.out.println("hash does not match"); ...</programlisting>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+
+ <qandaset defaultlabel="qanda"
+ xml:id="exerciseInsertLoginCredentials">
+ <title>Gui authentication: The real McCoy</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>We now implement a refined version to enter
+ <code>Person</code> records based on the solutions of two
+ related exercises:</para>
+
+ <glosslist>
+ <glossentry>
+ <glossterm><xref
+ linkend="exercisefilterUserInput"/></glossterm>
+
+ <glossdef>
+ <para>Avoiding SQL injection by sanitizing user
+ input</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm><xref
+ linkend="exerciseSqlInjectPrepare"/></glossterm>
+
+ <glossdef>
+ <para>Avoiding SQL injection by using
+ <classname>java.sql.PreparedStatement</classname>
+ objects.</para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+
+ <para>A better solution should combine both techniques.
+ Non-vulnerability a basic requirement. Checking an E-Mail
+ for minimal conformance is an added value.</para>
+
+ <para>In order to address authentication the relation Person
+ has to be extended appropriately. The GUI needs two
+ additional fields for login name and password as well. The
+ following video demonstrates the intended behaviour:</para>
+
+ <figure xml:id="videoConnectAuth">
+ <title>Intended usage behaviour for insertion of data
+ records.</title>
+
+ <mediaobject>
+ <videoobject>
+ <videodata fileref="Ref/Video/connectauth.mp4"/>
+ </videoobject>
+ </mediaobject>
+ </figure>
+
+ <para>Don't forget to use password hashes like those from
+ <xref linkend="exerciseHashTraining"/>. Due to their length
+ you may want to consider the data type
+ <code>TEXT</code>.</para>
+ </question>
+
+ <answer>
+ <para>In comparison to earlier versions it does make sense
+ to add some internal container structures. First we note,
+ that each GUI input field requires:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>A label like <quote>Enter password</quote>.</para>
+ </listitem>
+
+ <listitem>
+ <para>A corresponding field object to hold user entered
+ input.</para>
+ </listitem>
+
+ <listitem>
+ <para>A validator checking for correctness of entered
+ data.</para>
+ </listitem>
+
+ <listitem>
+ <para>A label or text field for warning messages in case
+ of invalid user input.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>First we start by grouping label <coref
+ linkend="uiuLabel"/>, input field's verifier <coref
+ linkend="uiuVerifier"/> and the error message label <coref
+ linkend="uiuErrmsg"/> in
+ <classname>sda.jdbc.intro.auth.UserInputUnit</classname>:</para>
+
+ <programlisting language="none">package sda.jdbc.intro.auth;
+...
+public class UserInputUnit {
+
+ final JLabel label; <co xml:id="uiuLabel"/>
+ final InputVerifierNotify verifier; <co xml:id="uiuVerifier"/>
+ final JLabel errorMessage; <co xml:id="uiuErrmsg"/>
+
+ public UserInputUnit(final String guiText, final InputVerifierNotify verifier) {
+ this.label = new JLabel(guiText);
+ this.verifier = verifier;
+ errorMessage = new JLabel();
+ } ...</programlisting>
+
+ <para>The actual GUI text field is being defined <coref
+ linkend="verfierGuiField"/> in class
+ <classname>sda.jdbc.intro.auth.InputVerifierNotify</classname>:</para>
+
+ <programlisting language="none">package sda.jdbc.intro.auth;
+...
+public abstract class InputVerifierNotify extends InputVerifier {
+
+ protected final String errorMessage;
+ public final JLabel validationLabel;
+ public final JTextField field; <co xml:id="verfierGuiField"/>
+
+ public InputVerifierNotify(final JTextField field, final String errorMessage) { ...</programlisting>
+
+ <para>We need two field verifier classes being derived from
+ <classname>sda.jdbc.intro.auth.InputVerifierNotify</classname>:</para>
+
+ <glosslist>
+ <glossentry>
+ <glossterm><classname>sda.jdbc.intro.auth.RegexpVerifier</classname></glossterm>
+
+ <glossdef>
+ <para>This one is well known from earlier versions and
+ is used to validate text input fields by regular
+ expressions.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm><classname>sda.jdbc.intro.auth.InputVerifierNotify</classname></glossterm>
+
+ <glossdef>
+ <para>This verifier class is responsible for comparing
+ our two password fields to have identical
+ values.</para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+
+ <para>All these components get assembled in
+ <classname>sda.jdbc.intro.auth.InsertPerson</classname>. We
+ remark some important points:</para>
+
+ <programlisting language="none">package sda.jdbc.intro.auth;
+...
+public class InsertPerson extends JFrame {
+... // GUI attributes for user input
+ final UserInputUnit name = <co linkends="listingInsertUserAuth-1"
+ xml:id="listingInsertUserAuth-1-co"/>
+ new UserInputUnit(
+ "Name",
+ new RegexpVerifier(new JTextField(15), "^[^;'\"]+$", "No special characters allowed"));
+
+ // We need a reference to the password field to avoid
+ // casting from JTextField later.
+ private final JPasswordField passwordField = new JPasswordField(10); <co
+ linkends="listingInsertUserAuth-2"
+ xml:id="listingInsertUserAuth-2-co"/>
+ private final UserInputUnit password =
+ new UserInputUnit(
+ "Password",
+ new RegexpVerifier(passwordField, "^.{6,20}$", "length from 6 to 20 characters"));
+...
+ private final UserInputUnit passwordRepeat =
+ new UserInputUnit(
+ "repeat pass.",
+ new EqualValueVerifier <co linkends="listingInsertUserAuth-3"
+ xml:id="listingInsertUserAuth-3-co"/> (new JPasswordField(10), passwordField, "Passwords do not match"));
+
+ private final UserInputUnit [] userInputUnits = <co
+ linkends="listingInsertUserAuth-4"
+ xml:id="listingInsertUserAuth-4-co"/>
+ {name, email, login, password, passwordRepeat};
+...
+ private void userLoginDialog() {...}
+...
+ public InsertPerson (){
+...
+ databaseFieldPanel.setLayout(new GridLayout(0, 3)); //Third column for validation label
+ add(databaseFieldPanel);
+
+ for (UserInputUnit unit: userInputUnits) { <co
+ linkends="listingInsertUserAuth-5"
+ xml:id="listingInsertUserAuth-5-co"/>
+ databaseFieldPanel.add(unit.label);
+ databaseFieldPanel.add(unit.verifier.field);
+ databaseFieldPanel.add(unit.verifier.validationLabel);
+ }
+ insertButton.addActionListener(new ActionListener() {
+ @Override public void actionPerformed(ActionEvent e) {
+ if (inputValuesAllValid()) {
+ if (persistenceHandler.add( <co
+ linkends="listingInsertUserAuth-6"
+ xml:id="listingInsertUserAuth-6-co"/>
+ name.getText(),
+ email.getText(),
+ login.getText(),
+ passwordField.getPassword())) {
+ clearMask();
+...}
+ private void clearMask() { <co linkends="listingInsertUserAuth-7"
+ xml:id="listingInsertUserAuth-7-co"/>
+ for (UserInputUnit unit: userInputUnits) {
+ unit.verifier.field.setText("");
+ unit.verifier.clear();
+ }
+ }
+ private boolean inputValuesAllValid() {<co
+ linkends="listingInsertUserAuth-8"
+ xml:id="listingInsertUserAuth-8-co"/>
+ for (UserInputUnit unit: userInputUnits) {
+ if (!unit.verifier.verify(unit.verifier.field)){
+ return false;
+ }
+ }
+ return true;
+ }
+}</programlisting>
+
+ <calloutlist>
+ <callout arearefs="listingInsertUserAuth-1-co"
+ xml:id="listingInsertUserAuth-1">
+ <para>All GUI related stuff for entering a user's
+ name</para>
+ </callout>
+
+ <callout arearefs="listingInsertUserAuth-2-co"
+ xml:id="listingInsertUserAuth-2">
+ <para>Password fields need special treatment:
+ <code>getText()</code> is superseded by
+ <code>getPassword()</code>. In order to avoid casts from
+ <classname>javax.swing.JTextField</classname> to
+ <classname>javax.swing.JPasswordField</classname> we
+ simply keep an extra reference.</para>
+ </callout>
+
+ <callout arearefs="listingInsertUserAuth-3-co"
+ xml:id="listingInsertUserAuth-3">
+ <para>In order to check both password fields for
+ identical values we need a different validator
+ <classname>sda.jdbc.intro.auth.EqualValueVerifier</classname>
+ expecting both password fields in its
+ constructor.</para>
+ </callout>
+
+ <callout arearefs="listingInsertUserAuth-4-co"
+ xml:id="listingInsertUserAuth-4">
+ <para>All 5 user input elements get grouped by an array.
+ This allows for iterations like in <coref
+ linkend="listingInsertUserAuth-7-co"/> or <coref
+ linkend="listingInsertUserAuth-8-co"/>.</para>
+ </callout>
+
+ <callout arearefs="listingInsertUserAuth-5-co"
+ xml:id="listingInsertUserAuth-5">
+ <para>Adding all GUI elements to the base pane in a
+ loop.</para>
+ </callout>
+
+ <callout arearefs="listingInsertUserAuth-6-co"
+ xml:id="listingInsertUserAuth-6">
+ <para>Providing user entered values to the persistence
+ provider.</para>
+ </callout>
+
+ <callout arearefs="listingInsertUserAuth-7-co"
+ xml:id="listingInsertUserAuth-7">
+ <para>Whenever a dataset has been successfully sent to
+ the database we have to clean our GUI to possibly enter
+ another record.</para>
+ </callout>
+
+ <callout arearefs="listingInsertUserAuth-8-co"
+ xml:id="listingInsertUserAuth-8">
+ <para>Thanks to our grouping aggregation of individual
+ input GUI field validation states becomes easy.</para>
+ </callout>
+ </calloutlist>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+
+ <qandaset defaultlabel="qanda" xml:id="quandaentry_ArchSecurity">
+ <title>Architectural security considerations</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>In <xref linkend="exerciseInsertLoginCredentials"/> we
+ achieved end user credential protection. How about the
+ overall application security? Provide improvement proposals
+ if appropriate. Hint: Consider the way credentials are being
+ supplied.</para>
+ </question>
+
+ <answer>
+ <para>Connecting the client to our database server solely
+ depends on credentials <coref
+ linkend="databaseUserHdmPassword"/> being stored in a
+ properties file
+ <filename>database.properties</filename>:</para>
+
+ <programlisting language="none">PersistenceHandler.jdbcUrl=jdbc:mysql://localhost:3306/hdm
+PersistenceHandler.username=hdmuser <co xml:id="databaseUserHdmUsername"/>
+PersistenceHandler.password=<emphasis role="bold">XYZ</emphasis> <co
+ xml:id="databaseUserHdmPassword"/></programlisting>
+
+ <para>This properties file is user accessible and contains
+ the password in clear text. Arbitrary applications
+ connecting to the database server using this account do have
+ all permissions being granted to <code>hdmuser</code> <coref
+ linkend="databaseUserHdmUsername"/>. In order for our
+ application to work correctly the set of granted permissions
+ contains at least inserting datasets. Thus new users e.g.
+ <code>smith</code> including credentials may be inserted.
+ Afterwards the original application can be started by
+ logging in as <code>smith</code>.</para>
+
+ <para>Conclusion: The current application architecture is
+ seriously flawed with respect to security.</para>
+
+ <para>Rather then using a common database account
+ <code>hdmuser</code> we may configure per-user accounts on
+ the database server having individual user credentials. This
+ way user credentials are no longer stored in our
+ <code>Person</code> table but are being managed by the
+ database server's user management and privilege facilities.
+ This completely avoids storing credentials on the client
+ side.</para>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+
+ <section xml:id="sda1SaxRdbms">
+ <title>SAX and RDBMS</title>
+
+ <qandaset defaultlabel="qanda" xml:id="exercise_saxAttrib">
+ <title>Reading XML attributes</title>
+
+ <qandadiv>
+ <qandaentry xml:id="saxRdbms">
+ <question>
+ <label>SAX processing with RDBMS access.</label>
+
+ <para>Implement the example given in <xref
+ linkend="saxRdbmsAccessPrinciple"/> to produce the output
+ sketched in <xref linkend="saxPriceOut"/>. You may start
+ by implementing <emphasis>and testing</emphasis> the
+ following methods of a RDBMS interfacing class using
+ <trademark
+ xlink:href="http://electronics.zibb.com/trademark/jdbc/29545026">JDBC</trademark>:</para>
+
+ <programlisting language="none">package sax.rdbms;
+
+public class RdbmsAccess {
+
+ public void connect(final String host, final int port,
+ final String userName, final String password) {
+ // <emphasis role="bold">open connection to a database</emphasis>
+ }
+ public String readPrice(final String articleNumber) {
+ return "0"; // <emphasis role="bold">To be implemented as access to a ResultSet object</emphasis>
+ }
+ public void close() {
+ // <emphasis role="bold">close database connection</emphasis>
+ }
+}</programlisting>
+
+ <para>You may find it helpful to write a small testbed for
+ the RDBMS access functionality prior to integrate it into
+ your <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym>
+ application producing HTML output.</para>
+ </question>
+
+ <answer>
+ <para>We start by creating a suitable RDBMS Table:</para>
+
+ <programlisting language="none">CREATE SCHEMA AUTHORIZATION midb2
+CREATE TABLE Product(
+ orderNo CHAR(10) NOT NULL PRIMARY KEY
+ ,price DECIMAL (9,2) NOT NULL
+)</programlisting>
+
+ <para>Next we feed some toy data:</para>
+
+ <programlisting language="none">INSERT INTO Product VALUES('x-223', 330.20);
+INSERT INTO Product VALUES('w-124', 110.40);</programlisting>
+
+ <para>Now we implement our RDBMS access class:</para>
+
+ <programlisting language="none">package dom.xsl;
+...
+public class DbAccess {
+
+ public void connect(final String jdbcUrl,
+ final String userName, final String password) {
+ try {
+ conn = DriverManager.getConnection(jdbcUrl, userName, password);
+ priceQuery = conn.prepareStatement(sqlPriceQuery);
+ } catch (SQLException e) {
+ System.err.println("Unable to open connection to database:" + e);}
+ }
+ public String readPrice(final String articleNumber) {
+ String result;
+ try {
+ priceQuery.setString(1, articleNumber);
+ final ResultSet rs = priceQuery.executeQuery();
+ if (rs.next()) {
+ result = rs.getString("price");
+ } else {
+ result = "No price available for article '" + articleNumber + "'";
+ }
+ } catch (SQLException e) {
+ result = "Error reading price for article '" + articleNumber + "':" + e;
+ }
+ return result;
+ }
+ public void close() {
+ try {conn.close();} catch (SQLException e) {
+ System.err.println("Error closing database connection:" + e);
+ }
+ }
+ static {
+ try { Class.forName("com.ibm.db2.jcc.DB2Driver");
+ } catch (ClassNotFoundException e) {
+ System.err.println("Unable to register Driver:" + e);}
+ }
+ private static final String sqlPriceQuery =
+ "SELECT price FROM Product WHERE orderNo = ?";
+ private PreparedStatement priceQuery = null;
+ private Connection conn = null;
+}</programlisting>
+
+ <para>This access layer may be tested independently from
+ handling catalog instances:</para>
+
+ <programlisting language="none">package dom/xsl;
+
+public class DbAccessDriver {
+
+ public static void main(String[] args) {
+ final DbAccess dbaccess = new DbAccess();
+ dbaccess.connect("jdbc:db2://db2.mi.hdm-stuttgart.de:10000/hdm",
+ "midb2", "password");
+ System.out.println(dbaccess.readPrice("x-223"));
+ System.out.println(dbaccess.readPrice("..aaargh!"));
+ dbaccess.close();
+ }
+}</programlisting>
+
+ <para>If the above test succeeds we may embed the RDBMS
+ access layer into our The <acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym>
+ handler:</para>
+
+ <programlisting language="none">package sax.rdbms;
+...
+public class HtmlEventHandler extends DefaultHandler{
+ public void startDocument() {
+ dbaccess.connect("jdbc:db2://db2.mi.hdm-stuttgart.de:10000/hdm",
+ "midb2", "password");
+ System.out.println("<html><head><title>Catalog</title></head>");
+ }
+ public void endDocument() {
+ System.out.println("</html>");
+ dbaccess.close();
+ }
+ public void startElement(String namespaceUri, String localName,
+ String rawName, Attributes attrs){
+ if (rawName.equals("catalog")){
+ System.out.println("<body><H1>A catalog</H1>"
+ +"<table border='1'><tbody>");
+ System.out.println("<tr><th>Order number</th>\n"
+ + "<th>Price</th>\n"
+ +" <th>Product</th></tr>");
+ } else if (rawName.equals("item")){
+ final String orderNo = attrs.getValue("orderNo");
+ System.out.print("<tr><td>" + orderNo
+ + "</td>\n<td>" + dbaccess.readPrice(orderNo)
+ + "</td>\n<td>");
+ } else {
+ System.err.println("Element '" + rawName + "' unknown");
+ }
+ }
+ public void endElement(String namespaceUri, String localName,
+ String rawName) {
+ if (rawName.equals("catalog")){
+ System.out.println("</tbody></table>");
+ } else if (rawName.equals("item")){
+ System.out.println("</td></tr>\n");
+ }
+ }
+ public void characters(char[] ch, int start, int length) {
+ System.out.print(new String(ch, start, length));
+ }
+ private DbAccess dbaccess = new DbAccess();
+}</programlisting>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+ </section>
+ </section>
+ </chapter>
+
+ <chapter xml:id="chapUnitTesting">
+ <title>Unit testing with <productname
+ xlink:href="http://testng.org">TestNG</productname></title>
+
+ <para>This chapter presents a very short introduction to the basic usage
+ of unit testing. We start with a simple stack implementation:</para>
+
+ <programlisting language="none">package sda.unittesting;
+
+public class MyStack {
+ int [] data = new int[5];
+ int numElements = 0;
+
+ public void push(final int n) {
+ data[numElements] = n;
+ numElements++;
+ }
+ public int pop() {
+ numElements--;
+ return data[numElements];
+ }
+ public int top() {
+ return data[numElements - 1];
+ }
+ public boolean empty() {
+ return 0 == numElements;
+ }
+}</programlisting>
+
+ <para>Readers being familiar with stacks will immediately notice a
+ deficiency in the above code: This stack is actually bounded. It only
+ allows us to store a maximum number of five integer values.</para>
+
+ <para>The following implementation allows us to functionally test our
+ <classname>sda.unittesting.MyStack</classname> implementation with
+ respect to the usual stack behaviour:</para>
+
+ <programlisting language="none" linenumbering="numbered">package sda.unittesting;
+
+public class MyStackFuncTest {
+
+ private static void assertTrue(boolean status) {
+ if (!status) {
+ throw new RuntimeException("Assert failed");
+ }
+ }
+ public static void main(String[] args) {
+ final MyStack stack = new MyStack();
+ // Test 1: A new MyStack instance should not contain any elements.
+ assertTrue(stack.empty());
+
+ // Test 2: Adding and removal
+ stack.push(4);
+ assertTrue (!stack.empty());
+ assertTrue (4 == stack.top());
+ assertTrue (4 == stack.pop());
+ assertTrue (stack.empty());
+
+ // Test 3: Trying to add more than five values
+ stack.push(1);stack.push(2);stack.push(3);stack.push(4);
+ stack.push(5);
+ stack.push(6);
+ assertTrue(6 == stack.pop());
+ }
+}</programlisting>
+
+ <para>Execution yields a runtime exception which is due to the attempted
+ insert operation <code>stack.push(6)</code>:</para>
+
+ <programlisting language="none">Exception in thread "main" java.lang.ArrayIndexOutOfBoundsException: 5
+ at sda.unittesting.MyStack.push(MyStack.java:8)
+ at sda.unittesting.MyStackFuncTest.main(MyStackFuncTest.java:20)</programlisting>
+
+ <para>The execution result is easy to understand since our
+ <classname>sda.unittesting.MyStack </classname> implementation only
+ allows to store 5 values.</para>
+
+ <para>Our testing application is fine so far. It does however lack some
+ features:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>automatic initialization before starting tests and
+ finalization at the end.</para>
+ </listitem>
+
+ <listitem>
+ <para>Our test is monolithic: We used comments to document different
+ tests. This knowledge is implicit and thus invisible to testing
+ frameworks. Test results (failure/success) cannot be assigned to
+ test 1, test 2 for example.</para>
+ </listitem>
+
+ <listitem>
+ <para>Aggregation and visualization of test results</para>
+ </listitem>
+
+ <listitem>
+ <para>Dependencies between individual tests</para>
+ </listitem>
+
+ <listitem>
+ <para>Ability to enable and disable tests according to a project's
+ maturity level. In our example test 3 might be disabled till an
+ unbounded implementation gets completed.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Testing frameworks like <productname
+ xlink:href="http://junit.org">Junit</productname> or <productname
+ xlink:href="http://testng.org">TestNG</productname> provide means for
+ efficient and flexible test organization. Using <productname
+ xlink:href="http://testng.org">TestNG</productname> our current test
+ application including only test 1 and test 2 reads:</para>
+
+ <programlisting language="none">package sda.unittesting;
+
+import org.testng.annotations.Test;
+
+public class MyStackTestSimple {
+
+ final MyStack stack = new MyStack();
+
+ @Test
+ public void empty() {
+ assert(stack.empty());
+ }
+ @Test
+ public void pushPopEmpty() {
+ assert (stack.empty());
+ stack.push(4);
+ assert (!stack.empty());
+ assert (4 == stack.top());
+ assert (4 == stack.pop());
+ assert (stack.empty());
+ }
+}</programlisting>
+
+ <para>We notice the absence of a <function>main()</function> method. Our
+ testing framework uses the above code for test definitions. In contrast
+ to our homebrew solution the individual tests are now defined in a
+ machine readable fashion. This allows for sophisticated statistics.
+ Executing inside <productname
+ xlink:href="http://testng.org">TestNG</productname> produces the
+ following results:</para>
+
+ <programlisting language="none">PASSED: empty
+PASSED: pushPopEmpty
+
+===============================================
+ Default test
+ Tests run: 2, Failures: 0, Skips: 0
+===============================================
+
+
+===============================================
+Default suite
+Total tests run: 2, Failures: 0, Skips: 0
+===============================================</programlisting>
+
+ <para>Both tests run successfully. So why did we omit test 3 which is
+ bound to fail? We now add it to the test suite:</para>
+
+ <programlisting language="none">package sda.unittesting;
+...
+public class MyStackTestSimple1 {
+...
+ @Test
+ public void empty() {
+ assert(stack.empty());
+...
+
+ @Test
+ public void push6() {
+ stack.push(1);
+ stack.push(2);
+ stack.push(3);
+ stack.push(4);
+ stack.push(5);
+ stack.push(6);
+ assert (6 == stack.pop());
+ } ...</programlisting>
+
+ <para>As expected test 3 fails. But the result shows test 2 failing as
+ well:</para>
+
+ <programlisting language="none">PASSED: empty
+FAILED: push6
+java.lang.ArrayIndexOutOfBoundsException: 5
+ at sda.unittesting.MyStack.push(MyStack.java:8)
+ at sda.unittesting.MyStackTestSimple1.push6(MyStackTestSimple1.java:30)
+ at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
+ ...
+
+FAILED: pushPopEmpty
+java.lang.AssertionError
+ at sda.unittesting.MyStackTestSimple1.pushPopEmpty(MyStackTestSimple1.java:15)
+ at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
+ ...
+
+===============================================
+ Default test
+ Tests run: 3, Failures: 2, Skips: 0
+===============================================</programlisting>
+
+ <para>This unexpected result is due to the execution order of the three
+ individual tests. Within our class
+ <classname>sda.unittesting.MyStackTestSimple1</classname> the three
+ tests appear in the sequence test 1, test 2 and test 3. This however is
+ just the order of source code. The testing framework will not infer any
+ order and thus execute our three tests in <emphasis
+ role="bold">arbitrary</emphasis> order. The execution log shows the
+ actual order:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Test <quote><code>empty</code></quote></para>
+ </listitem>
+
+ <listitem>
+ <para>Test <quote><code>push6</code></quote></para>
+ </listitem>
+
+ <listitem>
+ <para>Test <quote><code>pushPopEmpty</code></quote></para>
+ </listitem>
+ </orderedlist>
+
+ <para>So the second test will raise an exception and leave the stack
+ filled with the maximum possible five elements. Thus it is not empty and
+ the <quote><code>pushPopEmpty</code></quote> test fails as well.</para>
+
+ <para>If we want to avoid this type of errors we may:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Declare tests within separate (test class) definitions</para>
+ </listitem>
+
+ <listitem>
+ <para>Define dependencies like test X can only be executed after
+ test Y.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The <productname
+ xlink:href="http://testng.org">TestNG</productname> framework offers a
+ feature which allows the definition of test groups and dependencies
+ between them. We use this feature to refine our test definition:</para>
+
+ <programlisting language="none">package sda.unittesting;
+...
+public class MyStackTest {
+ ...
+ @Test (<emphasis role="bold">groups = "basic"</emphasis>)
+ public void empty() {
+ assert(stack.empty());
+ }
+ @Test (<emphasis role="bold">groups = "basic"</emphasis>)
+ public void pushPopEmpty() {
+ ...
+ }
+
+ @Test (<emphasis role="bold">dependsOnGroups = "basic"</emphasis>)
+ public void push6() {
+ ...
+ }</programlisting>
+
+ <para>The first two tests will now belong to the same test group
+ <quote>basic</quote>. The <emphasis role="bold"><code>dependsOnGroups =
+ "basic"</code></emphasis> declaration will guarantee that our
+ <code>push6</code> test will be launched as the last one. So we get the
+ expected result:</para>
+
+ <programlisting language="none">PASSED: empty
+PASSED: pushPopEmpty
+FAILED: push6
+java.lang.ArrayIndexOutOfBoundsException: 5
+ at sda.unittesting.MyStack.push(MyStack.java:8)
+ at sda.unittesting.MyStackTest.push6(MyStackTest.java:30)
+ at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
+...
+
+
+===============================================
+ Default test
+ Tests run: 3, Failures: 1, Skips: 0
+===============================================</programlisting>
+
+ <para>In fact the order between the first two tests might be critical as
+ well. The <quote><code>pushPopEmpty</code></quote> test leaves our stack
+ in an empty state. If this is not the case reversing the execution order
+ of <quote><code>pushPopEmpty</code></quote> and
+ <quote><code>empty</code></quote> would cause an error as well.</para>
+
+ <para>Programming <abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Integrated_development_environment">IDE</abbrev>s
+ like eclipse provide elements for test result visualization. Our last
+ test gets summarized as:</para>
+
+ <screenshot>
+ <info>
+ <title><productname
+ xlink:href="http://testng.org">TestNG</productname> result
+ presentation in eclipse</title>
+ </info>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Screen/eclipseTestngResult.screen.png"
+ scale="75"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>We can drill down from a result of type failure to its occurrence
+ within the corresponding code.</para>
+ </chapter>
+
+ <chapter xml:id="fo">
+ <title>Generating printed output</title>
+
+ <titleabbrev>Print</titleabbrev>
+
+ <section xml:id="foIntro">
+ <title>Online and print versions</title>
+
+ <titleabbrev>online / print</titleabbrev>
+
+ <para>We already learned how to transform XML documents into HTML by
+ means of a <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> style sheet
+ processor. In principle we may create printed output by using a HTML
+ Browser's print function. However the result will not meet reasonable
+ typographical standards. A list of commonly required features for
+ printed output includes:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Line breaks</term>
+
+ <listitem>
+ <para>Text paragraphs have to be divided into lines. To achieve
+ best results the processor must implement the hyphenation rules
+ of the language in question in order to automatically hyphenate
+ long words. This is especially important for text columns of
+ limited width as appearing in newspapers.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Page breaks</term>
+
+ <listitem>
+ <para>Since printed pages are limited in height the content has
+ to be broken into pages. This may be difficult to
+ achieve:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Large images being indivisible may have to be deferred
+ to the following page leaving large amounts of empty
+ space.</para>
+ </listitem>
+
+ <listitem>
+ <para>Long tables may have to be subdivided into smaller
+ blocks. Thus it may be required to define sets of additional
+ footers like <quote>to be continued on the next page</quote>
+ and additional table headers containing column descriptions
+ on subsequent pages.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Page references</term>
+
+ <listitem>
+ <para>Document internal references via <link
+ xlink:href="http://www.w3.org/TR/xml#id">ID</link> / <link
+ xlink:href="http://www.w3.org/TR/xml#idref">IDREF</link> pairs
+ may be represented as page references like <quote>see page
+ 32</quote>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Left and right pages</term>
+
+ <listitem>
+ <para>Books usually have a different layout for
+ <quote>left</quote> and <quote>right</quote> pages. Page numbers
+ usually appear on the left side of a <quote>left</quote> page
+ and vice versa.</para>
+
+ <para>Very often the head of each page contains additional
+ information e.g. a chapter's name on each <quote>left</quote>
+ page head and the actual section's name on each
+ <quote>right</quote> page's head.</para>
+
+ <para>In addition chapters usually start on a
+ <quote>right</quote> page. Sometimes a chapter's starting page
+ has special layout features e.g. a missing description in the
+ page's head which will only be given on subsequent pages.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Footnotes</term>
+
+ <listitem>
+ <para>Footnotes have to be numbered on a per page basis and have
+ to appear on the current page.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section xml:id="foStart">
+ <title>A simple <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ document</title>
+
+ <titleabbrev>Simple <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev></titleabbrev>
+
+ <para>A renderer for printed output from XML content also needs
+ instructions how to format the different elements. A common way to
+ define these formatting properties is by using <emphasis>Formatting
+ Objects</emphasis> (<abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>)
+ standard. <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ documents may be compared to HTML. A HTML document has to be rendered
+ by a piece of software called a browser in order to be viewed as an
+ image. Likewise <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ documents have to be rendered by a piece of software called a
+ formatting objects processor which typically yields PostScript or PDF
+ output. As a starting point we take a simple example:</para>
+
+ <figure xml:id="foHelloWorld">
+ <title>The most simple <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ document</title>
+
+ <programlisting language="none"><?xml version="1.0" encoding="utf-8"?>
+<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
+
+ <fo:layout-master-set>
+ <!-- Define a simple page layout -->
+ <fo:simple-page-master master-name="simplePageLayout"
+ page-width="60mm" page-height="100mm">
+ <fo:region-body/>
+ </fo:simple-page-master>
+ </fo:layout-master-set>
+ <!-- Print a set of pages using the previously defined layout -->
+ <fo:page-sequence master-reference="simplePageLayout">
+ <fo:flow flow-name="xsl-region-body">
+ <emphasis role="bold"><fo:block>Hello, World ...</fo:block></emphasis>
+ </fo:flow>
+ </fo:page-sequence>
+</fo:root></programlisting>
+ </figure>
+
+ <para>PDF generation is initiated by executing a <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ processor. At the MI department the script <code>fo2pdf</code> invokes
+ <orgname>RenderX</orgname>'s <productname
+ xlink:href="http://www.renderx.com">xep</productname>
+ processor:</para>
+
+ <programlisting language="none">fo2pdf -fo hello.fo -pdf hello.pdf</programlisting>
+
+ <para>This creates a PDF file which may be printed or previewed by
+ e.g. <productname
+ xlink:href="http://www.adobe.com">Adobe</productname>'s acrobat reader
+ or evince under Linux. For a list of command line options see
+ <productname xlink:href="http://www.renderx.com/reference.html">xep's
+ documentation</productname>.</para>
+ </section>
+
+ <section xml:id="layoutParam">
+ <title>Page layout</title>
+
+ <para>The result from of our <quote>Hello, World ...</quote> code is
+ not very impressive. In order to develop more elaborated examples we
+ have to understand the underlying layout model being defined in a
+ <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_simple-page-master">fo:simple-page-master</link>
+ element. First of all <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ allows to subdivide a physical page into different regions:</para>
+
+ <figure xml:id="foRegionList">
+ <title>Regions being defined in a page.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/regions.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The most important area in this model is denoted by <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_region-body">fo:region-body</link>.
+ Other regions like <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_region-before">fo:region-before</link>
+ are typically used as containers for meta information such as chapter
+ headings and page numbering. We take a closer look to the <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_region-body">fo:region-body</link>
+ area and supply an example of parameterization:</para>
+
+ <figure xml:id="foParamRegBody">
+ <title>A complete <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ parameterizing of a physical page and the <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_region-body">fo:region-body</link>.</title>
+
+ <programlisting language="none"><?xml version="1.0" encoding="utf-8"?>
+<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"
+ font-size="6pt">
+
+ <fo:layout-master-set> <co xml:id="programlisting_fobodyreg_masterset"/>
+ <fo:simple-page-master master-name="<emphasis role="bold">simplePageLayout</emphasis>" <co
+ xml:id="programlisting_fobodyreg_simplepagelayout"/>
+ page-width = "50mm" page-height = "80mm"
+ margin-top = "5mm" margin-bottom = "20mm"
+ margin-left = "5mm" margin-right = "10mm">
+
+ <fo:region-body <co xml:id="programlisting_fobodyreg_regionbody"/>
+ margin-top = "10mm" margin-bottom = "5mm"
+ margin-left = "10mm" margin-right = "5mm"/>
+ </fo:simple-page-master>
+ </fo:layout-master-set>
+
+ <fo:page-sequence master-reference="<emphasis role="bold">simplePageLayout</emphasis>"> <co
+ xml:id="programlisting_fobodyreg_pagesequence"/>
+ <fo:flow flow-name="xsl-region-body"> <co
+ xml:id="programlisting_fobodyreg_flow"/>
+ <fo:block space-after="2mm">Dumb text .. dumb text.</fo:block> <co
+ xml:id="programlisting_fobodyreg_block"/>
+ <fo:block space-after="2mm">Dumb text .. dumb text.</fo:block> <coref
+ linkend="programlisting_fobodyreg_block"/>
+ <fo:block space-after="2mm">Dumb text .. dumb text.</fo:block> <coref
+ linkend="programlisting_fobodyreg_block"/>
+ <fo:block space-after="2mm">Dumb text .. dumb text.</fo:block> <coref
+ linkend="programlisting_fobodyreg_block"/>
+ </fo:flow>
+ </fo:page-sequence>
+</fo:root></programlisting>
+ </figure>
+
+ <calloutlist>
+ <callout arearefs="programlisting_fobodyreg_masterset">
+ <para>As the name suggests multiple layout definitions can appear
+ here. In this example only one layout is defined.</para>
+ </callout>
+
+ <callout arearefs="programlisting_fobodyreg_simplepagelayout">
+ <para>Each layout definition carries a key attribute master-name
+ being unique with respect to all defined layouts appearing in
+ <emphasis>the</emphasis> <tag
+ class="starttag">fo:layout-master-set</tag>. We may thus call it a
+ <emphasis>primary key</emphasis> attribute. The current layout
+ definition's key has the value <code>simplePageLayout</code>. The
+ length specifications appearing here are visualized in <xref
+ linkend="paramRegBodyVisul"/> and correspond to the white
+ rectangle.</para>
+ </callout>
+
+ <callout arearefs="programlisting_fobodyreg_regionbody">
+ <para>Each layout definition <emphasis>must</emphasis> have a
+ region body being the region in which the documents main text flow
+ will appear. A layout definition <emphasis>may</emphasis> also
+ define top, bottom and side regions as we will see <link
+ linkend="paramHeadFoot">later</link>. The body region is shown
+ with pink background in <xref
+ linkend="paramRegBodyVisul"/>.</para>
+ </callout>
+
+ <callout arearefs="programlisting_fobodyreg_pagesequence">
+ <para>A <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ document may have multiple page sequences for example one per each
+ chapter of a book. It <emphasis>must</emphasis> reference an
+ <emphasis>existing</emphasis> layout definition via its
+ <code>master-reference</code> attribute. So we may regard this
+ attribute as a foreign key targeting the set of all defined layout
+ definitions.</para>
+ </callout>
+
+ <callout arearefs="programlisting_fobodyreg_flow">
+ <para>A flow allows us to define in which region output shall
+ appear. In the current example only one layout containing one
+ region of type body definition being able to receive text output
+ exists.</para>
+ </callout>
+
+ <callout arearefs="programlisting_fobodyreg_block">
+ <para>A <tag class="starttag">fo:block</tag> element may be
+ compared to a paragraph element <tag class="starttag">p</tag> in
+ HTML. The attribute <link
+ xlink:href="http://www.w3.org/TR/xsl/#space-after">space-after</link>="2mm"
+ adds a space of two mm after each <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_block">fo:block</link>
+ container.</para>
+ </callout>
+ </calloutlist>
+
+ <para>The result looks like:</para>
+
+ <figure xml:id="paramRegBodyVisul">
+ <title>Parameterizing page- and region view port. All length
+ dimensions are in mm.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/overlay.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+
+ <section xml:id="headFoot">
+ <title>Headers and footers</title>
+
+ <titleabbrev>Header/footer</titleabbrev>
+
+ <para>Referring to <xref linkend="foRegionList"/> we now want to add
+ fixed headers and footers frequently being used for page numbers. In a
+ textbook each page might have the actual chapter's name in its header.
+ This name should not change as long as the text below <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_region-body">fo:region-body</link>
+ still belongs to the same chapter. In <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ this is achieved by:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Encapsulating each chapter's content in a <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_page-sequence">fo:page-sequence</link>
+ of its own.</para>
+ </listitem>
+
+ <listitem>
+ <para>Defining the desired header text below <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_static-content">fo:static-content</link>
+ in the area defined by <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_region-before">fo:region-before</link>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The notion <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_static-content">fo:static-content</link>
+ refers to the fact that the content is constant (static) within the
+ given page sequence. The new version reads:</para>
+
+ <figure xml:id="paramHeadFoot">
+ <title>Parameterizing header and footer.</title>
+
+ <programlisting language="none"><?xml version="1.0" encoding="utf-8"?>
+<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"
+ font-size="6pt">
+
+ <fo:layout-master-set>
+ <fo:simple-page-master master-name="simplePageLayout"
+ page-width = "50mm" page-height = "80mm"
+ margin-top = "5mm" margin-bottom = "20mm"
+ margin-left = "5mm" margin-right = "10mm">
+
+ <fo:region-body margin-top = "10mm" margin-bottom = "5mm" <co
+ xml:id="programlisting_head_foot_bodydef"/>
+ margin-left = "10mm" margin-right = "5mm"/>
+
+ <fo:region-before extent="5mm"/> <co
+ xml:id="programlisting_head_foot_beforedef"/>
+ <fo:region-after extent="5mm"/> <co
+ xml:id="programlisting_head_foot_afterdef"/>
+
+ </fo:simple-page-master>
+ </fo:layout-master-set>
+
+ <fo:page-sequence master-reference="simplePageLayout">
+
+ <fo:static-content flow-name="xsl-region-before"> <co
+ xml:id="programlisting_head_foot_beforeflow"/>
+ <fo:block
+ font-weight="bold"
+ font-size="8pt">Headertext</fo:block>
+ </fo:static-content>
+
+ <fo:static-content flow-name="xsl-region-after"> <co
+ xml:id="programlisting_head_foot_afterflow"/>
+ <fo:block>
+ <fo:page-number/>
+ </fo:block>
+ </fo:static-content>
+
+ <fo:flow flow-name="xsl-region-body">
+ <fo:block space-after="8mm">Dumb text .. dumb text.</fo:block>
+ <fo:block space-after="8mm">Dumb text .. dumb text.</fo:block>
+ <fo:block space-after="8mm">More text .. more text.</fo:block>
+ <fo:block space-after="8mm">More text .. more text.</fo:block>
+ <fo:block space-after="8mm">More text .. more text.</fo:block>
+ </fo:flow>
+ </fo:page-sequence>
+</fo:root></programlisting>
+ </figure>
+
+ <calloutlist>
+ <callout arearefs="programlisting_head_foot_bodydef">
+ <para>Defining the body region.</para>
+ </callout>
+
+ <callout arearefs="programlisting_head_foot_beforedef programlisting_head_foot_afterdef">
+ <para>Defining two regions at the top and bottom of each page. The
+ <code>extent</code> attribute denotes the height of these regions.
+ <emphasis>Caveat</emphasis>: The attribute <code>extent</code>'s
+ value gets subtracted from the <code>margin-top</code> or
+ <code>margin-bottom</code> value being defined in the
+ corresponding <tag class="starttag">fo:region-body</tag> element.
+ So if we consider for example the <tag>fo:region-before</tag> we
+ have to obey:</para>
+
+ <para>extent <= margin-top</para>
+
+ <para>Otherwise we may not even see any output.</para>
+ </callout>
+
+ <callout arearefs="programlisting_head_foot_beforeflow">
+ <para>A <code>fo:static-content</code> denotes text portions which
+ are decoupled from the <quote>usual</quote> text flow. For example
+ as a book's chapter advances over multiple pages we expect the
+ constant chapter's title to appear on top of each page. In the
+ current example the static string <code>Headertext</code> will
+ appear on each page's top for the whole <tag
+ class="starttag">fo:page-sequence</tag> in which it is defined.
+ Notice the <code>flow-name="xsl-region-after"</code> reference to
+ the region being defined in <coref
+ linkend="programlisting_head_foot_beforedef"/>.</para>
+ </callout>
+
+ <callout arearefs="programlisting_head_foot_afterflow">
+ <para>We do the same here for the page's footer. Instead of static
+ text we output <tag>fo_page-number</tag> yielding the current
+ page's number.</para>
+
+ <para>This time <code>flow-name="xsl-region-after"</code>
+ references the region definition in <coref
+ linkend="programlisting_head_foot_afterdef"/>. Actually the
+ attribute <code>flow-name</code> is restricted to the following
+ five values corresponding to all possible region definitions
+ within a layout:</para>
+
+ <informaltable>
+ <?dbhtml table-width="50%" ?>
+
+ <?dbfo table-width="50%" ?>
+
+ <tgroup cols="2">
+ <colspec align="left" colwidth="1*"/>
+
+ <colspec align="left" colwidth="1*"/>
+
+ <tbody>
+ <row>
+ <entry><tag class="starttag">fo:region-body</tag></entry>
+
+ <entry>xsl-region-body</entry>
+ </row>
+
+ <row>
+ <entry><tag
+ class="starttag">fo:region-before</tag></entry>
+
+ <entry>xsl-region-before</entry>
+ </row>
+
+ <row>
+ <entry><tag class="starttag">fo:region-after</tag></entry>
+
+ <entry>xsl-region-after</entry>
+ </row>
+
+ <row>
+ <entry><tag class="starttag">fo:region-start</tag></entry>
+
+ <entry>xsl-region-start</entry>
+ </row>
+
+ <row>
+ <entry><tag class="starttag">fo:region-end</tag></entry>
+
+ <entry>xsl-region-end</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </callout>
+ </calloutlist>
+
+ <para>This results in two pages with page numbers 1 and 2:</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/headfoot.fig"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>The free chapter from <xref linkend="bibHarold04"/> book
+ contains additional information on extended <link
+ xlink:href="http://www.cafeconleche.org/books/bible2/chapters/ch18.html#d1e2250">layout
+ definitions</link>. The <orgname
+ xlink:href="http://w3.org">W3C</orgname> as the holder of the FO
+ standard defines the elements <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_layout-master-set">fo:layout-master-set</link>,
+ <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_simple-page-master">fo:simple-page-master</link>
+ and <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_page-sequence">fo:page-sequence</link></para>
+ </section>
+
+ <section xml:id="foContainer">
+ <title>Important Objects</title>
+
+ <section xml:id="fo_block">
+ <title><code>fo:block</code></title>
+
+ <para>The FO standard borrows a lot from the CSS standard. Most
+ formatting objects may have <link
+ xlink:href="http://www.w3.org/TR/xsl/#section-N19349-Description-of-Property-Groups">CSS
+ like properties</link> with similar semantics, some properties have
+ been added. We take a <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_block">fo:block</link>
+ container as an example:</para>
+
+ <figure xml:id="blockInline">
+ <title>A <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_block">fo:block</link>
+ with a <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_inline">fo:inline</link>
+ descendant.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/blockprop.fo.pdf"/>
+ </imageobject>
+ </mediaobject>
+
+ <programlisting language="none">...
+<fo:block font-weight='bold'
+ border-bottom-style='dashed'
+ border-style='solid'
+ border='1mm'>A lot of attributes and <fo:inline background-color='black'
+ color='white'>inverted</fo:inline> text.</fo:block> ...</programlisting>
+ </figure>
+
+ <para>The <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_inline">fo:inline</link>
+ descendant serves as a means to change the <quote>current</quote>
+ property set. In HTML/CSS this may be achieved by using the
+ <code>SPAN</code> tag:</para>
+
+ <programlisting language="none"><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+ <head>
+ <title>Blocks/spans and CSS</title>
+ </head>
+ <body>
+ <h1>Blocks/spans and CSS</h1>
+ <p style="font-weight: bold; border: 1mm;
+ border-style: solid; border-bottom-style: dashed;"
+ >A lot of attributes and
+ <span style="color: white;background-color: black;"
+ >inverted</span> text.</p>
+ </body>
+</html></programlisting>
+
+ <para>Though being encapsulated in an attribute <code>class</code>
+ we find a one-to-one correspondence between FO and CSS in this case.
+ The HTML rendering works as expected.<mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Screen/mozparaspancss.screen.png"/>
+ </imageobject>
+ </mediaobject>:</para>
+ </section>
+
+ <section xml:id="fo_list">
+ <title>Lists</title>
+
+ <para>The easiest type of lists are unlabeled (itemized) lists as
+ being expressed by the <code>UL</code>/<code>LI</code> tags in HTML.
+ FO allows a much more detailed parametrization regarding indents and
+ distances between labels and item content. Relevant elements are
+ <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_list-block">fo:list-block</link>,
+ <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_list-item">fo:list-item</link>
+ and <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_list-item-body">fo:list-item-body</link>.
+ The drawback is a more complex setup for <quote>default</quote>
+ lists:</para>
+
+ <figure xml:id="listItemize">
+ <title>An itemized list and result.</title>
+
+ <programlisting language="none">...
+<fo:list-block
+ provisional-distance-between-starts="2mm">
+ <fo:list-item>
+ <fo:list-item-label end-indent="label-end()">
+ <fo:block>&#8226;</fo:block>
+ </fo:list-item-label>
+ <fo:list-item-body start-indent="body-start()">
+ <fo:block>Flowers</fo:block>
+ </fo:list-item-body>
+ </fo:list-item>
+
+ <fo:list-item>
+ <fo:list-item-label end-indent="label-end()">
+ <fo:block>&#8226;</fo:block>
+ </fo:list-item-label>
+ <fo:list-item-body start-indent="body-start()">
+ <fo:block>Animals</fo:block>
+ </fo:list-item-body>
+ </fo:list-item>
+</fo:list-block> ...</programlisting>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="left" fileref="Ref/Fig/itemize.fo.pdf"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The result looks somewhat primitive in relation to the amount
+ of source code it necessitates. The power of these constructs shows
+ up when trying to format nested lists of possibly different types
+ like enumerations or definition lists under the requirement of
+ typographical excellence. More complex examples are presented in
+ <link
+ xlink:href="http://www.cafeconleche.org/books/bible2/chapters/ch18.html#d1e4979">Xmlbible
+ book</link> of <xref linkend="bibHarold04"/>.</para>
+ </section>
+
+ <section xml:id="leaderRule">
+ <title>Leaders and rules</title>
+
+ <titleabbrev>Leaders/rules</titleabbrev>
+
+ <para>Sometimes adjustable horizontal space between two neighbouring
+ objects has to be filled e.g. in a book's table of contents. The
+ <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_leader">fo:leader</link>
+ serves this purpose:</para>
+
+ <figure xml:id="leaderToc">
+ <title>Two simulated entries in a table of contents.</title>
+
+ <programlisting language="none">...
+<fo:block text-align-last='justify'>Valid
+ XML<fo:leader leader-pattern="dots"/>
+page 7</fo:block>
+
+<fo:block text-align-last='justify'>XSL
+<fo:leader leader-pattern='dots'/>
+page 42</fo:block> ...</programlisting>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="left" fileref="Ref/Fig/leader.fo.pdf"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The attributes' value <link
+ xlink:href="http://www.w3.org/TR/xsl/#text-align-last">text-align-last</link>
+ = <code>'justify'</code> forces the <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_block">fo:block</link> to
+ extend to the available width of the current <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_region-body">fo:region-body</link>
+ area. The <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_leader">fo:leader</link>
+ inserts the necessary amount of content of the specified type
+ defined in in <link
+ xlink:href="http://www.w3.org/TR/xsl/#leader-pattern">leader-pattern</link>
+ to fill up the gap between its neighbouring components. This
+ principle can be extended to multiple objects:</para>
+
+ <figure xml:id="leaderMulti">
+ <title>Four entries separated by equal amounts of dotted
+ space.</title>
+
+ <programlisting language="none"><fo:block text-align-last='justify'>A<fo:leader
+leader-pattern="dots"/>B<fo:leader
+leader-pattern="dots"/>C<fo:leader leader-pattern="dots"/>D</fo:block></programlisting>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/leadermulti.fo.pdf"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>A <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_leader">fo:leader</link>
+ may also be used to draw horizontal lines to separate objects. In
+ this case there are no neighbouring components within the
+ <quote>current</quote> line in which the <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_leader">fo:leader</link>
+ appears. This is frequently used to draw a border between
+ <code>xsl-region-body</code> and <code>xsl-region-before</code>
+ and/or <code>xsl-region-after</code>:</para>
+
+ <figure xml:id="leaderSeparate">
+ <title>A horizontal line separator between header and body of a
+ page.</title>
+
+ <programlisting language="none">...
+<fo:page-sequence master-reference="simplePageLayout">
+ <fo:static-content flow-name="xsl-region-before">
+ <fo:block text-align-last='justify'>FO<fo:leader/>page 5</fo:block>
+ <fo:block text-align-last='justify'>
+ <fo:leader leader-pattern="rule" leader-length="100%"/>
+ </fo:block>
+ </fo:static-content>
+ <fo:flow flow-name="xsl-region-body">
+ <fo:block>Some body text ...</fo:block>
+ </fo:flow>
+</fo:page-sequence>...</programlisting>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="left" fileref="Ref/Fig/separate.fo.pdf"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Note the empty leader <code><</code> <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_leader">fo:leader</link>
+ <code>/></code> between the <quote> <code>FO</code> </quote> and
+ the <quote>page 5</quote> text node inserting horizontal whitespace
+ to get the page number centered to the header's right edge. This is
+ in accordance with the <link
+ xlink:href="http://www.w3.org/TR/xsl/#leader-pattern">leader-pattern</link>
+ attributes default value <code>space</code>.</para>
+ </section>
+
+ <section xml:id="pageNumbering">
+ <title>Page numbers</title>
+
+ <para>We already saw an example of page numbering via <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_page-number">fo:page-number</link>
+ in <xref linkend="paramHeadFoot"/>. Sometimes a different style for
+ page numbering is desired. The default page numbering style may be
+ changed by means of the <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_page-sequence">fo:page-sequence</link>
+ element's attribute <link
+ xlink:href="http://www.w3.org/TR/xsl/#format">format</link>. For a
+ closer explanation the <link
+ xlink:href="http://www.w3.org/TR/2007/REC-xslt20-20070123/#convert">W3X
+ XSLT standards documentation</link> may be consulted:</para>
+
+ <figure xml:id="pageNumberingRoman">
+ <title>Roman style page numbers.</title>
+
+ <programlisting language="none">...
+<fo:page-sequence format="i"
+ master-reference="simplePageLayout">
+ <fo:static-content
+ flow-name="xsl-region-after">
+ <fo:block text-align-last='justify'>
+ <fo:leader leader-pattern="rule"
+ leader-length="100%"/>
+ </fo:block>
+ <fo:block font-weight="bold">
+ <fo:page-number/>
+ </fo:block>
+ </fo:static-content>
+
+ <fo:flow flow-name="xsl-region-body">
+ <fo:block>Some text...</fo:block>
+ <fo:block>More text, more text,
+ more text.</fo:block>
+ <fo:block>More text, more text,
+ more text.</fo:block>
+ <fo:block>Enough text.</fo:block>
+ </fo:flow>
+</fo:page-sequence> ...</programlisting>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="left" fileref="Ref/Fig/pageStack.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+
+ <section xml:id="foMarker">
+ <title>Marker</title>
+
+ <figure xml:id="dictionary">
+ <title>A dictionary with running page headers.</title>
+
+ <programlisting language="none">...
+<fo:page-sequence
+ master-reference="simplePageLayout">
+ <fo:static-content flow-name="xsl-region-before">
+ <fo:block font-weight="bold">
+ <fo:retrieve-marker retrieve-class-name="alpha"
+ retrieve-position="first-starting-within-page"
+ />-<fo:retrieve-marker
+ retrieve-position="last-starting-within-page"
+ retrieve-class-name="alpha"/>
+ </fo:block>
+ <fo:block text-align-last='justify'>
+ <fo:leader leader-pattern="rule" leader-length="100%"/></fo:block>
+ </fo:static-content>
+
+ <fo:flow flow-name="xsl-region-body">
+ <fo:block>
+ <fo:marker marker-class-name="alpha">A
+ </fo:marker>Ant</fo:block>
+ <fo:block>
+ <fo:marker marker-class-name="alpha">B
+ </fo:marker>Bug</fo:block>
+ <fo:block>
+ <fo:marker marker-class-name="alpha">L
+ </fo:marker>Lion</fo:block>
+ <fo:block>
+ <fo:marker marker-class-name="alpha">N
+ </fo:marker>Nose</fo:block>
+ <fo:block>
+ <fo:marker marker-class-name="alpha">P
+ </fo:marker>Peg</fo:block>
+ </fo:flow>
+</fo:page-sequence> ...</programlisting>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="left" fileref="Ref/Fig/dictionaryStack.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+
+ <section xml:id="foIntRef">
+ <title>Internal references</title>
+
+ <titleabbrev>References</titleabbrev>
+
+ <para>Regarding printed documents we may define two categories of
+ document internal references:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Page number references</emphasis></term>
+
+ <listitem>
+ <para>This is the <quote>classical</quote> type of a reference
+ e.g. in books. An author refers the reader to a distant
+ location by writing <quote>... see further explanation in
+ section 4.5 on page 234</quote>. A book's table of contents
+ assigning page numbers to topics is another example. This way
+ the implementation of a reference relies solely on the
+ features a printed document offers.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis>Hypertext references</emphasis></term>
+
+ <listitem>
+ <para>This way of implementing references utilizes features of
+ (online) viewers for printable documents. For example PDF
+ viewers like <productname
+ xlink:href="http://www.adobe.com">Adobe's Acrobat
+ reader</productname> or the evince application are able to
+ follow hypertext links in a fashion known from HTML browsers.
+ This browser feature is based on hypertext capabilities
+ defined in the Adobe's PDF de-facto standard.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Of course the second type of references is limited to people
+ who use an online viewer application instead of reading a document
+ from physical paper.</para>
+
+ <para>We now show the implementation of <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ based page references. As already being discussed for <link
+ xlink:href="http://www.w3.org/TR/xml#id">ID</link> / <link
+ xlink:href="http://www.w3.org/TR/xml#idref">IDREF</link> pairs we
+ need a link destination (anchor) and a link source. The <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ standard uses the same anchor implementation as in XML for <link
+ xlink:href="http://www.w3.org/TR/xml#id">ID</link> typed attributes:
+ <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ objects <emphasis>may</emphasis> have an attribute <link
+ xlink:href="http://www.w3.org/TR/xsl/#id">id</link> with a document
+ wide unique value. The <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ element <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_page-number-citation">fo:page-number-citation</link>
+ is used to actually create a page reference via its attribute <link
+ xlink:href="http://www.w3.org/TR/xsl/#ref-id">ref-id</link>:</para>
+
+ <figure xml:id="refJavaXml">
+ <title>Two blocks mutual page referencing each other.</title>
+
+ <programlisting language="none">...
+ <fo:flow flow-name='xsl-region-body'>
+ <fo:block id='xml'>Java section see page
+ <fo:page-number-citation ref-id='java'/>.
+ </fo:block>
+
+ <fo:block id='java'>XML section see page
+ <fo:page-number-citation ref-id='xml'/>.
+ </fo:block>
+ </fo:flow> ...</programlisting>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="left" fileref="Ref/Fig/pagerefStack.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>NB: Be careful defining <link
+ xlink:href="http://www.w3.org/TR/xsl/#id">id</link> attributes for
+ objects being descendants of <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_static-content">fo:static-content</link>
+ nodes. Such objects typically appear on multiple pages and are
+ therefore no unique anchors. A reference carrying such an id value
+ thus actually refers to 1 <= n values on n different pages.
+ Typically a user agent will choose the first object of this set when
+ clicking the link. So in effect the parent <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_page-sequence">fo:page-sequence</link>
+ is chosen as the effective link target.</para>
+
+ <para>The element <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_basic-link">fo:basic-link</link>
+ creates PDF hypertext links. We extend the previous example:</para>
+
+ <figure xml:id="refJavaXmlHyper">
+ <title>Two blocks with mutual page- and hypertext
+ references.</title>
+
+ <programlisting language="none"><fo:flow flow-name='xsl-region-body'>
+ <fo:block id='xml'>Java section see <fo:basic-link color="blue"
+ internal-destination="java">page<fo:page-number-citation
+ ref-id='java'/>.</fo:basic-link></fo:block>
+
+<fo:block id='java'>XML section see
+ <fo:basic-link color="blue"
+ internal-destination="xml">page <fo:page-number-citation
+ ref-id='xml'/>.</fo:basic-link></fo:block >
+</fo:flow></programlisting>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/pagerefhyperStack.fig"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+
+ <section xml:id="pdfBookmarks">
+ <title>PDF bookmarks</title>
+
+ <titleabbrev>Bookmarks</titleabbrev>
+
+ <para>The PDF specification allows to define so called bookmarks
+ offering an explorer like navigation:</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Screen/pdfbookmarks.screen.png"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>PDF bookmarks are <link
+ xlink:href="http://www.w3.org/TR/2006/REC-xsl11-20061205/#d0e14206">part
+ of the XSL-FO 1.1</link> Standard. Some <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ processors still continue to use proprietary solutions for bookmark
+ creation with respect to the older <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ 1.0 standard. For details of bookmark extensions by
+ <orgname>RenderX</orgname>'s processor see <link
+ xlink:href="http://www.renderx.com/tutorial.html#PDF_Bookmarks">xep's
+ documentation</link>.</para>
+ </section>
+ </section>
+
+ <section xml:id="xml2fo">
+ <title>Constructing <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ from XML documents</title>
+
+ <titleabbrev><abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ from XML</titleabbrev>
+
+ <para>So far we have learnt some basic <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ elements. As with HTML we typically generate FO code from other
+ sources rather than crafting it by hand. The general picture
+ is:</para>
+
+ <figure xml:id="htmlFoProduction">
+ <title>Different target formats from common source.</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/crossmedia.fig" scale="65"/>
+ </imageobject>
+
+ <caption>
+ <para>We may generate both online and printed documentation from
+ a common source. This requires style sheets for the desired
+ destination formats in question.</para>
+ </caption>
+ </mediaobject>
+ </figure>
+
+ <para>We discussed the <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ standard as an input format for printable output production by a
+ renderer. In this way a <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ document is similar to HTML being a format to be rendered by a web
+ browser for visual (screen oriented) output production. The
+ transformation from a XML source (e.g. a memo document) to <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ is still missing. As for HTML we may use <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> as a
+ transformation means. We generate the sender's surname from a memo
+ document instance:</para>
+
+ <figure xml:id="memo2fosurname">
+ <title>Generating a sender's surname for printing.</title>
+
+ <programlisting language="none"><?xml version="1.0" encoding="utf-8"?>
+<xsl:stylesheet version="1.0"
+ xmlns:fo="http://www.w3.org/1999/XSL/Format"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+ <xsl:output method="xml" indent="yes"/>
+
+ <xsl:template match="/">
+ <fo:root>
+ <fo:layout-master-set>
+ <fo:simple-page-master master-name="simplePageLayout"
+ page-width="294mm" page-height="210mm" margin="5mm">
+ <fo:region-body margin="15mm"/>
+ </fo:simple-page-master>
+ </fo:layout-master-set>
+ <fo:page-sequence master-reference="simplePageLayout">
+ <fo:flow flow-name="xsl-region-body">
+ <fo:block font-size="20pt">
+ <xsl:text>Sender:</xsl:text>
+ <fo:inline font-weight='bold'>
+ <xsl:value-of select="memo/from/surname"/>
+ </fo:inline>
+ </fo:block>
+ </fo:flow>
+ </fo:page-sequence>
+ </fo:root>
+ </xsl:template>
+</xsl:stylesheet></programlisting>
+ </figure>
+
+ <para>A suitable XML document instance reads:</para>
+
+ <figure xml:id="memoMessage">
+ <title>A <code>memo</code> document instance.</title>
+
+ <programlisting language="none"><?xml version="1.0" ?>
+<!DOCTYPE memo SYSTEM "memo.dtd">
+<memo>
+ <from>
+ <name>Martin</name>
+ <surname>Goik</surname>
+ </from>
+ <to>
+ <name>Adam</name>
+ <surname>Hacker</surname>
+ </to>
+ <to>
+ <name>Eve</name>
+ <surname>Intruder</surname>
+ </to>
+ <date year="2005" month="1" day="6"/>
+ <subject>Firewall problems</subject>
+ <content>
+ <para>Thanks for your excellent work.</para>
+ <para>Our firewall is definitely broken!</para>
+ </content>
+</memo></programlisting>
+ </figure>
+
+ <para>Some remarks:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>The <link
+ xlink:href="http://www.w3.org/TR/2007/REC-xslt20-20070123/#element-stylesheet">xsl_stylesheet</link>
+ element contains a namespace definition for the target FO
+ document's namespace, namely:</para>
+
+ <programlisting language="none">xmlns:xsl="http://www.w3.org/1999/XSL/Transform"</programlisting>
+
+ <para>This is required to use elements like <link
+ xlink:href="http://www.w3.org/TR/xsl/#fo_block">fo:block</link>
+ belonging to the FO namespace.</para>
+ </listitem>
+
+ <listitem>
+ <para>The option value <code>indent="yes"</code> in <link
+ xlink:href="http://www.w3.org/TR/2007/REC-xslt20-20070123/#element-output">xsl_output</link>
+ is usually set to "no" in a production environment to avoid
+ whitespace related problems.</para>
+ </listitem>
+
+ <listitem>
+ <para>The generation of a print format like PDF is actually a two
+ step process. To generate message.pdf from message.xml by a
+ stylesheet memo2fo.xsl we need the following calls:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>XML document instance to FO</emphasis></term>
+
+ <listitem>
+ <programlisting language="none">xml2xml message.xml memo2fo.xsl -o message.fo</programlisting>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis>FO to PDF</emphasis></term>
+
+ <listitem>
+ <programlisting language="none">fo2pdf -fo message.fo -pdf message.pdf</programlisting>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/Fig/xml2fo2pdf.fig"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>When debugging of the intermediate <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ file is not required both steps may be combined into a single
+ call:</para>
+
+ <programlisting language="none">fo2pdf -xml message.xml -xsl memo2fo.xsl -pdf message.pdf</programlisting>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section xml:id="foCatalog">
+ <title>Formatting a catalog.</title>
+
+ <titleabbrev>A catalog</titleabbrev>
+
+ <para>We now take the <link linkend="climbingCatalog">climbing catalog
+ example</link> with prices being added and incrementally create a
+ series of PDF versions improving from one version to another.</para>
+
+ <qandaset defaultlabel="qanda" xml:id="idCatalogStart">
+ <title>A first PDF version of the catalog</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>Write a <abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSL</abbrev> script
+ to generate a starting version <filename
+ xlink:href="Ref/src/Dom/climbenriched.start.pdf">climbenriched.start.pdf</filename>.</para>
+ </question>
+
+ <answer>
+ <programlisting language="none"><?xml version="1.0" encoding="utf-8"?>
+<xsl:stylesheet version="1.0"
+ xmlns:fo="http://www.w3.org/1999/XSL/Format"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+ <xsl:output method="xml" indent="yes"/>
+
+ <xsl:template match="/">
+ <fo:root font-size="10pt">
+ <fo:layout-master-set>
+ <fo:simple-page-master master-name="productPage"
+ page-width="80mm" page-height="110mm" margin="5mm">
+ <fo:region-body margin="15mm"/>
+ <fo:region-before extent="10mm"/>
+ </fo:simple-page-master>
+ </fo:layout-master-set>
+ <xsl:apply-templates select="catalog/product" />
+ </fo:root>
+ </xsl:template>
+
+ <xsl:template match="product">
+ <fo:page-sequence master-reference="productPage">
+ <fo:static-content flow-name="xsl-region-before">
+ <fo:block font-weight="bold">
+ <xsl:value-of select="title"/>
+ </fo:block>
+ </fo:static-content>
+ <fo:flow flow-name="xsl-region-body">
+ <xsl:apply-templates select="description/para"/>
+
+ <fo:block>Price:<xsl:value-of select="@price"/></fo:block>
+ <fo:block>Order no:<xsl:value-of select="@id"/></fo:block>
+ </fo:flow>
+ </fo:page-sequence>
+ </xsl:template>
+
+ <xsl:template match="para">
+ <fo:block space-after="10px">
+ <xsl:value-of select="."/>
+ </fo:block>
+ </xsl:template>
+
+</xsl:stylesheet></programlisting>
+ </answer>
+ </qandaentry>
+
+ <qandaentry xml:id="idCatalogProduct">
+ <question>
+ <label>Header, page numbers and table formatting</label>
+
+ <para>Extend <xref linkend="idCatalogStart"/> by adding page
+ numbers. The order number and prices shall be formatted as
+ tables. Add a ruler to each page's head. The result should
+ look like <filename
+ xlink:href="Ref/src/Dom/climbenriched.product.pdf">climbenriched.product.pdf</filename></para>
+ </question>
+
+ <answer>
+ <para>Solution see <filename
+ xlink:href="Ref/src/Dom/catalog2fo.product.xsl">catalog2fo.product.xsl</filename>.</para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry xml:id="idCatalogToc">
+ <question>
+ <label>A table of contents.</label>
+
+ <para>Each product description's page number shall appear in a
+ table of contents together with the product's
+ <code>title</code> as in <filename
+ xlink:href="Ref/src/Dom/climbenriched.toc.pdf">climbenriched.toc.pdf</filename>.</para>
+ </question>
+
+ <answer>
+ <para>Solution see <filename
+ xlink:href="Ref/src/Dom/catalog2fo.toc.xsl">catalog2fo.toc.xsl</filename>.</para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry xml:id="idCatalogToclink">
+ <question>
+ <label>A table of contents with hypertext links.</label>
+
+ <para>The table of contents' entries may offer hypertext
+ features to supporting browsers as in <filename
+ xlink:href="Ref/src/Dom/climbenriched.toclink.pdf">climbenriched.toclink.pdf</filename>.
+ In addition include the document's <tag
+ class="starttag">introduction</tag>.</para>
+ </question>
+
+ <answer>
+ <para>Solution see <filename
+ xlink:href="Ref/src/Dom/catalog2fo.toclink.xsl">catalog2fo.toclink.xsl</filename>.</para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry xml:id="idCatalogFinal">
+ <question>
+ <label>A final version.</label>
+
+ <para>Add the following features:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Number the table of contents starting with page i,
+ ii, iii, iv and so on. Start the product descriptions with
+ page 1. On each page's footer a text <quote>page xx of
+ yy</quote> shall be displayed. This requires the
+ definition of an anchor <code>id</code> on the <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ document's last page.</para>
+ </listitem>
+
+ <listitem>
+ <para>Add PDF bookmarks by using <orgname>XEP</orgname>'s
+ <abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section">FO</abbrev>
+ extensions. This requires the namespace declaration
+ <code>xmlns:rx="http://www.renderx.com/XSL/Extensions"</code>
+ in the XSLT script's header.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>The result may look like <filename
+ xlink:href="Ref/src/Dom/climbenriched.final.pdf">climbenriched.final.pdf</filename>.
+ N.B.: It may take some effort to achieve this result. This
+ effort is left to the <emphasis>interested</emphasis>
+ participants.</para>
+ </question>
+
+ <answer>
+ <para>Solution see <filename
+ xlink:href="Ref/src/Dom/catalog2fo.toclink.xsl">catalog2fo.toclink.xsl</filename>.</para>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+ </chapter>
+
+ <appendix>
+ <title>W3C production rules</title>
+
+ <productionset>
+ <title><link
+ xlink:href="http://www.w3.org/TR/2008/REC-xml-20081126/#charsets">Characters</link></title>
+
+ <production xml:id="w3RecXml_NT-Letter">
+ <lhs>Letter</lhs>
+
+ <rhs><nonterminal def="#w3RecXml_NT-BaseChar">BaseChar</nonterminal>
+ | <nonterminal
+ def="#w3RecXml_NT-Ideographic">Ideographic</nonterminal></rhs>
+ </production>
+
+ <production xml:id="w3RecXml_NT-BaseChar">
+ <lhs>BaseChar</lhs>
+
+ <rhs>[#x0041-#x005A] |Â [#x0061-#x007A] |Â [#x00C0-#x00D6]
+ |Â [#x00D8-#x00F6] |Â [#x00F8-#x00FF] |Â [#x0100-#x0131]
+ |Â [#x0134-#x013E] |...(values omitted here, see W3C
+ documentation)</rhs>
+ </production>
+
+ <production xml:id="w3RecXml_NT-Ideographic">
+ <lhs>Ideographic</lhs>
+
+ <rhs>[#x4E00-#x9FA5] |Â #x3007 |Â [#x3021-#x3029]</rhs>
+ </production>
+
+ <production xml:id="w3RecXml_NT-CombiningChar">
+ <lhs>CombiningChar</lhs>
+
+ <rhs>[#x0300-#x0345] |Â ...(values omitted here)</rhs>
+ </production>
+
+ <production xml:id="w3RecXml_NT-Digit">
+ <lhs>Digit</lhs>
+
+ <rhs>[#x0030-#x0039] |Â [#x0660-#x0669] |Â [#x06F0-#x06F9]
+ |Â [#x0966-#x096F] |Â [#x09E6-#x09EF] |Â [#x0A66-#x0A6F]
+ |Â [#x0AE6-#x0AEF] |Â [#x0B66-#x0B6F] |Â [#x0BE7-#x0BEF]
+ |Â [#x0C66-#x0C6F] |Â [#x0CE6-#x0CEF] |Â [#x0D66-#x0D6F]
+ |Â [#x0E50-#x0E59] |Â [#x0ED0-#x0ED9] |Â [#x0F20-#x0F29]</rhs>
+ </production>
+
+ <production xml:id="w3RecXml_NT-Extender">
+ <lhs>Extender</lhs>
+
+ <rhs>#x00B7 |Â #x02D0 |Â #x02D1 |Â #x0387 |Â #x0640 |Â #x0E46 |Â #x0EC6
+ |Â #x3005 |Â [#x3031-#x3035] |Â [#x309D-#x309E] |Â [#x30FC-#x30FE]</rhs>
+ </production>
+ </productionset>
+ </appendix>
+
+ <appendix>
+ <title>Glossary</title>
+
+ <para/>
+
+ <glossary>
+ <glossentry xml:id="gloss_API">
+ <glossterm><abbrev xlink:href="http://en.wikipedia.org/wiki/Api"
+ xml:id="abbr_api">API</abbrev></glossterm>
+
+ <glossdef>
+ <para>Application programming interface</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_SqlDdl">
+ <glossterm><abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Data_definition_language"
+ xml:id="abbr_Ddl">DDL</abbrev> <link
+ linkend="gloss_SQL">(SQL)</link></glossterm>
+
+ <glossdef>
+ <para>Data definition language. The subset of <link
+ linkend="gloss_SQL">SQL</link> dealing with the creation of tables,
+ views etc.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_DOM">
+ <glossterm><acronym xlink:href="http://www.w3.org/DOM"
+ xml:id="abbr_Dom">DOM</acronym></glossterm>
+
+ <glossdef>
+ <para>The <link linkend="gloss_W3C">W3C</link> <link
+ xlink:href="http://www.w3.org/DOM">Document Object Model</link>
+ standard</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_DTD">
+ <glossterm><abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Document_Type_Declaration"
+ xml:id="abbr_Dtd">DTD</abbrev></glossterm>
+
+ <glossdef>
+ <para>Document Type Definition. An older standard with respect to
+ <link linkend="gloss_RelaxNG">RelaxNG</link> and <link
+ linkend="gloss_RelaxNG">XML schema</link> to define an XML documents
+ grammar.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_EBNF">
+ <glossterm><abbrev>EBNF</abbrev></glossterm>
+
+ <glossdef>
+ <para>Extended Backus-Naur form.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_ftp">
+ <glossterm><abbrev
+ xlink:href="http://en.wikipedia.org/wiki/File_Transfer_Protocol"
+ xml:id="abbr_Ftp">ftp</abbrev></glossterm>
+
+ <glossdef>
+ <para>File Transfer Protocol</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_FO">
+ <glossterm><abbrev
+ xlink:href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo-section"
+ xml:id="abbr_Fo">FO</abbrev></glossterm>
+
+ <glossdef>
+ <para>The Formatting Objects Standard for printable output
+ generation</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_HDM">
+ <glossterm><orgname xlink:href="http://www.hdm-stuttgart.de"
+ xml:id="org_Hdm">Hdm</orgname></glossterm>
+
+ <glossdef>
+ <para xml:lang="de">Hochschule der Medien.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_Hql">
+ <glossterm><abbrev
+ xlink:href="http://docs.jboss.org/hibernate/orm/4.1/manual/en-US/html/ch16.html"
+ xml:id="abbr_Hql">HQL</abbrev></glossterm>
+
+ <glossdef>
+ <para>The <link
+ xlink:href="http://docs.jboss.org/hibernate/orm/3.3/reference/en/html/queryhql.html">Hibernate
+ Query Language</link>.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_http">
+ <glossterm><abbrev xlink:href="http://www.w3.org/Protocols"
+ xml:id="abbr_Http">http</abbrev></glossterm>
+
+ <glossdef>
+ <para>The Hypertext Transfer Protocol</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_IDE">
+ <glossterm><abbrev
+ xlink:href="http://en.wikipedia.org/wiki/Integrated_development_environment"
+ xml:id="abbr_Ide">IDE</abbrev></glossterm>
+
+ <glossdef>
+ <para>Integrated Development Environment</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_J2EE">
+ <glossterm><trademark
+ xlink:href="http://www.oracle.com/technetwork/java/javaee"
+ xml:id="tm_J2ee">J2EE</trademark></glossterm>
+
+ <glossdef>
+ <para>Java Platform, Enterprise Edition</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_Java">
+ <glossterm><trademark
+ xlink:href="http://www.oracle.com/us/legal/third-party-trademarks/index.html">Java</trademark></glossterm>
+
+ <glossdef>
+ <para>General purpose programming language with support for object
+ oriented concepts.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_Javadoc">
+ <glossterm><trademark
+ xlink:href="http://docs.oracle.com/javase/1.5.0/docs/guide/javadoc">Javadoc</trademark></glossterm>
+
+ <glossdef>
+ <para>Extracting documentation embedded in <link
+ linkend="gloss_Java"><trademark>Java</trademark></link> source
+ code.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_JDBC">
+ <glossterm><trademark
+ xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc"
+ xml:id="tm_Jdbc">JDBC</trademark></glossterm>
+
+ <glossdef>
+ <para>XXX.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_JDK">
+ <glossterm><trademark
+ xlink:href="http://www.oracle.com/technetwork/java/javase"
+ xml:id="tm_Jdk">JDK</trademark></glossterm>
+
+ <glossdef>
+ <para>Java Development Kit.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_JPA">
+ <glossterm><abbrev
+ xlink:href="http://www.javaworld.com/javaworld/jw-01-2008/jw-01-jpa1.html"
+ xml:id="abbr_Jpa">JPA</abbrev></glossterm>
+
+ <glossdef>
+ <para><link
+ xlink:href="http://www.javaworld.com/javaworld/jw-01-2008/jw-01-jpa1.html">Java
+ Persistence Architecture</link></para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_JRE">
+ <glossterm><trademark
+ xlink:href="http://www.oracle.com/technetwork/java/javase"
+ xml:id="tm_Jre">JRE</trademark></glossterm>
+
+ <glossdef>
+ <para>Java Runtime Environment</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_MathML">
+ <glossterm><abbrev>MathML</abbrev></glossterm>
+
+ <glossdef>
+ <para><link xlink:href="http://www.w3.org/Math">Mathematical Markup
+ Language</link></para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_MIB">
+ <glossterm><orgname xlink:href="http://www.mi.hdm-stuttgart.de"
+ xml:id="org_Mib">MIB</orgname></glossterm>
+
+ <glossdef>
+ <para xml:lang="de">Bachelor Studiengang Medieninformatik</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_Mysql">
+ <glossterm><trademark
+ xlink:href="http://www.mysql.com/about/legal/trademark.html"
+ xml:id="tm_Mysql">Mysql</trademark></glossterm>
+
+ <glossdef>
+ <para>Open source Oracle database product</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_MP3">
+ <glossterm><abbrev>MP3</abbrev></glossterm>
+
+ <glossdef>
+ <para>Audio codec.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_ORM">
+ <glossterm><abbrev>ORM</abbrev></glossterm>
+
+ <glossdef>
+ <para>Object relational mapping.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_PHP">
+ <glossterm><abbrev
+ xlink:href="http://www.php.net">PHP</abbrev></glossterm>
+
+ <glossdef>
+ <para>Hypertext preprocessor</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_RelaxNG">
+ <glossterm><acronym
+ xlink:href="http://relaxng.org">RelaxNG</acronym></glossterm>
+
+ <glossdef>
+ <para>An <link
+ xlink:href="http://standards.iso.org/ittf/PubliclyAvailableStandards/c037605_ISO_IEC_19757-2_2003(E).zip">ISO</link>
+ standard to define the grammar of XML documents. Primary use for
+ document oriented applications.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_SAX">
+ <glossterm><acronym
+ xlink:href="http://www.saxproject.org">SAX</acronym></glossterm>
+
+ <glossdef>
+ <para><link xlink:href="http://www.saxproject.org">Simple API for
+ XML</link>.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_SQL">
+ <glossterm><acronym
+ xlink:href="http://en.wikipedia.org/wiki/Sql">SQL</acronym></glossterm>
+
+ <glossdef>
+ <para><link xlink:href="http://en.wikipedia.org/wiki/SQL">Structured
+ query language</link>.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_SVG">
+ <glossterm><abbrev>SVG</abbrev></glossterm>
+
+ <glossdef>
+ <para><link xlink:href="http://www.w3.org/Graphics/SVG">Scalable
+ Vector Graphics</link>.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_TCP">
+ <glossterm><acronym
+ xlink:href="http://en.wikipedia.org/wiki/Transmission_Control_Protocol"
+ xml:id="abbr_Tcp">TCP</acronym></glossterm>
+
+ <glossdef>
+ <para>Transmission Control Protocol</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_URL">
+ <glossterm><abbrev xlink:href="http://www.ietf.org/rfc/rfc1738.txt"
+ xml:id="abbr_Url">URL</abbrev></glossterm>
+
+ <glossdef>
+ <para>Uniform Resource Locator</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_W3C">
+ <glossterm><orgname
+ xlink:href="http://www.w3.org">W3C</orgname></glossterm>
+
+ <glossdef>
+ <para>World Wide Web Consortium</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_XHTML">
+ <glossterm><abbrev>XHTML</abbrev></glossterm>
+
+ <glossdef>
+ <para>Html as <link linkend="gloss_XML">XML</link> <link
+ xlink:href="http://www.w3.org/TR/xhtml11">standard</link>.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_XML">
+ <glossterm><abbrev
+ xlink:href="http://www.w3.org/XML">Xml</abbrev></glossterm>
+
+ <glossdef>
+ <para>The <link xlink:href="http://www.w3.org/XML">Extensible Markup
+ Language</link>.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_XmlSchema">
+ <glossterm>XML Schema</glossterm>
+
+ <glossdef>
+ <para>A W3C standard to define grammars for XML documents. Rich set
+ of features with respect to data modeling.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_XPath">
+ <glossterm><acronym xlink:href="http://www.w3.org/TR/xpath"
+ xml:id="abbr_Xpath">XPath</acronym></glossterm>
+
+ <glossdef>
+ <para>XML Path Language</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_XSD">
+ <glossterm><abbrev
+ xlink:href="http://www.w3.org/Style/XSL">XSD</abbrev></glossterm>
+
+ <glossdef>
+ <para>XML Schema description Language</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="gloss_XSL">
+ <glossterm><abbrev xlink:href="http://www.w3.org/Style/XSL"
+ xml:id="abbr_Xsl">XSL</abbrev></glossterm>
+
+ <glossdef>
+ <para>Extensible Stylesheet Language</para>
+ </glossdef>
+ </glossentry>
+ </glossary>
+ </appendix>
- <xi:include href="glossary.xml" xpointer="element(/1)"/>
+ <xi:include href="../bibliography.xml" xpointer="element(/1)"/>
</book>
diff --git a/Doc/try.xml b/Doc/try.xml
new file mode 100755
index 0000000000000000000000000000000000000000..a0b2492357fc825aaf17e0066a12bb0a0a406c0a
--- /dev/null
+++ b/Doc/try.xml
@@ -0,0 +1,419 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<book version="5.0" xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns:m="http://www.w3.org/1998/Math/MathML"
+ xmlns:html="http://www.w3.org/1999/xhtml"
+ xmlns:db="http://docbook.org/ns/docbook">
+ <info>
+ <title xml:id="sda1"/>
+
+ <author>
+ <personname><firstname/><surname/></personname>
+
+ <affiliation>
+ <orgname/>
+ </affiliation>
+ </author>
+
+ <pubdate/>
+ </info>
+
+ <chapter xml:id="company">
+ <title>Data models</title>
+
+ <para>Wanted: A data model to represent entities and their
+ relationships</para>
+
+ <section xml:id="companyRepresent">
+ <title>Representing a company</title>
+
+ <para>Entities to be represented:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Employee</para>
+ </listitem>
+
+ <listitem>
+ <para>Departments</para>
+ </listitem>
+
+ <listitem>
+ <para>Projects</para>
+ </listitem>
+
+ <listitem>
+ <para>...</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Relationships:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Each employee is being assigned to exactly one
+ department</para>
+ </listitem>
+
+ <listitem>
+ <para>Each employee may participate in an arbitrary number of
+ projects. For each project an employee's number of weekly working
+ hours participation is being defined.</para>
+ </listitem>
+
+ <listitem>
+ <para>Each department may have a parent department</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>We start creating a database table representing
+ <code>Department</code> entities:</para>
+
+ <programlisting>CREATE TABLE Department(
+ id BIGINT PRIMARY KEY <co linkends="departmentTable-1"
+ xml:id="deptTableSurrogateKey"/>
+ ,name CHAR(20) NOT NULL UNIQUE <co linkends="departmentTable-2"
+ xml:id="deptTableBusinessKey"/>
+)</programlisting>
+
+ <calloutlist>
+ <callout arearefs="deptTableSurrogateKey" xml:id="departmentTable-1">
+ <para>The <code>Department</code> table's
+ <emphasis>surrogate</emphasis> key</para>
+ </callout>
+
+ <callout arearefs="deptTableBusinessKey" xml:id="departmentTable-2">
+ <para>The <code>Department</code> table's unique name, e.g.
+ <quote>Sales</quote>.</para>
+ </callout>
+ </calloutlist>
+
+ <para>Each <code>Employee</code> is being affiliated (see <coref
+ linkend="employeeAffiliation"/> below) with exactly one
+ <code>Department</code>. Its fax number is the only nullable
+ property.</para>
+
+ <programlisting>CREATE TABLE Employee (
+ id BIGINT PRIMARY KEY
+ ,number INTEGER NOT NULL UNIQUE
+ ,name CHAR(20) NOT NULL
+ ,surname CHAR(20) NOT NULL
+ ,department BIGINT NOT NULL REFERENCES Department <co
+ xml:id="employeeAffiliation"/>
+ ,telephone CHAR(4) NOT NULL
+ ,fax CHAR(4)
+);</programlisting>
+
+ <qandaset>
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>Explain the (<acronym linkend="gloss_Sql">SQL</acronym>)
+ technical difference between a <code>PRIMARY KEY</code> and a
+ UNIQUE <acronym linkend="gloss_SqlDdl">DDL</acronym> statement
+ with respect to data integrity constraints.</para>
+ </question>
+
+ <answer>
+ <para>A primary key attribute must not be <code>NULL</code> and
+ defines a unique set of attribute values within a given table. A
+ UNIQUE attribute allows <code>NULL</code> values and may thus be
+ complemented by a NOT NULL constraint to form a <link
+ linkend="glossCandidateKey">candidate key</link> for the sake of
+ allowing to identify <emphasis>all</emphasis> datasets of a
+ given table..</para>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>Explain the above notion of <emphasis>surrogate
+ key</emphasis>s, business keys and their roles for application
+ developers. Why should surrogate be preferred when defining
+ foreign key targets?</para>
+ </question>
+
+ <answer>
+ <para>A surrogate key is being defined as a technical means to
+ reference objects on database level by foreign keys in a
+ <quote>sound </quote> manner. Its values are not intended to be
+ visible to end users and should thus not appear in e.g. <abbrev
+ linkend="gloss_Gui">GUI</abbrev> components. This allows
+ surrogate keys to be implemented by immutable attributes.</para>
+
+ <para>On contrary business keys should not be used as reference
+ targets. This avoids transactional hassles being imposed by e.g.
+ <code>ON UPDATE CASCADE</code> and other transitive foreign key
+ attribute updates caused by changing business key values. The
+ following variant uses a business key as a foreign key
+ target:</para>
+
+ <programlisting>CREATE TABLE Department(
+ id BIGINT PRIMARY KEY
+ ,name CHAR(20) NOT NULL UNIQUE <co linkends="cascadeBusinessKey-1"
+ xml:id="employeeDepartmentBusiness"/>
+);
+
+CREATE TABLE Employee (
+ id BIGINT PRIMARY KEY
+ ,number INTEGER NOT NULL UNIQUE
+ ,name CHAR(20) NOT NULL
+ ,surname CHAR(20) NOT NULL
+ ,department CHAR(20) NOT NULL REFERENCES Department(name) <co
+ linkends="cascadeBusinessKey-2"
+ xml:id="employeeDepartmentCascade"/>
+ ,telephone CHAR(4) NOT NULL
+ ,fax CHAR(4)
+);</programlisting>
+
+ <calloutlist>
+ <callout arearefs="employeeDepartmentBusiness"
+ xml:id="cascadeBusinessKey-1">
+ <para>Defining a business key</para>
+ </callout>
+
+ <callout arearefs="employeeDepartmentCascade"
+ xml:id="cascadeBusinessKey-2">
+ <para>Referencing a business key</para>
+ </callout>
+ </calloutlist>
+
+ <para>If we update a <code>Department.name</code> attribute, all
+ <code>Employee</code> datasets referencing this department have
+ to be changed as well. Thus the intended change of a single
+ attribute possibly causes a whole bunch of transitive updates
+ adding to potential lock conflicts in a concurrent database
+ application .</para>
+
+ <para>If being intended though we should at least add a CASCADE
+ clause;</para>
+
+ <programlisting>CREATE TABLE Employee (
+...
+ ,department CHAR(20) NOT NULL REFERENCES Department(name)
+ <emphasis role="bold">ON UPDATE CASCADE</emphasis>
+...</programlisting>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+
+ <para>We now add projects <coref linkend="projectEntity"/> and employee
+ affiliations to projects <coref linkend="projectAffiliation"/>:</para>
+
+ <programlisting>CREATE TABLE Project ( <co xml:id="projectEntity"/>
+ id BIGINT PRIMARY KEY
+ ,number INTEGER NOT NULL UNIQUE
+ ,name CHAR(20) NOT NULL UNIQUE
+ ,status SMALLINT NOT NULL
+ ,CHECK (status IN (1,2,3,3)) -- planned, active, on hold, finished --
+);
+
+CREATE TABLE EmployeeProject ( <co xml:id="projectAffiliation"/>
+ employee BIGINT NOT NULL REFERENCES Employee
+ ,project BIGINT NOT NULL REFERENCES Project
+ ,PRIMARY KEY(employee, project)
+ ,weeklyHours INTEGER NOT NULL
+)</programlisting>
+
+ <qandaset>
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>The property <code>status</code> has been implemented as
+ type <code>SMALLINT</code>. Consider the following
+ alternative:</para>
+
+ <programlisting>CREATE TABLE Project (
+ id BIGINT PRIMARY KEY
+ ,number INTEGER NOT NULL UNIQUE
+ ,name CHAR(20) NOT NULL UNIQUE
+ ,<emphasis role="bold">status CHAR(10) NOT NULL</emphasis>
+ ,CHECK (<emphasis role="bold">status IN ('planned', 'active', 'onHold','finished')</emphasis>)
+);</programlisting>
+
+ <para>What are the pros and cons?</para>
+ </question>
+
+ <answer>
+ <glosslist>
+ <glossentry>
+ <glossterm>Advantage of CHAR(10) implementation</glossterm>
+
+ <glossdef>
+ <para>Data residing in a database can be easily retrieved
+ by <code>SELECT</code> statements without having
+ difficulties interpreting both <code>WHERE </code>clauses
+ and result sets:</para>
+
+ <programlisting>SELECT * FROM Project
+WHERE status = 'active'</programlisting>
+
+ <para>On contrary using the <code>SMALLINT</code>
+ implementation requires: </para>
+
+ <programlisting>SELECT * FROM Project
+WHERE status = 2 -- any clue about status definitions when lacking documentation? --</programlisting>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Advantage of <code>SMALLINT</code>
+ implementation</glossterm>
+
+ <glossdef>
+ <para>When building applications our <code>SMALLINT</code>
+ status field will best be mapped as an user defined
+ <code>enum</code>:</para>
+
+ <programlisting>public enum ProjectStatus {
+ planned
+ ,active
+ ,onHold
+ ,finished;
+}</programlisting>
+
+ <para>This allows for easily understandable switch
+ statements:</para>
+
+ <programlisting>ProjectStatus status;
+ ...
+switch (status) {
+ case planned:
+ ...
+ break;
+
+ case active:
+ ...
+ break;
+ default:
+ ...
+}
+...</programlisting>
+
+ <para>In fact starting from Java 1.7 the above
+ <code>switch</code> statement will work for
+ <classname>String</classname> objects as well:</para>
+
+ <programlisting>String status;
+ ...
+switch (status) {
+ case "planned":
+ ...
+ break;
+
+ case "active":
+ ...
+ break;
+ default:
+ ...
+}</programlisting>
+
+ <para>But despite being syntactic sugar the above code
+ actually implements an <code>if ... else if ...
+ else</code> block relying on
+ <methodname>String.equals()</methodname> rather than a
+ true integer based jump table:</para>
+
+ <programlisting>String status;
+ ...
+ if (status.equals("planned")) {
+ ...
+ } else if (status.equals("active")) {
+ } else {
+ ...
+ }
+}</programlisting>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
+ </section>
+
+ <section>
+ <title>A media store</title>
+
+ <para>The media store example has been chosen as a second main example
+ in addition to the company database. It will be developed by you in a
+ step by step manner thereby exploring lecture related features and
+ technological standards.</para>
+
+ <para>We have outlined a schema forming a building block for a company's
+ internal organization. You are now being expected to develop a data
+ model suitable to build a media store. After talking to potential
+ customers the following entities have been identified to be
+ required:</para>
+
+ <glosslist>
+ <glossentry>
+ <glossterm>Album</glossterm>
+
+ <glossdef>
+ <para>The basic building block to be sold. An album is being
+ composed of tracks. Each Album does have a name not necessarily
+ unique across your media store. Albums may be related to
+ performing artists.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Track</glossterm>
+
+ <glossdef>
+ <para>Each song belongs to exactly one Album. The smallest media
+ item having the following properties:</para>
+
+ <glosslist>
+ <glossentry>
+ <glossterm>name</glossterm>
+
+ <glossdef>
+ <para>A song's name is unique with respect to its
+ <quote>owning</quote> album.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>format</glossterm>
+
+ <glossdef>
+ <para>One of <code>mp3</code>, <code>flac</code> or
+ <code>mp4</code>.</para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Artist</glossterm>
+
+ <glossdef>
+ <para>An artist may participate in arbitrary albums. It shall be
+ possible to annotate an artist's <quote>lead</quote> role with
+ respect to an album he/she is being affiliated with.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>name, surname</para>
+ </listitem>
+
+ <listitem>
+ <para>sex</para>
+ </listitem>
+ </itemizedlist>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+ </section>
+ </chapter>
+
+ <xi:include href="glossary.xml" xpointer="element(/1)"/>
+</book>
diff --git a/Sda2/Makefile b/Sda2/Makefile
index ef6e90a934fab05981a562011e420cde12305252..97e94efa9cd4915b2b84cdff8dd8e52e0ca76b93 100644
--- a/Sda2/Makefile
+++ b/Sda2/Makefile
@@ -35,7 +35,7 @@ ${BUILDNAVI}/index.html ${BUILDNAVI}/printversion.pdf:${SCRIPTBASENAME}.xml
mkdir -p ${BUILDNAVI} ${BUILDNONAVI}
$(MAKE) jdoc
java -cp ${CP} de.hdm_stuttgart.mi.codeformat.Docbook2docbook ${SCRIPTBASENAME}
- saxon9he-xslt -xi -s:${SCRIPTBASENAME}.convert.xml -xsl:../ws/Docbook/Extensions/Xsl/docbook2docbook.xsl > ${SCRIPTBASENAME}.convert.answer.xml
+ saxon9he-xslt -s:${SCRIPTBASENAME}.convert.xml -xsl:../ws/Docbook/Extensions/Xsl/docbook2docbook.xsl > ${SCRIPTBASENAME}.convert.answer.xml
/usr/share/xmlmind/bin/xxetool convert -p suppress.navigation 1 -p eclipse.plugin.id $(PLUGINID) ${PPARAM} db5.toEclipseHelp ${SCRIPTBASENAME}.convert.answer.xml \
-u $(BUILDNONAVI)
mkdir -p Ref/Fig/Generate;rm -f Ref/Fig/Generate/*.tex;\
@@ -43,7 +43,7 @@ ${BUILDNAVI}/index.html ${BUILDNAVI}/printversion.pdf:${SCRIPTBASENAME}.xml
cd Ref/Fig;make all
/usr/share/xmlmind/bin/xxetool convert -p eclipse.plugin.id $(PLUGINID) ${PPARAM} db5.toEclipseHelp ${SCRIPTBASENAME}.convert.answer.xml -u $(BUILDNAVI)
perl -i -p -e '$$/=undef;s/\n[ \t]*<!DOCTYPE[^>]+\n[^>]*>$$//m' ${BUILDNAVI}/*.xml ${BUILDNONAVI}/*.xml
- saxon9he-xslt -xi -s:${SCRIPTBASENAME}.convert.answer.xml -xsl:../ws/Docbook/Extensions/Xsl/docbook2print.xsl > ${SCRIPTBASENAME}.convert.answer.print.xml
+ saxon9he-xslt -s:${SCRIPTBASENAME}.convert.answer.xml -xsl:../ws/Docbook/Extensions/Xsl/docbook2print.xsl > ${SCRIPTBASENAME}.convert.answer.print.xml
/usr/share/xmlmind/bin/xxetool convert db5.toPSFile ${SCRIPTBASENAME}.convert.answer.print.xml \
-s pdf -s "|pdf" -u $(BUILDNAVI)/printversion.pdf
rsync `find . -name \*.ogv` $(BUILDNAVI)/resources
diff --git a/Doc/Ref/Fig/billing.fig b/Sda2/Ref/Fig/billing.fig
similarity index 100%
rename from Doc/Ref/Fig/billing.fig
rename to Sda2/Ref/Fig/billing.fig
diff --git a/Doc/Ref/Fig/billingData.fig b/Sda2/Ref/Fig/billingData.fig
similarity index 100%
rename from Doc/Ref/Fig/billingData.fig
rename to Sda2/Ref/Fig/billingData.fig
diff --git a/Doc/Ref/Fig/billingMapJoined.fig b/Sda2/Ref/Fig/billingMapJoined.fig
similarity index 100%
rename from Doc/Ref/Fig/billingMapJoined.fig
rename to Sda2/Ref/Fig/billingMapJoined.fig
diff --git a/Doc/Ref/Fig/billingSql.fig b/Sda2/Ref/Fig/billingSql.fig
similarity index 100%
rename from Doc/Ref/Fig/billingSql.fig
rename to Sda2/Ref/Fig/billingSql.fig
diff --git a/Doc/Ref/Fig/classUser.fig b/Sda2/Ref/Fig/classUser.fig
similarity index 100%
rename from Doc/Ref/Fig/classUser.fig
rename to Sda2/Ref/Fig/classUser.fig
diff --git a/Doc/Ref/Fig/figureInherit.fig b/Sda2/Ref/Fig/figureInherit.fig
similarity index 100%
rename from Doc/Ref/Fig/figureInherit.fig
rename to Sda2/Ref/Fig/figureInherit.fig
diff --git a/Doc/Ref/Fig/mapUser.fig b/Sda2/Ref/Fig/mapUser.fig
similarity index 100%
rename from Doc/Ref/Fig/mapUser.fig
rename to Sda2/Ref/Fig/mapUser.fig
diff --git a/Doc/Ref/Fig/mapUserIntegrity.fig b/Sda2/Ref/Fig/mapUserIntegrity.fig
similarity index 100%
rename from Doc/Ref/Fig/mapUserIntegrity.fig
rename to Sda2/Ref/Fig/mapUserIntegrity.fig
diff --git a/Doc/Ref/Fig/mavenIntro.fig b/Sda2/Ref/Fig/mavenIntro.fig
similarity index 100%
rename from Doc/Ref/Fig/mavenIntro.fig
rename to Sda2/Ref/Fig/mavenIntro.fig
diff --git a/Doc/Ref/Fig/persistProvider.fig b/Sda2/Ref/Fig/persistProvider.fig
similarity index 100%
rename from Doc/Ref/Fig/persistProvider.fig
rename to Sda2/Ref/Fig/persistProvider.fig
diff --git a/Sda2/Ref/Fig/pre.tex b/Sda2/Ref/Fig/pre.tex
new file mode 100644
index 0000000000000000000000000000000000000000..73c377e7101dc46546d0a2d08dc6907fe7ae975e
--- /dev/null
+++ b/Sda2/Ref/Fig/pre.tex
@@ -0,0 +1,88 @@
+\documentclass{beamer}
+
+
+\mode<presentation>{
+ %\usetheme{Darmstadt} %Warsaw AnnArbor
+ %\setbeamercovered{transparent} % oder auch nicht
+ \setbeamercovered{invisible}
+
+\definecolor{hdmred}{rgb}{0.7137,0,0.1216}
+
+
+%war in den assozieerten color themes undefiniert
+\setbeamercolor{structure}{fg=black,bg=white}
+\setbeamercolor{normal text}{fg=black,bg=white}
+\setbeamercolor*{example text}{fg=green, bg=magenta}
+\setbeamercolor{alerted text}{red}
+
+\setbeamercolor*{palette primary}{fg=white,bg=hdmred!85!white}
+\setbeamercolor*{palette secondary}{fg=white,bg=hdmred}
+\setbeamercolor*{palette tertiary}{use=structure,fg=white,bg=structure.fg!50!black}
+\setbeamercolor*{palette quaternary}{fg=white,bg=black}
+
+\setbeamercolor*{palette sidebar primary}{fg=hdmred!10!black}
+\setbeamercolor*{palette sidebar quaternary}{fg=yellow!10!orange}
+\setbeamercolor*{palette sidebar secondary}{fg=white}
+\setbeamercolor*{palette sidebar tertiary}{fg=hdmred!50!black}
+\setbeamercolor{frametitle}{bg=hdmred!70!white}
+
+
+\setbeamercolor{block title example}{use=example text,fg=white,bg=example text.fg!75!black}
+\setbeamercolor{block title alerted}{use=alerted text,fg=white,bg=alerted text.fg!75!black}
+\setbeamercolor{block body alerted}{parent=normal text,use=block title alerted,bg=block title alerted.bg!10!bg}
+\setbeamercolor{block body example}{parent=normal text,use=block title example,bg=block title example.bg!10!bg}
+\setbeamercolor{block body}{parent=normal text,use=block title,bg=block title.bg!10!bg}
+\setbeamercolor{block title}{use=structure,fg=white,bg=structure.fg!75!black}
+
+\setbeamercolor*{palette sidebar primary}{use=structure,fg=structure.fg!10}
+\setbeamercolor*{palette sidebar quaternary}{fg=white}
+\setbeamercolor*{palette sidebar secondary}{fg=white}
+\setbeamercolor*{palette sidebar tertiary}{use=structure,fg=structure.fg!50}
+\setbeamercolor*{separation line}{}
+\setbeamercolor*{sidebar}{use=structure,bg=structure.fg}
+\setbeamercolor{titlelike}{parent=palette primary}
+\setbeamercolor*{fine separation line}{}
+\setbeamercolor{frametitle right}{use=frametitle}
+
+}
+\usepackage{svn-multi}
+\usepackage{xmpmulti}
+\usepackage{pifont}
+\usepackage{listings}
+%\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+%\usepackage{textcomp}
+%\usepackage{times}
+
+\hypersetup{colorlinks=true,linkcolor=blue,anchorcolor=blue,citecolor=blue,filecolor=blue,menucolor=blue,runcolor=blue,urlcolor=blue}
+
+\newenvironment{mycenterframe}[2][c]{%
+\begin{frame}[#1]{#2}%
+% \begin{center}%
+}{%
+%\end{center}%
+\end{frame}%
+}
+
+\newcommand{\multifigure}[1]{%
+\multiinclude[<+->][format={pdf},graphics={width=\textwidth}]%
+{#1}%
+}
+
+\definecolor{xmlOpenTag}{rgb}{1,.3,0.3}
+\definecolor{xmlCloseTag}{rgb}{.8,.5,.5}
+\definecolor{xmlAttributeTag}{rgb}{0,1,0}
+
+\lstset{emphstyle=\color{xmlOpenTag}, emphstyle={[2]\color{xmlAttributeTag}}}
+
+\lstdefinelanguage{xmlwellformed}{morecomment=[s][\color{xmlOpenTag}]{<}{>},morecomment=[s][\color{xmlCloseTag}]{</}{>},keywordstyle=\color{red}}
+
+
+\newcounter{tstep}
+\stepcounter{tstep}
+\newcommand{\myexercise}[1]{%
+Exercise \arabic{tstep}\stepcounter{tstep}: #1}
+
+
+\begin{document}
+
diff --git a/Doc/Ref/Fig/transitiveDep.fig b/Sda2/Ref/Fig/transitiveDep.fig
similarity index 100%
rename from Doc/Ref/Fig/transitiveDep.fig
rename to Sda2/Ref/Fig/transitiveDep.fig
diff --git a/Doc/Ref/Screen/CreateMaven/1.png b/Sda2/Ref/Screen/CreateMaven/1.png
similarity index 100%
rename from Doc/Ref/Screen/CreateMaven/1.png
rename to Sda2/Ref/Screen/CreateMaven/1.png
diff --git a/Doc/Ref/Screen/CreateMaven/2.png b/Sda2/Ref/Screen/CreateMaven/2.png
similarity index 100%
rename from Doc/Ref/Screen/CreateMaven/2.png
rename to Sda2/Ref/Screen/CreateMaven/2.png
diff --git a/Doc/Ref/Screen/CreateMaven/3.png b/Sda2/Ref/Screen/CreateMaven/3.png
similarity index 100%
rename from Doc/Ref/Screen/CreateMaven/3.png
rename to Sda2/Ref/Screen/CreateMaven/3.png
diff --git a/Doc/Ref/Screen/CreateMaven/4.png b/Sda2/Ref/Screen/CreateMaven/4.png
similarity index 100%
rename from Doc/Ref/Screen/CreateMaven/4.png
rename to Sda2/Ref/Screen/CreateMaven/4.png
diff --git a/Doc/Ref/Screen/CreateMaven/5.png b/Sda2/Ref/Screen/CreateMaven/5.png
similarity index 100%
rename from Doc/Ref/Screen/CreateMaven/5.png
rename to Sda2/Ref/Screen/CreateMaven/5.png
diff --git a/Doc/Ref/Screen/CreateMaven/6.png b/Sda2/Ref/Screen/CreateMaven/6.png
similarity index 100%
rename from Doc/Ref/Screen/CreateMaven/6.png
rename to Sda2/Ref/Screen/CreateMaven/6.png
diff --git a/Doc/Ref/Screen/CreateMaven/mysql1.png b/Sda2/Ref/Screen/CreateMaven/mysql1.png
similarity index 100%
rename from Doc/Ref/Screen/CreateMaven/mysql1.png
rename to Sda2/Ref/Screen/CreateMaven/mysql1.png
diff --git a/Doc/Ref/Screen/CreateMaven/mysql2.png b/Sda2/Ref/Screen/CreateMaven/mysql2.png
similarity index 100%
rename from Doc/Ref/Screen/CreateMaven/mysql2.png
rename to Sda2/Ref/Screen/CreateMaven/mysql2.png
diff --git a/Doc/Ref/Screen/CreateMaven/mysql3.png b/Sda2/Ref/Screen/CreateMaven/mysql3.png
similarity index 100%
rename from Doc/Ref/Screen/CreateMaven/mysql3.png
rename to Sda2/Ref/Screen/CreateMaven/mysql3.png
diff --git a/Doc/Ref/Screen/CreateMaven/mysql4.png b/Sda2/Ref/Screen/CreateMaven/mysql4.png
similarity index 100%
rename from Doc/Ref/Screen/CreateMaven/mysql4.png
rename to Sda2/Ref/Screen/CreateMaven/mysql4.png
diff --git a/Doc/Ref/Screen/CreateMaven/mysql5.png b/Sda2/Ref/Screen/CreateMaven/mysql5.png
similarity index 100%
rename from Doc/Ref/Screen/CreateMaven/mysql5.png
rename to Sda2/Ref/Screen/CreateMaven/mysql5.png
diff --git a/Sda2/Ref/Fig/ldapSampleUsers.png b/Sda2/Ref/Screen/ldapSampleUsers.png
similarity index 100%
rename from Sda2/Ref/Fig/ldapSampleUsers.png
rename to Sda2/Ref/Screen/ldapSampleUsers.png
diff --git a/Sda2/sda2.xml b/Sda2/sda2.xml
index f3c5f685b478286f92de4e87ef3102c9e0a6cf7f..e82eaf22bc0f572f6daaae0c9f684bb114f74f80 100644
--- a/Sda2/sda2.xml
+++ b/Sda2/sda2.xml
@@ -1,15 +1,33 @@
<?xml version="1.0" encoding="UTF-8"?>
-<part version="5.0" xmlns="http://docbook.org/ns/docbook"
+<book version="5.0" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook">
+ <info>
<title>Structured data and applications 2</title>
+ <author>
+ <personname><firstname>Martin</firstname>
+ <surname>Goik</surname></personname>
+
+ <affiliation>
+ <orgname>http://medieninformatik.hdm-stuttgart.de</orgname>
+ </affiliation>
+ </author>
+
+ <legalnotice>
+ <para>Source code available at <uri
+ xlink:href="https://version.mi.hdm-stuttgart.de/git/GoikLectures">https://version.mi.hdm-stuttgart.de/git/GoikLectures</uri></para>
+ </legalnotice>
+ </info>
+
+
+
<chapter xml:id="ldap">
- <title><xi:include href="../acronyms.xml" xpointer="glo_LDAP"/></title>
+ <title><xi:include href="../acronyms.xml" xpointer="element(glo_LDAP)"/></title>
<section xml:id="ldapIntro">
<title>Getting started with <xi:include href="../acronyms.xml"
@@ -209,7 +227,7 @@ uidNumber: 1023
<screenshot>
<mediaobject>
<imageobject>
- <imagedata fileref="Ref/Fig/ldapSampleUsers.png"/>
+ <imagedata fileref="Ref/Screen/ldapSampleUsers.png"/>
</imageobject>
</mediaobject>
</screenshot>
@@ -893,9 +911,7 @@ public class User {
It is thus desired to automate these tasks while still using
<trademark
xlink:href="http://www.oracle.com/technetwork/java/javase/jdbc">JDBC</trademark>
- as a low level transport layer. This is being shown in <xref
- linkend="jdbcFourTier"/>. That figure already mentions Hibernate as a
- possible persistence service provider.</para>
+ for the low level transport layer.</para>
<para>The following sections start with a single class
<classname>hibintro.v1.model.User</classname>:</para>
@@ -3307,4 +3323,4 @@ public class PersistUser {
</chapter>
<xi:include href="../bibliography.xml" xpointer="element(/1)"/>
-</part>
+</book>