XBinder v2.9.x

This file contains release notes on the version 2.9.x release of the XBinder XML schema compiler.

Contents

Introduction

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. XBinder is capable of generating C, C++, Java, or C# code that can encode/decode to and from XML, JSON, or EXI.

This package contains the XBinder compiler executable, run-time libraries, documentation and sample programs.

Release Notes

This release of XBinder adds the following new capabilities:
Alpha-level Support for Efficient XML Interchange (EXI)

This release adds some support for EXI targeted mainly at the use of EXI as used in the ISO 15118 Vehicle-to-Grid (V2G) standards. Only schema-informed encoding and decoding with default header options is supported at this time. Support for some XSD types such as xsd:any is not yet available. Also not supported are derived types where use of an xsi:type attribute is required to determine the actual type of a data element at run-time.

Validation of XML files against XSD files in the editor

A user can validate an XML file against one of more XSD schema files within the editor.

Addition of auto-indent to XSD schema editing

An auto-indent capability was added in the XBEditor for editing XSD files. The indent tab count and tab character can be selected through the Option dialog.

Notification of file changes outside the editor

If a file being edited or viewed changes outside the editor, the user is notified via a popup dialog and provided with the option to load the updated version.

General Stability Improvements to the XBEditor GUI

Many improvements were made to the XBEditor GUI. This included general stability changes where a number of crashes were fixed.

Generation of portable makefiles

Portable makefiles using relative file paths are now generated which allow makefiles to be ported between different OS's including Windows and Linux with no changes required.

Qt version used for -use-qt command line option

Code compatible with Qt version 6.x is now generated if the -use-qt option is specified on the command line. Previously code supporting version 5.x was generated.

Compatibility

If -use-qt is used on the command-line, generated code will no longer be compatible with Qt 5.x. In particular, QtLinkedList is no longer used since it is a deprecated class in Qt.

Documentation

The following documents are available in PDF format in the doc subdirectory of the XBinder installation:
  1. C/C++ User's Manual
  2. C/C++ Runtime Reference Manual
  3. Java/C# User's Manual

These manuals are also available online in HTML and PDF formats at the following URL:

https://obj-sys.com/support/xbinder-manuals.php

Windows Installation

The steps to install XBinder on a Windows system are as follows:

  1. Download the XBinder package for Windows. This is located on your account product page if you have a licensed version or in the directory provided in the evaluation email that was sent if you downloaded an evaluation version.

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

  3. This release of this product has an associated license key that allows the product to operate on licensed host computers or for an evaluation period. The evaluation version uses a time-limited license that expires after the evaluation period (30 days). After installation is complete, this license file must be activated to allow the product to operate. This key should have been provided in 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 key may be activated through the XBEditor GUI by going to the Tools -> Options menu item. This will provide a dialog in which the key value may be entered or copy/pasted. The Activate button would then be clicked to activate the license. Note that if an existing license is in place prior to this, it would need to first be deactivated by clicking the Deactivate button.

    The key can also be activated through the command-line by using the -lickey command-line option. The key must be provided as a contiguous string of character with no embedded spaces or newline characters. This command only needs to be done one time to activate the license.

The compiler should now be operational. The following command can be executed from a command prompt to verify operation:

<rootdir>\bin\xbinder

Linux/macOS Installation

The steps to install XBinder on a Linux/masOS system are as follows:

  1. Download the XBinder package for Linux or macOS. This is located on your account product page if you have a licensed version or in the directory provided in the evaluation email that was sent if you downloaded an evaluation version.

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

  3. This release of XBinder has an associated license key that must be installed to allow the compiler to operate. See the section on Windows installation for details on installing this license.

The compiler should now be operational. The following command can be executed from a command prompt to verify operation:

<rootdir>/bin/xbinder

Contents of the Release

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 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. Note that on Linux, a file named 'xbinder.sh' is included in the same directory. This is a shell script for activating the GUI which sets environment variables to ensure the correct shared object files are used. This should always be used to start the GUI.

<installdir>/doc
This directory contains the XBinder C/C++ and Java/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, JSON, 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). For Linux/UNIX, there is a static library (.a) and shared object library (.so).

<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>/c/sample_exi
<installdir>/c/sample_json
<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 data record and writes it to a file. The reader reads the encoded 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. If you have a non-evaluation kit, you will also find variants of the runtime for Java-based platforms: JSE 1.4, JME CLDC, and Android.

<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>/rtjsonsrc/*
<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>/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.

Getting Started

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.

Getting Started with C or C++

To run a simple test of the command-line version of the compiler from Windows or UNIX, do the following:

  1. Open a Visual Studio or other command shell window.

  2. Change directory (cd) to the employee sample directory: c/sample/employee.

  3. Execute the nmake (Windows) or make (Linux/UNIX) utility program:

    nmake

    (note: nmake is a make utility program that comes with Microsoft Visual Studio. A native command-prompt terminal window may need to be used for this utility program to be located.

    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.

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

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

Getting Started with Java

To run a simple test of the command-line version of the compiler from Windows or UNIX, do the following:

  1. Open an MS-DOS or other command shell window.

  2. Change directory (cd) to the Employee sample directory: java/sample/Employee.

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

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

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

Getting Started with C#

To run a simple test of the command-line version of the compiler from Windows, do the following:

  1. Open an MS-DOS command shell window.

  2. Change directory (cd) to the employee sample directory: csharp/sample/employee.

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

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

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

Known Problems and Issues

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:

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.

Reporting Problems

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.