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 provided by XMLSpy is an open Java API, which 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 allowed us to integrate DocFlex/XML with XMLSpy so as to insert automatically graphic diagrams generated by XMLSpy into the XML schema documentation generated by DocFlex/XML XSDDoc (with the full support of diagram hyperlinks). This, in effect, creates a new 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-2012
- Via both the old and new XMLSpy Java APIs
Possibility to run 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-2012, “Professional” or “Enterprise” edition.
Basically, what is needed for the integration to work is that your XMLSpy edition supports:
1. XMLSpy Java API
2. “XML Schema documentation” feature
(For instance, the “Standard” edition has no such things.)
Java version 7.x, 6.x or 5.x (JDK or JRE) installed on your system. (Java 7 may be preferable as it is the fastest!)
A computer with at least 1 GB RAM (2 GB is better!)

Licensing / Processing Modes

Being a complex piece of software, which took great efforts to develop, the XMLSpy Integration requires a separate licensing. Depending on your license, the integration may work in one of two different modes: full or trial, as described in the following table:

Processing

Description

Full Mode

The Full Mode is activated in the presence of a Commercial or Academic License for “DocFlex/XML XMLSpy Integration”.
This mode allows you to use the integration without any limitations. Once it is enabled, you may think about the integration as just another part of DocFlex/XML executables.
Anything else will depend on your other licenses.

Trial Mode

The Trial Mode is activated in the presence of a Trial License for “DocFlex/XML XMLSpy Integration”. In this mode, the integration will work the same as in the full mode. However, no matter what your other licenses are the following limitations will be enforced:

You may use the integration working in trial mode only during the limited period of time (30 days) provided by your Trial License.

Any output documents generated in trial mode will be specifically distorted. Such documents may be used only for evaluation of this software. Any other usage is prohibited!

The trial mode for XMLSpy Integration will not affect your possibility to create/modify templates. This is controlled by your license for DocFlex/XML SDK!

See Also:

2. Getting It Work

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.

However, in order to use it, you need to have a license for “DocFlex/XML XMLSpy Integration” and to specify some additional settings.

Obtain a License

The XMLSpy Integration requires a separate license, which you should receive by e-mail. If you don't have it yet, you can

