What You Need to Use This Book

In this book I assume that you have certain prerequisite knowledge. You also need to have several software tools, source code, and some XML files in order to make full use of this book. This section tells you what you need to already know as well as what those additional resources are, where they are, and how to get them.

What You Should Already Know

All readers should already have a basic understanding of XML. Familiarity with XML 1.0 DTDs may be helpful but is not absolutely necessary. If you aren't already familiar with XML, there are several good introductions to the subject. On my Web site I give a few recommendations. If you don't mind doing a bit of somewhat technical reading, you can also review the XML Recommendation at the W3C Web site, http://www.w3.org.

End users should be comfortable with the general concept of file format conversion, that is, taking a file that exists in one format and converting it to another file in a different format. Some rudimentary programming experience will be helpful if you plan to develop XSLT stylesheets or write scripts that use the utilities developed in the book.

Application developers should be familiar with either Java or C++ and their respective basic library functions. For those interested in the C++ implementation, prior experience with Microsoft's Component Object Model ( COM ) is helpful but not required.

Web Site and Contact Information

The Web site for this book has nearly everything you need (or pointers to the information you want). There you will find:

• Executable versions of the utilities in both Java jar file format and Win32 binary format

• Full source code in C++ and Java

• Example schemas and XSLT stylesheets

• Sample input and output files

• Other sample and support files

• Updated links (current at the time of final editing)

The URL for the book's Web site is: http://awprofessional.com/titles/032115940. You can find additional examples and frequently updated references to other good books at http://www.rawlinsecconsulting.com/booksupplement.

Please feel free to contact me with any questions, comments, errata, bug reports , and so on via e-mail at [e-mail].

General Software

If the only XML syntax work you expect to do is to code parameter files for running the utilities in this book, probably all you need is a good text or programming editor such as emacs. For Windows users, Microsoft's XML Notepad (Beta version 1.5, May 3, 1999) is available as a free download. I would give you a URL for it, but Microsoft has an annoying tendency to move things around on its site. So, I won't go any farther than pointing you to http://www.microsoft.com and suggesting that you search for "XML Notepad". XML Notepad should ensure that you create a well- formed XML document , that is, one that complies with W3C's XML Recommendation in certain key aspects. ( Note : When used with Internet Explorer version 4.01 and earlier, XML Notepad converted all characters to uppercase. Very few people are likely to have this problem now since most people run later versions of Internet Explorer. If you run into this problem, you'll need to upgrade Internet Explorer to version 5.0 or later.) The Windows Notepad, emacs, or vi will probably do just fine for very light use.

However, if you're going to do much with XSLT or schema design, spending a couple hundred dollars for a good XML tool will probably be a good investment. I list my favorites below.

• XMLSPY by Altova GmbH : All you need is the Integrated Development Environment ( IDE ). It helps you design schemas in various schema syntaxes, create instance documents, validate both, and develop and test XSLT stylesheets. XMLSPY runs only on Win32 platforms (Windows NT, 2000, XP, 98, ME). A free evaluation download is available from http://www.xmlspy.com. I used version 4.3 for this book.

• TurboXML (formerly XML Authority) by TIBCO : Similar in functionality to XMLSPY, as a Java-based application it runs on many platforms including Windows, Linux, Solaris, HP-UX, and other UNIX platforms. A free evaluation download is available from http://www.tibco.com.

