FlatXmlDataSet.java

  1. /*
  2.  *
  3.  * The DbUnit Database Testing Framework
  4.  * Copyright (C)2002-2004, DbUnit.org
  5.  *
  6.  * This library is free software; you can redistribute it and/or
  7.  * modify it under the terms of the GNU Lesser General Public
  8.  * License as published by the Free Software Foundation; either
  9.  * version 2.1 of the License, or (at your option) any later version.
  10.  *
  11.  * This library is distributed in the hope that it will be useful,
  12.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14.  * Lesser General Public License for more details.
  15.  *
  16.  * You should have received a copy of the GNU Lesser General Public
  17.  * License along with this library; if not, write to the Free Software
  18.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  19.  *
  20.  */

  22. package org.dbunit.dataset.xml;

  24. import org.slf4j.Logger;
  25. import org.slf4j.LoggerFactory;

  27. import org.dbunit.dataset.CachedDataSet;
  28. import org.dbunit.dataset.DataSetException;
  29. import org.dbunit.dataset.IDataSet;

  31. import org.xml.sax.InputSource;

  33. import java.io.File;
  34. import java.io.IOException;
  35. import java.io.InputStream;
  36. import java.io.OutputStream;
  37. import java.io.Reader;
  38. import java.io.Writer;
  39. import java.net.URL;
  40. import java.nio.charset.Charset;

  42. /**
  43.  * Reads and writes flat XML dataset document. Each XML element corresponds to a table row.
  44.  *       Each XML element name corresponds to a table name. The XML attributes
  45.  *       correspond to table columns.
  46.  * <p>
  47.  * Flat XML dataset document sample:
  48.  * <p>
  49.  * <pre>
  50.  * &lt;!DOCTYPE dataset SYSTEM "my-dataset.dtd"&gt;
  51.  * &lt;dataset&gt;
  52.  *     &lt;TEST_TABLE COL0="row 0 col 0"
  53.  *         COL1="row 0 col 1"
  54.  *         COL2="row 0 col 2"/&gt;
  55.  *     &lt;TEST_TABLE COL1="row 1 col 1"/&gt;
  56.  *     &lt;SECOND_TABLE COL0="row 0 col 0"
  57.  *           COL1="row 0 col 1" /&gt;
  58.  *     &lt;EMPTY_TABLE/&gt;
  59.  * &lt;/dataset&gt;</pre>
  60.  * <p>
  61.  * To specify null values, omit corresponding attribute.
  62.  * In the above example, missing COL0 and COL2 attributes of TEST_TABLE second row represents null values.
  63.  * <p>
  64.  * Table metadata is deduced from the first row of each table by default. 
  65.  * <b>Beware that DbUnit may think a table misses some columns if the first row of that table has one or more null values.</b>
  66.  * You can do one of the following things to avoid this:
  67.  * <ul>
  68.  * <li>Use a DTD. DbUnit will use the columns declared in the DTD as table metadata. 
  69.  * DbUnit only supports external system URI. The URI can be absolute or relative.
  70.  * </li>
  71.  * <li>Since DBUnit 2.3.0 there is a functionality called "column sensing" which basically 
  72.  * reads in the whole XML into a buffer and dynamically adds new columns as they appear. 
  73.  * It can be used as demonstrated in the following example:
  74.  * <pre>
  75.  *   // since dbunit 2.4.7
  76.  *   FlatXmlDataSetBuilder builder = new FlatXmlDataSetBuilder();
  77.  *   builder.setInputSource(new File("src/xml/flatXmlTableTest.xml"));
  78.  *   builder.setColumnSensing(true);
  79.  *   IDataSet dataSet = builder.build();
  80.  *   
  81.  *   // or dbunit release <= 2.4.6:
  82.  *   boolean enableColumnSensing = true;
  83.  *   IDataSet dataSet = new FlatXmlDataSet(
  84.  *            new File("src/xml/flatXmlTableTest.xml"), false, enableColumnSensing);
  85.  * </pre>
  86.  * </li>
  87.  * </ul>
  88.  * </p>
  89.  * 
  90.  * @author Manuel Laflamme
  91.  * @author gommma (gommma AT users.sourceforge.net)
  92.  * @author Last changed by: $Author$
  93.  * @version $Revision$ $Date$
  94.  * @since 1.0 (Mar 12, 2002) 
  95.  */
  96. public class FlatXmlDataSet extends CachedDataSet
  97. {
  98.     /**
  99.      * Logger for this class
  100.      */
  101.     private static final Logger logger = LoggerFactory.getLogger(FlatXmlDataSet.class);

  103.     /**
  104.      * Creates a new {@link FlatXmlDataSet} with the data of the given producer.
  105.      * @param flatXmlProducer The producer that provides the {@link FlatXmlDataSet} content
  106.      * @throws DataSetException 
  107.      * @since 2.4.7
  108.      */
  109.     public FlatXmlDataSet(FlatXmlProducer flatXmlProducer) throws DataSetException
  110.     {
  111.         super(flatXmlProducer, flatXmlProducer.isCaseSensitiveTableNames());
  112.     }
  113.     
  114.     /**
  115.      * Creates an FlatXmlDataSet object with the specified InputSource.
  116.      * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet}
  117.      */
  118.     public FlatXmlDataSet(InputSource source) throws IOException, DataSetException
  119.     {
  120.         super(new FlatXmlProducer(source));
  121.     }

  123.     /**
  124.      * Creates an FlatXmlDataSet object with the specified xml file.
  125.      * Relative DOCTYPE uri are resolved from the xml file path.
  126.      *
  127.      * @param xmlFile the xml file
  128.      * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet}
  129.      */
  130.     public FlatXmlDataSet(File xmlFile) throws IOException, DataSetException
  131.     {
  132.         this(xmlFile, true);
  133.     }

  135.     /**
  136.      * Creates an FlatXmlDataSet object with the specified xml file.
  137.      * Relative DOCTYPE uri are resolved from the xml file path.
  138.      *
  139.      * @param xmlFile the xml file
  140.      * @param dtdMetadata if <code>false</code> do not use DTD as metadata
  141.      * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet}
  142.      */
  143.     public FlatXmlDataSet(File xmlFile, boolean dtdMetadata)
  144.             throws IOException, DataSetException
  145.     {
  146.         this(xmlFile.toURL(), dtdMetadata);
  147.     }

  149.     /**
  150.      * Creates an FlatXmlDataSet object with the specified xml file.
  151.      * Relative DOCTYPE uri are resolved from the xml file path.
  152.      *
  153.      * @param xmlFile the xml file
  154.      * @param dtdMetadata if <code>false</code> do not use DTD as metadata
  155.      * @param columnSensing Whether or not the columns should be sensed automatically. Every XML row
  156.      * is scanned for columns that have not been there in a previous column.
  157.      * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet}
  158.      */
  159.     public FlatXmlDataSet(File xmlFile, boolean dtdMetadata, boolean columnSensing)
  160.             throws IOException, DataSetException
  161.     {
  162.         this(xmlFile.toURL(), dtdMetadata, columnSensing);
  163.     }

  165.     /**
  166.      * Creates an FlatXmlDataSet object with the specified xml file.
  167.      * Relative DOCTYPE uri are resolved from the xml file path.
  168.      *
  169.      * @param xmlFile the xml file
  170.      * @param dtdMetadata if <code>false</code> do not use DTD as metadata
  171.      * @param columnSensing Whether or not the columns should be sensed automatically. Every XML row
  172.      * is scanned for columns that have not been there in a previous column.
  173.      * @param caseSensitiveTableNames Whether or not this dataset should use case sensitive table names
  174.      * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet}
  175.      */
  176.     public FlatXmlDataSet(File xmlFile, boolean dtdMetadata, boolean columnSensing, boolean caseSensitiveTableNames)
  177.     throws IOException, DataSetException
  178.     {
  179.         this(xmlFile.toURL(), dtdMetadata, columnSensing, caseSensitiveTableNames);
  180.     }

  182.     /**
  183.      * Creates an FlatXmlDataSet object with the specified xml URL.
  184.      * Relative DOCTYPE uri are resolved from the xml file path.
  185.      *
  186.      * @param xmlUrl the xml URL
  187.      * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet}
  188.      */
  189.     public FlatXmlDataSet(URL xmlUrl) throws IOException, DataSetException
  190.     {
  191.         this(xmlUrl, true);
  192.     }

  194.     /**
  195.      * Creates an FlatXmlDataSet object with the specified xml URL.
  196.      * Relative DOCTYPE uri are resolved from the xml file path.
  197.      *
  198.      * @param xmlUrl the xml URL
  199.      * @param dtdMetadata if <code>false</code> do not use DTD as metadata
  200.      * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet}
  201.      */
  202.     public FlatXmlDataSet(URL xmlUrl, boolean dtdMetadata)
  203.             throws IOException, DataSetException
  204.     {
  205.         this(xmlUrl, dtdMetadata, false);
  206.     }
  207.     

  209.     /**
  210.      * Creates an FlatXmlDataSet object with the specified xml URL.
  211.      * Relative DOCTYPE uri are resolved from the xml file path.
  212.      *
  213.      * @param xmlUrl the xml URL
  214.      * @param dtdMetadata if <code>false</code> do not use DTD as metadata
  215.      * @param columnSensing Whether or not the columns should be sensed automatically. Every XML row
  216.      * is scanned for columns that have not been there in a previous column.
  217.      * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet}
  218.      */
  219.     public FlatXmlDataSet(URL xmlUrl, boolean dtdMetadata, boolean columnSensing)
  220.     throws IOException, DataSetException
  221.     {
  222.         super(new FlatXmlProducer(
  223.                 new InputSource(xmlUrl.toString()), dtdMetadata, columnSensing));
  224.     }

  226.     /**
  227.      * Creates an FlatXmlDataSet object with the specified xml file.
  228.      * Relative DOCTYPE uri are resolved from the xml file path.
  229.      *
  230.      * @param xmlUrl the xml file
  231.      * @param dtdMetadata if <code>false</code> do not use DTD as metadata
  232.      * @param columnSensing Whether or not the columns should be sensed automatically. Every XML row
  233.      * is scanned for columns that have not been there in a previous column.
  234.      * @param caseSensitiveTableNames Whether or not this dataset should use case sensitive table names
  235.      * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet}
  236.      */
  237.     public FlatXmlDataSet(URL xmlUrl, boolean dtdMetadata, boolean columnSensing, boolean caseSensitiveTableNames)
  238.     throws IOException, DataSetException
  239.     {
  240.         super(new FlatXmlProducer(
  241.                   new InputSource(xmlUrl.toString()), dtdMetadata, columnSensing, caseSensitiveTableNames), 
  242.               caseSensitiveTableNames);
  243.     }

  245.     /**
  246.      * Creates an FlatXmlDataSet object with the specified xml reader.
  247.      * Relative DOCTYPE uri are resolved from the current working directory.
  248.      *
  249.      * @param xmlReader the xml reader
  250.      * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet}
  251.      */
  252.     public FlatXmlDataSet(Reader xmlReader) throws IOException, DataSetException
  253.     {
  254.         this(xmlReader, true);
  255.     }

  257.     /**
  258.      * Creates an FlatXmlDataSet object with the specified xml reader.
  259.      * Relative DOCTYPE uri are resolved from the current working directory.
  260.      *
  261.      * @param xmlReader the xml reader
  262.      * @param dtdMetadata if <code>false</code> do not use DTD as metadata
  263.      * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet}
  264.      */
  265.     public FlatXmlDataSet(Reader xmlReader, boolean dtdMetadata)
  266.             throws IOException, DataSetException
  267.     {
  268.         this(xmlReader, dtdMetadata, false, false);
  269.     }

  271.     /**
  272.      * Creates an FlatXmlDataSet object with the specified xml file.
  273.      * Relative DOCTYPE uri are resolved from the xml file path.
  274.      *
  275.      * @param xmlReader the xml reader
  276.      * @param dtdMetadata if <code>false</code> do not use DTD as metadata
  277.      * @param columnSensing Whether or not the columns should be sensed automatically. Every XML row
  278.      * is scanned for columns that have not been there in a previous column.
  279.      * @param caseSensitiveTableNames Whether or not this dataset should use case sensitive table names
  280.      * @since 2.4.3
  281.      * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet}
  282.      */
  283.     public FlatXmlDataSet(Reader xmlReader, boolean dtdMetadata, boolean columnSensing, boolean caseSensitiveTableNames)
  284.     throws IOException, DataSetException
  285.     {
  286.         super(new FlatXmlProducer(new InputSource(xmlReader), dtdMetadata, columnSensing, caseSensitiveTableNames),
  287.                 caseSensitiveTableNames);
  288.     }

  290.     /**
  291.      * Creates an FlatXmlDataSet object with the specified xml and dtd readers.
  292.      *
  293.      * @param xmlReader the xml reader
  294.      * @param dtdReader the dtd reader
  295.      * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet}
  296.      */
  297.     public FlatXmlDataSet(Reader xmlReader, Reader dtdReader)
  298.             throws IOException, DataSetException
  299.     {
  300.         this(xmlReader, new FlatDtdDataSet(dtdReader));
  301.     }

  303.     /**
  304.      * Creates an FlatXmlDataSet object with the specified xml reader.
  305.      *
  306.      * @param xmlReader the xml reader
  307.      * @param metaDataSet the dataset used as metadata source.
  308.      * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet}
  309.      */
  310.     public FlatXmlDataSet(Reader xmlReader, IDataSet metaDataSet)
  311.             throws IOException, DataSetException
  312.     {
  313.         super(new FlatXmlProducer(new InputSource(xmlReader), metaDataSet));
  314.     }

  316.     /**
  317.      * Creates an FlatXmlDataSet object with the specified xml input stream.
  318.      * Relative DOCTYPE uri are resolved from the current working directory.
  319.      *
  320.      * @param xmlStream the xml input stream
  321.      * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet}
  322.      */
  323.     public FlatXmlDataSet(InputStream xmlStream) throws IOException, DataSetException
  324.     {
  325.         this(xmlStream, true);
  326.     }

  328.     /**
  329.      * Creates an FlatXmlDataSet object with the specified xml input stream.
  330.      * Relative DOCTYPE uri are resolved from the current working directory.
  331.      *
  332.      * @param xmlStream the xml input stream
  333.      * @param dtdMetadata if <code>false</code> do not use DTD as metadata
  334.      * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet}
  335.      */
  336.     public FlatXmlDataSet(InputStream xmlStream, boolean dtdMetadata)
  337.             throws IOException, DataSetException
  338.     {
  339.         super(new FlatXmlProducer(new InputSource(xmlStream), dtdMetadata));
  340.     }

  342.     /**
  343.      * Creates an FlatXmlDataSet object with the specified xml and dtd input
  344.      * stream.
  345.      *
  346.      * @param xmlStream the xml input stream
  347.      * @param dtdStream the dtd input stream
  348.      * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet}
  349.      */
  350.     public FlatXmlDataSet(InputStream xmlStream, InputStream dtdStream)
  351.             throws IOException, DataSetException
  352.     {
  353.         this(xmlStream, new FlatDtdDataSet(dtdStream));
  354.     }

  356.     /**
  357.      * Creates an FlatXmlDataSet object with the specified xml input stream.
  358.      *
  359.      * @param xmlStream the xml input stream
  360.      * @param metaDataSet the dataset used as metadata source.
  361.      * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet}
  362.      */
  363.     public FlatXmlDataSet(InputStream xmlStream, IDataSet metaDataSet)
  364.             throws IOException, DataSetException
  365.     {
  366.         super(new FlatXmlProducer(new InputSource(xmlStream), metaDataSet));
  367.     }

  369.     /**
  370.      * Write the specified dataset to the specified output stream as xml.
  371.      */
  372.     public static void write(IDataSet dataSet, OutputStream out)
  373.             throws IOException, DataSetException
  374.     {
  375.         logger.debug("write(dataSet={}, out={}) - start", dataSet, out);

  377.         FlatXmlWriter datasetWriter = new FlatXmlWriter(out);
  378.         datasetWriter.setIncludeEmptyTable(true);
  379.         datasetWriter.write(dataSet);
  380.     }

  382.     /**
  383.      * Write the specified dataset to the specified writer as xml.
  384.      */
  385.     public static void write(IDataSet dataSet, Writer writer)
  386.             throws IOException, DataSetException
  387.     {
  388.         logger.debug("write(dataSet={}, writer={}) - start", dataSet, writer);
  389.         write(dataSet, writer, null);
  390.     }

  392.     /**
  393.      * Write the specified dataset to the specified writer as xml.
  394.      */
  395.     public static void write(IDataSet dataSet, Writer writer, Charset charset)
  396.             throws IOException, DataSetException
  397.     {
  398.         logger.debug("write(dataSet={}, writer={}, charset={}) - start",
  399.                 dataSet, writer, charset);

  401.         final FlatXmlWriter datasetWriter = new FlatXmlWriter(writer, charset);
  402.         datasetWriter.setIncludeEmptyTable(true);
  403.         datasetWriter.write(dataSet);
  404.     }

  406.     /**
  407.      * Write a DTD for the specified dataset to the specified output.
  408.      * @deprecated use {@link FlatDtdDataSet#write}
  409.      */
  410.     public static void writeDtd(IDataSet dataSet, OutputStream out)
  411.             throws IOException, DataSetException
  412.     {
  413.         logger.debug("writeDtd(dataSet={}, out={}) - start", dataSet, out);
  414.         FlatDtdDataSet.write(dataSet, out);
  415.     }
  416. }











Created with JaCoCo 0.8.3.201901230119