Documentation

To run experiments with XCheck-Java, follow the following steps (some steps are optional):

  1. Download and install
  2. Prepare the query engine
  3. Write an experiment
  4. Configure the experiment's setting
  5. Run the experiment
  6. Check the experiment's outcomes

Download and install

Download XCheck-Java package (XCheck-Java.zip) from the download page. To install XCheck-Java, just unzip the package. The output is a folder called XCheck-Java containing the following:

Read the GNU General Public License (file License in XCheck-Java or in source folders) before proceding.

Prepare the query engine

XCheck-Java runs a given experiment on a given query engine. XCheck-Java works both with query engines that are command-line tools or that define an API. In the former case, all you have to do is to write an adapter for the specific engine to test. This is an XML document that contains information about the engine, in particular the command to run the engine and optional commands to run before and after the execution of the experiment.

To write an adapter, write an XML document describing the engine to test according to the DTD adapter.dtd contained in folder schema and put the adapter in folder adapters. This folder already contains some examples.

Whenever the query engine to test is available as an API, proceed as follows:

  1. Write an adapter document containing the description of the engine (excluding the execution command).
  2. Define a Java class, let's call it XCheckMyEngine, that inherits from the abstract class XCheckVoid (contained in XCheckVoid.java in the source folder).
  3. Override the following methods:
    • Document parseInputDocument(int j, String target). This method parses the input XML document. The parameter int j is the index of the document and String target is the name of the file containing the document to parse. The output is an org.w3c.dom Document object corresponding to the input document. If an error occurs while parsing the document, then save the error message in variable errorMessageDocument[j] and notify that there was an error for this document by setting errorDocument[j] to Boolean value true.
    • Object executeInputQuery(int j, Document document, String query). This method executes a query. The parameter int j is the index of the query, Document document is the input document on which the query should run, and String query is the query string to execute. The method returns an object with the query result. If an error occurs while parsing the query, then save the error message in variable errorMessageQuery[j] and notify that there was an error for this query by setting errorQuery[j] to Boolean value true.
    • void serializeResult(Object result, String resultFileName, Document document) This method serializes the query result. The parameter Object result is the query result to serialize, String resultFileName is the name of the result file, and Document document is the input document (this parameter might be useful to create the serializer).
  4. Add to the class XCheckMyEngine the following main method: 
    public static void main(String[] args) {
    
  XCheckMyEngine myEngine = new XCheckMyEngine();
  myEngine.check(args);
}
    The method check, inherited from XCheckVoid, executes the test for the engine defined in the above described overridden methods.
  5. Compile the resulting Java file and put the bytecode class files in the main folder XCheck-Java. If you prefer to use a different folder to run XCheck-Java, then override the field xcheckHome inherited from XCheckVoid class.

Folder source contains two examples: XCheckJAXP.java for the Java API for XML Processing (JAXP) and XCheckBaseX for BaseX.

Write an experiment

XCheck-Java defines an experiment as a list of queries. These queries can be either self-containing statements, e.g. the XQuery statement doc("auction.xml")//items, or they can be queries that need to be processed on a target document to specify, for instance the XPath query //items or the equivalent XSLT statement:

<?xml version="1.0"?> 
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:template match="/">
    <xsl:copy-of select="//items"/>
  </xsl:template>
</xsl:stylesheet>

In the latter case, the target documents are specified in the experiment document.

An experiment is described in an XML document that should be valid with respect to the DTD experiment.dtd contained in folder schema. To write a new experiment do the following:

  1. create a new folder for the experiment in the folder experiment;
  2. write an XML document called experiment.xml describing your experiment (the document must validate experiment.dtd) and put it in the created folder;
  3. you may include queries in the experiment document or in separated files. In the latter case, create a folder queries in the folder for the experiment in put the query files in there;
  4. create a folder documents in the folder for the experiment and put XML documents to query in there. In this folder you can also add document schemas if they are relevant for the querying.

Folder experiments of XCheck-java contains some examples.

Configure the experiment's setting

The execution of XCheck-Java can be configured using the XML document config.xml contained in folder XCheck-Java. This documents is valid with respect to the DTD config.dtd included in folder schema. The configuration parameters are:

Run the experiment

XCheck-Java works both with query engines that are command-line tools or that define an API. In the former case run XCheck-Java as follows:

java XCheck engine experiment

where engine in the engine's adapter name and experiment is the name of the experiment folder.

In the latter case run XCheck-Java as follows:

java XCheckMyEngine engine experiment

where XCheckMyEngine is the Java class created as described in section Prepare the query engine, engine in the engine's adapter name, and experiment is the name of the experiment folder.

Check the experiment's outcomes

XCheck-Java stores the outcomes of the performed experiment in a folder called outcome_engine, where engine is the name of the tested query engine. This folder is stored in the folder created for the experiment. The outcomes include:

All this output can be configured by the user (see section Configure the experiment's setting). Folder experiments contains examples of performed experiments.

XHTML + CSS