The license comes 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 (Full Edition) or DocFlex/XML RE installation, where the license is searched by default (near 'docflex-xml.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.

Primary Settings

To be able to run DocFlex/XML+XMLSpy (and call this everything from whatever else), basically, you need to specify four settings:

XMLSpy Integration Main Class
XMLSpy Version
XMLSpy API Java Class Path
XMLSpy API Library Path

Here are all details:

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=2012

XMLSpy API Java Class Path

These are the jar-files supplied by Altova, which allow a Java application to run XMLSpy.

Currently, Altova maintains two parallel versions of XMLSpy Java API:

The early API, which existed all the time since the very start, is implemented by 'XMLSpyInterface.jar' file found in XMLSpy installation directory, e.g.:
C:\Program Files\Altova\XMLSpy2012\XMLSpyInterface.jar
Since XMLSpy 2012, there is another completely different API. It is implemented by two jar-files: 'XMLSpyAPI.jar' and 'AltovaAutomation.jar' found in 'JavaAPI' subdirectory of the XMLSpy installation directory, e.g.:
C:\Program Files\Altova\XMLSpy2012\JavaAPI\

The XMLSpy Integration supports both APIs. Although, it can work with only one API version at a time, to make matter simpler, you should specify all XMLSpy API jar-files (of both API versions) together using -m option like the following:

set XMLSPY_HOME=C:\Program Files\Altova\XMLSpy2012
...

-m:XMLSPY_CLASSPATH= "%XMLSPY_HOME%\XMLSpyInterface.jar;%XMLSPY_HOME%\JavaAPI\XMLSpyAPI.jar; %XMLSPY_HOME%\JavaAPI\AltovaAutomation.jar"

Notice that the whole classpath is enclosed in double quotes! This is needed because 'Program Files' contains a space. Without quotes, such a classpath will be broken by the spaces and interpreted as several separate command line arguments.

XMLSpy API Library Path
XMLSpy itself is a Windows application, so all those jar-files (above) eventually call from themselves some Windows DLLs, which are loaded by the JVM and must be found by it.
Here again the situation is different for different XMLSpy API versions:
1. In the case of early XMLSpy API, the bridge DLL is 'XmlSpyLib.dll' located in Windows 'system32' directory, e.g.:
  C:\WINDOWS\system32\XmlSpyLib.dll
  It is installed there during the XMLSpy installation. JVM typically finds this DLL by default (without any special settings).
2. In the case of new XMLSpy API, the bridge DLL is 'AltovaAutomation.dll' located in 'JavaAPI' subdirectory of the XMLSpy installation directory, e.g.:
  C:\Program Files\Altova\XMLSpy2012\JavaAPI\AltovaAutomation.dll
  That DLL cannot be found by default! So, you must always specify its location (its parent directory) separately on the Java command line using -m option as follows:
  set XMLSPY_HOME=C:\Program Files\Altova\XMLSpy2012
  ...
  -m:XMLSPY_LIBPATH="%XMLSPY_HOME%\JavaAPI"
  
  The double quotes are necessary to not break the option by spaces in XMLSpy home pathname.

See Also:

The old and new XMLSpy Java APIs

Sample Windows BAT File

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 (with the red are highlighted settings related to XMLSpy Integration):

xsddoc.bat

set DFH=C:\docflex-xml

set

CLASSPATH= %DFH%\lib\xml-apis.jar;%DFH%\lib\xercesImpl.jar;%DFH%\lib\resolver.jar;%DFH%\lib\docflex-xml.jar

set XMLSPY_HOME=C:\Program Files\Altova\XMLSpy2012

set XMLSPY_VERSION=2012

set

XMLSPY_CLASSPATH= %XMLSPY_HOME%\XMLSpyInterface.jar;%XMLSPY_HOME%\JavaAPI\XMLSpyAPI.jar; %XMLSPY_HOME%\JavaAPI\AltovaAutomation.jar

set

XMLSPY_LIBPATH= %XMLSPY_HOME%\JavaAPI

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

Related Template Parameters

Besides the primary settings, the integration is controlled by quite a lot of other settings, which are exposed as template parameters. See:

DocFlex/XML | XSDDoc | Templates | Parameters | Integrations | XMLSpy

Using them, you can adjust other things as well as to specify how to overcome certain problems of particular XMLSpy versions.

3. Running on Windows

Quick Start

All those complicated settings described above are needed to tell DocFlex/XML that the XMLSpy Integration must be used as a provider of diagrams and to set it up to run XMLSpy. But when it concerns simply running everything on Windows, you don't need to learn too much.

Here are all the steps to have your XML schema documentation generated with the XMLSpy diagrams embedded in it:

Download DocFlex/XML (any edition) and unpack the downloaded zip.
Save the docflex-xml.license file (containing the “XMLSpy Integration” license) in the directory:
{docflex-xml}/lib

Now, go to the directory:

{docflex-xml}/integrations/XMLSpy

Edit generator.bat found in that directory, in these lines:

::---------------------------------------------------------------------- :: Specify the location of JRE/JDK 7.x, 6.x, 5.x or 1.4.x here ::---------------------------------------------------------------------- set JAVA_HOME=C:\Program Files\Java\jre7 ::---------------------------------------------------------------------- :: Specify the location of XMLSpy home directory and XMLSpy version ::---------------------------------------------------------------------- set XMLSPY_HOME=C:\Program Files\Altova\XMLSpy2012 set XMLSPY_VERSION=2012

(It may be so you won't need to change anything.)

Now, just run that generator.bat.
The DocFlex/XML integrated with XMLSpy will be working! To test it, you can click the <Run> button and generate a demo XML schema doc by the standard “XML Schema for XML schemas” with all diagrams.

Windows 64-bit

After you have setup everything as described above, you may still be unable to run DocFlex/XML+XMLSpy. Instead, you may get an error saying that some XMLSpy DLL cannot be found.

The most likely cause is that your operating system is a 64-bit Windows (e.g. Windows 7 64-bit), but either XMLSpy or Java installed on it is 32-bit. (That's because 32-bit Java doesn't know how to run a 64-bit DLL and vice versa).

When your computer runs Windows 64-bit, please make sure that both XMLSpy 64-bit and Java 64-bit are installed on it!

Otherwise, the integration won't work!

4. 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:\Program Files\Java\jdk1.7
call %ANT_HOME%\bin\ant.bat xsddoc

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

5. Running with Apache Maven

How to run DocFlex/XML with Maven is basically explained on this page: DocFlex/XML | Integrations | Apache Maven.

The following project POM file shows how to configure the DocFlex/XML Maven Plugin 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

...

<DFH>C:\docflex-xml</DFH>

<XMLSPY_HOME>C:\Program Files\Altova\XMLSpy2012</XMLSPY_HOME>

<XMLSPY_VERSION>2012</XMLSPY_VERSION>

<XMLSPY_CLASSPATH>

${XMLSPY_HOME}\XMLSpyInterface.jar;${XMLSPY_HOME}\JavaAPI\XMLSpyAPI.jar;${XMLSPY_HOME}\JavaAPI\AltovaAutomation.jar</

</XMLSPY_CLASSPATH>

<XMLSPY_LIBPATH>${XMLSPY_HOME}\JavaAPI</XMLSPY_LIBPATH>

</properties>

...

<groupId>docflex</groupId>

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

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

<param>-m:XMLSPY_VERSION=${XMLSPY_VERSION}</param>

<param>-m:XMLSPY_CLASSPATH=${XMLSPY_CLASSPATH}</param>

<param>-m:XMLSPY_LIBPATH=${XMLSPY_LIBPATH}</param>

<param>-template</param>

<param>${DFH}\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:\Program Files\Java\jdk1.7
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!)

6. Running on Linux

Since XMLSpy is a Windows application, the only way to run it on Linux is via some Windows emulator. Such an emulator does exist. It is called “Wine” (see http://www.winehq.org/). XMLSpy does work on it!

DocFlex/XML is a Java application, so it works equally on Linux. But there is a problem: the XMLSpy Java API, to which DocFlex/XML must connect, requires running from itself some Windows DLLs. This prohibits DocFlex/XML while running on Linux Java to call XMLSpy (because Linux Java doesn't know how to call Windows DLLs!). So, the only possible solution is to install Java for Windows on Wine and to run DocFlex/XML on that Java instead. That turned out to work!

Installation

Here are the steps you need to do to have DocFlex/XML+XMLSpy running together on your Linux system:

Install Wine. Here you can read how: http://www.winehq.org/download/

In fact, in most cases you don't need to download anything directly. For instance, under Fedora 16, Wine can be installed as follows:
Open a terminal and
su - -- your root password -- yum install wine
That's all.

Install XMLSpy on Wine. Use a command like this:

wine XMLSpyEnt2012.exe

or simply click on the XMLSpyEnt2012.exe in a Linux file manager GUI.

When the standard XMLSpy installation dialog appears, pass all its steps (the same as on Windows).

The standard XMLSpy installation works just fine on the modern Linux/Wine. What is written on Altova own website is outdated information: http://www.altova.com/support_platform_linux.html. You won't get it work on recent Linux versions like they suggest!

After that, you will need to run XMLSpy so as to register your license for it. Typically the installer already creates (via Wine) a link on the desktop to run XMLSpy. If you don't see such a link, you can run XMLSpy directly. Open a terminal and type like this:

wine 'C:\Program Files\Altova\XMLSpy2012\XMLSpy.exe'

XMLSpy will be launched! (Note that everything will work a bit slower than on a native system)

Install Java for Windows on Wine. Use a command like this:
wine jdk-7u4-windows-i586.exe
(or just click on the 'jdk-7u4-windows-i586.exe' in a Linux file manager). When Java installation dialog appears, pass all installation steps.

Sample Bash File

Now you can run everything together (DocFlex/XML+XMLSpy) using the following shell script file:

generator.sh


#!/bin/sh



# DocFlex/XML home directory

DFH='/home/docflex-xml'



# DocFlex/XML class path

CLASSPATH="$DFH/lib/xml-apis.jar;$DFH/lib/xercesImpl.jar;$DFH/lib/resolver.jar;$DFH/lib/docflex-xml.jar"



# XMLSpy home directory and XMLSpy version

XMLSPY_HOME='C:\Program Files\Altova\XMLSpy2012'



# XMLSpy version

XMLSPY_VERSION='2012'



# XMLSpy class path (for all XMLSpy API versions together)



  XMLSPY_CLASSPATH="
  $XMLSPY_HOME\\XMLSpyInterface.jar;$XMLSPY_HOME\\JavaAPI\\XMLSpyAPI.jar;
$XMLSPY_HOME\\JavaAPI\\AltovaAutomation.jar"





# XMLSpy library path (the location of Windows DLLs implementing

# the bridge between XMLSpy Java API v2012 and XMLSpy.exe)


XMLSPY_LIBPATH="$XMLSPY_HOME\\JavaAPI"



# Specify the XMLSpy Integration class as element image provider

OPTIONS='-m:IMAGE_PROVIDER_CLASS=com.docflex.xml.xmlspy.SpyKit'



# Pass XMLSpy version to the integration

OPTIONS="$OPTIONS -m:XMLSPY_VERSION=$XMLSPY_VERSION"



# Pass XMLSpy class path

OPTIONS="$OPTIONS -m:XMLSPY_CLASSPATH='$XMLSPY_CLASSPATH'"



# Pass XMLSpy library path

OPTIONS="$OPTIONS -m:XMLSPY_LIBPATH='$XMLSPY_LIBPATH'"



# Specify the template

OPTIONS="$OPTIONS -template '$DFH/templates/XSDDoc/FramedDoc.tpl'"



# Specify output format, output directory etc.

OPTIONS="$OPTIONS -format HTML -d '$DFH/out' -nodialog -launchviewer=false"




#-------------------------------------------------------------------------------------

# Run DocFlex/XML generator to document an XML schema (specified in the last argument)

#-------------------------------------------------------------------------------------

# The 'eval' is needed here to have all arguments containing spaces passed correctly.

# Otherwise, such arguments get broken into several ones, which spoils the whole Java command line.

#-------------------------------------------------------------------------------------



  eval 
  "wine java -cp '$CLASSPATH' com.docflex.xml.Generator $OPTIONS http://www.w3.org/2001/XMLSchema.xsd"

Problems/Issues

On Different Linux Distributions

So far, we tried to run DocFlex/XML+XMLSpy on three different Linux distributions and found the following:

Fedora 16
Both XMLSpy and Java for Windows can be installed there (over Wine).
The integration works acceptable (it is the fastest in fact). But there is a problem with fonts. The “Arial” font used by XMLSpy was mapped to some Fedora's system font, which looked ugly. That concerned the diagrams generated by XMLSpy, because they use that font too.
The solution is to find the Windows Arial font, e.g.:
c:\Windows\Fonts\arial.ttf
and install it on Fedora. (In Fedora KDE, this can be done via System Settings | System Administration | Font Management).
Once a proper “Arial” font is installed, the diagrams generated by XMLSpy look the same as on Windows.
Ubuntu 11.10
Everything installs OK and Ubuntu's Wine does include all necessary Windows fonts.
openSUSE 12.1
That was the worst case. Although XMLSpy itself did work there, the Windows Java didn't. We weren't able to run DocFlex/XML from openSUSE's Wine. It just hung. Therefore, no integration was possible.

Linux 64-bit

On Linux 64-bit, you can install either XMLSpy 64-bit / Windows Java 64-bit or XMLSpy 32-bit / Windows Java 32-bit. How this will work ultimately depends on a particular version of Wine.

Currently, we've found that only 32-bit XMLSpy/Java combination worked well on 64-bit Linux.

When we tried 64-bit XMLSpy/Java, there were some inconsistencies. So we weren't able to run the integration.

Quitting of XMLSpy

After all XML schemas have been processed and all diagrams generated, XMLSpy is not needed any longer. Then, a template set (XSDDoc) issues a command to quit XMLSpy.

Unfortunately, currently the quitting of XMLSpy via its Java API while running on Linux/Wine always produces some internal exception/error, which may hinder finishing the generation of the documentation (even though all the diagrams are perfectly ready).

See Also:

The old and new XMLSpy Java APIs

7. How Integration Works

It 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 is supported by Altova itself, who includes in XMLSpy a special Java API.

Running XMLSpy from templates

The integration exposes some of the XMLSpy Java API 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.)

Obtaining diagram images and imagemaps

Unfortunately, XMLSpy Java API currently lacks a direct support of the generation of content model diagrams (and imagemaps to them) suitable for documentation. But XMLSpy does produce all those things by itself when it generates its own XML schema docs. This opens a way to work around that problem. Once XMLSpy is made to generate its own documentation, further it is possible to extract automatically from that documentation any diagrams and imagemaps we need. Fortunately, the XMLSpy Java API does allow all this!

So, the integration actually works by calling XMLSpy to generate its own (reduced) documentation for every initially specified XML schema file. Further, that intermediate documentation is used by DocFlex/XML (the integration bridge) to obtain the diagram images and imagemaps created by XMLSpy so as to use them in the documentation output generated by XSDDoc.

All temporary files produced by XMLSpy are stored in the directory

{documentation_files}/xmlspy

where '{documentation_files}' is either the main output directory (specified to the DocFlex generator) or the directory associated with the main output file.

For each initially specified XML schema to be documented, DocFlex/XML calls XMLSpy to generate its own most simplified (however with diagrams) documentation. That documentation is stored in a separate subdirectory (within '{documentation_files}/xmlspy') under the name derived from the XML schema file name, for example:

{documentation_files}/xmlspy/schema-for-xslt20_xsd

The documentation generated by XMLSpy consists of a single 'index.html' file and a number of diagram image files (like 'index_p23.png').

Further, DocFlex parses the index.html produced by XMLSpy and associates the diagram images (and hypertext maps to them) generated by XMLSpy with the corresponding schema components documented by XSDDoc templates. To do so, DocFlex needs to know precisely what the XMLSpy HTML output file may contain and how this should be treated. That, in turn, varies with the XMLSpy versions. However, actually only a few specific things are different. Basically, everything comes down to which extra XML schema features the XMLSpy's own documentation generator now supports. But, the integration cannot know such things by itself. So, it needs to be told about this via template parameters.

Those template parameters that hint the integration how the XMLSpy output should be parsed and interpreted are found in the “Integrations | XMLSpy | Workarounds” parameter group. But, in most cases you won't need to specify them directly. Their default values are derived from the XMLSpy version number, which is specified in “Integrations | XMLSpy | XMLSpy Version” parameter. The possibility to change the “Workarounds” parameters is provided because some intermediate XMLSpy versions (releases) may already support certain new extra features, but yet not all found in the next full version.

Once, XSDDoc finishes, the original XMLSpy documentation is not needed any longer and can be deleted. This is controlled by the parameter: “Integrations | XMLSpy | Delete Temporary Docs”.

Getting diagrams into DocFlex/XML output

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 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.

8. Problems/Issues of XMLSpy Versions

We have tested all XMLSpy versions from 2004 to 2012 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, hyperlinks from them (used in XML schema documentation) and other things.

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 features or just bugs waiting for Altova to fix 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).

The old and new XMLSpy Java APIs

XMLSpy is a Windows native application. However, it does allow Java programs to communicate with itself via a special XMLSpy Java API. That API is implemented in the form of some Java classes (packed in one or several JAR-files) that are backed by some Windows DLL.

DLL stands for Dynamic Link Library. Apparently, the whole XMLSpy Java API is implemented as a Java ActiveX bridge.

XMLSpy 2012 provides two different (parallel) Java APIs to connect to it:

The old API
That API existed all the time. It is implemented by two files:
C:\Program Files\Altova\XMLSpy\XMLSpyInterface.jar C:\Windows\system32\XmlSpyLib.dll
It is currently the most stable and if you run everything on Windows you should prefer this API.
The new API
It appeared since XMLSpy 2012 and is implemented by the files found in the directory:
C:\Program Files\Altova\XMLSpy\JavaAPI\
namely:
XMLSpyAPI.jar AltovaAutomation.jar AltovaAutomation.dll
As of the XMLSpy v2012, the main problem of this API is that it always raises some internal Java exception when quitting XMLSpy. However, that exception is tolerable and can be ignored in most cases.
Although, we don't know why Altova created another Java API for XMLSpy, it is likely that the new API will be given a priority in the next XMLSpy version. So, if something doesn't work with some future XMLSpy version (since 2012), you may try to switch to this API.

Which of those APIs is actually used?

Displacement of imagemap coordinates

As of the versions XMLSpy 2004-2012, 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 assume that it is 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 a bug in XMLSpy, it may be fixed 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.

Visualization of identity constraints

Since the version 2009, 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:

Start XMLSpy IDE.
Open any XML schema with it.
Find on the toolbar the “IDC” button (it has “Visualize identity constraints” tooltip) and turn it off.
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.

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 hyperlinks to enclosing types

Yellow panels that may appear on the 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. However, it tries... The diagram imagemap does include a hyperlink for each complexType component represented by the yellow panels. The problem is that the imagemap shape specified for such a hyperlink is always a rectangle collapsed to zero size (one or both its sides are always zero!), instead of being exactly the rectangle covering the panel. This, of course, is a bug, which is even impossible to fix from outside, because one would need to know what exactly is shown on the diagram.

Currently, this problem shows up in all versions of XMLSpy (including the latest XMLSpy 2012). So, we have no choice but to wait for Altova to fix it...

Missing hyperlinks to some local attributes

This problem occurs in XMLSpy 2006-2007.

Although these versions of XMLSpy depict all local attributes on the diagrams, those local attributes that are defined within global attribute groups will have no hyperlinks to the corresponding documentation.

This happens because XMLSpy 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 has been fixed since XMLSpy 2008.

Missing hyperlinks to all attributes

Only since the version 2005, XMLSpy started to show all attributes (both global and local ones) on the diagrams. However, if you use XMLSpy 2005, none of the attributes 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.

Missing attributes on diagrams

XMLSpy 2004 does not show attributes on the content model diagrams.

Use XMLSpy 2008 (or later) to have all attributes both shown on diagrams and properly hyperlinked to the corresponding documentation.

Missing diagrams of redefined components

Although all tested XMLSpy versions process redefinitions of XML schema components (those specified within <xs:redefine> elements), XMLSpy 2006 and early versions do not document the original components (those being redefined). So, if you use XMLSpy 2006, only component redefinitions will have their diagrams!

Use XMLSpy 2007 (or later) to have the diagrams generated for both the original components and their redefinitions.