Conformance Guide to XML-X



Table of Contents

Introduction

Scope

This document describes how to test an XML-X package for compatibility with others already written.

This is not a reference document, nor a draft for a standard. The document is ordered with highest priority tests at the top, lower priority tests at bottom.

Purpose

Packages in XML-X provide means to read and write XML-X packets. Each implementation should be able to read and write each other's packets.

Approach

The conformance requirements are not absolute. No standard is defined as yet. As all implementations are open source, so far, and as many are intended simply to assist with internal comms, there is no strict requirement for conformance with the other implementations of XML-X nor with the specification.

Documents

See the main XML-X site for other documents on XML-X.

Unit Tests

Example

Each class should have an example() method that returns an example object filled with data that is legal but meaningless. Each successive call should return distinct data. Over many calls, all plausible broad possibilities for each field should be cycled through, randomly.

Equals

Each class should have an equals() method that compares two objects and returns the equality.

Unit test

The package should have a unit test that conducts the following cycle for each XML-X packet,

  1. calls example() to get an object,
  2. writes out the XML,
  3. reads the XML back in and recovers the object, and
  4. compares the recovered object with the original.

A program should cycle through all packets, many times each.

Cross Tests

There should be a test program (conventionally called CompatibilityTester) that deals with streams of random junk XML-X packets.

Write, Read, Pipe, Diff

It should have these modes:

  1. Create a stream of packets, by calling example() many times,
  2. Read a stream, and recover packets as objects,
  3. Pipe a stream: read in packets, recover objects, write them out,
  4. Diff two streams: read in two streams, recover, and test each pair of packets for equality.

Help

For tester sanity, the compatibility tester should stick as closely as possible to the following user interface: 

$ $JAVA webfunds.xmlx.test.CompatibilityTester
-mode must be provided: write,read,pipe,diff,...

Usage: CompatibilityTester [opts] -mode {write,read,pipe,diff,...} [tags...]

Opts:   -output output_file_name     (- is stdout)
        -input input_file_name       (- is stdin)
        -n number_of_test_cyles      [1 for write]
        -v verbosity                 [2]

Modes:  write     write out random requests to (-output) file
        read      read in packets from (-input) file and recover them
        pipe      read all in from (-input) and write to (-output)
        diff      compare XML-X packets in two files (working?)

        self      example-write-read-diff cycle (like unit test)

See also handler.test.Test for Unit Tests,
and test.TestClient for testing servers.

For any missing features, add (unsupported) to the above help screen.

Structure of Stream

The stream should have a structure that indicates where separation of XML-X packets are. For example, 3 extra newlines, or this comment, on a line by itself: 

       <!-- END_PACKET -->

Client / Server

A toy server may be provided that has these modes.

  1. Piping as above, so the server just reads in and writes out the same, recovered packet.

  2. Junk request mode. On receiving each request, a related junk reply should be generated.

  3. Test server mode. On receiving each request, a stateful reply is returned. Such a state might be lost when the server is shut down, so, for example, the server creates a junk user on request, and pretends to accept transactions.

A matching client may be written to query the server (including, servers written in other languages) with junk packets, and junk requests.

Conclusion

By using the above test, implementations should be able to quickly establish compatibility.