Altova XMLSpy® is a well-known XML editor and IDE that, besides many other things, includes a graphical XML Schema editor representing some XML schema components (mostly those defining complex content models) in the form of graphical diagrams, which can be edited.

It should be noted that probably all modern XML editors currently support such a feature. However, the content model diagrams generated by XMLSpy look particularly elaborated and neat.

Along with the XML schema editor, XMLSpy includes an XML schema documentation generator able to generate rather poor (basically single-file) documentation, however, with all those beautiful diagrams included (along with the diagram hyperlinks).

Another crucial feature included in XMLSpy (and lacking in other XML editors) is an open Java API (provided by XMLSpyInterface.jar found in the XMLSpy installation directory). It allows any Java application to call from itself some XMLSpy functionality, essentially turning XMLSpy into a kind of DLL (Dynamically Linked Library).

Those two features (the open Java API and XMLSpy's own XSD doc-generator) made possible to develop an integration of DocFlex/XML with XMLSpy, which is able to automatically insert the graphic diagrams generated by XMLSpy into the XML schema documentation generated by DocFlex/XML XSDDoc (with the full support of diagram hyperlinks). This, essentially, creates a new fantastic XML Schema Documentation Generator with diagramming capabilities no other single product is offering now!

Click on the following screenshot to see a sample documentation generated with it:

Key Features

Supported XMLSpy versions: 2004-2009
Possibility to control XMLSpy from DocFlex/XML templates:
- Launching XMLSpy as a parallel system application
- Using it as a dynamically linked library to perform certain operations
- Quitting XMLSpy, when it is no longer needed (without stopping the template application)
Forcing XMLSpy to open specified XML schemas and to generate the content model diagrams for all their components (along with the hypertext image maps).
Associating the diagrams (and image maps hyperlinks) generated by XMLSpy with the DSM elements representing the XML schema components in templates and making them available (via Image Control) to be inserted in the output documentation generated by DocFlex/XML.
Automatic insertion of XSD component diagrams produced by XMLSpy into the XML schema documentation generated by DocFlex/XML XSDDoc. The diagrams can be generated in the following formats:
- PNG
- EMF (only since XMLSpy 2009)
which are fully supported both in HTML and RTF output.
Full support of diagram hyperlinks (in HTML output).
Possibility to run the unified DocFlex/XML+XMLSpy template-driven documentation generators from both Apache Ant and Maven.

Technical Requirements

Altova XMLSpy®, versions 2004-2009, “Professional” or “Enterprise” edition.
Basically, what is needed for the integration to work is that your XMLSpy edition supports:
1. XMLSpy Java interface (XMLSpyInterface.jar)
2. “XML Schema documentation” feature
(For instance, the “Standard” edition has no such things.)
Java version 6 or 5.0 (JDK or JRE) installed on your system. (Java 6 is better as it works faster).
A computer with at least 1 GB RAM (2 GB is better!)

How Integration Works

This is not an XMLSpy plugin. That would be actually impossible because XMLSpy itself is not based on Java. Rather, the integration allows DocFlex/XML to launch an instance of XMLSpy as a separate parallel process and call some its functionality, essentially turning XMLSpy into a DLL (Dynamically Linked Library).

Such usage in fact was supported by Altova itself, who includes in XMLSpy the 'XMLSpyInterface.jar' Java library, which provides all necessary interfaces.

The integration exposes that functionality to templates via several FlexQuery functions, which allow a template to:

Launch XMLSpy (start a session to communicate with it).
Process with XMLSpy a specified XSD file. That is force XMLSpy to open that schema and generate diagrams (along with imagemaps) for its components to be further processed by the integration.
Shut down the XMLSpy.

(You can find all those functions via Template Designer main menu: Help | Assistant | Functions by Category | XMLSpy Integration Functions.)

But having XMLSpy generate the diagrams is not enough. Further, the diagrams need to be inserted into the output generated with templates. Here is how it is done.

DocFlex/XML templates operate with abstract data entities called DSM elements (and DSM attributes), on which everything contained in XML files (as well as XML files themselves; see #DOCUMENTS) is mapped. That mapping is maintained by a special module called XML DSM driver. Each DSM element may have a certain graphic representation called element image, which is provided by a special extension of the DSM driver called Element Image Provider. Element images can be easily operated in templates using Image Controls.

Once the diagrams have been generated by XMLSpy, the integration associates them (as well as imagemap hyperlinks) with the DSM elements representing corresponding XML schema components. Further, a special Element Image Provider implemented within the integration treats each diagram as an element image of the DSM element associated with the XML schema components depicted on that diagram. In that way, the diagrams become accessible via Image Controls in templates, which makes possible to easily program their insertion in the output generated by DocFlex/XML.

Since XMLSpy Integration is heavily connected with the DocFlex/XML core, all Java classes implementing it are currently included in the general DocFlex/XML Java library: docflex-xml.jar (or docflex-xml-re.jar). However, in order to use it, the integration needs to be installed separately and requires separate licensing.

2. Installation

To be able to run XMLSpy with DocFlex/XML generator (and call it from within templates), basically, you need to specify only three additional settings:

The location of XMLSpyInterface.jar
This file, supplied by Altova itself, provides all Java interfaces to run XMLSpy from a Java application. It must be found in your XMLSpy installation directory, e.g.:
C:\Program Files\Altova\XMLSpy2009\XMLSpyInterface.jar
The location of XMLSpyInterface.jar should be specified on the DocFlex/XML Java class path, e.g.:

-cp "C:\Program Files\Altova\XMLSpy2009\XMLSpyInterface.jar";lib\xml-apis.jar;lib\xercesImpl.jar;lib\resolver.jar;lib\docflex-xml.jar

Notice that it is enclosed in double quotes! This is needed because 'Program Files' contains a space. Without quotes, such a classpath will be broken by the space and interpreted as two separate command line arguments.
XMLSpy Integration main class
It should be specified on the Java command line (that runs generator or template designer) using -M option as the following:
-m:IMAGE_PROVIDER_CLASS=com.docflex.xml.xmlspy.SpyKit
XMLSpy version
This should be also specified with -M option on the command line, e.g.:
-m:XMLSPY_VERSION=2009

License File

Besides the settings described above, the XMLSpy Integration requires a separate license, which you should receive by e-mail. The license may come as a single 'docflex-xml-xmlspy.license' file or it may be included in a combined 'docflex-xml.license' file (along with other licenses). Either of those files should be saved in the 'lib' directory of your DocFlex/XML SDK or DocFlex/XML RE installation, where the license is searched by default (near 'docflex-xml.jar' or 'docflex-xml-re.jar' file).

It is also possible to specify any other location of your license file directly on the generator or template designer command line using -license option.

Windows BAT Example

Let's suppose, you want to generate a framed HTML documentation using XSDDoc | Templates | FramedDoc.tpl template by the XML schema located at the URL http://www.w3.org/2001/XMLSchema.xsd.

Here is a simple Windows BAT command file that would launch such a generation.

xsddoc.bat

`set`	`DFH=C:\docflex-xml`
`set`	`CP="C:\Program Files\Altova\XMLSpy2009\XMLSpyInterface.jar";%DFH%\lib\xml-apis.jar;%DFH%\lib\xercesImpl.jar;%DFH%\lib\resolver.jar;%DFH%\lib\docflex-xml.jar`

`java`	`-Xmx512m -cp %CP% com.docflex.xml.Generator -m:IMAGE_PROVIDER_CLASS=com.docflex.xml.xmlspy.SpyKit -m:XMLSPY_VERSION=2009 -template %DFH%\templates\XSDDoc\FramedDoc.tpl -format HTML -d %DFH%\out -nodialog -launchviewer=false http://www.w3.org/2001/XMLSchema.xsd`

3. Running with Apache Ant

You can easily integrate DocFlex/XML + XMLSpy with the Apache Ant automated build system.

As an example, here is an ANT build.xml file doing the same as the Windows BAT file described above.

build.xml

<?xml version="1.0"?>

</java>

</target>

</project>

To run that build.xml file, you can use a Windows BAT command file specified like the following:

set ANT_HOME=C:\apache-ant
set PATH=%ANT_HOME%\bin;%PATH%
set JAVA_HOME=C:\jre1.6
call %ANT_HOME%\bin\ant.bat xsddoc

(Note that it should be started from the directory containing the Ant build.xml file!)

4. Running with Apache Maven

How to run DocFlex/XML with Maven is basically explained on the page: DocFlex/XML | Integrations | Apache Maven. Here are a few updates concerning XMLSpy Integration, in particular:

How to install DocFlex/XML Maven 2 Plugin so as to accommodate XMLSpy.
An example project POM file that shows how to run the unified DocFlex/XML XSDDoc+XMLSpy XML schema documentation generator from Maven.

Installing Maven Plugin

If you want to run DocFlex/XML + XMLSpy from Maven, the DocFlex/XML Maven 2 Plugin should be installed (or reinstalled) a bit different than described in DocFlex/XML | Integrations | Apache Maven | Apache Maven 2 Plugin.

Please follow these steps:

Edit maven/plugin/pom.xml as follows.

Specify the absolute pathname of docflex-xml.jar (or docflex-xml-re.jar) according to your DocFlex/XML installation in the following lines:

<dependency>
  <groupId>docflex</groupId>
  <artifactId>docflex-xml</artifactId>
  <version>1.8.0</version>
  <scope>system</scope>
  <systemPath>C:\docflex-xml-1.8.0\lib\docflex-xml.jar</systemPath>
</dependency>

Uncomment these lines and specify the absolute location of the XMLSpy Java Interface Library and version:

<dependency>
  <groupId>xmlspy</groupId>
  <artifactId>XMLSpyInterface</artifactId>
  <version>2009</version>
  <scope>system</scope>
  <systemPath>C:\Program Files\Altova\XMLSpy2009\XMLSpyInterface.jar</systemPath>
</dependency>

Edit maven/plugin/install.bat to specify the correct locations of your JDK/JRE and Maven installations.
Run this command file.
If everything is correct, the DocFlex/XML Maven 2 Plugin will be compiled and installed.

Project POM Example

This example shows how to configure the DocFlex/XML Maven 2 Plugin in a project POM file to generate a framed HTML XML schema documentation by the XML schema located at http://www.w3.org/2001/XMLSchema.xsd using DocFlex/XML | XSDDoc | FramedDoc.tpl + XMLSpy Integration, so that the result doc would appear on the “Project Reports” page of a Maven-generated project site.

pom.xml

...

<groupId>docflex</groupId>

<artifactId>docflex-xml-maven-plugin</artifactId>

<param>-m:IMAGE_PROVIDER_CLASS=com.docflex.xml.xmlspy.SpyKit</param>

<param>-m:XMLSPY_VERSION=2009</param>

<param>-template</param>

<param>C:\docflex-xml\templates\XSDDoc\FramedDoc.tpl</param>

<param>-p:docTitle</param>

<param>XML Schema for XML Schemas</param>

<param>-format</param>

<param>-nodialog</param>

<param>-quiet</param>

<param>http://www.w3.org/2001/XMLSchema.xsd</param>

</generatorParams>

<outputFolder>xsddoc</outputFolder>

<name>XSDDoc</name>

<description>XML Schema for XML Schemas</description>

</configuration>

</plugin>

</plugins>

</reporting>

...

</project>

To run that pom.xml file, you can use a Windows BAT command file specified like the following:

set JAVA_HOME=C:\jdk1.6
set M2_HOME=C:\apache-maven-2.0.9
set MAVEN_OPTS=-Xms256m -Xmx512m
call %M2_HOME%\bin\mvn.bat site:site

(Note that it should be started from the directory containing the Maven pom.xml file!)

5. Specifics of XMLSpy Versions

We have tested all XMLSpy versions from 2004 to 2009 and ensured that DocFlex/XML XMLSpy Integration works with all of them.

However, in the process, we discovered a number of problems/issues specific to all or particular XMLSpy versions, which concern the generation of content model diagrams and their hyperlinks (used in XML schema documentation).

Some of those issues we were able to work around completely on the programming level. Some could be fixed programmatically too, however may need special attention from the user because they could not work properly on some XMLSpy versions. Such workarounds are controlled via template parameters. Other problems could be fixed by the users themselves via XMLSpy settings. At last, certain issues are either not supported things or just bugs waiting when Altova itself fixes them (they may be already supported/fixed since some later XMLSpy version).

Below we discuss all such problems/issues that may need your special attention or are good to be aware about (as they might be fixed in some later or future XMLSpy versions).

All versions (2004-2009)

Displacement of imagemap coordinates
As of the versions XMLSpy 2004-2009, all rectangle areas contained in the hypertext imagemaps associated with the content model diagrams generated by XMLSpy are shifted slightly to the top and left, which makes every clickable area to appear somewhat displaced from where it should be.
We have found no rational purpose behind this and assumed that it was simply a bug. Therefore, we programmed a correction by adding (+10,+5) to every (x,y) coordinate found in the imagemaps.
Now, this works fine. But since it is likely the bug of XMLSpy, they may fix it some time later. So, our correction would actually produce a distortion by itself. In that case, you can always disable such corrections using Integrations | XMLSpy | Fix Imagemap Coordinates parameter found in DocFlex/XML XSDDoc templates.
Missing hyperlinks to enclosing types
Yellow panels that may appear on diagrams generated by XMLSpy are meant to represent global complexType components, whose content models are inherited by the given component depicted on the diagram. See, for example, on this screenshot (click to view HTML):

Such a panel contains all elements and attributes that constitute the complex content model defined by the type. Their representations may be properly hyperlinked to the corresponding documentation. However, the type itself, whose name is written at the top-left corner of the panel, never has a hyperlink!
That happens because XMLSpy does not generate a proper hyperlink for the enclosing type. But, it tries! The diagram imagemap does include a hyperlink for each complexType component represented by yellow panels. The problem is that the shape specified for such a hyperlink in the imagemap, instead of being exactly the rectangle covering the panel, actually is a rectangle collapsed to zero size (one or both its sides are always zero). This is obviously a bug (which is even impossible to fix from outside, because one would need to know what is shown on the diagram)! So, we have no choice but to wait when Altova fixes it by itself...

XMLSpy 2009

Visualization of identity constraints
Since this version, XMLSpy is able to visualize the schema-wide identity constraints (IDC) in component diagrams.
Unfortunately, this new feature, probably useful by itself, may also cause a problem. On some XML schemas (for instance, http://www.w3.org/2001/XMLSchema.xsd), the generation of IDC visualizations may take great a lot of time, in fact many times more than without them! We anticipate that for some big XML schemas, when that feature is enabled, it may render XMLSpy almost useless for the purpose of XML schema documentation generation. Fortunately, this may be disabled!
So, if you find that DocFlex/XML XSDDoc integrated with XMLSpy works very slowly, do the following:
1. Start XMLSpy IDE.
2. Open any XML schema with it.
3. Find on the toolbar the “IDC” button (it has “Visualize identity constraints” tooltip) and turn it off.
4. Then, you may quit XMLSpy.
After that, the identity constraints visualizations won't be generated anymore, and you may enjoy the fastest speed of the unified XML schema documentation generator.

XMLSpy 2008

We have found no specific problems with this version (except those mentioned above).

XMLSpy 2007

Problems with opening some XML schemas
XMLSpy 2007 seems to have problems with opening some quite perfect XML schemas.
For instance, when opening the XML schema located by URL http://www.w3.org/2001/XMLSchema.xsd, XMLSpy reported some errors found in that schema and popped up message dialogs about this.
When we tried to run XSDDoc for that XML schema with the XMLSpy Integration enabled, XMLSpy either wasn't able to generate its own documentation by it or a system error (e.g. "XMLSpy has encountered a problem and needs to be closed...") was reported.
It must be said, however, that such strange behaviour was rather rare. Most XML schemas we tried were processed correctly.
Since XMLSpy 2008, such problems do not appear any longer.
Missing hyperlings to some local attributes
Although XMLSpy 2007 does show all local attributes on the diagrams, those local attributes that are defined within global attribute groups will not be hyperlinked to the corresponding documentation.
This happens because XMLSpy 2007 does not document separately any attributes defined within attribute groups. Although diagram hyperlinks are generated for such attributes, those hyperlinks actually lead to nowhere. So, they cannot be associated with any pieces of documentation and used by the integration.
This apparent bug in XMLSpy 2007 was fixed since XMLSpy 2008.

XMLSpy 2006

The same problems as with XMLSpy 2007.

XMLSpy 2005

Missing hyperlinks to all attributes
Although XMLSpy 2005 does show on diagrams all attributes (both global and local ones), none of them will be hyperlinked to the corresponding documentation.
This is because XMLSpy 2005 does not document separately any attributes and no diagram hyperlinks for them are generated. It is not a bug, but rather a missing feature. Only since XMLSpy 2008 everything is OK with the attributes.

XMLSpy 2004

No attributes on diagrams
XMLSpy 2004 does not include attributes in content model diagrams.
Use XMLSpy 2008 (or later) to have all attributes both shown on diagrams and properly hyperlinked to the corresponding documentation.