Other tools with similar functionality also exist (for example, eXcelon's Stylus Studio). However, I've not tested or extensively reviewed any of them, so I don't have much to say about them. I have heard of some free, open source tools, but they were still in development when I wrote this book. If I find any good ones I'll post links on my Web site.

If you would like a different way to view an XML document (but not edit it), Internet Explorer version 5.5 is handy. It allows you to expand or contract elements with children so that you can view the complete document tree or just focus on certain branches.

This completes my recommendations for general purpose software. The developer recommendations for the Java and C++ environments are discussed next , but I must raise an important cautionary flag first.

CAUTION Don't Change Horses in the Middle of a Stream!

I feel a bit of a nag when reminding people to pay attention to the basics. But it seems that we often forget them or make exceptions when dealing with new technology. After you have downloaded the latest tools and APIs, don't update them until you've finished your project! With updates seeming to come every month or two in the XML world, there is a great temptation to apply them just as soon as they come out. However, I've had too many experiences on other projects over the years of starting to work in the morning and discovering that code that worked last night doesn't work today, even though I didn't change anything. After hours of debugging I found that new libraries had been installed and the problem wasn't my code at all. Save the updates of the APIs until your code is stable and thoroughly tested. Then download the latest, rebuild, and retest.

Java Software

The Java code in this book was developed using the libraries listed below. It may compile and run under later versions, but it hasn't been tested that way. Due to changes in support for the W3C XML Schema language, the versions listed are the minimum that I recommend.

• Java 2 Standard Edition Version 1.3.1_03 (http://java.sun.com/j2se/1.3) : To compile the code you'll need the full software development kit ( SDK ). If you're only going to download and run the book utilities, you'll just need the Java Runtime Environment ( JRE ).

• Java XML Pack, Spring 02 (http://java.sun.com/xml/downloads) : If you're only going to run the Java utilities, you don't need the full kit. However, you will need the Java jar archive files from the kit.

• Xerces2 Java Parser 2.0.1 (http://xml.apache.org) : This software is required for all Java XML development and runtime presented in this book. For the most part I use standard Java API for XML Processing ( JAXP ) features, but the routines to serialize a DOM document use specific Xerces2 routines. (Although the precise name of the parser is "Xerces2," I'll observe the common custom of referring to it as just "Xerces" unless I mean to refer specifically to this version of Xerces.)

• Xalan-Java 2.3.1 (http://xml.apache.org) : This software is required for Java-based XSLT transformations. Other Java-based XSLT implementations may work but have not been tested.

Refer to my Web site for specific instructions about how to install the jar files for your particular version of Java.

Note : The book's Java code was developed using version 1.2 of Sun's JAXP. The Java XML Pack has an implementation of the JAXP 1.2 specification that uses Xerces2 as the default parser. (Xerces2 conforms to the JAXP 1.1 specification.) To be sure that you get the latest bug fixes I recommend downloading the most recent version of Xerces2 from the Apache site.

The Java code was developed and tested with Borland's JBuilder Version 6 on Windows NT Workstation version 4. It was also tested on Windows 98.

C++ Software

As previously mentioned, the C++ implementation presented here is based on Microsoft's MSXML library, listed below. The code was developed and tested with MSXML version 4.0. This is the minimum version required. The code may work with later versions but has not been tested. Changes will be required to make it run with different DOM implementations.

• MSXML 4.0 Microsoft XML Core Services (http://www.microsoft.com/downloads) : This is required for both development and runtime. MSXML runs as a COM service.

• MSXSL.EXE Command Line Transformation Utility (no version number, last updated 9/10/2001; http://msdn.microsoft.com/downloads). This is required for runtime XSLT transformations from command line.

The C++ code in this book was developed under Visual C++ 6.0 and tested on Windows NT Workstation 4.0 and Windows 98. (No, you don't need .NET!)

MXSML, Win32, and COM as Legacy Technologies?

Incredible but true! When I conceived this project, MSXML 4.0 (with full support for the final W3C XML Schema Recommendation) was still pretty new. However, before I really got going, Microsoft came out with .NET. Not only does .NET offer a different DOM API than MSXML (though reportedly it still uses MSXML under the hood), it is a completely new and different framework. XML is only a small piece.

When this happened I became a bit concerned that working with the DOM via MSXML's COM interfaces would be dealing with obsolete technology. However, on reflection I decided that it fit very well with the thrust of the book. I just didn't expect to run into legacy applications and technology in this particular area! Considering the paradigm shift that .NET imposes and the impact of migrating from Visual Studio 6.0 to Visual Studio .NET, I think there may be an audience for this book for some time to come.

Bottom line: This book gives you a way to do XML from Win32 without having to migrate to .NET.

Alternatives to MSXML?

While struggling to get the COM- related stuff working and fully debugged , I began to question my decision to use MSXML instead of some other DOM implementation that worked with C++. But, given the realities of C++ applications on Win32, I still think that MSXML is the best choice for this book. Many development shops are all Microsoft and wouldn't look at APIs from any other source. MSXML is fairly mature, installs easily, and is widely considered to offer some of the best support for W3C XML Schema. However, if you are comfortable with the licensing terms of the Apache C++ Xerces implementation, you can save yourself a lot of the COM headaches by using it instead of MSXML.