This file contains release notes on the version 2.0.x release of the XBinder XML schema compiler.
Thank you for downloading the XBinder XML schema compiler software. XBinder is an XML data-binding tool for working with XML schema definitions. It creates compatible programming language structures/classes and encoders and decoders to allow rapid translation between XML documents and program objects. This release generates C, C++, Java, and C# code that can encode/decode to and from XML.This package contains the XBinder compiler executable, run-time libraries, documentation and sample programs.
New features in this release include the following:
- Java / C# Code Generation
- The major new feature added in this release is the addition of code generation in both the Java and C# programming languages. This code generation is modelled along the same basic lines as C++; therefore, a consistent object-oriented interface is provided across different language types making it easier to port applications to different environments.
- Support for Different Derivation Models in C++
- There are now two distinct derivation models that are fully supported for handling XSD complexContent derived types in C++. The 'extended' model is the model that existed in older versions of XBinder and is the more natural model for dealing with complexContent extensions. However, 'extended' was found to not cleanly support all use cases of XSD complexContent types (in particular, certain types of restrictions) so the 'interface' model (similar to a Java interface) was added to flatten the structure to support all cases. In this release, the derivation model to be used can be selected using the -derivModel command line switch. Automatic selection is also done based on the contents of the schema being compiled with 'extended' taking preference over 'interface' where possible.
- Project-level Factory Class Added for C/C++ Decode and Validation
- Many XSD-based protocols specify multiple global element declarations that describe different XML document types that may be exchanged in a transaction. In the past when using XSD specifications of this type with XBinder, it was necessary to manually parse the outer level tag of a document in order to determine the correct decode and/or validation function to invoke. This release of XBinder adds an option to generate a factory class (-genFactory) to automate this process.
- Support added for UTF-16 and ISO-8859-1 character encodings
- It is now possible to both decode and encode documents to and from these character encoding formats in C/C++. The internal format maintained as UTF-8.
- Support added for nillable elements for C/C++
- Previous versions of XBinder did not provide any support for nillable elements or adding the xsi:nil attribute. This is now supported in this version (for C/C++).
- GUI Improvements
- The XBEditor GUI has been improved to include auto-completion of elements and attributes when creating new schema files. All GUI's have also been updated to use the latest version of Qt (4.5.1).
The primary code change in C/C++ that would affect backward compatibility is the change to support multiple derivation models in C/C++. Existing users of XBinder C++ 1.4 and 1.5 will need to add '-derivModel interface' to the XBinder command-line in order to produce compatible code.There also has been a file name change for project-specific C/C++ items in this version. In previous versions, a file named '<project>_Namespace' was generated containing namespace information. In this version, the namespace information as well as other project-specific items (for example, the factory class if -genFactory is specified) is stored in a file named '<project>_Project'. Use of the '-compat 1.5' switch will cause the old file naming convention to be used.
C/C++ users may find this version of XBinder selects a signed integer data type where an earlier version selected an unsigned integer data type. If you encounter this problem and wish to opt for unsigned integer types, specify the -useUnsignedInts flag on the XBinder command line.
The following documents are available in PDF format in the doc subdirectory of the XBinder installation:
- C/C++ User's Manual
- C/C++ Runtime Reference Manual
- Java/C# User's Manual
These manuals are also available online in HTML and PDF formats at the following URL:
The system requirements for this software are as follows:
- Microsoft Windows operating system (Windows 2000 or later)
- Microsoft Visual C++ version 6.0 or .NET, Borland C++ v5.5 or higher, or GNU gcc 3.2 or higher.
- In order to run the GUI applications, version 2.0 or higher of the Microsoft .NET Framework is required
The steps to install XBinder on a Windows system are as follows:
- Download the XBinder package for Windows. This is located at the following URL:
- XBinder for Windows is packaged in a self-extracting executable file format. To install, all that should be necessary is to double-click this file after downloading and then following the setup wizard instructions from that point.
- This release of this product has an associated license file that allows the product to operate on licensed host computers. The evaluation version uses a time-limited license that expires after the evaluation period (typically 30 to 45 days). After installation is complete, this license file must be installed to allow the product to operate. This was sent in the osyslic.txt file that was attached to the E-mail message that was sent at the time the product was downloaded. If you did not receive a license file, please contact us.
- The osyslic.txt file must be copied to a location where the compiler can find it. This can be done in one of the following ways:
- a. The file can be copied into the same directory as the XBinder executable file (xbinder.exe). This would be the bin subdirectory of the installation root directory.
- b. The file can be copied to a different directory and an environment variable named 'OSLICDIR' created to point at this directory location.
- c. The file can be copied into any of the directories specified within your PATH environment variable (copying to the c:\windows directory works on most systems).
The compiler should now be operational. The following command can be executed from a command prompt to verify operation:
<rootdir>\bin\xbinder
The system requirements for this software are as follows:
- Linux (x86 or amd64), Solaris (sparc or x86), HP-UX (PA-RISC or Itanium), or Apple Mac OSX 10.3 or higher
- GNU gcc 3.2 or higher or native C or C++ compiler
The steps to install XBinder on a Linux/UNIX system are as follows:
- Download one of the XBinder distribution package files for Linux or UNIX. The available packages can be found at this URL:
- XBinder for Linux/UNIX is packaged in a gzipped .tar file. To install, unzip the file (gunzip) and untar (tar xf) in any directory. Note that in order to run the sample programs, write access to the sample directories is required, so make sure that you have write access to the base directory where the package is installed.
- This release of XBinder has an associated license file that must be installed to allow the compiler to operate. See the section on Windows installation for details on installing this license file.
The compiler should now be operational. The following command can be executed from a command prompt to verify operation:
<rootdir>/bin/xbinder
The following subdirectories contain the following files (note: <installdir> refers to the installation directory that was specified during the installation process):
- <installdir>/bin/xbinder.exe
- The command-line compiler executable file. This program is invoked on XML schema source files to generate C or C++ encode/decode structures and functions. It is recommended you modify your PATH environment variable to include <installdir>/bin to allow the compiler executable to be run from anywhere.
- <installdir>/bin/xbeditor.exe
- A graphical user interface (GUI) XML schema editor program. This is a basic editor that is suitable for basic viewing and editing of XML schema files used with XBinder. It also allows generated code files to be viewed. XBinder options can be set and the compiler invoked directly from the editor. If compilation errors exist, they can easily be located and corrected within the editor.
- <installdir>/bin/xbindergui.exe
- A graphical user interface (GUI) wizard program designed to make file selection and specification of user options easier. This wizard will collect all information required to do a compilation and then invoke the command-line version of the compiler with the selected options.
- <installdir>/bin/xml2exi.exe
- <installdir>/bin/exi2xml.exe
- Command-line utility programs for transforming XML files to/from Efficient XML Interchange (EXI) format.
- <installdir>/doc
- This directory contains the XBinder C/C++ Users and Runtime Reference Manual PDF documentation files.
- <installdir>/c/lib/*.dll
- <installdir>/c/lib/*.lib
- The XBinder C run-time library files. These contain the low-level XML and EXI encode/decode and common runtime functions. For Windows, there is a dynamic link library (.dll) and standard library file (.lib) for linking with the DLL. There is also a static library for direct linkage to the object modules (this is the library file with the '_a.lib' suffix). The static library included in the evaluation version is not thread-safe. A thread-safe version can be provided upon request. For Linux/UNIX, there is a static library (.a) and shared object library (.so or .sl).
- <installdir>/cpp/lib/*.dll
- <installdir>/cpp/lib/*.lib
- The XBinder C++ run-time library files. These are the same as the C libraries except that they contain the compiled built-in C++ classes as well.
- <installdir>/c/sample
- <installdir>/cpp/sample
- <installdir>/csharp/sample
- <installdir>/java/sample
- The sample directories contain sample programs illustrating the use of the compiler. Most sample programs contain a writer and a reader program. The writer encodes a sample XML data record and writes it to a disk file. The reader reads the encoded XML data from the file, decodes it, and then prints the results of the decode operation.
- <installdir>/java
- Files related to Java code generation. This includes the Java run-time .jar file (xbrt.jar) that is required for use with compiled Java code.
- <installdir>/csharp
- Files related to C# code generation. This includes the C# run-time .dll file (xbrt.dll) that is required for use with compiled C# code.
- <installdir>/rtxsrc/*
- <installdir>/rtdomsrc/*
- <installdir>/rtexisrc/*
- <installdir>/rtxmlsrc/*
- The installation run-time source directories contain the header files required to compile the compiler generated code.
- <installdir>/libxml2src/*
- The libxml2 parser run-time source directories contain the source files for the libxml2 C XML parser. This is the default SAX parser used with the XBinder XML runtime.
- <installdir>/expatsrc/*
- The XML parser run-time source directories contain the source files for the Expat C XML parser. This is an optional SAX parser that can be configured to work with XBinder.
- <installdir>/xbqt4edit/*
- <installdir>/xbqt4wiz/*
- XBinder GUI subdirectories. This directory contains the source code and build files for the XBinder GUI applications. The code in this subdirectory is licensed under the GPL; therefore, users can modify it to get it running on their target platform. The code makes use of the Nokia Qt Software (tm) GUI building software.
- <installdir>/xsd/*
- Sample XML schema files. These are public schemas taken from large XML schema-based standards. They are used by some of the sample programs to demonstrate XBinder's ability to compile large, complex schemas.
XBinder contains a GUI Editor and Wizard program that makes specification of options to the compiler easier. The installation procedure should have provided Start Menu options and Desktop icons for activating these applications. On Linux/UNIX, the GUI executables are located in the bin subdirectory along with the XBinder command-line executable. The GUI can be started by simply running the GUI executable from the command-line.
To run a simple test of the command-line version of the compiler from Windows or UNIX, do the following:
- Open an MS-DOS or other command shell window.
- Change directory (cd) to the employee sample directory: c/sample/employee.
- Execute the nmake (Windows) or make (Linux/UNIX) utility program:
nmake
(note: nmake is a make utility program that comes with the Microsoft Visual C++ compiler. It may be necessary to execute the batch file vcvars32.bat that comes with Visual C++ in order to set up the environment variables to use this utility).
This should cause the compiler to be invoked to compile the employee.xsd sample file. It will then invoke the Visual C++ compiler to compile the generated C file and the test drivers. The result should be a writer.exe and reader.exe program file which, when invoked, will encode and decode a sample employee record.
- Invoke writer from the command line:
writer
This will generate an encoded record and write it to a disk file. By default, the file generated is message.xml. The test program has a number of command line switches that control the encoding. To view the switches, enter writer ? and a usage display will be shown.
- Invoke reader from the command line:
reader
This will read the disk file that was just created by the writer program and decode its contents. The resulting decoded data will be written to standard output. The test program has a number of command line switches that control the encoding. To view the switches, enter reader ? and a usage display will be shown.
To run a simple test of the command-line version of the compiler from Windows or UNIX, do the following:
- Open an MS-DOS or other command shell window.
- Change directory (cd) to the Employee sample directory: java/sample/Employee.
- Execute the build.bat (Windows) or build.sh (Linux/UNIX) utility program:
build.bat
This should cause the compiler to be invoked to compile the employee.xsd sample file. It will then invoke the Java compiler to compile the generated Java files and the test drivers. The result should be a Writer.class and Reader.class program file which, when invoked, will encode and decode a sample employee record.
- Invoke writer.bat (Windows) or writer.sh (Linux/UNIX) from the command line:
writer.bat
This will generate an encoded record and write it to a disk file. By default, the file generated is message.xml. The test program has a number of command line switches that control the encoding. To view the switches, enter writer.bat ? and a usage display will be shown.
- Invoke reader.bat (Windows) or reader.sh (Linux/UNIX) from the command line:
reader.bat
This will read the disk file that was just created by the writer program and decode its contents. The resulting decoded data will be written to standard output. The test program has a number of command line switches that control the encoding. To view the switches, enter reader.bat ? and a usage display will be shown.
To run a simple test of the command-line version of the compiler from Windows, do the following:
- Open an MS-DOS command shell window.
- Change directory (cd) to the employee sample directory: csharp/sample/employee.
- Execute the nmake utility program:
nmake
(note: nmake is a make utility program that comes with the Microsoft Visual C# compiler. It may be necessary to execute the batch file vcvars32.bat that comes with Visual C# in order to set up the environment variables to use this utility).
This should cause the compiler to be invoked to compile the employee.xsd sample file. It will then invoke the Visual C# compiler to compile the generated C# files and the test drivers. The result should be a writer.exe and reader.exe program file which, when invoked, will encode and decode a sample employee record.
- Invoke writer from the command line:
writer
This will generate an encoded record and write it to a disk file. By default, the file generated is message.xml. The test program has a number of command line switches that control the encoding. To view the switches, enter writer ? and a usage display will be shown.
- Invoke reader from the command line:
reader
This will read the disk file that was just created by the writer program and decode its contents. The resulting decoded data will be written to standard output. The test program has a number of command line switches that control the encoding. To view the switches, enter reader ? and a usage display will be shown.
The XBinder compiler is designed for use with the type of XML messages used in the XML infoset ( http://www.w3.org/TR/xml-infoset). It is defined for XML messaging applications such as the messages exchanged in a SOAP protocol data exchange as opposed to more free-form applications such as XML document models or database applications.
The following features defined in the 2001 edition of XML Schema are currently not supported:
- Redefinition of Schema Components (xsd:redefine)
- final and block properties
- DTD's
It is our desire to make a practical XML data binding tool that can handle the syntax that people use, not something that can handle every possible syntax. So we are interested in hearing what you are using in practice that doesn't work. In other words, if you create overly complex syntax in order to try and break this tool, you probably will.
Report problems you encounter by sending E-mail to support@obj-sys.com. The preferred format of example programs is the same as the sample programs. Please provide a writer and reader and indicate where in the code the problem occurs.
If you have any further questions or comments on what you would like to see in the product or what is difficult to use or understand, please communicate them to us. Your feedback is important to us. Please let us know how it works out for you - either good or bad.