
EXI Interoperability Framework
------------------------------

This distribution was developed by the Efficient XML Interchange (EXI) Working Group.  
It may be updated, replaced or obsoleted at any time.  It is not intended as a means 
to validate conformance, but rather to evaluate the clarity of the EXI Format 1.0
Specification.  However, it may also be use to facilitate EXI implementation 
development.  Comments/questions should be sent to the public-exi@w3.org mailing 
list (public archive). 


Introduction
------------

The EXI interoperability framework is a testing framework developed by the W3C
EXI working group for the purpose of conducting interoperability assessment.
It uses XML test files designed to cover features in the EXI spec. The XML
test files are fed to EXI implementations to generate EXI encodings.  The 
encodings are decoded to produce a round-tripped XML to compare with the 
original XML test files. 

The EXI framework is built on top of another framework called Japex,
which provides basic functionality for drawing charts, generating XML
and HTML reports, etc. Japex is included in this distribution.


Directory structure
-------------------

'candidates' directory contains sub-directories for each implementation. 
The implementation files and test drivers are located in these 
sub-directories.

'config' directory contains the Japex configuration files for
running the tests. These configuration files are composed of
configuration files for drivers and tests cases using XInclude.

'data' directory contains the XML test files.

'encodings' directory contains the EXI encodings generated for the
working group testing.

'framework' directory contains the framework for running the tests. Each 
implementation extends a class in this framework to provide a test component.

'japex' directory contains the Japex distribution.


Setting Up Implementations for Testing
--------------------------------------

EXI implementations are not included in this distribution and must be downloaded
and plugged into the framework to run the tests. To plug-in an implementation, you 
need to have both the EXI implementation and corresponding drivers.  The framework 
is defined to run even if all the implementations used in the EXI WG testing are 
not available on your system.  Instructions for obtaining the EXI implementations 
used in EXI WG testing are given below.

Efficient XML - Please contact products@agiledelta.com using "W3C EXI interop framework" 
                in the subject line to request access to Efficient XML files and the
                corresponding drivers.

Exificient - Download the exificient.jar file(s) (http://exificient.sourceforge.net)
             and put it in the 'candidates/exificient/lib' directory.  Drivers for 
             Exificient are included in this distribution.

Canon's EXI Implementation - Please contact youenn.fablet@crf.canon.fr using "W3C EXI 
                             interop framework" in the subject line to request access to 
                             Canon's EXI implementation and the corresponding drivers.

See http://www.w3.org/XML/EXI/#implementations for a current list of EXI implementations.

This distribution includes drivers for one of the implementations used in the EXI 
WG interoperability testing (Exificient). These drivers use the SAX API. Writing drivers
for other Java implementations should be straightforward using the provided Exificient 
drivers as a template.

To set up the implementation, it should be placed in 'candidates/<implementation>/lib/'.  
You will also need to update the following configuration files to trigger the use of the 
implementation:

* 'config/property/interoperability/encoding/java/drivers.xml' for encoding tests
* 'config/property/interoperability/decoding/java/drivers.xml' for decoding tests

Note that the framework distribution already contains a set of EXI encoded files for 
each of the three EXI implementations used by the EXI WG in interoperability testing: 
Efficient XML, Exificient, and Canon's EXI implementation.  


How to Use
----------

You must have Ant (http://ant.apache.org) to build and run the framework. 

Open a command line tool and go to the root of the EXI interoperability framework folder.

To run encoding tests, type:
	ant run-iot-encoding-classes-java -DtestCases=config/testCases-interop/all.xml

The last parameter config/testCases-interop/all.xml' may be replaced by any other test 
configuration file. Encoding results will be put in a sub-folder of the 
'reports/property/interoperability/encoding' folder.

To run decoding tests, type:
	ant run-iot-decoding-classes-java -DtestCases=config/testCases-interop/all.xml  -DexiDataDir=./encodings/Canon

The ' config/testCases-interop/all.xml' parameter may be replaced by any other test configuration file.

The './encodings/Canon' parameter may be replaced by any other encoding set.

Three full encoding sets are provided in the test framework within the 'encodings' folder.

Decoding results will be put in a sub-folder of the 'reports/property/interoperability/decoding' 
folder.


Limitations
-----------

This release of the framework supports Java-based EXI implementations only

This release requires JDK 1.5.  It has not been tested with other Java versions.

The data-type aware method of comparing XML files (i.e., diff tool) has been maintained 
to avoid false difference reports when using the included test files.  Other test files 
may trigger false difference reports.

Depending on the local installation directory, path names used in this release may trigger
path-length errors in some operating systems.  Affected working group members resolved this
by using a simple work-around of setting up the testing in environment in a local directory 
closer to the root.  
