XMLC Tutorial: Introduction

Contents

  1. What XMLC Does
  2. How to Run XMLC
  3. Using XMLC

What XMLC Does

XMLC is a Java-based compiler that takes a document written in the Hypertext Markup Language (HTML) or the eXtensible Markup Language (XML) and creates Java classes that will faithfully recreate the document. The resulting Java classes can be used to insert dynamic content into the document framework at run time. XMLC, therefore, is a wonderful way to create dynamic HTML or XML documents from Java.

Other techniques exist to create dynamic HTML content such as Server Side Includes (SSI), Common Gateway Interface (CGI) scripts, Active Server Pages (ASP), Java Server Pages (JSP), etc. XMLC has several advantages over these other methods. These include:

With XMLC, a document is compiled into a Java class. This compilation is done before the application is run. A dynamic document can be created faster by this method than by techniques that dynamically create an entire document at run time.

It appears that the future will see an increasing use of XML documents. XMLC is, by its very nature, XML ready. If you wish to use XML in your projects or if you wish to migrate an HTML-based interface to XML, XMLC can help.

XMLC creates Java classes. Java is becoming a very common language for the creation of Web-based applications. CGI is currently the most commonly used method for this, but Java servlets are much more efficient than CGI scripts. This means that Java servlets are faster and also use less system resources. XMLC works well with Enhydra since Enhydra is based on Java servlets.

XMLC makes use of the World Wide Web Consortium (W3C) Document Object Model (DOM) standard. Use of standards ensures that XMLC will not soon become obsolete.

The best single advantage of XMLC is the ability to completely separate HTML templates (the pages that an artist creates) from Java code (the controlling logic that programmers create). XMLC allows artists to generate and edit HTML from design tools that support the HTML 4.0 standard.

This tutorial covers XMLC version 1.2, which is the version shipped in Enhydra 3.0.1. A standalone version of XMLC is also available. This version uses the Xerces (http://xml.apache.org/xerces-j/index.html) DOM implementation.

This tutorial also shows the Java code generated by XMLC for most examples. It should be noted that it is not necessary to keep or use directly the generated source code. In fact, XMLC by default just generates a compiled Java class file to hide this level of complexity from you. If you prefer to see and understand the "guts" of what XMLC does, you can look at the Java source code listed in the examples. If it scares you to see unnecessary source code, just ignore it.

How to Run XMLC

All of the examples in this tutorial will assume that you have access to a command line running the Bash shell. Since Bash is available on a wide variety of platforms, this should not be difficult. In fact, you will require Bash to be able to use Enhydra as it is shipped as of this writing. The Bash prompt used in the examples is a dollar sign ('$'), which is the minimal default prompt for users other than the superuser.

XMLC is included in the Enhydra application server distribution in versions 2.1b2 or later. You can get Enhydra and XMLC from http://www.enhydra.org/. XMLC is also available as a standalone application.

A common place to install Enhydra is /usr/local/enhydra. We will refer to this directory as $ENHYDRA in examples. If you install Enhydra elsewhere, substitute that location anywhere you see $ENHYDRA. Using this notation, XMLC can be run from a Bash shell script located in $ENHYDRA/bin/xmlc. If this script is not executable, you will need to either make it executable (with the chmod command) or run it directly from Bash (as 'bash $ENHYDRA/bin/xmlc').

If you like, you can run the examples exactly as shown by setting an environment variable to the base Enhydra directory like this:


$ export ENHYDRA=/usr/local/enhydra

The next thing to do is to set the Java CLASSPATH variable. In order to run XMLC, you will need to set your CLASSPATH variable so that the Java interpreter can locate the Enhydra classes (including the XMLC Java classes) and the Swing classes. XMLC uses classes from both the Enhydra and Swing trees, so they both must be installed before you can use XMLC. A typical CLASSPATH, which includes any classes in the current directory and the locations of Enhydra classes could be set like this:


$ export CLASSPATH .:/mnt/tools/enhydra/enhydra3.0.1/lib/enhydra.jar

If we look at the $ENHYDRA/bin/xmlc shell script, we will see that it simply starts a Java interpreter and passes it the XMLC Java class. (Note that in the enhydra-src3.0.1 dirstibution, the script will be in $ENHYDRA/output/xmlc1.2/bin/xmlc.) The script sets a number of variables, the executes:


exec ${JAVA} ${JAVAC_ARG} ${MX_ARG} org.enhydra.xml.xmlc.commands.xmlc.XMLC "$@"

XMLC is itself written in Java! This is the first clue to how XMLC works. As we shall see later in this tutorial, XMLC makes good use of the Java DOM classes produced by the W3C. Since XMLC is itself Java code, we could use XMLC as part of another Java program. Although this tutorial does not (yet) address this, the potential is a powerful part of XMLC.

If we run the $ENHYDRA/bin/xmlc shell script without parameters, we see that it reports a usage message and exits:


$ $ENHYDRA/bin/xmlc
wrong # args: xmlc [options] [optfile.xmlc ...] src.ext
$

If you run the $ENHYDRA/bin/xmlc shell script with an invalid option (e.g. "-help"), it will return a useful list of valid options. This tutorial covers some of the more commonly used options.

Using XMLC

To generate a Java class from XMLC, you simply give the $ENHYDRA/bin/xmlc shell script the name of an HTML or XML file on the command line:


$ $ENHYDRA/bin/xmlc hello.html

The command shown would generate a Java class file called "hello.class" in the same directory. Note that this is compiled Java bytecode; you would not be able to read it. If you wanted to see the Java source code that was created, you could specify the "-keep" option on the xmlc command line:


$ $ENHYDRA/bin/xmlc -keep hello.html

This option would generate both the "hello.class" bytecode and another file called "hello.java". The latter is the Java source code. We will discuss the generated code in much more detail in later chapters.

Generally speaking, Java classes generated by XMLC can be used to perform any of the following tasks:

The following tutorial chapters will show how each of these is accomplished. Specifically, the first example will show how to replace text within HTML tags that are identified with an id attribute or that is within a <SPAN> tag. The second chapter will show how to deal with <FORM> elements. The third chapter will discuss the manipulation of URLs. The fourth chapter will show how to manage the grouping of elements and the last chapter will show how to deal with less common occurances.