diff --git a/pom.xml b/pom.xml index 1bc35aed0..349754990 100644 --- a/pom.xml +++ b/pom.xml @@ -835,6 +835,11 @@ org.apache.maven.plugins maven-javadoc-plugin ${javadocPluginVersion} + + + -Xdoclint:all,-missing + + attach-javadocs diff --git a/src/changes/changes.xml b/src/changes/changes.xml index 0f3e07512..7862b37bb 100644 --- a/src/changes/changes.xml +++ b/src/changes/changes.xml @@ -215,6 +215,9 @@ Update github_actions dependency actions/setup-java from 5.6.0 to 5.7.0 (#903). + + Fix the Javadoc @param/@return/@throws gaps across the main source tree that issue 902's from-scratch doclint pass left unaddressed since they are warnings, not build-failing errors: missing one-sentence summaries on classes/interfaces/methods/fields whose doc block was tag-only (doclint's "no main description"), entirely missing or description-less @param/@return/@throws tags, and missing field/method comments including on org.dbunit.assertion.DbComparisonFailure's and PropertyChangeMulticaster's private fields and readObject/writeObject methods, which doclint checks regardless of visibility once a class implements Serializable. + diff --git a/src/main/java/org/dbunit/AbstractDatabaseTester.java b/src/main/java/org/dbunit/AbstractDatabaseTester.java index 74ee9a6b8..5dd2123cb 100644 --- a/src/main/java/org/dbunit/AbstractDatabaseTester.java +++ b/src/main/java/org/dbunit/AbstractDatabaseTester.java @@ -163,6 +163,8 @@ protected String getSchema() /** * Returns the DatabaseOperation to call when starting the test. + * + * @return the setup {@link DatabaseOperation}. */ public DatabaseOperation getSetUpOperation() { @@ -173,6 +175,8 @@ public DatabaseOperation getSetUpOperation() /** * Returns the DatabaseOperation to call when ending the test. + * + * @return the tear-down {@link DatabaseOperation}. */ public DatabaseOperation getTearDownOperation() { diff --git a/src/main/java/org/dbunit/Assertion.java b/src/main/java/org/dbunit/Assertion.java index aa2bdf429..b8c2ebe01 100644 --- a/src/main/java/org/dbunit/Assertion.java +++ b/src/main/java/org/dbunit/Assertion.java @@ -62,6 +62,13 @@ private Assertion() } /** + * Asserts that the two specified datasets' tables are equal, ignoring the given columns. + * + * @param expectedDataset dataset containing the expected results. + * @param actualDataset dataset containing the actual results. + * @param tableName name of the table to compare. + * @param ignoreCols columns to ignore during comparison. + * @throws DatabaseUnitException if an error occurs during comparison. * @see DbUnitAssert#assertEqualsIgnoreCols(IDataSet, IDataSet, String, * String[]) */ @@ -74,6 +81,12 @@ public static void assertEqualsIgnoreCols(final IDataSet expectedDataset, } /** + * Asserts that the two specified tables are equal, ignoring the given columns. + * + * @param expectedTable table containing the expected results. + * @param actualTable table containing the actual results. + * @param ignoreCols columns to ignore during comparison. + * @throws DatabaseUnitException if an error occurs during comparison. * @see DbUnitAssert#assertEqualsIgnoreCols(ITable, ITable, String[]) */ public static void assertEqualsIgnoreCols(final ITable expectedTable, @@ -85,6 +98,15 @@ public static void assertEqualsIgnoreCols(final ITable expectedTable, } /** + * Asserts that the specified dataset table matches the given query's result, ignoring the given columns. + * + * @param expectedDataset dataset containing the expected results. + * @param connection connection used to query the actual results. + * @param sqlQuery SQL query used to obtain the actual results. + * @param tableName name of the table being compared. + * @param ignoreCols columns to ignore during comparison. + * @throws DatabaseUnitException if an error occurs during comparison. + * @throws SQLException if an error occurs while executing the query. * @see DbUnitAssert#assertEqualsByQuery(IDataSet, IDatabaseConnection, * String, String, String[]) */ @@ -98,6 +120,15 @@ public static void assertEqualsByQuery(final IDataSet expectedDataset, } /** + * Asserts that the specified table matches the given query's result, ignoring the given columns. + * + * @param expectedTable table containing the expected results. + * @param connection connection used to query the actual results. + * @param tableName name of the table being compared. + * @param sqlQuery SQL query used to obtain the actual results. + * @param ignoreCols columns to ignore during comparison. + * @throws DatabaseUnitException if an error occurs during comparison. + * @throws SQLException if an error occurs while executing the query. * @see DbUnitAssert#assertEqualsByQuery(ITable, IDatabaseConnection, * String, String, String[]) */ @@ -111,6 +142,11 @@ public static void assertEqualsByQuery(final ITable expectedTable, } /** + * Asserts that the two specified datasets are equal. + * + * @param expectedDataSet dataset containing the expected results. + * @param actualDataSet dataset containing the actual results. + * @throws DatabaseUnitException if an error occurs during comparison. * @see DbUnitAssert#assertEquals(IDataSet, IDataSet) */ public static void assertEquals(final IDataSet expectedDataSet, @@ -120,6 +156,12 @@ public static void assertEquals(final IDataSet expectedDataSet, } /** + * Asserts that the two specified datasets are equal. + * + * @param expectedDataSet dataset containing the expected results. + * @param actualDataSet dataset containing the actual results. + * @param failureHandler the failure handler used to report mismatches. + * @throws DatabaseUnitException if an error occurs during comparison. * @see DbUnitAssert#assertEquals(IDataSet, IDataSet, FailureHandler) * @since 2.4 */ @@ -132,6 +174,11 @@ public static void assertEquals(final IDataSet expectedDataSet, } /** + * Asserts that the two specified tables are equal. + * + * @param expectedTable table containing the expected results. + * @param actualTable table containing the actual results. + * @throws DatabaseUnitException if an error occurs during comparison. * @see DbUnitAssert#assertEquals(ITable, ITable) */ public static void assertEquals(final ITable expectedTable, @@ -141,6 +188,12 @@ public static void assertEquals(final ITable expectedTable, } /** + * Asserts that the two specified tables are equal. + * + * @param expectedTable table containing the expected results. + * @param actualTable table containing the actual results. + * @param additionalColumnInfo additional columns to include in failure messages. + * @throws DatabaseUnitException if an error occurs during comparison. * @see DbUnitAssert#assertEquals(ITable, ITable, Column[]) */ public static void assertEquals(final ITable expectedTable, @@ -152,6 +205,12 @@ public static void assertEquals(final ITable expectedTable, } /** + * Asserts that the two specified tables are equal. + * + * @param expectedTable table containing the expected results. + * @param actualTable table containing the actual results. + * @param failureHandler the failure handler used to report mismatches. + * @throws DatabaseUnitException if an error occurs during comparison. * @see DbUnitAssert#assertEquals(ITable, ITable, FailureHandler) * @since 2.4 */ @@ -164,6 +223,13 @@ public static void assertEquals(final ITable expectedTable, } /** + * Asserts that the two specified datasets are equal, using the given value comparers. + * + * @param expectedDataSet dataset containing the expected results. + * @param actualDataSet dataset containing the actual results. + * @param defaultValueComparer the value comparer used when no more specific comparer is configured. + * @param tableColumnValueComparers the per-table, per-column value comparers to use. + * @throws DatabaseUnitException if an error occurs during comparison. * @see DbUnitValueComparerAssert#assertWithValueComparer(IDataSet, * IDataSet, ValueComparer, Map) * @since 2.6.0 @@ -179,6 +245,13 @@ public static void assertWithValueComparer(final IDataSet expectedDataSet, } /** + * Asserts that the two specified tables are equal, using the given value comparers. + * + * @param expectedTable table containing the expected results. + * @param actualTable table containing the actual results. + * @param defaultValueComparer the value comparer used when no more specific comparer is configured. + * @param columnValueComparers the per-column value comparers to use. + * @throws DatabaseUnitException if an error occurs during comparison. * @see DbUnitValueComparerAssert#assertWithValueComparer(ITable, ITable, * ValueComparer, Map) * @since 2.6.0 @@ -193,6 +266,14 @@ public static void assertWithValueComparer(final ITable expectedTable, } /** + * Asserts that the two specified datasets are equal, using the given value comparers. + * + * @param expectedDataSet dataset containing the expected results. + * @param actualDataSet dataset containing the actual results. + * @param failureHandler the failure handler used to report mismatches. + * @param defaultValueComparer the value comparer used when no more specific comparer is configured. + * @param tableColumnValueComparers the per-table, per-column value comparers to use. + * @throws DatabaseUnitException if an error occurs during comparison. * @see DbUnitValueComparerAssert#assertWithValueComparer(IDataSet, * IDataSet, FailureHandler, ValueComparer, Map) * @since 2.6.0 @@ -209,6 +290,14 @@ public static void assertWithValueComparer(final IDataSet expectedDataSet, } /** + * Asserts that the two specified tables are equal, using the given value comparers. + * + * @param expectedTable table containing the expected results. + * @param actualTable table containing the actual results. + * @param additionalColumnInfo additional columns to include in failure messages. + * @param defaultValueComparer the value comparer used when no more specific comparer is configured. + * @param columnValueComparers the per-column value comparers to use. + * @throws DatabaseUnitException if an error occurs during comparison. * @see DbUnitValueComparerAssert#assertWithValueComparer(ITable, ITable, * Column[], ValueComparer, Map) * @since 2.6.0 @@ -225,6 +314,14 @@ public static void assertWithValueComparer(final ITable expectedTable, } /** + * Asserts that the two specified tables are equal, using the given value comparers. + * + * @param expectedTable table containing the expected results. + * @param actualTable table containing the actual results. + * @param failureHandler the failure handler used to report mismatches. + * @param defaultValueComparer the value comparer used when no more specific comparer is configured. + * @param columnValueComparers the per-column value comparers to use. + * @throws DatabaseUnitException if an error occurs during comparison. * @see DbUnitValueComparerAssert#assertWithValueComparer(ITable, ITable, * FailureHandler, ValueComparer, Map) * @since 2.6.0 @@ -240,11 +337,22 @@ public static void assertWithValueComparer(final ITable expectedTable, columnValueComparers); } + /** + * Returns the shared {@link DbUnitAssert} instance used for equals-based comparisons. + * + * @return the shared {@link DbUnitAssert} instance. + */ public static DbUnitAssert getEqualsInstance() { return EQUALS_INSTANCE; } + /** + * Returns the shared {@link DbUnitValueComparerAssert} instance used for value-comparer-based + * comparisons. + * + * @return the shared {@link DbUnitValueComparerAssert} instance. + */ public static DbUnitValueComparerAssert getValueCompareInstance() { return VALUE_COMPARE_INSTANCE; diff --git a/src/main/java/org/dbunit/DBTestCase.java b/src/main/java/org/dbunit/DBTestCase.java index a0f05397f..13c90d75d 100644 --- a/src/main/java/org/dbunit/DBTestCase.java +++ b/src/main/java/org/dbunit/DBTestCase.java @@ -43,10 +43,18 @@ public abstract class DBTestCase extends DatabaseTestCase { */ private static final Logger logger = LoggerFactory.getLogger(DBTestCase.class); + /** + * Creates a testCase with no name. + */ public DBTestCase() { super(); } + /** + * Creates a testCase with the given name. + * + * @param name the test case name. + */ public DBTestCase(String name) { super(name); } diff --git a/src/main/java/org/dbunit/DataSourceBasedDBTestCase.java b/src/main/java/org/dbunit/DataSourceBasedDBTestCase.java index e7733fa1f..d3da77cb3 100644 --- a/src/main/java/org/dbunit/DataSourceBasedDBTestCase.java +++ b/src/main/java/org/dbunit/DataSourceBasedDBTestCase.java @@ -42,10 +42,18 @@ public abstract class DataSourceBasedDBTestCase extends DBTestCase */ private static final Logger logger = LoggerFactory.getLogger(DataSourceBasedDBTestCase.class); + /** + * Creates a testCase with no name. + */ public DataSourceBasedDBTestCase() { } + /** + * Creates a testCase with the given name. + * + * @param name the test case name. + */ public DataSourceBasedDBTestCase( String name ) { super( name ); @@ -65,6 +73,8 @@ protected IDatabaseTester newDatabaseTester() /** * Returns the test DataSource. + * + * @return the test DataSource. */ protected abstract DataSource getDataSource(); } diff --git a/src/main/java/org/dbunit/DatabaseTestCase.java b/src/main/java/org/dbunit/DatabaseTestCase.java index b0510932a..60be6b47c 100644 --- a/src/main/java/org/dbunit/DatabaseTestCase.java +++ b/src/main/java/org/dbunit/DatabaseTestCase.java @@ -49,25 +49,44 @@ public abstract class DatabaseTestCase implements InvocationInterceptor { private final String name; + /** + * Default constructor. + */ protected DatabaseTestCase() { this.name = null; } + /** + * Constructs a test case with the given name. + * + * @param name the test case name. + */ protected DatabaseTestCase(final String name) { this.name = name; } + /** + * Returns this test case's name. + * + * @return this test case's name. + */ public String getName() { return this.name; } /** * Returns the test database connection. + * + * @return the test database connection. + * @throws Exception if the connection cannot be retrieved or created. */ protected abstract IDatabaseConnection getConnection() throws Exception; /** * Returns the test dataset. + * + * @return the test dataset. + * @throws Exception if the dataset cannot be retrieved or created. */ protected abstract IDataSet getDataSet() throws Exception; @@ -75,7 +94,9 @@ public String getName() { * Creates a IDatabaseTester for this testCase.
* * A {@link DefaultDatabaseTester} is used by default. - * @throws Exception + * + * @return the newly created database tester. + * @throws Exception if the database tester cannot be created. */ protected IDatabaseTester newDatabaseTester() throws Exception{ logger.debug("newDatabaseTester() - start"); @@ -100,7 +121,9 @@ protected void setUpDatabaseConfig(final DatabaseConfig config) * Gets the IDatabaseTester for this testCase.
* If the IDatabaseTester is not set yet, this method calls * newDatabaseTester() to obtain a new instance. - * @throws Exception + * + * @return the IDatabaseTester for this testCase. + * @throws Exception if a new database tester cannot be created. */ protected IDatabaseTester getDatabaseTester() throws Exception { if ( this.tester == null ) { @@ -112,6 +135,9 @@ protected IDatabaseTester getDatabaseTester() throws Exception { /** * Close the specified connection. Override this method of you want to * keep your connection alive between tests. + * + * @param connection the connection to close. + * @throws Exception if the connection cannot be closed. * @deprecated since 2.4.4 define a user defined {@link #getOperationListener()} in advance */ @Deprecated @@ -125,6 +151,9 @@ protected void closeConnection(final IDatabaseConnection connection) throws Exce /** * Returns the database operation executed in test setup. + * + * @return the database operation executed in test setup. + * @throws Exception if the operation cannot be determined. */ protected DatabaseOperation getSetUpOperation() throws Exception { @@ -133,6 +162,9 @@ protected DatabaseOperation getSetUpOperation() throws Exception /** * Returns the database operation executed in test cleanup. + * + * @return the database operation executed in test cleanup. + * @throws Exception if the operation cannot be determined. */ protected DatabaseOperation getTearDownOperation() throws Exception { @@ -142,6 +174,12 @@ protected DatabaseOperation getTearDownOperation() throws Exception //////////////////////////////////////////////////////////////////////////// // TestCase class + /** + * Prepares the database, using the database tester, connection, and dataset from + * {@link #getDatabaseTester()}, {@link #getConnection()}, and {@link #getDataSet()}. + * + * @throws Exception if the setup operation fails. + */ protected void setUp() throws Exception { logger.debug("setUp() - start"); @@ -154,6 +192,11 @@ protected void setUp() throws Exception databaseTester.onSetup(); } + /** + * Runs the tear-down operation and releases the database tester. + * + * @throws Exception if the tear-down operation fails. + */ protected void tearDown() throws Exception { logger.debug("tearDown() - start"); @@ -216,6 +259,9 @@ private void runTearDownOperation() throws Exception } /** + * Returns the operation listener used by the database tester, creating a default one on + * first access. + * * @return The {@link IOperationListener} to be used by the {@link IDatabaseTester}. * @since 2.4.4 */ diff --git a/src/main/java/org/dbunit/DatabaseUnitException.java b/src/main/java/org/dbunit/DatabaseUnitException.java index c3b9fdca6..eee689722 100644 --- a/src/main/java/org/dbunit/DatabaseUnitException.java +++ b/src/main/java/org/dbunit/DatabaseUnitException.java @@ -49,6 +49,8 @@ public DatabaseUnitException() /** * Constructs an DatabaseUnitException with the specified detail * message and no encapsulated exception. + * + * @param msg the detail message. */ public DatabaseUnitException(String msg) { @@ -58,6 +60,9 @@ public DatabaseUnitException(String msg) /** * Constructs an DatabaseUnitException with the specified detail * message and encapsulated exception. + * + * @param msg the detail message. + * @param e the encapsulated exception. */ public DatabaseUnitException(String msg, Throwable e) { @@ -67,6 +72,8 @@ public DatabaseUnitException(String msg, Throwable e) /** * Constructs an DatabaseUnitException with the encapsulated * exception and use string representation as detail message. + * + * @param e the encapsulated exception. */ public DatabaseUnitException(Throwable e) { @@ -76,6 +83,7 @@ public DatabaseUnitException(Throwable e) /** * Returns the nested exception or null if none. * @deprecated Use {@link #getCause()} to retrieve the nested exception + * @return the nested exception, or null if none. */ public Throwable getException() { diff --git a/src/main/java/org/dbunit/DatabaseUnitRuntimeException.java b/src/main/java/org/dbunit/DatabaseUnitRuntimeException.java index b625b0900..f80d82b8b 100644 --- a/src/main/java/org/dbunit/DatabaseUnitRuntimeException.java +++ b/src/main/java/org/dbunit/DatabaseUnitRuntimeException.java @@ -50,7 +50,7 @@ public DatabaseUnitRuntimeException() /** * Constructs an DatabaseUnitRuntimeException with the specified * detail message and no encapsulated exception. - * @param msg Exception message + * @param msg the detail message. */ public DatabaseUnitRuntimeException(String msg) { @@ -60,7 +60,7 @@ public DatabaseUnitRuntimeException(String msg) /** * Constructs an DatabaseUnitRuntimeException with the specified * detail message and encapsulated exception. - * @param msg + * @param msg the detail message. * @param cause The cause of this exception */ public DatabaseUnitRuntimeException(String msg, Throwable cause) @@ -81,6 +81,7 @@ public DatabaseUnitRuntimeException(Throwable cause) /** * Returns the encapsulated exception or null if none. * @deprecated Use {@link Exception#getCause()} instead + * @return the encapsulated exception, or null if none. */ public Throwable getException() { diff --git a/src/main/java/org/dbunit/DefaultExpectedDataSetAndVerifyTableDefinitionVerifier.java b/src/main/java/org/dbunit/DefaultExpectedDataSetAndVerifyTableDefinitionVerifier.java index 1b8960a22..8c6b26a04 100644 --- a/src/main/java/org/dbunit/DefaultExpectedDataSetAndVerifyTableDefinitionVerifier.java +++ b/src/main/java/org/dbunit/DefaultExpectedDataSetAndVerifyTableDefinitionVerifier.java @@ -53,6 +53,14 @@ public void verify(final VerifyTableDefinition[] verifyTableDefinitions, } } + /** + * Logs the mismatch and delegates to {@link #failOnMismatch(DatabaseConfig, Set)}. + * + * @param verifyTableDefinitions the configured table definitions to verify. + * @param expectedTableNames the table names present in the expected dataset. + * @param config the database configuration in effect. + * @throws DataSetException if the mismatch is not allowed to be suppressed. + */ protected void handleCountMismatch( final VerifyTableDefinition[] verifyTableDefinitions, final String[] expectedTableNames, final DatabaseConfig config) @@ -74,6 +82,13 @@ protected void handleCountMismatch( failOnMismatch(config, mismatchedTableNames); } + /** + * Returns the expected table names that have no corresponding {@link VerifyTableDefinition}. + * + * @param verifyTableDefinitions the configured table definitions to verify. + * @param expectedTableNames the table names present in the expected dataset. + * @return the expected table names with no corresponding {@link VerifyTableDefinition}. + */ protected Set makeMismatchedTableNamesList( final VerifyTableDefinition[] verifyTableDefinitions, final String[] expectedTableNames) @@ -101,6 +116,13 @@ protected Set makeMismatchedTableNamesList( return tables; } + /** + * Returns whether the given expected table name has a corresponding {@link VerifyTableDefinition}. + * + * @param verifyTableDefinitions the configured table definitions to search. + * @param expectedTableName the expected table name to look for. + * @return true if a corresponding {@link VerifyTableDefinition} exists. + */ protected boolean isVerifyTableDefinitionsHasTable( final VerifyTableDefinition[] verifyTableDefinitions, final String expectedTableName) @@ -119,6 +141,14 @@ protected boolean isVerifyTableDefinitionsHasTable( return isExpectedTableFound; } + /** + * Fails with a {@link DataSetException} listing the mismatched tables, unless + * {@link DatabaseConfig#PROPERTY_ALLOW_VERIFYTABLEDEFINITION_EXPECTEDTABLE_COUNT_MISMATCH} is set. + * + * @param config the database configuration in effect. + * @param mismatchCountTables the expected table names with no corresponding {@link VerifyTableDefinition}. + * @throws DataSetException if the mismatch is not allowed to be suppressed. + */ protected void failOnMismatch(final DatabaseConfig config, final Set mismatchCountTables) throws DataSetException { diff --git a/src/main/java/org/dbunit/DefaultOperationListener.java b/src/main/java/org/dbunit/DefaultOperationListener.java index 78653cc21..2d1a14729 100644 --- a/src/main/java/org/dbunit/DefaultOperationListener.java +++ b/src/main/java/org/dbunit/DefaultOperationListener.java @@ -41,7 +41,6 @@ public class DefaultOperationListener implements IOperationListener{ */ private static final Logger logger = LoggerFactory.getLogger(DefaultOperationListener.class); - public void connectionRetrieved(IDatabaseConnection connection) { logger.debug("connectionCreated(connection={}) - start", connection); // Is by default a no-op diff --git a/src/main/java/org/dbunit/DefaultPrepAndExpectedTestCase.java b/src/main/java/org/dbunit/DefaultPrepAndExpectedTestCase.java index cc8d02a9e..bf405eb54 100644 --- a/src/main/java/org/dbunit/DefaultPrepAndExpectedTestCase.java +++ b/src/main/java/org/dbunit/DefaultPrepAndExpectedTestCase.java @@ -85,6 +85,7 @@ public class DefaultPrepAndExpectedTestCase extends DBTestCase private static final String DATABASE_TESTER_IS_NULL_MSG = "databaseTester is null; must configure or set it first"; + /** Message prefix used for wrapped test failures. */ public static final String TEST_ERROR_MSG = "DbUnit test error."; private IDatabaseTester databaseTester; @@ -462,6 +463,8 @@ public Object runTest(final VerifyTableDefinition[] verifyTables, * * @param testSteps * The test steps to run. + * @return the user-defined object returned by the test steps. + * @throws Exception if the test steps fail. */ protected Object runTestSteps(final PrepAndExpectedTestCaseSteps testSteps) throws Exception @@ -590,7 +593,7 @@ protected void tearDown() throws Exception * cleanupData() for this test's lifecycle rather than a fresh one, and * leaves it open; cleanupData() closes it. See #800. * - * @throws Exception + * @throws Exception if preparing the data fails. */ public void setupData() throws Exception { @@ -678,6 +681,13 @@ public void verifyData() throws Exception } } + /** + * Verifies a single table's actual data against its expected data. + * + * @param connection the database connection to load the actual data from. + * @param verifyTableDefinition the table definition to verify. + * @throws Exception if verifying the table fails. + */ protected void verifyData(final IDatabaseConnection connection, final VerifyTableDefinition verifyTableDefinition) throws Exception { @@ -701,6 +711,13 @@ protected void verifyData(final IDatabaseConnection connection, defaultValueComparer, columnValueComparers); } + /** + * Loads the given table's expected data from the expected dataset. + * + * @param tableName the name of the table to load. + * @return the table's expected data. + * @throws DataSetException if loading the table fails. + */ public ITable loadTableDataFromDataSet(final String tableName) throws DataSetException { @@ -723,6 +740,14 @@ public ITable loadTableDataFromDataSet(final String tableName) return table; } + /** + * Loads the given table's actual data from the database. + * + * @param tableName the name of the table to load. + * @param connection the database connection to load the data from. + * @return the table's actual data. + * @throws Exception if loading the table fails. + */ public ITable loadTableDataFromDatabase(final String tableName, final IDatabaseConnection connection) throws Exception { @@ -770,7 +795,7 @@ public ITable loadTableDataFromDatabase(final String tableName, * columns. Key is column name, value is the * {@link ValueComparer}. Can be null and will * default to defaultValueComparer for all columns in all tables. - * @throws DatabaseUnitException + * @throws DatabaseUnitException if the tables' row counts, columns, or data do not match. */ protected void verifyData(final ITable expectedTable, final ITable actualTable, final String[] excludeColumns, @@ -834,7 +859,7 @@ protected void verifyData(final ITable expectedTable, * If expected column definitions exist and are {@link DataType.UNKNOWN}, * make them from actual table column definitions. * - * @throws DataSetException + * @throws DataSetException if the actual table's columns cannot be retrieved. */ private Column[] makeExpectedTableColumns(final Column[] actualColumns, final ITableMetaData expectedTableMetaData) throws DataSetException @@ -915,7 +940,16 @@ private void logSortedTable(final String tableTypeName, } } - /** Compare the tables, enables easy overriding. */ + /** + * Compare the tables, enables easy overriding. + * + * @param expectedTable the table containing all expected results. + * @param actualTable the table containing all actual results. + * @param additionalColumnInfo the additional columns to include in failure messages. + * @param defaultValueComparer the value comparer used when no more specific comparer is configured. + * @param columnValueComparers the per-column value comparers to use. + * @throws DatabaseUnitException if the tables' row counts, columns, or data do not match. + */ protected void compareData(final ITable expectedTable, final ITable actualTable, final Column[] additionalColumnInfo, final ValueComparer defaultValueComparer, @@ -935,6 +969,8 @@ protected void compareData(final ITable expectedTable, * Not null. * @param excludeColumns * Nullable. + * @return the additional column info, excluding excludeColumns. + * @throws DataSetException if the expected table's columns cannot be retrieved. */ protected Column[] makeAdditionalColumnInfo(final ITable expectedTable, final String[] excludeColumns) throws DataSetException @@ -954,6 +990,7 @@ protected Column[] makeAdditionalColumnInfo(final ITable expectedTable, * Not null. * @param allColumns * Not null. + * @return the additional column info, excluding excludeColumns. */ protected Column[] makeAdditionalColumnInfo(final String[] excludeColumns, final Column[] allColumns) @@ -1046,7 +1083,7 @@ public IDataSet makeCompositeDataSet(final String[] dataFiles, * @param includeColumns * The include filters; use null to mean include all. * @return The filtered table. - * @throws DataSetException + * @throws DataSetException if applying the filters fails. */ public ITable applyColumnFilters(final ITable table, final String[] excludeColumns, final String[] includeColumns) @@ -1240,11 +1277,21 @@ public void setVerifyTableDefs( this.verifyTableDefs = verifyTableDefs; } + /** + * Returns the verifier used to check that verify table definitions and the expected dataset agree. + * + * @return the verifier used to check that verify table definitions and the expected dataset agree. + */ public ExpectedDataSetAndVerifyTableDefinitionVerifier getExpectedDataSetAndVerifyTableDefinitionVerifier() { return expectedDataSetAndVerifyTableDefinitionVerifier; } + /** + * Sets the verifier used to check that verify table definitions and the expected dataset agree. + * + * @param expectedDataSetAndVerifyTableDefinitionVerifier the verifier to use. + */ public void setExpectedDataSetAndVerifyTableDefinitionVerifier( final ExpectedDataSetAndVerifyTableDefinitionVerifier expectedDataSetAndVerifyTableDefinitionVerifier) { diff --git a/src/main/java/org/dbunit/ExpectedDataSetAndVerifyTableDefinitionVerifier.java b/src/main/java/org/dbunit/ExpectedDataSetAndVerifyTableDefinitionVerifier.java index 978515734..99ed8a6d4 100644 --- a/src/main/java/org/dbunit/ExpectedDataSetAndVerifyTableDefinitionVerifier.java +++ b/src/main/java/org/dbunit/ExpectedDataSetAndVerifyTableDefinitionVerifier.java @@ -16,6 +16,11 @@ public interface ExpectedDataSetAndVerifyTableDefinitionVerifier /** * Verify {@link VerifyTableDefinition}s and expectedDataSet configurations * agree. + * + * @param verifyTableDefinitions the table definitions to verify. + * @param expectedDataSet the expected dataset to verify against. + * @param config the database configuration in effect. + * @throws DataSetException if the verify table definitions and expected dataset disagree. */ void verify(VerifyTableDefinition[] verifyTableDefinitions, IDataSet expectedDataSet, DatabaseConfig config) diff --git a/src/main/java/org/dbunit/JdbcBasedDBTestCase.java b/src/main/java/org/dbunit/JdbcBasedDBTestCase.java index 306ed0d22..f42373f45 100644 --- a/src/main/java/org/dbunit/JdbcBasedDBTestCase.java +++ b/src/main/java/org/dbunit/JdbcBasedDBTestCase.java @@ -41,11 +41,19 @@ public abstract class JdbcBasedDBTestCase extends DBTestCase */ private static final Logger logger = LoggerFactory.getLogger(JdbcBasedDBTestCase.class); + /** + * Default constructor. + */ public JdbcBasedDBTestCase() { super(); } + /** + * Constructs a test case with the given name. + * + * @param name the test case name. + */ public JdbcBasedDBTestCase( String name ) { super( name ); @@ -72,11 +80,15 @@ protected IDatabaseTester newDatabaseTester() throws ClassNotFoundException /** * Returns the test connection url. + * + * @return the test connection url. */ protected abstract String getConnectionUrl(); /** * Returns the JDBC driver classname. + * + * @return the JDBC driver classname. */ protected abstract String getDriverClass(); @@ -84,6 +96,8 @@ protected IDatabaseTester newDatabaseTester() throws ClassNotFoundException * Returns the password for the connection.
* Subclasses may override this method to provide a custom password.
* Default implementations returns null. + * + * @return the password for the connection. */ protected String getPassword() { @@ -94,6 +108,8 @@ protected String getPassword() * Returns the username for the connection.
* Subclasses may override this method to provide a custom username.
* Default implementations returns null. + * + * @return the username for the connection. */ protected String getUsername() { diff --git a/src/main/java/org/dbunit/JndiBasedDBTestCase.java b/src/main/java/org/dbunit/JndiBasedDBTestCase.java index 07b9c09fa..8e0d43c52 100644 --- a/src/main/java/org/dbunit/JndiBasedDBTestCase.java +++ b/src/main/java/org/dbunit/JndiBasedDBTestCase.java @@ -41,10 +41,18 @@ public abstract class JndiBasedDBTestCase extends DBTestCase */ private static final Logger logger = LoggerFactory.getLogger(JndiBasedDBTestCase.class); + /** + * Default constructor. + */ public JndiBasedDBTestCase() { } + /** + * Constructs a test case with the given name. + * + * @param name the test case name. + */ public JndiBasedDBTestCase( String name ) { super( name ); @@ -65,6 +73,8 @@ protected IDatabaseTester newDatabaseTester() /** * Returns the JNDI lookup name for the test DataSource. + * + * @return the JNDI lookup name for the test DataSource. */ protected abstract String getLookupName(); @@ -72,6 +82,8 @@ protected IDatabaseTester newDatabaseTester() * Returns the JNDI properties to use.
* Subclasses must override this method to provide customized JNDI * properties. Default implementation returns an empty Properties object. + * + * @return the JNDI properties to use. */ protected Properties getJNDIProperties() { diff --git a/src/main/java/org/dbunit/PrepAndExpectedTestCase.java b/src/main/java/org/dbunit/PrepAndExpectedTestCase.java index 2c4595826..1b4cf9bde 100644 --- a/src/main/java/org/dbunit/PrepAndExpectedTestCase.java +++ b/src/main/java/org/dbunit/PrepAndExpectedTestCase.java @@ -43,7 +43,7 @@ public interface PrepAndExpectedTestCase * @param expectedDataFiles * The expected data files (as classpath resources) to load as * expected data and verify actual data matches at test end. - * @throws Exception + * @throws Exception if the test cannot be configured. */ void configureTest(VerifyTableDefinition[] verifyTableDefinitions, String[] prepDataFiles, String[] expectedDataFiles) @@ -53,7 +53,7 @@ void configureTest(VerifyTableDefinition[] verifyTableDefinitions, * Execute pre-test steps. Call this method before performing the test * steps. * - * @throws Exception + * @throws Exception if the pre-test steps fail. */ void preTest() throws Exception; @@ -68,7 +68,7 @@ void configureTest(VerifyTableDefinition[] verifyTableDefinitions, * @param expectedDataFiles * The expected data files (as classpath resources) to load as * expected data and verify actual data matches at test end. - * @throws Exception + * @throws Exception if the pre-test steps fail. */ void preTest(VerifyTableDefinition[] verifyTables, String[] prepDataFiles, String[] expectedDataFiles) throws Exception; @@ -87,7 +87,7 @@ void preTest(VerifyTableDefinition[] verifyTables, String[] prepDataFiles, * @param testSteps * The test steps to run. * @return User defined object from running the test steps. - * @throws Exception + * @throws Exception if the test steps fail. * @since 2.5.2 */ Object runTest(VerifyTableDefinition[] verifyTables, String[] prepDataFiles, @@ -98,7 +98,7 @@ Object runTest(VerifyTableDefinition[] verifyTables, String[] prepDataFiles, * Execute all post-test steps. Call this method after performing the test * steps. * - * @throws Exception + * @throws Exception if the post-test steps fail. */ void postTest() throws Exception; @@ -111,7 +111,7 @@ Object runTest(VerifyTableDefinition[] verifyTables, String[] prepDataFiles, * Useful to specify false when test has failure in progress * (e.g. an exception) and verifying data would fail, masking * original test failure. - * @throws Exception + * @throws Exception if the post-test steps fail. */ void postTest(boolean verifyData) throws Exception; @@ -119,7 +119,7 @@ Object runTest(VerifyTableDefinition[] verifyTables, String[] prepDataFiles, * For the provided VerifyTableDefinitions, verify each table's actual * results are as expected. * - * @throws Exception + * @throws Exception if verifying the data fails. */ void verifyData() throws Exception; @@ -128,7 +128,7 @@ Object runTest(VerifyTableDefinition[] verifyTables, String[] prepDataFiles, * provided databaseTester. See * {@link org.dbunit.IDatabaseTester#onTearDown()}. * - * @throws Exception + * @throws Exception if cleaning up the data fails. */ void cleanupData() throws Exception; diff --git a/src/main/java/org/dbunit/PrepAndExpectedTestCaseSteps.java b/src/main/java/org/dbunit/PrepAndExpectedTestCaseSteps.java index 8f461c811..07e5e9d48 100644 --- a/src/main/java/org/dbunit/PrepAndExpectedTestCaseSteps.java +++ b/src/main/java/org/dbunit/PrepAndExpectedTestCaseSteps.java @@ -34,7 +34,7 @@ public interface PrepAndExpectedTestCaseSteps * Run the specific test steps. * * @return User defined object from the test run. - * @throws Exception + * @throws Exception if the test steps fail. */ Object run() throws Exception; } diff --git a/src/main/java/org/dbunit/PropertiesBasedJdbcDatabaseTester.java b/src/main/java/org/dbunit/PropertiesBasedJdbcDatabaseTester.java index a136a462c..43199c6a9 100644 --- a/src/main/java/org/dbunit/PropertiesBasedJdbcDatabaseTester.java +++ b/src/main/java/org/dbunit/PropertiesBasedJdbcDatabaseTester.java @@ -63,7 +63,7 @@ public class PropertiesBasedJdbcDatabaseTester extends JdbcDatabaseTester /** * Creates a new {@link JdbcDatabaseTester} using specific {@link System#getProperty(String)} * values as initialization parameters - * @throws Exception + * @throws Exception if the configured driver class was not found. */ public PropertiesBasedJdbcDatabaseTester() throws Exception { @@ -88,7 +88,7 @@ public PropertiesBasedJdbcDatabaseTester() throws Exception * @param connectionProvider Caches and validates the connection across * calls. Can be null, in which case a new * connection is created on every call as before. - * @throws Exception If the configured driver class was not found + * @throws Exception if the configured driver class was not found. * @since 3.4.0 */ public PropertiesBasedJdbcDatabaseTester(final CachingConnectionProvider connectionProvider) diff --git a/src/main/java/org/dbunit/VerifyTableDefinition.java b/src/main/java/org/dbunit/VerifyTableDefinition.java index f535c0bb0..11c26603e 100644 --- a/src/main/java/org/dbunit/VerifyTableDefinition.java +++ b/src/main/java/org/dbunit/VerifyTableDefinition.java @@ -206,28 +206,53 @@ public VerifyTableDefinition(final String table, verifyTableDefinitionVerifier.verify(this); } + /** + * Returns the table name. + * + * @return the table name. + */ public String getTableName() { return tableName; } + /** + * Returns the column names excluded from verification. + * + * @return the column names excluded from verification. + */ public String[] getColumnExclusionFilters() { return columnExclusionFilters; } + /** + * Returns the column names included in verification. + * + * @return the column names included in verification. + */ public String[] getColumnInclusionFilters() { return columnInclusionFilters; } - /** @since 2.6.0 */ + /** + * Returns the default value comparer used for columns without a specific one. + * + * @return the default value comparer used for columns without a specific one. + * @since 2.6.0 + */ public ValueComparer getDefaultValueComparer() { return defaultValueComparer; } - /** @since 2.6.0 */ + /** + * Returns the per-column value comparers. + * + * @return the per-column value comparers. + * @since 2.6.0 + */ public Map getColumnValueComparers() { return columnValueComparers; @@ -255,16 +280,32 @@ public String toString() return sb.toString(); } + /** + * Returns a null-safe string representation of the given array. + * + * @param array the array to format, possibly null. + * @return a null-safe string representation of the given array. + */ protected String arrayToString(final String[] array) { return array == null ? "" : Arrays.toString(array); } + /** + * Returns the verifier used to validate this instance. + * + * @return the verifier used to validate this instance. + */ public VerifyTableDefinitionVerifier getVerifyTableDefinitionVerifier() { return verifyTableDefinitionVerifier; } + /** + * Sets the verifier used to validate this instance. + * + * @param verifyTableDefinitionVerifier the verifier used to validate this instance. + */ public void setVerifyTableDefinitionVerifier( final VerifyTableDefinitionVerifier verifyTableDefinitionVerifier) { diff --git a/src/main/java/org/dbunit/ant/AbstractStep.java b/src/main/java/org/dbunit/ant/AbstractStep.java index d8d19700b..c4137b250 100644 --- a/src/main/java/org/dbunit/ant/AbstractStep.java +++ b/src/main/java/org/dbunit/ant/AbstractStep.java @@ -67,16 +67,30 @@ public abstract class AbstractStep extends ProjectComponent implements DbUnitTas */ private static final Logger logger = LoggerFactory.getLogger(AbstractStep.class); + /** Flat XML data format identifier. */ public static final String FORMAT_FLAT = "flat"; + /** XML data format identifier. */ public static final String FORMAT_XML = "xml"; + /** DTD (metadata-only) format identifier. */ public static final String FORMAT_DTD = "dtd"; + /** CSV data format identifier. */ public static final String FORMAT_CSV = "csv"; + /** Excel data format identifier. */ public static final String FORMAT_XLS = "xls"; + /** YAML data format identifier. */ public static final String FORMAT_YML = "yml"; private boolean ordered = false; - + /** + * Builds a dataset from the given connection, restricted to the given tables and queries. + * + * @param connection the database connection. + * @param tables the list of {@link Table}, {@link Query}, and {@link QuerySet} elements + * configuring which tables/queries to include; the whole database is used if empty. + * @return the assembled dataset. + * @throws DatabaseUnitException if building the dataset fails. + */ protected IDataSet getDatabaseDataSet(IDatabaseConnection connection, List tables) throws DatabaseUnitException { @@ -114,7 +128,6 @@ protected IDataSet getDatabaseDataSet(IDatabaseConnection connection, } } - private ForwardOnlyDataSet[] createForwardOnlyDataSetArray(List dataSets) throws DataSetException, SQLException { ForwardOnlyDataSet[] forwardOnlyDataSets = new ForwardOnlyDataSet[dataSets.size()]; @@ -168,7 +181,15 @@ else if (item instanceof Table) return queryDataSets; } - + /** + * Loads a dataset from the given source file in the given format. + * + * @param src the source file. + * @param format the data format, one of the FORMAT_* constants. + * @param forwardonly true to stream the dataset forward-only instead of caching it. + * @return the loaded dataset. + * @throws DatabaseUnitException if loading the dataset fails. + */ protected IDataSet getSrcDataSet(File src, String format, boolean forwardonly) throws DatabaseUnitException { @@ -222,7 +243,6 @@ else if (format.equalsIgnoreCase(FORMAT_YML)) } } - /** * Checks if the given format is a format which contains tabular data. * @param format The format to check @@ -262,12 +282,11 @@ protected void checkDataFormat(String format) } } - /** * Creates and returns an {@link InputSource} * @param file The file for which an {@link InputSource} should be created * @return The input source for the given file - * @throws MalformedURLException + * @throws MalformedURLException if the file's path cannot be converted to a URL. */ public static InputSource getInputSource(File file) throws MalformedURLException { @@ -275,12 +294,22 @@ public static InputSource getInputSource(File file) throws MalformedURLException return source; } - public boolean isOrdered() + /** + * Returns whether the resulting dataset's tables must be ordered. + * + * @return true if the resulting dataset's tables must be ordered. + */ + public boolean isOrdered() { return ordered; } - public void setOrdered(boolean ordered) + /** + * Sets whether the resulting dataset's tables must be ordered. + * + * @param ordered true if the resulting dataset's tables must be ordered. + */ + public void setOrdered(boolean ordered) { this.ordered = ordered; } diff --git a/src/main/java/org/dbunit/ant/Compare.java b/src/main/java/org/dbunit/ant/Compare.java index c44662eeb..83fbed068 100644 --- a/src/main/java/org/dbunit/ant/Compare.java +++ b/src/main/java/org/dbunit/ant/Compare.java @@ -61,11 +61,19 @@ public class Compare extends AbstractStep private List _tables = new ArrayList(); private boolean _sort = false; + /** + * Returns the source file containing the expected dataset. + * @return the source file containing the expected dataset. + */ public File getSrc() { return _src; } + /** + * Sets the source file containing the expected dataset. + * @param src the source file containing the expected dataset. + */ public void setSrc(File src) { logger.debug("setSrc(src={}) - start", src); @@ -73,6 +81,10 @@ public void setSrc(File src) _src = src; } + /** + * Sets whether the compared tables must be sorted before comparison. + * @param sort true to sort the compared tables before comparison. + */ public void setSort(boolean sort) { logger.debug("setSort(sort={}) - start", String.valueOf(sort)); @@ -80,11 +92,19 @@ public void setSort(boolean sort) _sort = sort; } + /** + * Returns the format of the source file. + * @return the format of the source file. + */ public String getFormat() { return _format != null ? _format : DEFAULT_FORMAT; } + /** + * Sets the format of the source file. + * @param format the format of the source file. + */ public void setFormat(String format) { logger.debug("setFormat(format={}) - start", format); @@ -95,11 +115,19 @@ public void setFormat(String format) _format = format; } + /** + * Returns the tables and queries to compare. + * @return the tables and queries to compare. + */ public List getTables() { return _tables; } + /** + * Adds a table to compare. + * @param table the table to compare. + */ public void addTable(Table table) { logger.debug("addTable(table={}) - start", table); @@ -107,6 +135,10 @@ public void addTable(Table table) _tables.add(table); } + /** + * Adds a query to compare. + * @param query the query to compare. + */ public void addQuery(Query query) { logger.debug("addQuery(query={}) - start", query); diff --git a/src/main/java/org/dbunit/ant/DbConfig.java b/src/main/java/org/dbunit/ant/DbConfig.java index 5d4f3ddd7..3ded2ffef 100644 --- a/src/main/java/org/dbunit/ant/DbConfig.java +++ b/src/main/java/org/dbunit/ant/DbConfig.java @@ -49,22 +49,35 @@ public class DbConfig extends ProjectComponent private Set properties = new HashSet(); private Set features = new HashSet(); - + + /** + * Default constructor. + */ public DbConfig() { } + /** + * Adds a property to be copied into the {@link DatabaseConfig} by {@link #copyTo(DatabaseConfig)}. + * + * @param property the property to add. + */ public void addProperty(Property property) { logger.trace("addProperty(property={}) - start)", property); - + this.properties.add(property); } + /** + * Adds a feature flag to be copied into the {@link DatabaseConfig} by {@link #copyTo(DatabaseConfig)}. + * + * @param feature the feature flag to add. + */ public void addFeature(Feature feature) { logger.trace("addFeature(feature={}) - start)", feature); - + this.features.add(feature); } @@ -72,7 +85,7 @@ public void addFeature(Feature feature) * Copies the parameters set in this configuration via ant into the given * {@link DatabaseConfig} that is used by the dbunit connection. * @param config The configuration object to be initialized/updated - * @throws DatabaseUnitException + * @throws DatabaseUnitException if a property value cannot be converted to its required type. */ public void copyTo(DatabaseConfig config) throws DatabaseUnitException { @@ -121,16 +134,32 @@ public static class Feature { private String name; private boolean value; - + + /** + * Returns the feature name. + * @return the feature name. + */ public String getName() { return name; } + /** + * Sets the feature name. + * @param name the feature name. + */ public void setName(String name) { this.name = name; } + /** + * Returns the feature value. + * @return the feature value. + */ public boolean isValue() { return value; } + /** + * Sets the feature value. + * @param value the feature value. + */ public void setValue(boolean value) { this.value = value; } diff --git a/src/main/java/org/dbunit/ant/DbUnitTask.java b/src/main/java/org/dbunit/ant/DbUnitTask.java index 311b842c6..a185d75f2 100644 --- a/src/main/java/org/dbunit/ant/DbUnitTask.java +++ b/src/main/java/org/dbunit/ant/DbUnitTask.java @@ -162,6 +162,8 @@ public class DbUnitTask extends Task /** * Set the JDBC driver to be used. + * + * @param driver the fully qualified class name of the JDBC driver. */ public void setDriver(final String driver) { @@ -171,6 +173,8 @@ public void setDriver(final String driver) /** * Set the DB connection url. + * + * @param url the JDBC connection URL. */ public void setUrl(final String url) { @@ -180,6 +184,8 @@ public void setUrl(final String url) /** * Set the user name for the DB connection. + * + * @param userId the database user name. */ public void setUserid(final String userId) { @@ -189,6 +195,8 @@ public void setUserid(final String userId) /** * Set the password for the DB connection. + * + * @param password the database password. */ public void setPassword(final String password) { @@ -198,6 +206,8 @@ public void setPassword(final String password) /** * Set the schema for the DB connection. + * + * @param schema the database schema. */ public void setSchema(final String schema) { @@ -207,6 +217,8 @@ public void setSchema(final String schema) /** * Set the flag for using the qualified table names. + * + * @param useQualifiedTableNames true to use qualified table names. */ public void setUseQualifiedTableNames(final Boolean useQualifiedTableNames) { @@ -218,6 +230,8 @@ public void setUseQualifiedTableNames(final Boolean useQualifiedTableNames) * Set the flag for supporting batch statements. * NOTE: This property cannot be used to force the usage of batch * statement if your database does not support it. + * + * @param supportBatchStatement true to use batch statements. */ public void setSupportBatchStatement(final Boolean supportBatchStatement) { @@ -225,24 +239,44 @@ public void setSupportBatchStatement(final Boolean supportBatchStatement) this.supportBatchStatement = supportBatchStatement; } + /** + * Sets the flag for logging a warning on unsupported data types. + * + * @param datatypeWarning true to log a warning on unsupported data types. + */ public void setDatatypeWarning(final Boolean datatypeWarning) { logger.trace("setDatatypeWarning(datatypeWarning={}) - start", String.valueOf(datatypeWarning)); this.datatypeWarning = datatypeWarning; } + /** + * Sets the fully qualified class name of the {@link IDataTypeFactory} to use. + * + * @param datatypeFactory the fully qualified class name of the {@link IDataTypeFactory} to use. + */ public void setDatatypeFactory(final String datatypeFactory) { logger.trace("setDatatypeFactory(datatypeFactory={}) - start", datatypeFactory); this.dataTypeFactory = datatypeFactory; } + /** + * Sets the pattern used to escape table and column names. + * + * @param escapePattern the pattern used to escape table and column names. + */ public void setEscapePattern(final String escapePattern) { logger.trace("setEscapePattern(escapePattern={}) - start", escapePattern); this.escapePattern = escapePattern; } + /** + * Returns the generic {@link DatabaseConfig} configuration child element. + * + * @return the generic {@link DatabaseConfig} configuration child element. + */ public DbConfig getDbConfig() { return dbConfig; @@ -254,6 +288,11 @@ public DbConfig getDbConfig() // this.dbConfig = dbConfig; // } + /** + * Sets the generic {@link DatabaseConfig} configuration child element. + * + * @param dbConfig the generic {@link DatabaseConfig} configuration child element. + */ public void addDbConfig(final DbConfig dbConfig) { logger.trace("addDbConfig(dbConfig={}) - start", dbConfig); @@ -262,6 +301,8 @@ public void addDbConfig(final DbConfig dbConfig) /** * Set the classpath for loading the driver. + * + * @param classpath the classpath for loading the driver. */ public void setClasspath(final Path classpath) { @@ -278,6 +319,8 @@ public void setClasspath(final Path classpath) /** * Create the classpath for loading the driver. + * + * @return the classpath for loading the driver. */ public Path createClasspath() { @@ -292,6 +335,8 @@ public Path createClasspath() /** * Set the classpath for loading the driver using the classpath reference. + * + * @param r the reference to the classpath for loading the driver. */ public void setClasspathRef(final Reference r) { @@ -302,6 +347,8 @@ public void setClasspathRef(final Reference r) /** * Gets the Steps. + * + * @return the steps to execute. */ public List getSteps() { @@ -310,6 +357,8 @@ public List getSteps() /** * Adds an Operation. + * + * @param operation the operation step to add. */ public void addOperation(final Operation operation) { @@ -320,6 +369,8 @@ public void addOperation(final Operation operation) /** * Adds a Compare to the steps List. + * + * @param compare the compare step to add. */ public void addCompare(final Compare compare) { @@ -330,6 +381,8 @@ public void addCompare(final Compare compare) /** * Adds an Export to the steps List. + * + * @param export the export step to add. */ public void addExport(final Export export) { @@ -338,7 +391,11 @@ public void addExport(final Export export) steps.add(export); } - + /** + * Returns the size of batch inserts. + * + * @return the size of batch inserts. + */ public String getBatchSize() { return batchSize; @@ -346,24 +403,38 @@ public String getBatchSize() /** * sets the size of batch inserts. - * @param batchSize + * @param batchSize the size of batch inserts. */ public void setBatchSize(final String batchSize) { this.batchSize = batchSize; } - + /** + * Returns the JDBC fetch size used for result sets. + * + * @return the JDBC fetch size used for result sets. + */ public String getFetchSize() { return fetchSize; } + /** + * Sets the JDBC fetch size used for result sets. + * + * @param fetchSize the JDBC fetch size used for result sets. + */ public void setFetchSize(final String fetchSize) { this.fetchSize = fetchSize; } + /** + * Sets the flag for skipping Oracle recycle bin tables. + * + * @param skipOracleRecycleBinTables true to skip Oracle recycle bin tables. + */ public void setSkipOracleRecycleBinTables(final Boolean skipOracleRecycleBinTables) { this.skipOracleRecycleBinTables = skipOracleRecycleBinTables; @@ -409,6 +480,12 @@ public void execute() throws BuildException } } + /** + * Loads the JDBC driver and opens the configured database connection. + * + * @return the opened database connection. + * @throws SQLException if the connection cannot be opened. + */ protected IDatabaseConnection createConnection() throws SQLException { logger.trace("createConnection() - start"); @@ -491,8 +568,8 @@ protected IDatabaseConnection createConnection() throws SQLException * Creates the dbunit connection using the two given arguments. The configuration * properties of the dbunit connection are initialized using the fields of this class. * - * @param jdbcConnection - * @param dbSchema + * @param jdbcConnection the JDBC connection to adapt. + * @param dbSchema the database schema. * @return The dbunit connection */ protected IDatabaseConnection createDatabaseConnection(final Connection jdbcConnection, diff --git a/src/main/java/org/dbunit/ant/DbUnitTaskStep.java b/src/main/java/org/dbunit/ant/DbUnitTaskStep.java index 6857c6bf6..e1bcce893 100644 --- a/src/main/java/org/dbunit/ant/DbUnitTaskStep.java +++ b/src/main/java/org/dbunit/ant/DbUnitTaskStep.java @@ -35,8 +35,19 @@ public interface DbUnitTaskStep { + /** + * Executes this step using the given database connection. + * + * @param connection the database connection to use. + * @throws DatabaseUnitException if the step fails. + */ public void execute(IDatabaseConnection connection) throws DatabaseUnitException; + /** + * Returns a message describing this step, for logging purposes. + * + * @return a message describing this step. + */ public String getLogMessage(); } diff --git a/src/main/java/org/dbunit/ant/Export.java b/src/main/java/org/dbunit/ant/Export.java index b6d906023..91107fbe8 100644 --- a/src/main/java/org/dbunit/ant/Export.java +++ b/src/main/java/org/dbunit/ant/Export.java @@ -74,6 +74,9 @@ public class Export extends AbstractStep private Charset _encoding = StandardCharsets.UTF_8; // if no encoding set by script than the default encoding (UTF-8) of the wrietr is used private List _tables = new ArrayList(); + /** + * Default constructor. + */ public Export() { } @@ -83,27 +86,47 @@ private String getAbsolutePath(File filename) return filename != null ? filename.getAbsolutePath() : "null"; } + /** + * Returns the destination file to export to. + * @return the destination file to export to. + */ public File getDest() { return _dest; } + /** + * Returns the export format. + * @return the export format. + */ public String getFormat() { return _format; } + /** + * Returns the tables and queries to export. + * @return the tables and queries to export. + */ public List getTables() { return _tables; } + /** + * Sets the destination file to export to. + * @param dest the destination file to export to. + */ public void setDest(File dest) { logger.debug("setDest(dest={}) - start", dest); _dest = dest; } + /** + * Sets the export format. + * @param format the export format. + */ public void setFormat(String format) { logger.debug("setFormat(format={}) - start", format); @@ -137,39 +160,67 @@ public Charset getEncoding() return this._encoding; } + /** + * Sets the encoding for XML output. + * @param encoding the name of the encoding for XML output. + */ public void setEncoding(String encoding) { setEncoding(Charset.forName(encoding)); } + /** + * Sets the encoding for XML output. + * @param encoding the encoding for XML output. + */ public void setEncoding(Charset encoding) { this._encoding = encoding; } + /** + * Adds a table to export. + * @param table the table to export. + */ public void addTable(Table table) { logger.debug("addTable(table={}) - start", table); _tables.add(table); } + /** + * Adds a query to export. + * @param query the query to export. + */ public void addQuery(Query query) { logger.debug("addQuery(query={}) - start", query); _tables.add(query); } + /** + * Adds a query set to export. + * @param querySet the query set to export. + */ public void addQuerySet(QuerySet querySet) { logger.debug("addQuerySet(querySet={}) - start", querySet); _tables.add(querySet); } - - + + + /** + * Returns the DOCTYPE to use for flat XML export. + * @return the DOCTYPE to use for flat XML export. + */ public String getDoctype() { return _doctype; } + /** + * Sets the DOCTYPE to use for flat XML export. + * @param doctype the DOCTYPE to use for flat XML export. + */ public void setDoctype(String doctype) { logger.debug("setDoctype(doctype={}) - start", doctype); @@ -256,10 +307,10 @@ else if (_format.equalsIgnoreCase(FORMAT_YML)) /** * Creates the dataset that is finally used for the export - * @param connection + * @param connection the database connection to export from. * @return The final dataset used for the export - * @throws DatabaseUnitException - * @throws SQLException + * @throws DatabaseUnitException if building the dataset fails. + * @throws SQLException if a database access error occurs. */ protected IDataSet getExportDataSet(IDatabaseConnection connection) throws DatabaseUnitException, SQLException diff --git a/src/main/java/org/dbunit/ant/Operation.java b/src/main/java/org/dbunit/ant/Operation.java index febf4ca40..9437db232 100644 --- a/src/main/java/org/dbunit/ant/Operation.java +++ b/src/main/java/org/dbunit/ant/Operation.java @@ -62,6 +62,7 @@ public class Operation extends AbstractStep private static final String DEFAULT_FORMAT = FORMAT_FLAT; + /** The name of the {@link DatabaseOperation} to execute, e.g. "CLEAN_INSERT". */ protected String _type = "CLEAN_INSERT"; private String _format; private List _sources = new ArrayList<>(); @@ -71,23 +72,43 @@ public class Operation extends AbstractStep private boolean _forwardOperation = true; private String _nullToken; + /** + * Returns the source files holding the operation's dataset. + * + * @return the source files holding the operation's dataset. + */ public File[] getSrc() { return _sources.toArray(new File[_sources.size()]); } + /** + * Sets the source files holding the operation's dataset. + * + * @param sources the source files holding the operation's dataset. + */ public void setSrc(File[] sources) { _sources.clear(); _sources.addAll(Arrays.asList(sources)); } + /** + * Sets the single source file holding the operation's dataset. + * + * @param src the source file holding the operation's dataset. + */ public void setSrc(File src) { _sources.clear(); _sources.add(src); } + /** + * Adds the files matched by the given Ant fileset to the operation's dataset sources. + * + * @param fileSet the Ant fileset to add. + */ public void addConfiguredFileset(FileSet fileSet) { DirectoryScanner scanner = fileSet.getDirectoryScanner(getProject()); @@ -96,11 +117,21 @@ public void addConfiguredFileset(FileSet fileSet) } } + /** + * Returns the dataset format, defaulting to {@value #DEFAULT_FORMAT} when not set. + * + * @return the dataset format. + */ public String getFormat() { return _format != null ? _format : DEFAULT_FORMAT; } + /** + * Sets the dataset format. + * + * @param format the dataset format. + */ public void setFormat(String format) { logger.debug("setFormat(format={}) - start", format); @@ -111,47 +142,93 @@ public void setFormat(String format) _format = format; } + /** + * Returns whether multiple sources are combined into a single dataset. + * + * @return {@code true} if multiple sources are combined into a single dataset. + */ public boolean isCombine() { return _combine; } + /** + * Sets whether multiple sources are combined into a single dataset. + * + * @param combine {@code true} to combine multiple sources into a single dataset. + */ public void setCombine(boolean combine) { _combine = combine; } + /** + * Returns whether the operation runs within a transaction. + * + * @return {@code true} if the operation runs within a transaction. + */ public boolean isTransaction() { return _transaction; } + /** + * Sets whether the operation runs within a transaction. + * + * @param transaction {@code true} to run the operation within a transaction. + */ public void setTransaction(boolean transaction) { _transaction = transaction; } - public String getNullToken() + /** + * Returns the token replaced with a null value in the dataset. + * + * @return the token replaced with a null value in the dataset. + */ + public String getNullToken() { return _nullToken; } - public void setNullToken(final String nullToken) + /** + * Sets the token to replace with a null value in the dataset. + * + * @param nullToken the token to replace with a null value in the dataset. + */ + public void setNullToken(final String nullToken) { this._nullToken = nullToken; } + /** + * Returns the database operation resolved from {@link #setType(String)}. + * + * @return the database operation resolved from {@link #setType(String)}. + */ public DatabaseOperation getDbOperation() { return _operation; } + /** + * Returns the operation type name. + * + * @return the operation type name. + */ public String getType() { return _type; } - public void setType(String type) + /** + * Sets the operation type, resolving it to the corresponding {@link DatabaseOperation}. + * + * @param type one of: UPDATE, INSERT, REFRESH, DELETE, DELETE_ALL, CLEAN_INSERT, NONE, + * MSSQL_CLEAN_INSERT, MSSQL_INSERT, or MSSQL_REFRESH. + */ + public void setType(String type) { logger.debug("setType(type={}) - start", type); diff --git a/src/main/java/org/dbunit/ant/Query.java b/src/main/java/org/dbunit/ant/Query.java index 4397c4f80..0b868e98f 100644 --- a/src/main/java/org/dbunit/ant/Query.java +++ b/src/main/java/org/dbunit/ant/Query.java @@ -43,15 +43,28 @@ public class Query private String name; private String sql; + /** + * Default constructor. + */ public Query() { } + /** + * Returns the table name. + * + * @return the table name. + */ public String getName() { return name; } + /** + * Sets the table name. + * + * @param name the table name. + */ public void setName(String name) { logger.debug("setName(name={}) - start", name); @@ -71,11 +84,21 @@ public String toString() return result.toString(); } + /** + * Returns the query's SQL. + * + * @return the query's SQL. + */ public String getSql() { return sql; } + /** + * Sets the query's SQL. + * + * @param sql the query's SQL. + */ public void setSql(String sql) { logger.debug("setSql(sql={}) - start", sql); diff --git a/src/main/java/org/dbunit/ant/QuerySet.java b/src/main/java/org/dbunit/ant/QuerySet.java index bdfabb62a..0b9521fce 100644 --- a/src/main/java/org/dbunit/ant/QuerySet.java +++ b/src/main/java/org/dbunit/ant/QuerySet.java @@ -117,30 +117,59 @@ public class QuerySet extends ProjectComponent private static String ERR_MSG = "Cannot specify 'id' and 'refid' attributes together in queryset."; + /** + * Default constructor. + */ public QuerySet() { super(); } + /** + * Adds a query to this queryset. + * + * @param query the query to add. + */ public void addQuery(final Query query) { logger.debug("addQuery(query={}) - start", query); queries.add(query); } + /** + * Adds a filterset whose tokens are substituted into this queryset's query SQL. + * + * @param filterSet the filterset to add. + */ public void addFilterSet(final FilterSet filterSet) { logger.debug("addFilterSet(filterSet={}) - start", filterSet); filterSets.add(filterSet); } + /** + * Returns the id under which this queryset can be referenced. + * + * @return the id under which this queryset can be referenced. + */ public String getId() { return id; } + /** + * Returns the id of the queryset this queryset references. + * + * @return the id of the queryset this queryset references. + */ public String getRefid() { return refid; } + /** + * Sets the id under which this queryset can be referenced. + * + * @param string the id under which this queryset can be referenced. + * @throws BuildException if refid is already set. + */ public void setId(final String string) throws BuildException { logger.debug("setId(string={}) - start", string); @@ -148,6 +177,12 @@ public void setId(final String string) throws BuildException { id = string; } + /** + * Sets the id of the queryset this queryset references. + * + * @param string the id of the queryset this queryset references. + * @throws BuildException if id is already set. + */ public void setRefid(final String string) throws BuildException { logger.debug("setRefid(string={}) - start", string); @@ -155,6 +190,11 @@ public void setRefid(final String string) throws BuildException { refid = string; } + /** + * Returns this queryset's queries, with filterset tokens substituted. + * + * @return this queryset's queries, with filterset tokens substituted. + */ public List getQueries() { logger.debug("getQueries() - start"); @@ -179,6 +219,11 @@ private void replaceTokens(final Query query) { } + /** + * Copies the queries from the given queryset into this one. + * + * @param referenced the queryset to copy queries from. + */ public void copyQueriesFrom(final QuerySet referenced) { logger.debug("copyQueriesFrom(referenced={}) - start", referenced); @@ -188,6 +233,15 @@ public void copyQueriesFrom(final QuerySet referenced) { } } + /** + * Builds a {@link QueryDataSet} from this queryset's queries, resolving a referenced + * queryset first if {@link #getRefid()} is set. + * + * @param connection the database connection needed to load data. + * @return the resulting dataset. + * @throws SQLException if a database access error occurs. + * @throws AmbiguousTableNameException if a table name is added more than once. + */ public QueryDataSet getQueryDataSet(final IDatabaseConnection connection) throws SQLException, AmbiguousTableNameException { diff --git a/src/main/java/org/dbunit/ant/Table.java b/src/main/java/org/dbunit/ant/Table.java index 30f5aefb9..ddc37ea6f 100644 --- a/src/main/java/org/dbunit/ant/Table.java +++ b/src/main/java/org/dbunit/ant/Table.java @@ -43,15 +43,28 @@ public class Table private String name; + /** + * Default constructor. + */ public Table() { } + /** + * Returns the table name. + * + * @return the table name. + */ public String getName() { return name; } + /** + * Sets the table name. + * + * @param name the table name. + */ public void setName(String name) { logger.debug("setName(name={}) - start", name); diff --git a/src/main/java/org/dbunit/assertion/DbAssertionFailedError.java b/src/main/java/org/dbunit/assertion/DbAssertionFailedError.java index ab828e915..13e8ee1fb 100644 --- a/src/main/java/org/dbunit/assertion/DbAssertionFailedError.java +++ b/src/main/java/org/dbunit/assertion/DbAssertionFailedError.java @@ -33,9 +33,17 @@ public class DbAssertionFailedError extends Error { private static final long serialVersionUID = 1L; + /** + * Constructs a DbAssertionFailedError with no detail message. + */ public DbAssertionFailedError () { } - + + /** + * Constructs a DbAssertionFailedError with the specified detail message. + * + * @param message the detail message. + */ public DbAssertionFailedError (String message) { super (message); } diff --git a/src/main/java/org/dbunit/assertion/DbComparisonFailure.java b/src/main/java/org/dbunit/assertion/DbComparisonFailure.java index a918150f2..b24247eb3 100644 --- a/src/main/java/org/dbunit/assertion/DbComparisonFailure.java +++ b/src/main/java/org/dbunit/assertion/DbComparisonFailure.java @@ -33,11 +33,16 @@ public class DbComparisonFailure extends AssertionError { private static final long serialVersionUID = 1L; + /** The reason for the comparison failure. */ private String reason; + /** The expected value. */ private String expected; + /** The actual value. */ private String actual; /** + * Constructs a DbComparisonFailure with the given reason, expected, and actual values. + * * @param reason The reason for the comparison failure * @param expected The expected value * @param actual The actual value @@ -56,16 +61,28 @@ public String getMessage() return buildMessage(this.reason, this.expected, this.actual); } + /** + * Returns the reason for the comparison failure. + * @return the reason for the comparison failure. + */ public String getReason() { return reason; } + /** + * Returns the expected value. + * @return the expected value. + */ public String getExpected() { return expected; } + /** + * Returns the actual value. + * @return the actual value. + */ public String getActual() { return actual; diff --git a/src/main/java/org/dbunit/assertion/DbUnitAssert.java b/src/main/java/org/dbunit/assertion/DbUnitAssert.java index 13b54803f..6d1e4bc1a 100644 --- a/src/main/java/org/dbunit/assertion/DbUnitAssert.java +++ b/src/main/java/org/dbunit/assertion/DbUnitAssert.java @@ -176,6 +176,10 @@ public void assertEqualsByQuery(final ITable expectedTable, /** * Asserts that the two specified dataset are equals. This method ignore the * tables order. + * + * @param expectedDataSet dataset containing all expected results. + * @param actualDataSet dataset containing all actual results. + * @throws DatabaseUnitException if an error occurs during comparison. */ public void assertEquals(final IDataSet expectedDataSet, final IDataSet actualDataSet) throws DatabaseUnitException @@ -190,6 +194,10 @@ public void assertEquals(final IDataSet expectedDataSet, * Asserts that the two specified dataset are equals. This method ignore the * tables order. * + * @param expectedDataSet dataset containing all expected results. + * @param actualDataSet dataset containing all actual results. + * @param failureHandler the failure handler used to report mismatches. Can be null. + * @throws DatabaseUnitException if an error occurs during comparison. * @since 2.4 */ public void assertEquals(final IDataSet expectedDataSet, @@ -200,6 +208,16 @@ public void assertEquals(final IDataSet expectedDataSet, null, null); } + /** + * Asserts each expected table against its corresponding actual table, using the default + * equality-based value comparer. + * + * @param expectedDataSet the dataset containing all expected results. + * @param actualDataSet the dataset containing all actual results. + * @param expectedNames the table names to compare, in comparison order. + * @param failureHandler the failure handler used if the assert fails because of a data mismatch. + * @throws DatabaseUnitException if a table comparison fails. + */ protected void compareTables(final IDataSet expectedDataSet, final IDataSet actualDataSet, final String[] expectedNames, final FailureHandler failureHandler) throws DatabaseUnitException @@ -217,7 +235,7 @@ protected void compareTables(final IDataSet expectedDataSet, * Table containing all expected results. * @param actualTable * Table containing all actual results. - * @throws DatabaseUnitException + * @throws DatabaseUnitException if an error occurs during comparison. */ public void assertEquals(final ITable expectedTable, final ITable actualTable) throws DatabaseUnitException @@ -249,7 +267,7 @@ public void assertEquals(final ITable expectedTable, * be useful to quickly identify the columns for which the * mismatch occurred (for example a primary key column). Can be * null. - * @throws DatabaseUnitException + * @throws DatabaseUnitException if an error occurs during comparison. */ public void assertEquals(final ITable expectedTable, final ITable actualTable, final Column[] additionalColumnInfo) @@ -290,7 +308,7 @@ public void assertEquals(final ITable expectedTable, * useful to quickly identify the rows for which the mismatch * occurred (for example by printing an additional primary key * column). Can be null. - * @throws DatabaseUnitException + * @throws DatabaseUnitException if an error occurs during comparison. * @since 2.4 */ public void assertEquals(final ITable expectedTable, @@ -323,6 +341,8 @@ public static class ComparisonColumn private DataType dataType; /** + * Creates a comparison column, resolving the {@link DataType} to use for comparison. + * * @param tableName * The table name which is only needed for debugging output. * @param expectedColumn @@ -345,6 +365,8 @@ public ComparisonColumn(final String tableName, } /** + * Returns the column actually being compared. + * * @return The column actually being compared. */ public String getColumnName() @@ -353,6 +375,8 @@ public String getColumnName() } /** + * Returns the {@link DataType} to use for the actual comparison. + * * @return The {@link DataType} to use for the actual comparison. */ public DataType getDataType() diff --git a/src/main/java/org/dbunit/assertion/DbUnitAssertBase.java b/src/main/java/org/dbunit/assertion/DbUnitAssertBase.java index fed2d63d2..2ac50ddc9 100644 --- a/src/main/java/org/dbunit/assertion/DbUnitAssertBase.java +++ b/src/main/java/org/dbunit/assertion/DbUnitAssertBase.java @@ -31,10 +31,15 @@ public class DbUnitAssertBase private FailureFactory junitFailureFactory = getJUnitFailureFactory(); + /** + * The value comparer defaults used when no comparer is explicitly configured for a table/column. + */ protected ValueComparerDefaults valueComparerDefaults = new DefaultValueComparerDefaults(); /** + * Returns the default failure handler, without additional column info. + * * @return The default failure handler * @since 2.4 */ @@ -44,6 +49,9 @@ protected FailureHandler getDefaultFailureHandler() } /** + * Returns the default failure handler, reporting the given additional columns on failure. + * + * @param additionalColumnInfo the additional columns to report on failure, may be null. * @return The default failure handler * @since 2.4 */ @@ -79,9 +87,15 @@ private FailureFactory getJUnitFailureFactory() } /** + * Builds the comparison columns to use for the assertion, pairing each expected column with + * its actual counterpart and resolving the correct datatype. + * * @param expectedTableName + * the name of the table being compared, used for failure reporting. * @param expectedColumns + * the expected columns, providing the comparison order. * @param actualColumns + * the actual columns, matched positionally to expectedColumns. * @param failureHandler * The {@link FailureHandler} to be used when no datatype can be * determined @@ -126,6 +140,12 @@ protected boolean skipCompare(final String columnName, return false; } + /** + * Returns the given failure handler, or the default one if the given handler is null. + * + * @param failureHandler the failure handler to validate, may be null. + * @return the given failure handler, or the default one if null. + */ protected FailureHandler determineFailureHandler( final FailureHandler failureHandler) { @@ -143,6 +163,15 @@ protected FailureHandler determineFailureHandler( return validFailureHandler; } + /** + * Compares the row counts of the two given tables, failing via the given failure handler on mismatch. + * + * @param expectedTable the table containing all expected results. + * @param actualTable the table containing all actual results. + * @param failureHandler the failure handler used to report a row count mismatch. + * @param expectedTableName the table name, used for failure reporting. + * @return true if both tables are empty, in which case column comparison can be skipped. + */ protected boolean compareRowCounts(final ITable expectedTable, final ITable actualTable, final FailureHandler failureHandler, final String expectedTableName) throws Error @@ -192,6 +221,16 @@ protected boolean compareRowCounts(final ITable expectedTable, return isTablesEmpty; } + /** + * Compares the columns of the two given tables, failing via the given failure handler on mismatch. + * + * @param expectedColumns the expected columns. + * @param actualColumns the actual columns. + * @param expectedMetaData the metadata of the expected table. + * @param actualMetaData the metadata of the actual table. + * @param failureHandler the failure handler used to report a column mismatch. + * @throws DataSetException if the column difference cannot be computed. + */ protected void compareColumns(final Column[] expectedColumns, final Column[] actualColumns, final ITableMetaData expectedMetaData, final ITableMetaData actualMetaData, @@ -210,6 +249,13 @@ protected void compareColumns(final Column[] expectedColumns, } } + /** + * Compares the number of expected and actual table names, failing via the given failure handler on mismatch. + * + * @param expectedNames the expected table names. + * @param actualNames the actual table names. + * @param failureHandler the failure handler used to report a table count mismatch. + */ protected void compareTableCounts(final String[] expectedNames, final String[] actualNames, final FailureHandler failureHandler) throws Error @@ -222,6 +268,13 @@ protected void compareTableCounts(final String[] expectedNames, } } + /** + * Compares the expected and actual table names, failing via the given failure handler on mismatch. + * + * @param expectedNames the expected table names, sorted. + * @param actualNames the actual table names, sorted. + * @param failureHandler the failure handler used to report a table name mismatch. + */ protected void compareTableNames(final String[] expectedNames, final String[] actualNames, final FailureHandler failureHandler) throws Error @@ -237,6 +290,14 @@ protected void compareTableNames(final String[] expectedNames, } } + /** + * Returns the table names of the given dataset, sorted and upper-cased unless + * the dataset is case-sensitive. + * + * @param dataSet the dataset providing the table names. + * @return the sorted table names. + * @throws DataSetException if the table names cannot be retrieved. + */ protected String[] getSortedTableNames(final IDataSet dataSet) throws DataSetException { @@ -285,7 +346,8 @@ protected String[] getSortedTableNames(final IDataSet dataSet) * {@link ValueComparerDefaults#getDefaultColumnValueComparerMapForTable(String)} or, * if that is empty, defaultValueComparer for all columns in all * tables. - * @throws DatabaseUnitException + * @throws DatabaseUnitException if an expected table is missing from the actual dataset, + * or a table comparison fails. */ public void assertWithValueComparer(final IDataSet expectedDataSet, final IDataSet actualDataSet, final FailureHandler failureHandler, @@ -324,6 +386,17 @@ public void assertWithValueComparer(final IDataSet expectedDataSet, tableColumnValueComparers); } + /** + * Asserts each expected table against its corresponding actual table. + * + * @param expectedDataSet the dataset containing all expected results. + * @param actualDataSet the dataset containing all actual results. + * @param expectedNames the table names to compare, in comparison order. + * @param failureHandler the failure handler used if the assert fails because of a data mismatch. + * @param defaultValueComparer the default value comparer, used when a table/column has none configured. + * @param tableColumnValueComparers the per-table, per-column value comparers to use. + * @throws DatabaseUnitException if a table comparison fails. + */ protected void compareTables(final IDataSet expectedDataSet, final IDataSet actualDataSet, final String[] expectedNames, final FailureHandler failureHandler, @@ -380,7 +453,7 @@ protected void compareTables(final IDataSet expectedDataSet, * {@link ValueComparerDefaults#getDefaultColumnValueComparerMapForTable(String)} or, * if that is empty, defaultValueComparer for all columns in the * table. - * @throws DatabaseUnitException + * @throws DatabaseUnitException if the tables' row counts, columns, or data do not match. */ public void assertWithValueComparer(final ITable expectedTable, final ITable actualTable, final FailureHandler failureHandler, @@ -443,6 +516,8 @@ public void assertWithValueComparer(final ITable expectedTable, } /** + * Compares the data of the two given tables using the default value comparers. + * * @param expectedTable * Table containing all expected results. * @param actualTable @@ -456,7 +531,7 @@ public void assertWithValueComparer(final ITable expectedTable, * useful to quickly identify the rows for which the mismatch * occurred (for example by printing an additional primary key * column). Must not be null at this stage - * @throws DataSetException + * @throws DataSetException if a data comparison fails. * @since 2.4 */ protected void compareData(final ITable expectedTable, @@ -477,6 +552,8 @@ protected void compareData(final ITable expectedTable, } /** + * Compares the data of the two given tables using the given value comparers. + * * @param expectedTable * {@link ITable} containing all expected results. * @param actualTable @@ -504,7 +581,7 @@ protected void compareData(final ITable expectedTable, * {@link ValueComparerDefaults#getDefaultColumnValueComparerMapForTable(String)} or, * if that is empty, defaultValueComparer for all columns in the * table. - * @throws DataSetException + * @throws DatabaseUnitException if a data comparison fails. * @since 2.4 * @since 2.6.0 */ @@ -567,6 +644,20 @@ protected void compareData(final ITable expectedTable, } } + /** + * Compares a single expected and actual cell value at the given row and column, failing + * via the given failure handler on mismatch. + * + * @param expectedTable {@link ITable} containing all expected results. + * @param actualTable {@link ITable} containing all actual results. + * @param comparisonCols the columns to be compared, also including the correct {@link DataType}s. + * @param failureHandler the failure handler used if the assert fails because of a data mismatch. + * @param defaultValueComparer the default value comparer, used when the column has none configured. + * @param columnValueComparers the per-column value comparers to use. + * @param rowNum the row index of the cell to compare. + * @param columnNum the index, into comparisonCols, of the column to compare. + * @throws DatabaseUnitException if the cell comparison fails. + */ protected void compareData(final ITable expectedTable, final ITable actualTable, final ComparisonColumn[] comparisonCols, final FailureHandler failureHandler, @@ -609,6 +700,18 @@ protected void compareData(final ITable expectedTable, } } + /** + * Reports a failure to the given failure handler if the given fail message is not null. + * + * @param expectedTable the table containing all expected results. + * @param actualTable the table containing all actual results. + * @param failureHandler the failure handler to report the difference to. + * @param rowNum the row index of the compared cell. + * @param columnName the name of the compared column. + * @param expectedValue the expected cell value. + * @param actualValue the actual cell value. + * @param failMessage the comparison failure message, or null if the values matched. + */ protected void failIfNecessary(final ITable expectedTable, final ITable actualTable, final FailureHandler failureHandler, final int rowNum, final String columnName, @@ -625,6 +728,15 @@ protected void failIfNecessary(final ITable expectedTable, } } + /** + * Returns the value comparer configured for the given column, or the default value comparer + * if the column has none configured. + * + * @param columnName the column name to look up. + * @param defaultValueComparer the value comparer to fall back to. + * @param columnValueComparers the per-column value comparers to look up columnName in. + * @return the value comparer to use for the given column. + */ protected ValueComparer determineValueComparer(final String columnName, final ValueComparer defaultValueComparer, final Map columnValueComparers) @@ -646,6 +758,13 @@ protected ValueComparer determineValueComparer(final String columnName, return valueComparer; } + /** + * Returns the given default value comparer, or {@link ValueComparerDefaults#getDefaultValueComparer()} + * if the given comparer is null. + * + * @param defaultValueComparer the value comparer to validate, may be null. + * @return the given value comparer, or the framework default if null. + */ protected ValueComparer determineValidDefaultValueComparer( final ValueComparer defaultValueComparer) { @@ -668,6 +787,14 @@ protected ValueComparer determineValidDefaultValueComparer( return validValueComparer; } + /** + * Returns the given per-table, per-column value comparer map, or + * {@link ValueComparerDefaults#getDefaultTableColumnValueComparerMap()} if the given map is + * null. + * + * @param tableColumnValueComparers the map to validate, may be null. + * @return the given map, or the framework default if null. + */ protected Map> determineValidTableColumnValueComparers( final Map> tableColumnValueComparers) { @@ -690,6 +817,15 @@ protected Map> determineValidTableColumnValue return validMap; } + /** + * Returns the given per-column value comparer map, or + * {@link ValueComparerDefaults#getDefaultColumnValueComparerMapForTable(String)} for the given + * table if the given map is null. + * + * @param columnValueComparers the map to validate, may be null. + * @param tableName the table name to look up the default map for, if needed. + * @return the given map, or the framework default if null. + */ protected Map determineValidColumnValueComparers( final Map columnValueComparers, final String tableName) @@ -713,6 +849,12 @@ protected Map determineValidColumnValueComparers( return validMap; } + /** + * Sets the value comparer defaults used when no comparer is explicitly configured + * for a table/column. + * + * @param valueComparerDefaults the value comparer defaults to use. + */ public void setValueComparerDefaults( final ValueComparerDefaults valueComparerDefaults) { diff --git a/src/main/java/org/dbunit/assertion/DbUnitValueComparerAssert.java b/src/main/java/org/dbunit/assertion/DbUnitValueComparerAssert.java index 7d942ff3a..4e5c87fa6 100644 --- a/src/main/java/org/dbunit/assertion/DbUnitValueComparerAssert.java +++ b/src/main/java/org/dbunit/assertion/DbUnitValueComparerAssert.java @@ -17,6 +17,7 @@ */ public class DbUnitValueComparerAssert extends DbUnitAssertBase { + /** * Asserts the two specified {@link IDataSet}s comparing their columns using * the default {@link ValueComparer} and handles failures using the default @@ -28,7 +29,7 @@ public class DbUnitValueComparerAssert extends DbUnitAssertBase * {@link IDataSet} containing all expected results. * @param actualDataSet * {@link IDataSet} containing all actual results. - * @throws DatabaseUnitException + * @throws DatabaseUnitException if an error occurs during comparison. */ public void assertWithValueComparer(final IDataSet expectedDataSet, final IDataSet actualDataSet) throws DatabaseUnitException @@ -54,7 +55,7 @@ public void assertWithValueComparer(final IDataSet expectedDataSet, * {@link ValueComparer} to use with all column value * comparisons. Can be null and will default to * {@link ValueComparerDefaults#getDefaultValueComparer()}. - * @throws DatabaseUnitException + * @throws DatabaseUnitException if an error occurs during comparison. */ public void assertWithValueComparer(final IDataSet expectedDataSet, final IDataSet actualDataSet, @@ -92,7 +93,7 @@ public void assertWithValueComparer(final IDataSet expectedDataSet, * {@link ValueComparerDefaults#getDefaultColumnValueComparerMapForTable(String)} or, * if that is empty, defaultValueComparer for all columns in all * tables. - * @throws DatabaseUnitException + * @throws DatabaseUnitException if an error occurs during comparison. */ public void assertWithValueComparer(final IDataSet expectedDataSet, final IDataSet actualDataSet, @@ -116,7 +117,7 @@ public void assertWithValueComparer(final IDataSet expectedDataSet, * {@link ITable} containing all expected results. * @param actualTable * {@link ITable} containing all actual results. - * @throws DatabaseUnitException + * @throws DatabaseUnitException if an error occurs during comparison. */ public void assertWithValueComparer(final ITable expectedTable, final ITable actualTable) throws DatabaseUnitException @@ -143,7 +144,7 @@ public void assertWithValueComparer(final ITable expectedTable, * {@link ValueComparer} to use with all column value * comparisons. Can be null and will default to * {@link ValueComparerDefaults#getDefaultValueComparer()}. - * @throws DatabaseUnitException + * @throws DatabaseUnitException if an error occurs during comparison. */ public void assertWithValueComparer(final ITable expectedTable, final ITable actualTable, final ValueComparer defaultValueComparer) @@ -184,7 +185,7 @@ public void assertWithValueComparer(final ITable expectedTable, * {@link ValueComparerDefaults#getDefaultColumnValueComparerMapForTable(String)} or, * if that is empty, defaultValueComparer for all columns in the * table. - * @throws DatabaseUnitException + * @throws DatabaseUnitException if an error occurs during comparison. */ public void assertWithValueComparer(final ITable expectedTable, final ITable actualTable, final ValueComparer defaultValueComparer, @@ -228,7 +229,7 @@ public void assertWithValueComparer(final ITable expectedTable, * {@link ValueComparerDefaults#getDefaultColumnValueComparerMapForTable(String)} or, * if that is empty, defaultValueComparer for all columns in the * table. - * @throws DatabaseUnitException + * @throws DatabaseUnitException if an error occurs during comparison. */ public void assertWithValueComparer(final ITable expectedTable, final ITable actualTable, final Column[] additionalColumnInfo, diff --git a/src/main/java/org/dbunit/assertion/DefaultFailureHandler.java b/src/main/java/org/dbunit/assertion/DefaultFailureHandler.java index 5cc0933e3..fe079b73e 100644 --- a/src/main/java/org/dbunit/assertion/DefaultFailureHandler.java +++ b/src/main/java/org/dbunit/assertion/DefaultFailureHandler.java @@ -85,6 +85,8 @@ public DefaultFailureHandler(final String[] additionalColumnInfo) } /** + * Sets the failure factory used to create assertion errors. + * * @param failureFactory * The {@link FailureFactory} to be used for creating assertion * errors. @@ -159,6 +161,14 @@ private String buildAdditionalColumnInfo(final ITable expectedTable, return sb.toString(); } + /** + * Returns the value of the given column, resolving through a {@link ColumnFilterTable} wrapper if needed. + * + * @param table the table to read the value from. + * @param rowIndex the row index to read. + * @param columnName the column name to read. + * @return the column value, or an error message string if it could not be retrieved. + */ protected Object getColumnValue(final ITable table, final int rowIndex, final String columnName) { @@ -176,6 +186,13 @@ protected Object getColumnValue(final ITable table, final int rowIndex, return value; } + /** + * Builds an error message describing why additional column info could not be retrieved. + * + * @param columnName the column name that could not be read. + * @param e the exception raised while reading the column. + * @return the formatted error message. + */ protected String makeAdditionalColumnInfoErrorMessage( final String columnName, final DataSetException e) { @@ -243,6 +260,12 @@ public void handle(final Difference diff) throw err; } + /** + * Builds the failure message for the given difference. + * + * @param diff the difference to describe. + * @return the formatted failure message. + */ protected String buildMessage(final Difference diff) { final StringBuilder builder = new StringBuilder(200); @@ -277,6 +300,12 @@ protected String buildMessage(final Difference diff) return builder.toString(); } + /** + * Appends the difference's fail message, if any, to the given builder. + * + * @param diff the difference whose fail message should be appended. + * @param builder the builder to append to. + */ protected void addFailMessage(final Difference diff, final StringBuilder builder) { @@ -288,6 +317,12 @@ protected void addFailMessage(final Difference diff, } } + /** + * Returns whether the given fail message is non-empty. + * + * @param failMessage the fail message to check. + * @return true if the given fail message is non-null and non-empty. + */ protected boolean isFailMessage(final String failMessage) { return failMessage != null && !failMessage.isEmpty(); @@ -316,6 +351,7 @@ public String toString() */ public static class DefaultFailureFactory implements FailureFactory { + public Error createFailure(final String message, final String expected, final String actual) { diff --git a/src/main/java/org/dbunit/assertion/DiffCollectingFailureHandler.java b/src/main/java/org/dbunit/assertion/DiffCollectingFailureHandler.java index 1aba6efab..4c77f5b20 100644 --- a/src/main/java/org/dbunit/assertion/DiffCollectingFailureHandler.java +++ b/src/main/java/org/dbunit/assertion/DiffCollectingFailureHandler.java @@ -49,17 +49,19 @@ public class DiffCollectingFailureHandler extends DefaultFailureHandler { private final List diffList = new ArrayList(); - - public void handle(Difference diff) + + public void handle(Difference diff) { // Simply collect the difference without throwing an exception this.diffList.add(diff); } /** + * Returns the list of collected {@link Difference}s. + * * @return The list of collected {@link Difference}s */ - public List getDiffList() + public List getDiffList() { return diffList; } diff --git a/src/main/java/org/dbunit/assertion/Difference.java b/src/main/java/org/dbunit/assertion/Difference.java index 900120354..a1f38e589 100644 --- a/src/main/java/org/dbunit/assertion/Difference.java +++ b/src/main/java/org/dbunit/assertion/Difference.java @@ -45,6 +45,16 @@ public class Difference private Object actualValue; private String failMessage; + /** + * Creates a difference with no fail message. + * + * @param expectedTable the table containing the expected results. + * @param actualTable the table containing the actual results. + * @param rowIndex the row index of the differing cell. + * @param columnName the name of the differing column. + * @param expectedValue the expected cell value. + * @param actualValue the actual cell value. + */ public Difference(final ITable expectedTable, final ITable actualTable, final int rowIndex, final String columnName, final Object expectedValue, final Object actualValue) @@ -53,6 +63,17 @@ public Difference(final ITable expectedTable, final ITable actualTable, actualValue, ""); } + /** + * Creates a difference with the given fail message. + * + * @param expectedTable the table containing the expected results. + * @param actualTable the table containing the actual results. + * @param rowIndex the row index of the differing cell. + * @param columnName the name of the differing column. + * @param expectedValue the expected cell value. + * @param actualValue the actual cell value. + * @param failMessage the comparison failure message. + */ public Difference(final ITable expectedTable, final ITable actualTable, final int rowIndex, final String columnName, final Object expectedValue, final Object actualValue, @@ -83,41 +104,73 @@ public String toString() return sb.toString(); } + /** + * Returns the table containing the expected results. + * @return the table containing the expected results. + */ public ITable getExpectedTable() { return expectedTable; } + /** + * Returns the table containing the actual results. + * @return the table containing the actual results. + */ public ITable getActualTable() { return actualTable; } + /** + * Returns the row index of the differing cell. + * @return the row index of the differing cell. + */ public int getRowIndex() { return rowIndex; } + /** + * Returns the name of the differing column. + * @return the name of the differing column. + */ public String getColumnName() { return columnName; } + /** + * Returns the expected cell value. + * @return the expected cell value. + */ public Object getExpectedValue() { return expectedValue; } + /** + * Returns the actual cell value. + * @return the actual cell value. + */ public Object getActualValue() { return actualValue; } + /** + * Returns the comparison failure message. + * @return the comparison failure message. + */ public String getFailMessage() { return failMessage; } + /** + * Sets the comparison failure message. + * @param failMessage the comparison failure message. + */ public void setFailMessage(final String failMessage) { this.failMessage = failMessage; diff --git a/src/main/java/org/dbunit/assertion/FailureFactory.java b/src/main/java/org/dbunit/assertion/FailureFactory.java index d7e26d19b..75d898c65 100644 --- a/src/main/java/org/dbunit/assertion/FailureFactory.java +++ b/src/main/java/org/dbunit/assertion/FailureFactory.java @@ -43,6 +43,8 @@ public interface FailureFactory public Error createFailure(String message, String expected, String actual); /** + * Creates a new assertion failure object with only a message and no expected/actual values. + * * @param message The reason for the failure * @return The assertion failure object for this handler (can be JUnit or some other) * which can be thrown on an assertion failure diff --git a/src/main/java/org/dbunit/assertion/FailureHandler.java b/src/main/java/org/dbunit/assertion/FailureHandler.java index 17ac7796d..97c580567 100644 --- a/src/main/java/org/dbunit/assertion/FailureHandler.java +++ b/src/main/java/org/dbunit/assertion/FailureHandler.java @@ -37,8 +37,8 @@ public interface FailureHandler extends DifferenceListener, FailureFactory * Returns a string to be appended to the assertion failure message. Is used to * provide some more information about a failure (for example to print out some * PK columns for identifying the failed rows in the DB). - * @param expectedTable - * @param actualTable + * @param expectedTable the table containing the expected results. + * @param actualTable the table containing the actual results. * @param row The row for which the assertion failed * @param columnName The column for which the assertion failed * @return A string that is appended to the assertion failure message diff --git a/src/main/java/org/dbunit/assertion/JUnitFailureFactory.java b/src/main/java/org/dbunit/assertion/JUnitFailureFactory.java index faab7c068..ab0ffe9dc 100644 --- a/src/main/java/org/dbunit/assertion/JUnitFailureFactory.java +++ b/src/main/java/org/dbunit/assertion/JUnitFailureFactory.java @@ -35,6 +35,7 @@ * @since 2.4.0 */ public class JUnitFailureFactory implements FailureFactory { + @Override public Error createFailure(final String message, final String expected, final String actual) { return new DbComparisonFailure( diff --git a/src/main/java/org/dbunit/assertion/SimpleAssert.java b/src/main/java/org/dbunit/assertion/SimpleAssert.java index 356fe0c74..ffcdcc792 100644 --- a/src/main/java/org/dbunit/assertion/SimpleAssert.java +++ b/src/main/java/org/dbunit/assertion/SimpleAssert.java @@ -40,7 +40,12 @@ public class SimpleAssert private static final Logger logger = LoggerFactory.getLogger(SimpleAssert.class); private FailureHandler failureHandler; - + + /** + * Constructs a SimpleAssert reporting failures through the given handler. + * + * @param failureHandler the handler used to report failures. + */ public SimpleAssert(FailureHandler failureHandler) { if (failureHandler == null) { @@ -66,10 +71,15 @@ protected void assertNotNullNorEmpty( String propertyName, String property ) .length() > 0 ); } + /** + * Evaluate if the given condition is true or not. + * + * @param condition condition to be tested + */ public void assertTrue(boolean condition) { assertTrue(null, condition); } - + /** * Evaluate if the given condition is true or not. * @param message message displayed if assertion is false @@ -81,14 +91,30 @@ public void assertTrue(String message, boolean condition) { } } + /** + * Evaluate that the given object is not null. + * + * @param object the object to check. + */ public void assertNotNull(Object object) { assertTrue(null, object!=null); } + /** + * Evaluate that the given object is not null. + * + * @param message message displayed if assertion is false + * @param object the object to check. + */ public void assertNotNull(String message, Object object) { assertTrue(message, object!=null); } - + + /** + * Reports a failure through this instance's {@link FailureHandler}. + * + * @param message message displayed for the failure. + */ public void fail(String message) { throw failureHandler.createFailure(message); } diff --git a/src/main/java/org/dbunit/assertion/comparer/value/ConditionalSelectorMultiValueComparer.java b/src/main/java/org/dbunit/assertion/comparer/value/ConditionalSelectorMultiValueComparer.java index f3e29ab56..1082f4b63 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/ConditionalSelectorMultiValueComparer.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/ConditionalSelectorMultiValueComparer.java @@ -20,6 +20,13 @@ public class ConditionalSelectorMultiValueComparer extends ValueComparerBase private final ValueComparerSelector valueComparerSelector; private final Map valueComparers; + /** + * Creates a comparer that selects a {@link ValueComparer} from the given map using the + * given selector. + * + * @param valueComparers the map of value comparers to select from. + * @param valueComparerSelector the selector used to choose a value comparer from the map. + */ public ConditionalSelectorMultiValueComparer(final Map valueComparers, final ValueComparerSelector valueComparerSelector) { assertNotNull(valueComparerSelector, "valueComparerSelector is null."); diff --git a/src/main/java/org/dbunit/assertion/comparer/value/ConditionalSetBiValueComparer.java b/src/main/java/org/dbunit/assertion/comparer/value/ConditionalSetBiValueComparer.java index d2b47fa88..b12c3f70b 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/ConditionalSetBiValueComparer.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/ConditionalSetBiValueComparer.java @@ -39,6 +39,9 @@ public class ConditionalSetBiValueComparer extends ValueComparerBase private final ValueComparer notInValuesValueComparer; /** + * Creates a comparer that selects between two {@link ValueComparer}s based on whether a + * value derived from the actual row is present in a set of values. + * * @param actualValueFactory * Factory to make the value to lookup in the values list. * @param values @@ -88,6 +91,15 @@ public String doCompare(final ITable expectedTable, return failMessage; } + /** + * Returns whether the value derived from the given row of the actual table is present + * in {@link #values}. + * + * @param actualTable the actual table to derive the value from. + * @param rowNum the row number to derive the value from. + * @return true if the derived value is present in {@link #values}. + * @throws DataSetException if the value cannot be derived from the actual table. + */ protected boolean isActualValueInValues(final ITable actualTable, final int rowNum) throws DataSetException { diff --git a/src/main/java/org/dbunit/assertion/comparer/value/DefaultValueComparerDefaults.java b/src/main/java/org/dbunit/assertion/comparer/value/DefaultValueComparerDefaults.java index ca95d683f..a2209d23d 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/DefaultValueComparerDefaults.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/DefaultValueComparerDefaults.java @@ -11,6 +11,7 @@ */ public class DefaultValueComparerDefaults implements ValueComparerDefaults { + @Override public ValueComparer getDefaultValueComparer() { diff --git a/src/main/java/org/dbunit/assertion/comparer/value/IsActualContainingExpectedStringValueComparer.java b/src/main/java/org/dbunit/assertion/comparer/value/IsActualContainingExpectedStringValueComparer.java index 51b5e1fdd..16da08193 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/IsActualContainingExpectedStringValueComparer.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/IsActualContainingExpectedStringValueComparer.java @@ -47,6 +47,15 @@ protected boolean isExpected(final ITable expectedTable, return isExpected; } + /** + * Returns whether the actual value, converted to a string, contains the expected value, + * also converted to a string. + * + * @param expectedValue the expected value. + * @param actualValue the actual value. + * @return true if the actual value's string form contains the expected value's string form. + * @throws TypeCastException if either value cannot be converted to a string. + */ protected boolean isContaining(final Object expectedValue, final Object actualValue) throws TypeCastException { diff --git a/src/main/java/org/dbunit/assertion/comparer/value/IsActualEqualToExpectedValueComparer.java b/src/main/java/org/dbunit/assertion/comparer/value/IsActualEqualToExpectedValueComparer.java index d8017dccf..23f906967 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/IsActualEqualToExpectedValueComparer.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/IsActualEqualToExpectedValueComparer.java @@ -13,6 +13,7 @@ */ public class IsActualEqualToExpectedValueComparer extends ValueComparerTemplateBase { + @Override protected boolean isExpected(final ITable expectedTable, final ITable actualTable, final int rowNum, final String columnName, diff --git a/src/main/java/org/dbunit/assertion/comparer/value/IsActualEqualToExpectedWithEmptyFailMessageValueComparer.java b/src/main/java/org/dbunit/assertion/comparer/value/IsActualEqualToExpectedWithEmptyFailMessageValueComparer.java index 1c083731c..08b6f9bab 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/IsActualEqualToExpectedWithEmptyFailMessageValueComparer.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/IsActualEqualToExpectedWithEmptyFailMessageValueComparer.java @@ -18,6 +18,7 @@ public class IsActualEqualToExpectedWithEmptyFailMessageValueComparer extends ValueComparerTemplateBase { + @Override protected boolean isExpected(final ITable expectedTable, final ITable actualTable, final int rowNum, final String columnName, diff --git a/src/main/java/org/dbunit/assertion/comparer/value/IsActualGreaterThanExpectedValueComparer.java b/src/main/java/org/dbunit/assertion/comparer/value/IsActualGreaterThanExpectedValueComparer.java index 68ac1aadb..1fe9b16b2 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/IsActualGreaterThanExpectedValueComparer.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/IsActualGreaterThanExpectedValueComparer.java @@ -13,6 +13,7 @@ */ public class IsActualGreaterThanExpectedValueComparer extends ValueComparerTemplateBase { + @Override protected boolean isExpected(final ITable expectedTable, final ITable actualTable, final int rowNum, final String columnName, diff --git a/src/main/java/org/dbunit/assertion/comparer/value/IsActualGreaterThanExpectedWithIgnoreMillisValueComparer.java b/src/main/java/org/dbunit/assertion/comparer/value/IsActualGreaterThanExpectedWithIgnoreMillisValueComparer.java index 11e1fa468..4cd5513b9 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/IsActualGreaterThanExpectedWithIgnoreMillisValueComparer.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/IsActualGreaterThanExpectedWithIgnoreMillisValueComparer.java @@ -13,6 +13,7 @@ public class IsActualGreaterThanExpectedWithIgnoreMillisValueComparer extends TimestampIgnoreMillisValueComparerBase { + @Override protected boolean compareTimestamps(final DataType dataType, final long actualTime, final long expectedTime) diff --git a/src/main/java/org/dbunit/assertion/comparer/value/IsActualGreaterThanOrEqualToExpectedValueComparer.java b/src/main/java/org/dbunit/assertion/comparer/value/IsActualGreaterThanOrEqualToExpectedValueComparer.java index 2ca7b316d..38cbd1005 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/IsActualGreaterThanOrEqualToExpectedValueComparer.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/IsActualGreaterThanOrEqualToExpectedValueComparer.java @@ -14,6 +14,7 @@ public class IsActualGreaterThanOrEqualToExpectedValueComparer extends ValueComparerTemplateBase { + @Override protected boolean isExpected(final ITable expectedTable, final ITable actualTable, final int rowNum, final String columnName, diff --git a/src/main/java/org/dbunit/assertion/comparer/value/IsActualGreaterThanOrEqualToExpectedWithIgnoreMillisValueComparer.java b/src/main/java/org/dbunit/assertion/comparer/value/IsActualGreaterThanOrEqualToExpectedWithIgnoreMillisValueComparer.java index 48fa483b2..0fa16efa2 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/IsActualGreaterThanOrEqualToExpectedWithIgnoreMillisValueComparer.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/IsActualGreaterThanOrEqualToExpectedWithIgnoreMillisValueComparer.java @@ -13,6 +13,7 @@ public class IsActualGreaterThanOrEqualToExpectedWithIgnoreMillisValueComparer extends TimestampIgnoreMillisValueComparerBase { + @Override protected boolean compareTimestamps(final DataType dataType, final long actualTime, final long expectedTime) diff --git a/src/main/java/org/dbunit/assertion/comparer/value/IsActualLessThanExpectedValueComparer.java b/src/main/java/org/dbunit/assertion/comparer/value/IsActualLessThanExpectedValueComparer.java index 470cf3260..7dc032e58 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/IsActualLessThanExpectedValueComparer.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/IsActualLessThanExpectedValueComparer.java @@ -13,6 +13,7 @@ */ public class IsActualLessThanExpectedValueComparer extends ValueComparerTemplateBase { + @Override protected boolean isExpected(final ITable expectedTable, final ITable actualTable, final int rowNum, final String columnName, diff --git a/src/main/java/org/dbunit/assertion/comparer/value/IsActualLessThanOrEqualToExpectedValueComparer.java b/src/main/java/org/dbunit/assertion/comparer/value/IsActualLessThanOrEqualToExpectedValueComparer.java index 250c4130b..bbb2411a4 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/IsActualLessThanOrEqualToExpectedValueComparer.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/IsActualLessThanOrEqualToExpectedValueComparer.java @@ -14,6 +14,7 @@ public class IsActualLessThanOrEqualToExpectedValueComparer extends ValueComparerTemplateBase { + @Override protected boolean isExpected(final ITable expectedTable, final ITable actualTable, final int rowNum, final String columnName, diff --git a/src/main/java/org/dbunit/assertion/comparer/value/IsActualNotEqualToExpectedValueComparer.java b/src/main/java/org/dbunit/assertion/comparer/value/IsActualNotEqualToExpectedValueComparer.java index f19328828..d2e7a5207 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/IsActualNotEqualToExpectedValueComparer.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/IsActualNotEqualToExpectedValueComparer.java @@ -13,6 +13,7 @@ */ public class IsActualNotEqualToExpectedValueComparer extends ValueComparerTemplateBase { + @Override protected boolean isExpected(final ITable expectedTable, final ITable actualTable, final int rowNum, final String columnName, diff --git a/src/main/java/org/dbunit/assertion/comparer/value/IsActualNotNullValueComparer.java b/src/main/java/org/dbunit/assertion/comparer/value/IsActualNotNullValueComparer.java index 12a15a663..2f469de99 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/IsActualNotNullValueComparer.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/IsActualNotNullValueComparer.java @@ -25,6 +25,11 @@ protected boolean isExpected(final ITable expectedTable, return actualValue != null; } + /** + * Returns the message used when the actual value is unexpectedly null. + * + * @return the message used when the actual value is unexpectedly null. + */ protected String makeFailMessage() { return ACTUAL_VALUE_IS_NULL; diff --git a/src/main/java/org/dbunit/assertion/comparer/value/IsActualNullValueComparer.java b/src/main/java/org/dbunit/assertion/comparer/value/IsActualNullValueComparer.java index fdf69d7c0..730ca40a8 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/IsActualNullValueComparer.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/IsActualNullValueComparer.java @@ -25,6 +25,11 @@ protected boolean isExpected(final ITable expectedTable, return actualValue == null; } + /** + * Returns the message used when the actual value is unexpectedly non-null. + * + * @return the message used when the actual value is unexpectedly non-null. + */ protected String makeFailMessage() { return ACTUAL_VALUE_IS_NOT_NULL; diff --git a/src/main/java/org/dbunit/assertion/comparer/value/IsActualWithinToleranceOfExpectedTimestampValueComparer.java b/src/main/java/org/dbunit/assertion/comparer/value/IsActualWithinToleranceOfExpectedTimestampValueComparer.java index ca0d6f4f1..8d526a1b5 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/IsActualWithinToleranceOfExpectedTimestampValueComparer.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/IsActualWithinToleranceOfExpectedTimestampValueComparer.java @@ -26,17 +26,28 @@ public class IsActualWithinToleranceOfExpectedTimestampValueComparer { private final Logger log = LoggerFactory.getLogger(getClass()); + /** One second, in milliseconds. */ public static final long ONE_SECOND_IN_MILLIS = 1000; + /** Two seconds, in milliseconds. */ public static final long TWO_SECONDS_IN_MILLIS = ONE_SECOND_IN_MILLIS * 2; + /** Three seconds, in milliseconds. */ public static final long THREE_SECONDS_IN_MILLIS = ONE_SECOND_IN_MILLIS * 3; + /** Four seconds, in milliseconds. */ public static final long FOUR_SECONDS_IN_MILLIS = ONE_SECOND_IN_MILLIS * 4; + /** Five seconds, in milliseconds. */ public static final long FIVE_SECONDS_IN_MILLIS = ONE_SECOND_IN_MILLIS * 5; + /** One minute, in milliseconds. */ public static final long ONE_MINUTE_IN_MILLIS = ONE_SECOND_IN_MILLIS * 60; + /** Two minutes, in milliseconds. */ public static final long TWO_MINUTES_IN_MILLIS = ONE_MINUTE_IN_MILLIS * 2; + /** Three minutes, in milliseconds. */ public static final long THREE_MINUTES_IN_MILLIS = ONE_MINUTE_IN_MILLIS * 3; + /** Four minutes, in milliseconds. */ public static final long FOUR_MINUTES_IN_MILLIS = ONE_MINUTE_IN_MILLIS * 4; + /** Five minutes, in milliseconds. */ public static final long FIVE_MINUTES_IN_MILLIS = ONE_MINUTE_IN_MILLIS * 5; + /** Ten minutes, in milliseconds. */ public static final long TEN_MINUTES_IN_MILLIS = ONE_MINUTE_IN_MILLIS * 10; private long lowToleranceValueInMillis; @@ -80,7 +91,14 @@ protected boolean isExpected(final ITable expectedTable, return isExpected; } - /** Since one is a known null, isExpected=true when they equal. */ + /** + * Since one is a known null, isExpected=true when they equal. + * + * @param expectedValue the expected value, possibly null. + * @param actualValue the actual value, possibly null. + * @return true if expectedValue and actualValue are the same reference + * (both null, or the same non-null instance). + */ protected boolean isExpectedWithNull(final Object expectedValue, final Object actualValue) { @@ -92,7 +110,15 @@ protected boolean isExpectedWithNull(final Object expectedValue, return isExpected; } - /** Neither is null so compare values with tolerance. */ + /** + * Neither is null so compare values with tolerance. + * + * @param expectedValue the expected value, not null. + * @param actualValue the actual value, not null. + * @param dataType the data type used to cast both values to a {@link Timestamp}. + * @return true if actualValue is within tolerance of expectedValue. + * @throws TypeCastException if either value cannot be cast using dataType. + */ protected boolean isExpectedWithoutNull(final Object expectedValue, final Object actualValue, final DataType dataType) throws TypeCastException { assertNotNull(expectedValue, "expectedValue is null."); @@ -109,6 +135,15 @@ protected boolean isExpectedWithoutNull(final Object expectedValue, final Object return isTolerant(diffTime); } + /** + * Casts the given value using the given data type, or returns it unchanged if the type + * is null or {@link DataType#UNKNOWN}. + * + * @param value the value to cast. + * @param type the data type to cast with, may be null. + * @return the cast value. + * @throws TypeCastException if the value cannot be cast using the given type. + */ protected Object getCastedValue(final Object value, final DataType type) throws TypeCastException { @@ -125,6 +160,12 @@ protected Object getCastedValue(final Object value, final DataType type) return castedValue; } + /** + * Returns whether the given time difference is within the configured tolerance range. + * + * @param diffTime the (non-negative) time difference, in milliseconds. + * @return true if diffTime is within the configured tolerance range. + */ protected boolean isTolerant(final long diffTime) { final boolean isLowTolerant = diffTime >= lowToleranceValueInMillis; @@ -141,12 +182,25 @@ protected boolean isTolerant(final long diffTime) return isTolerant; } + /** + * Returns the given {@link Timestamp} value's time in milliseconds. + * + * @param timestampValue the value to convert, must be a {@link Timestamp}. + * @return the timestamp's time in milliseconds. + */ protected long convertValueToTimeInMillis(final Object timestampValue) { final Timestamp timestamp = (Timestamp) timestampValue; return timestamp.getTime(); } + /** + * Returns the absolute time difference between the given times. + * + * @param actualTimeInMillis the actual time, in milliseconds. + * @param expectedTimeInMillis the expected time, in milliseconds. + * @return the absolute difference between the two times, in milliseconds. + */ protected long calcTimeDifference(final long actualTimeInMillis, final long expectedTimeInMillis) { diff --git a/src/main/java/org/dbunit/assertion/comparer/value/NeverFailsValueComparer.java b/src/main/java/org/dbunit/assertion/comparer/value/NeverFailsValueComparer.java index 16ec7eb20..1be4f36cc 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/NeverFailsValueComparer.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/NeverFailsValueComparer.java @@ -14,6 +14,7 @@ */ public class NeverFailsValueComparer extends ValueComparerTemplateBase { + @Override protected boolean isExpected(final ITable expectedTable, final ITable actualTable, final int rowNum, final String columnName, diff --git a/src/main/java/org/dbunit/assertion/comparer/value/TimestampIgnoreMillisValueComparerBase.java b/src/main/java/org/dbunit/assertion/comparer/value/TimestampIgnoreMillisValueComparerBase.java index 9d11e7447..5a73fabbb 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/TimestampIgnoreMillisValueComparerBase.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/TimestampIgnoreMillisValueComparerBase.java @@ -43,6 +43,14 @@ protected boolean isExpected(final ITable expectedTable, return isExpected; } + /** + * Determines whether the actual value matches the expected value when at least one of them + * is null. + * + * @param expectedValue the expected value, possibly null. + * @param actualValue the actual value, possibly null. + * @return true if the values are considered equal. + */ protected boolean isExpectedWithNull(final Object expectedValue, final Object actualValue) { @@ -59,6 +67,16 @@ protected boolean isExpectedWithNull(final Object expectedValue, return isExpected; } + /** + * Determines whether the actual value matches the expected value, ignoring milliseconds, + * given that neither is null. + * + * @param dataType the column's data type. + * @param expectedValue the expected value, never null. + * @param actualValue the actual value, never null. + * @return true if the values are considered equal, ignoring milliseconds. + * @throws TypeCastException if a value cannot be converted for comparison. + */ protected boolean isExpectedWithoutNull(final DataType dataType, final Object expectedValue, final Object actualValue) throws TypeCastException @@ -81,6 +99,13 @@ private long truncateToSecond(final long timeInMilliseconds) * (timeInMilliseconds / ONE_SECOND_IN_MILLIS); } + /** + * Converts the given value to milliseconds since the epoch. + * + * @param timestampValue the value to convert, a {@link Timestamp} or a {@link String} + * formatted as yyyy-MM-dd HH:mm:ss. + * @return the value converted to milliseconds since the epoch, or 0 if the value is neither. + */ protected long convertValueToTimeInMillis(final Object timestampValue) { final Timestamp timestamp; diff --git a/src/main/java/org/dbunit/assertion/comparer/value/ValueComparer.java b/src/main/java/org/dbunit/assertion/comparer/value/ValueComparer.java index dfb5c2ef7..661d5c5e8 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/ValueComparer.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/ValueComparer.java @@ -33,7 +33,7 @@ public interface ValueComparer * @param actualValue * The current actual value for the column. * @return compare failure message or null if successful compare. - * @throws DatabaseUnitException + * @throws DatabaseUnitException if the comparison cannot be performed. */ String compare(ITable expectedTable, ITable actualTable, int rowNum, String columnName, DataType dataType, Object expectedValue, diff --git a/src/main/java/org/dbunit/assertion/comparer/value/ValueComparerBase.java b/src/main/java/org/dbunit/assertion/comparer/value/ValueComparerBase.java index 9e442018c..678b86277 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/ValueComparerBase.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/ValueComparerBase.java @@ -55,6 +55,15 @@ public String compare(final ITable expectedTable, final ITable actualTable, /** * Do the comparison and return a fail message or null if comparison passes. * + * @param expectedTable Table containing all expected results. + * @param actualTable Table containing all actual results. + * @param rowNum The current row number comparing. + * @param columnName The name of the current column comparing. + * @param dataType The {@link DataType} for the current column comparing. + * @param expectedValue The current expected value for the column. + * @param actualValue The current actual value for the column. + * @return compare failure message or null if successful compare. + * @throws DatabaseUnitException if the comparison cannot be performed. * @see ValueComparer#compare(ITable, ITable, int, String, DataType, Object, * Object) */ diff --git a/src/main/java/org/dbunit/assertion/comparer/value/ValueComparerDefaults.java b/src/main/java/org/dbunit/assertion/comparer/value/ValueComparerDefaults.java index b298409e9..608c87c29 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/ValueComparerDefaults.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/ValueComparerDefaults.java @@ -10,10 +10,26 @@ */ public interface ValueComparerDefaults { + /** + * Returns the default value comparer, used when a table/column has none configured. + * + * @return the default value comparer. + */ ValueComparer getDefaultValueComparer(); + /** + * Returns the default per-table, per-column value comparer map. + * + * @return the default per-table, per-column value comparer map. + */ Map> getDefaultTableColumnValueComparerMap(); + /** + * Returns the default per-column value comparer map for the given table. + * + * @param tableName the table name to get the default column value comparer map for. + * @return the default per-column value comparer map for the given table. + */ Map getDefaultColumnValueComparerMapForTable( String tableName); } diff --git a/src/main/java/org/dbunit/assertion/comparer/value/ValueComparerSelector.java b/src/main/java/org/dbunit/assertion/comparer/value/ValueComparerSelector.java index 207e2bce2..c9b27f902 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/ValueComparerSelector.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/ValueComparerSelector.java @@ -17,9 +17,19 @@ public interface ValueComparerSelector { /** + * Selects a {@link ValueComparer} from the given map for the given row and column. + * + * @param expectedTable Table containing all expected results. + * @param actualTable Table containing all actual results. + * @param rowNum The current row number comparing. + * @param columnName The name of the current column comparing. + * @param dataType The {@link DataType} for the current column comparing. + * @param expectedValue The current expected value for the column. + * @param actualValue The current actual value for the column. + * @param valueComparers The map of value comparers to select from. * @return The selected {@link ValueComparer} from the specified * valueComparers map. - * @throws DatabaseUnitException + * @throws DatabaseUnitException if a value comparer cannot be selected. */ ValueComparer select(ITable expectedTable, ITable actualTable, int rowNum, String columnName, DataType dataType, Object expectedValue, diff --git a/src/main/java/org/dbunit/assertion/comparer/value/ValueComparerTemplateBase.java b/src/main/java/org/dbunit/assertion/comparer/value/ValueComparerTemplateBase.java index 22595f071..ec97cca6d 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/ValueComparerTemplateBase.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/ValueComparerTemplateBase.java @@ -13,6 +13,7 @@ */ public abstract class ValueComparerTemplateBase extends ValueComparerBase { + /** * {@inheritDoc} * @@ -46,6 +47,8 @@ protected String doCompare(final ITable expectedTable, /** * Makes the fail message using {@link #getFailPhrase()}. * + * @param expectedValue the current expected value for the column. + * @param actualValue the current actual value for the column. * @return the formatted fail message with the fail phrase. */ protected String makeFailMessage(final Object expectedValue, @@ -56,12 +59,28 @@ protected String makeFailMessage(final Object expectedValue, expectedValue); } - /** @return true if comparing actual to expected is as expected. */ + /** + * Determines whether the actual value compares as expected against the expected value. + * + * @param expectedTable Table containing all expected results. + * @param actualTable Table containing all actual results. + * @param rowNum The current row number comparing. + * @param columnName The name of the current column comparing. + * @param dataType The {@link DataType} for the current column comparing. + * @param expectedValue The current expected value for the column. + * @param actualValue The current actual value for the column. + * @return true if comparing actual to expected is as expected. + * @throws DatabaseUnitException if the comparison cannot be performed. + */ protected abstract boolean isExpected(final ITable expectedTable, final ITable actualTable, final int rowNum, final String columnName, final DataType dataType, final Object expectedValue, final Object actualValue) throws DatabaseUnitException; - /** @return The text snippet for substitution in {@link #BASE_FAIL_MSG}. */ + /** + * Returns the text snippet for substitution in {@link #BASE_FAIL_MSG}. + * + * @return The text snippet for substitution in {@link #BASE_FAIL_MSG}. + */ protected abstract String getFailPhrase(); } diff --git a/src/main/java/org/dbunit/assertion/comparer/value/ValueComparers.java b/src/main/java/org/dbunit/assertion/comparer/value/ValueComparers.java index 0e153b6d6..a498b7ead 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/ValueComparers.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/ValueComparers.java @@ -11,11 +11,18 @@ */ public abstract class ValueComparers { + /** + * Default constructor. + */ protected ValueComparers() { } - /** @see IsActualEqualToExpectedValueComparer */ + /** + * Compares actual and expected values for equality. + * + * @see IsActualEqualToExpectedValueComparer + */ public static final ValueComparer isActualEqualToExpected = new IsActualEqualToExpectedValueComparer(); @@ -40,62 +47,112 @@ protected ValueComparers() new IsActualWithinToleranceOfExpectedTimestampValueComparer(0, ONE_SECOND_IN_MILLIS); - /** @see IsActualNotEqualToExpectedValueComparer */ + /** + * Compares actual and expected values for inequality. + * + * @see IsActualNotEqualToExpectedValueComparer + */ public static final ValueComparer isActualNotEqualToExpected = new IsActualNotEqualToExpectedValueComparer(); - /** @see IsActualGreaterThanExpectedValueComparer */ + /** + * Checks whether the actual value is greater than the expected value. + * + * @see IsActualGreaterThanExpectedValueComparer + */ public static final ValueComparer isActualGreaterThanExpected = new IsActualGreaterThanExpectedValueComparer(); - /** @see IsActualGreaterThanOrEqualToExpectedValueComparer */ + /** + * Checks whether the actual value is greater than or equal to the expected value. + * + * @see IsActualGreaterThanOrEqualToExpectedValueComparer + */ public static final ValueComparer isActualGreaterThanOrEqualToExpected = new IsActualGreaterThanOrEqualToExpectedValueComparer(); - /** @see IsActualLessThanOrEqualToExpectedValueComparer */ + /** + * Checks whether the actual value is less than or equal to the expected value. + * + * @see IsActualLessThanOrEqualToExpectedValueComparer + */ public static final ValueComparer isActualLessOrEqualToThanExpected = new IsActualLessThanOrEqualToExpectedValueComparer(); - /** @see IsActualLessThanExpectedValueComparer */ + /** + * Checks whether the actual value is less than the expected value. + * + * @see IsActualLessThanExpectedValueComparer + */ public static final ValueComparer isActualLessThanExpected = new IsActualLessThanExpectedValueComparer(); - /** @see IsActualNotNullValueComparer */ + /** + * Checks whether the actual value is not null. + * + * @see IsActualNotNullValueComparer + */ public static final ValueComparer isActualNotNullValueComparer = new IsActualNotNullValueComparer(); - /** @see IsActualNullValueComparer */ + /** + * Checks whether the actual value is null. + * + * @see IsActualNullValueComparer + */ public static final ValueComparer isActualNullValueComparer = new IsActualNullValueComparer(); - /** @see IsActualWithinToleranceOfExpectedTimestampValueComparer */ + /** + * Checks whether the actual timestamp is up to one second newer than the expected timestamp. + * + * @see IsActualWithinToleranceOfExpectedTimestampValueComparer + */ public static final ValueComparer isActualWithinOneSecondNewerOfExpectedTimestamp = new IsActualWithinToleranceOfExpectedTimestampValueComparer(0, ONE_SECOND_IN_MILLIS); - /** @see IsActualWithinToleranceOfExpectedTimestampValueComparer */ + /** + * Checks whether the actual timestamp is up to one second older than the expected timestamp. + * + * @see IsActualWithinToleranceOfExpectedTimestampValueComparer + */ public static final ValueComparer isActualWithinOneSecondOlderOfExpectedTimestamp = new IsActualWithinToleranceOfExpectedTimestampValueComparer( ONE_SECOND_IN_MILLIS, 0); - /** @see IsActualWithinToleranceOfExpectedTimestampValueComparer */ + /** + * Checks whether the actual timestamp is up to one minute newer than the expected timestamp. + * + * @see IsActualWithinToleranceOfExpectedTimestampValueComparer + */ public static final ValueComparer isActualWithinOneMinuteNewerOfExpectedTimestamp = new IsActualWithinToleranceOfExpectedTimestampValueComparer(0, ONE_MINUTE_IN_MILLIS); - /** @see IsActualWithinToleranceOfExpectedTimestampValueComparer */ + /** + * Checks whether the actual timestamp is up to one minute older than the expected timestamp. + * + * @see IsActualWithinToleranceOfExpectedTimestampValueComparer + */ public static final ValueComparer isActualWithinOneMinuteOlderOfExpectedTimestamp = new IsActualWithinToleranceOfExpectedTimestampValueComparer( ONE_MINUTE_IN_MILLIS, 0); /** + * Checks whether the actual value contains the expected string. + * * @see IsActualContainingExpectedStringValueComparer * @since 2.7.0 */ public static final ValueComparer isActualContainingExpectedStringValueComparer = new IsActualContainingExpectedStringValueComparer(); - /** @see NeverFailsValueComparer */ + /** + * Verifies nothing and never fails. + * + * @see NeverFailsValueComparer + */ public static final ValueComparer neverFails = new NeverFailsValueComparer(); } diff --git a/src/main/java/org/dbunit/assertion/comparer/value/ValueFactory.java b/src/main/java/org/dbunit/assertion/comparer/value/ValueFactory.java index 625f5c7e5..1e4e9f73d 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/ValueFactory.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/ValueFactory.java @@ -24,7 +24,7 @@ public interface ValueFactory * @param rowNum * The row number to make the value for. * @return The type. - * @throws DataSetException + * @throws DataSetException if the value cannot be made from the row. */ T make(ITable table, int rowNum) throws DataSetException; } diff --git a/src/main/java/org/dbunit/assertion/comparer/value/builder/ColumnValueComparerMapBuilder.java b/src/main/java/org/dbunit/assertion/comparer/value/builder/ColumnValueComparerMapBuilder.java index 6d91e4841..b70fb9eb2 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/builder/ColumnValueComparerMapBuilder.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/builder/ColumnValueComparerMapBuilder.java @@ -20,6 +20,8 @@ public class ColumnValueComparerMapBuilder /** * Add a columnName to {@link ValueComparer} mapping. * + * @param columnName the column name to map. + * @param valueComparer the value comparer to associate with the column name. * @return this for fluent syntax. */ public ColumnValueComparerMapBuilder add(final String columnName, @@ -29,7 +31,11 @@ public ColumnValueComparerMapBuilder add(final String columnName, return this; } - /** @return The assembled map. */ + /** + * Builds the map of column name to {@link ValueComparer}. + * + * @return The assembled map. + */ public Map build() { return Collections.unmodifiableMap(comparers); diff --git a/src/main/java/org/dbunit/assertion/comparer/value/builder/TableColumnValueComparerMapBuilder.java b/src/main/java/org/dbunit/assertion/comparer/value/builder/TableColumnValueComparerMapBuilder.java index 39ac0b5a9..41156154f 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/builder/TableColumnValueComparerMapBuilder.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/builder/TableColumnValueComparerMapBuilder.java @@ -20,6 +20,7 @@ public class TableColumnValueComparerMapBuilder /** * Add all mappings from the specified table map to this builder. * + * @param tableColumnValueComparers the table map to add. * @return this for fluent syntax. */ public TableColumnValueComparerMapBuilder add( @@ -34,6 +35,7 @@ public TableColumnValueComparerMapBuilder add( * Add all mappings from the specified * {@link TableColumnValueComparerMapBuilder} builder to this builder. * + * @param tableColumnValueComparerMapBuilder the builder whose mappings to add. * @return this for fluent syntax. */ public TableColumnValueComparerMapBuilder add( @@ -50,6 +52,8 @@ public TableColumnValueComparerMapBuilder add( * Add all mappings from the specified column map to a column map for the * specified table in this builder. * + * @param tableName the table to add the column map for. + * @param columnValueComparers the column map to add. * @return this for fluent syntax. */ public TableColumnValueComparerMapBuilder add(final String tableName, @@ -66,6 +70,8 @@ public TableColumnValueComparerMapBuilder add(final String tableName, * Add all mappings from the specified {@link ColumnValueComparerMapBuilder} * builder to a column map for the specified table in this builder. * + * @param tableName the table to add the column map for. + * @param columnValueComparerMapBuilder the builder whose column mappings to add. * @return this for fluent syntax. */ public TableColumnValueComparerMapBuilder add(final String tableName, @@ -83,6 +89,9 @@ public TableColumnValueComparerMapBuilder add(final String tableName, /** * Add a table to column to {@link ValueComparer} mapping. * + * @param tableName the table the mapping applies to. + * @param columnName the column the mapping applies to. + * @param valueComparer the value comparer to map to the given table and column. * @return this for fluent syntax. */ public TableColumnValueComparerMapBuilder add(final String tableName, @@ -94,12 +103,22 @@ public TableColumnValueComparerMapBuilder add(final String tableName, return this; } - /** @return The unmodifiable assembled map. */ + /** + * Assembles and returns the built map. + * + * @return The unmodifiable assembled map. + */ public Map> build() { return Collections.unmodifiableMap(comparers); } + /** + * Returns the column map for the given table, creating and registering one if absent. + * + * @param tableName the table to find or create the column map for. + * @return the column map for the given table. + */ protected Map findOrMakeColumnMap( final String tableName) { @@ -113,6 +132,11 @@ protected Map findOrMakeColumnMap( return map; } + /** + * Creates a new, empty column-to-{@link ValueComparer} map. + * + * @return a new, empty column-to-{@link ValueComparer} map. + */ protected Map makeColumnToValueComparerMap() { return new HashMap<>(); diff --git a/src/main/java/org/dbunit/assertion/comparer/value/verifier/DefaultVerifyTableDefinitionVerifier.java b/src/main/java/org/dbunit/assertion/comparer/value/verifier/DefaultVerifyTableDefinitionVerifier.java index 0818e3715..c9e30e733 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/verifier/DefaultVerifyTableDefinitionVerifier.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/verifier/DefaultVerifyTableDefinitionVerifier.java @@ -31,6 +31,14 @@ public void verify(final VerifyTableDefinition verifyTableDefinition) verify(tableName, columnExclusionFilters, columnValueComparers); } + /** + * Verify the given columnExclusionFilters and columnValueComparers agree, e.g. a + * {@link ValueComparer} does not exist for an excluded column. + * + * @param tableName the table name, used for failure reporting. + * @param columnExclusionFilters the columns excluded from comparison. + * @param columnValueComparers the per-column value comparers configured. + */ public void verify(final String tableName, final String[] columnExclusionFilters, final Map columnValueComparers) @@ -46,7 +54,13 @@ public void verify(final String tableName, } } - /** Verify the columnExclusionFilters and columnValueComparers agree. */ + /** + * Verify the columnExclusionFilters and columnValueComparers agree. + * + * @param tableName the table name, used for failure reporting. + * @param columnExclusionFilters the columns excluded from comparison. + * @param columnValueComparers the per-column value comparers configured. + */ protected void doVerify(final String tableName, final String[] columnExclusionFilters, final Map columnValueComparers) @@ -59,6 +73,14 @@ protected void doVerify(final String tableName, } } + /** + * Fails with an {@link IllegalStateException} if the given columnName has both a column + * exclusion and a specific {@link ValueComparer} configured. + * + * @param tableName the table name, used for failure reporting. + * @param columnName the excluded column name to check. + * @param columnValueComparers the per-column value comparers configured. + */ protected void failIfColumnValueComparersHaveExcludedColumn( final String tableName, final String columnName, final Map columnValueComparers) @@ -83,6 +105,12 @@ protected void failIfColumnValueComparersHaveExcludedColumn( } } + /** + * Returns whether any column exclusion filters are configured. + * + * @param columnExclusionFilters the columns excluded from comparison. + * @return true if any column exclusion filters are configured. + */ protected boolean hasColumnExclusionFilters( final String[] columnExclusionFilters) { @@ -98,6 +126,12 @@ protected boolean hasColumnExclusionFilters( return !isMissing; } + /** + * Returns whether any column value comparers are configured. + * + * @param columnValueComparers the per-column value comparers configured. + * @return true if any column value comparers are configured. + */ protected boolean hasColumnValueComparers( final Map columnValueComparers) { diff --git a/src/main/java/org/dbunit/assertion/comparer/value/verifier/VerifyTableDefinitionVerifier.java b/src/main/java/org/dbunit/assertion/comparer/value/verifier/VerifyTableDefinitionVerifier.java index 089d28900..5008545bb 100644 --- a/src/main/java/org/dbunit/assertion/comparer/value/verifier/VerifyTableDefinitionVerifier.java +++ b/src/main/java/org/dbunit/assertion/comparer/value/verifier/VerifyTableDefinitionVerifier.java @@ -13,6 +13,10 @@ */ public interface VerifyTableDefinitionVerifier { - /** Verify the {@link VerifyTableDefinition} is valid. */ + /** + * Verify the {@link VerifyTableDefinition} is valid. + * + * @param verifyTableDefinition the table definition to verify. + */ void verify(final VerifyTableDefinition verifyTableDefinition); } diff --git a/src/main/java/org/dbunit/database/AbstractResultSetTable.java b/src/main/java/org/dbunit/database/AbstractResultSetTable.java index a08570b95..4b8639297 100644 --- a/src/main/java/org/dbunit/database/AbstractResultSetTable.java +++ b/src/main/java/org/dbunit/database/AbstractResultSetTable.java @@ -48,10 +48,24 @@ public abstract class AbstractResultSetTable extends AbstractTable */ private static final Logger logger = LoggerFactory.getLogger(AbstractResultSetTable.class); + /** + * The metadata of this table. + */ protected ITableMetaData _metaData; private Statement _statement; + /** + * The result set backing this table's rows. + */ protected ResultSet _resultSet; + /** + * Creates a table wrapping the given already-executed result set. + * + * @param metaData the table metadata. + * @param resultSet the result set backing this table's rows. + * @throws SQLException if statement creation or execution fails. + * @throws DataSetException if metadata retrieval fails. + */ public AbstractResultSetTable(ITableMetaData metaData, ResultSet resultSet) throws SQLException, DataSetException { @@ -59,14 +73,25 @@ public AbstractResultSetTable(ITableMetaData metaData, ResultSet resultSet) _resultSet = resultSet; } + /** + * Creates a table from a table name, SQL statement, and connection. + * + * @param tableName the table name. + * @param selectStatement the SQL select statement. + * @param connection the database connection. + * @throws DataSetException if metadata retrieval fails. + * @throws SQLException if statement creation or execution fails. + */ public AbstractResultSetTable(String tableName, String selectStatement, IDatabaseConnection connection) throws DataSetException, SQLException { this(tableName, selectStatement, connection, false); } - + /** + * Creates a table from a table name, SQL statement, and connection. + * * @param tableName the table name. * @param selectStatement the SQL select statement. * @param connection the database connection. @@ -112,6 +137,14 @@ protected AbstractResultSetTable(String tableName, String selectStatement, } } + /** + * Creates a table from a metadata descriptor and a connection, using a forward-only result set. + * + * @param metaData the table metadata. + * @param connection the database connection. + * @throws DataSetException if metadata retrieval fails. + * @throws SQLException if statement creation or execution fails. + */ public AbstractResultSetTable(ITableMetaData metaData, IDatabaseConnection connection) throws DataSetException, SQLException { diff --git a/src/main/java/org/dbunit/database/AmbiguousTableNameException.java b/src/main/java/org/dbunit/database/AmbiguousTableNameException.java index 5aa5ca883..e017ff7c3 100644 --- a/src/main/java/org/dbunit/database/AmbiguousTableNameException.java +++ b/src/main/java/org/dbunit/database/AmbiguousTableNameException.java @@ -49,20 +49,43 @@ */ public class AmbiguousTableNameException extends DataSetException { + /** + * Constructs an AmbiguousTableNameException with no detail + * message and no encapsulated exception. + */ public AmbiguousTableNameException() { } + /** + * Constructs an AmbiguousTableNameException with the specified detail + * message and no encapsulated exception. + * + * @param msg the detail message, typically the ambiguous table name. + */ public AmbiguousTableNameException(String msg) { super(msg); } + /** + * Constructs an AmbiguousTableNameException with the specified detail + * message and encapsulated exception. + * + * @param msg the detail message, typically the ambiguous table name. + * @param e the encapsulated exception. + */ public AmbiguousTableNameException(String msg, Throwable e) { super(msg, e); } + /** + * Constructs an AmbiguousTableNameException with the encapsulated + * exception and use string representation as detail message. + * + * @param e the encapsulated exception. + */ public AmbiguousTableNameException(Throwable e) { super(e); diff --git a/src/main/java/org/dbunit/database/CachedResultSetTable.java b/src/main/java/org/dbunit/database/CachedResultSetTable.java index af0fd053c..fae113055 100644 --- a/src/main/java/org/dbunit/database/CachedResultSetTable.java +++ b/src/main/java/org/dbunit/database/CachedResultSetTable.java @@ -38,10 +38,10 @@ public class CachedResultSetTable extends CachedTable implements IResultSetTable { /** - * @param metaData - * @param resultSet - * @throws SQLException - * @throws DataSetException + * @param metaData the table metadata. + * @param resultSet the result set to load into memory. + * @throws SQLException if reading the result set fails. + * @throws DataSetException if metadata retrieval fails. * @deprecated since 2.3.0 prefer direct usage of {@link ForwardOnlyResultSetTable#ForwardOnlyResultSetTable(ITableMetaData, ResultSet)} and then invoke {@link CachedResultSetTable#CachedResultSetTable(IResultSetTable)} */ public CachedResultSetTable(ITableMetaData metaData, ResultSet resultSet) @@ -51,11 +51,11 @@ public CachedResultSetTable(ITableMetaData metaData, ResultSet resultSet) } /** - * @param metaData - * @param connection - * @throws SQLException - * @throws DataSetException - * @deprecated since 2.4.4 prefer direct usage of {@link ForwardOnlyResultSetTable#ForwardOnlyResultSetTable(ITableMetaData, IDatabaseConnection)} and then invoke {@link CachedResultSetTable#CachedResultSetTable(IResultSetTable)} + * @param metaData the table metadata. + * @param connection the database connection to query. + * @throws SQLException if executing the query fails. + * @throws DataSetException if metadata retrieval fails. + * @deprecated since 2.4.4 prefer direct usage of {@link ForwardOnlyResultSetTable#ForwardOnlyResultSetTable(ITableMetaData, IDatabaseConnection)} and then invoke {@link CachedResultSetTable#CachedResultSetTable(IResultSetTable)} */ public CachedResultSetTable(ITableMetaData metaData, IDatabaseConnection connection) throws SQLException, DataSetException @@ -63,6 +63,13 @@ public CachedResultSetTable(ITableMetaData metaData, this(new ForwardOnlyResultSetTable(metaData, connection)); } + /** + * Creates a table that eagerly loads and caches all rows of the given table, then closes it. + * + * @param table the source table to load into memory. + * @throws DataSetException if loading the rows fails. + * @throws SQLException if reading the underlying result set fails. + */ public CachedResultSetTable(IResultSetTable table) throws DataSetException, SQLException { super(table.getTableMetaData()); diff --git a/src/main/java/org/dbunit/database/CyclicTablesDependencyException.java b/src/main/java/org/dbunit/database/CyclicTablesDependencyException.java index c4a675522..54b0fa050 100644 --- a/src/main/java/org/dbunit/database/CyclicTablesDependencyException.java +++ b/src/main/java/org/dbunit/database/CyclicTablesDependencyException.java @@ -34,14 +34,22 @@ */ public class CyclicTablesDependencyException extends DataSetException { + /** + * Constructs a CyclicTablesDependencyException with the specified detail message. + * + * @param message the detail message. + */ public CyclicTablesDependencyException(String message) { super(message); } - + /** - * @param tableName - * @param cyclicTableNames + * Constructs a CyclicTablesDependencyException for the given table and its + * cyclic dependencies. + * + * @param tableName the table with a foreign-key dependency cycle. + * @param cyclicTableNames the names of the tables composing the cycle. * @since 2.4.2 */ public CyclicTablesDependencyException(String tableName, Set cyclicTableNames) diff --git a/src/main/java/org/dbunit/database/DatabaseConfig.java b/src/main/java/org/dbunit/database/DatabaseConfig.java index 87fd1df93..a02046c17 100644 --- a/src/main/java/org/dbunit/database/DatabaseConfig.java +++ b/src/main/java/org/dbunit/database/DatabaseConfig.java @@ -53,41 +53,62 @@ public class DatabaseConfig */ private static final Logger logger = LoggerFactory.getLogger(DatabaseConfig.class); + /** Name of the property configuring the {@link IStatementFactory} implementation to use. */ public static final String PROPERTY_STATEMENT_FACTORY = "http://www.dbunit.org/properties/statementFactory"; + /** Name of the property configuring the {@link IResultSetTableFactory} implementation to use. */ public static final String PROPERTY_RESULTSET_TABLE_FACTORY = "http://www.dbunit.org/properties/resultSetTableFactory"; + /** Name of the property configuring the {@link IDataTypeFactory} implementation to use. */ public static final String PROPERTY_DATATYPE_FACTORY = "http://www.dbunit.org/properties/datatypeFactory"; + /** Name of the property configuring the pattern used to escape table and column names. */ public static final String PROPERTY_ESCAPE_PATTERN = "http://www.dbunit.org/properties/escapePattern"; + /** Name of the property configuring the JDBC table types considered when reading the database schema. */ public static final String PROPERTY_TABLE_TYPE = "http://www.dbunit.org/properties/tableType"; + /** Name of the property configuring the {@link IColumnFilter} used to determine primary key columns. */ public static final String PROPERTY_PRIMARY_KEY_FILTER = "http://www.dbunit.org/properties/primaryKeyFilter"; + /** Name of the property configuring the batch size used for batched statements. */ public static final String PROPERTY_BATCH_SIZE = "http://www.dbunit.org/properties/batchSize"; - public static final String PROPERTY_FETCH_SIZE = + /** Name of the property configuring the JDBC fetch size used for result sets. */ + public static final String PROPERTY_FETCH_SIZE = "http://www.dbunit.org/properties/fetchSize"; + /** Name of the property configuring the {@link IMetadataHandler} implementation to use. */ public static final String PROPERTY_METADATA_HANDLER = "http://www.dbunit.org/properties/metadataHandler"; + /** + * Name of the property configuring whether verifying a table definition allows the expected + * table to have a different column count. + */ public static final String PROPERTY_ALLOW_VERIFYTABLEDEFINITION_EXPECTEDTABLE_COUNT_MISMATCH = "http://www.dbunit.org/properties/allowVerifytabledefinitionExpectedtableCountMismatch"; + /** Name of the property configuring the {@link IColumnFilter} used to determine MS SQL identity columns. */ public static final String PROPERTY_IDENTITY_COLUMN_FILTER = "http://www.dbunit.org/properties/mssql/identityColumnFilter"; + /** Name of the feature controlling whether table names are treated as case sensitive. */ public static final String FEATURE_CASE_SENSITIVE_TABLE_NAMES = "http://www.dbunit.org/features/caseSensitiveTableNames"; + /** Name of the feature controlling whether table names are qualified with the schema name. */ public static final String FEATURE_QUALIFIED_TABLE_NAMES = "http://www.dbunit.org/features/qualifiedTableNames"; + /** Name of the feature controlling whether batched statements are used. */ public static final String FEATURE_BATCHED_STATEMENTS = "http://www.dbunit.org/features/batchedStatements"; + /** Name of the feature controlling whether unsupported data type warnings are logged. */ public static final String FEATURE_DATATYPE_WARNING = "http://www.dbunit.org/features/datatypeWarning"; + /** Name of the feature controlling whether Oracle recycle bin tables are skipped. */ public static final String FEATURE_SKIP_ORACLE_RECYCLEBIN_TABLES = "http://www.dbunit.org/features/skipOracleRecycleBinTables"; + /** Name of the feature controlling whether empty fields are allowed in flat XML datasets. */ public static final String FEATURE_ALLOW_EMPTY_FIELDS = "http://www.dbunit.org/features/allowEmptyFields"; + /** Name of the feature controlling whether all columns are used for sorting when a table has no primary key. */ public static final String FEATURE_SORT_ALL_COLUMNS_WHEN_NO_PRIMARY_KEY = "http://www.dbunit.org/features/sortAllColumnsWhenNoPrimaryKey"; @@ -147,6 +168,9 @@ public class DatabaseConfig private final Configurator configurator; + /** + * Constructs a database config with the framework's default properties and features. + */ public DatabaseConfig() { setFeature(FEATURE_BATCHED_STATEMENTS, false); @@ -172,9 +196,11 @@ public DatabaseConfig() } /** + * Returns the configurator of this database config. + * * @return The configurator of this database config */ - protected Configurator getConfigurator() + protected Configurator getConfigurator() { return configurator; } @@ -327,7 +353,7 @@ protected void checkObjectAllowed(String property, Object value) * specified as string. * @param stringProperties The properties as strings. The key of the properties can be either the long or * the short name. - * @throws DatabaseUnitException + * @throws DatabaseUnitException if a string value cannot be converted to its required property type. */ public void setPropertiesByString(Properties stringProperties) throws DatabaseUnitException { @@ -487,6 +513,13 @@ public static class ConfigProperty private Class propertyType; private boolean nullable; + /** + * Creates a descriptor for a configuration property. + * + * @param property the property name. + * @param propertyType the allowed java type of the property's value. + * @param nullable whether the property's value may be null. + */ public ConfigProperty(String property, Class propertyType, boolean nullable) { super(); @@ -504,14 +537,26 @@ public ConfigProperty(String property, Class propertyType, boolean nullable) { this.nullable = nullable; } + /** + * Returns the property name. + * @return the property name. + */ public String getProperty() { return property; } + /** + * Returns the allowed java type of the property's value. + * @return the allowed java type of the property's value. + */ public Class getPropertyType() { return propertyType; } + /** + * Returns whether the property's value may be null. + * @return true if the property's value may be null. + */ public boolean isNullable() { return nullable; } @@ -572,6 +617,8 @@ protected static class Configurator private DatabaseConfig config; /** + * Creates a configurator backed by the given database config. + * * @param config The configuration to be used by this configurator * @since 2.4.4 */ diff --git a/src/main/java/org/dbunit/database/DatabaseConnection.java b/src/main/java/org/dbunit/database/DatabaseConnection.java index 11c6d05a1..8229063db 100644 --- a/src/main/java/org/dbunit/database/DatabaseConnection.java +++ b/src/main/java/org/dbunit/database/DatabaseConnection.java @@ -53,7 +53,7 @@ public class DatabaseConnection extends AbstractDatabaseConnection * Creates a new DatabaseConnection. * * @param connection the adapted JDBC connection - * @throws DatabaseUnitException + * @throws DatabaseUnitException if the connection cannot be adapted. */ public DatabaseConnection(Connection connection) throws DatabaseUnitException { @@ -74,7 +74,7 @@ public DatabaseConnection(Connection connection) throws DatabaseUnitException * * The first one creates the "default" user where everything is interpreted by oracle in uppercase. * The second one is completely lowercase because of the quotes. - * @throws DatabaseUnitException + * @throws DatabaseUnitException if the connection cannot be adapted. */ public DatabaseConnection(Connection connection, String schema) throws DatabaseUnitException { @@ -166,7 +166,7 @@ private void printConnectionInfo() * @param validateStrict If true an exception is thrown when the given schema * does not exist according to the DatabaseMetaData. If false the validation * will only print a warning if the schema was not found. - * @throws DatabaseUnitException + * @throws DatabaseUnitException if schema validation fails. */ private void validateSchema(boolean validateStrict) throws DatabaseUnitException { diff --git a/src/main/java/org/dbunit/database/DatabaseDataSet.java b/src/main/java/org/dbunit/database/DatabaseDataSet.java index 92c701131..911a94808 100644 --- a/src/main/java/org/dbunit/database/DatabaseDataSet.java +++ b/src/main/java/org/dbunit/database/DatabaseDataSet.java @@ -87,7 +87,7 @@ public class DatabaseDataSet extends AbstractDataSet * Creates a new database data set * @param connection The database connection * @param caseSensitiveTableNames Whether or not this dataset should use case sensitive table names - * @throws SQLException + * @throws SQLException if retrieving the database metadata fails. * @since 2.4 */ public DatabaseDataSet(IDatabaseConnection connection, boolean caseSensitiveTableNames) throws SQLException @@ -100,7 +100,7 @@ public DatabaseDataSet(IDatabaseConnection connection, boolean caseSensitiveTabl * @param connection The database connection * @param caseSensitiveTableNames Whether or not this dataset should use case sensitive table names * @param tableFilter Table filter to specify tables to be omitted in this dataset. Can be null. - * @throws SQLException + * @throws SQLException if retrieving the database metadata fails. * @since 2.4.3 */ public DatabaseDataSet(IDatabaseConnection connection, boolean caseSensitiveTableNames, ITableFilterSimple tableFilter) diff --git a/src/main/java/org/dbunit/database/DatabaseDataSourceConnection.java b/src/main/java/org/dbunit/database/DatabaseDataSourceConnection.java index eda22a41e..2511ab904 100644 --- a/src/main/java/org/dbunit/database/DatabaseDataSourceConnection.java +++ b/src/main/java/org/dbunit/database/DatabaseDataSourceConnection.java @@ -53,12 +53,33 @@ public class DatabaseDataSourceConnection extends AbstractDatabaseConnection private final String _password; private Connection _connection; + /** + * Creates a connection using the data source bound at the given JNDI name, in the given schema. + * + * @param context the JNDI context to look up the data source in. + * @param jndiName the JNDI name the data source is bound at. + * @param schema the database schema. + * @throws NamingException if the JNDI lookup fails. + * @throws SQLException if a database access error occurs. + */ public DatabaseDataSourceConnection(InitialContext context, String jndiName, String schema) throws NamingException, SQLException { this((DataSource)context.lookup(jndiName), schema, null, null); } + /** + * Creates a connection using the data source bound at the given JNDI name, in the given schema, + * authenticating with the given credentials. + * + * @param context the JNDI context to look up the data source in. + * @param jndiName the JNDI name the data source is bound at. + * @param schema the database schema. + * @param user the database user. + * @param password the database password. + * @throws NamingException if the JNDI lookup fails. + * @throws SQLException if a database access error occurs. + */ public DatabaseDataSourceConnection(InitialContext context, String jndiName, String schema, String user, String password) throws NamingException, SQLException @@ -66,36 +87,86 @@ public DatabaseDataSourceConnection(InitialContext context, String jndiName, this((DataSource)context.lookup(jndiName), schema, user, password); } + /** + * Creates a connection using the data source bound at the given JNDI name. + * + * @param context the JNDI context to look up the data source in. + * @param jndiName the JNDI name the data source is bound at. + * @throws NamingException if the JNDI lookup fails. + * @throws SQLException if a database access error occurs. + */ public DatabaseDataSourceConnection(InitialContext context, String jndiName) throws NamingException, SQLException { this(context, jndiName, null); } + /** + * Creates a connection using the data source bound at the given JNDI name, authenticating + * with the given credentials. + * + * @param context the JNDI context to look up the data source in. + * @param jndiName the JNDI name the data source is bound at. + * @param user the database user. + * @param password the database password. + * @throws NamingException if the JNDI lookup fails. + * @throws SQLException if a database access error occurs. + */ public DatabaseDataSourceConnection(InitialContext context, String jndiName, String user, String password) throws NamingException, SQLException { this(context, jndiName, null, user, password); } + /** + * Creates a connection using the given data source. + * + * @param dataSource the data source to adapt. + * @throws SQLException if a database access error occurs. + */ public DatabaseDataSourceConnection(DataSource dataSource) throws SQLException { this(dataSource, null, null, null); } + /** + * Creates a connection using the given data source, authenticating with the given credentials. + * + * @param dataSource the data source to adapt. + * @param user the database user. + * @param password the database password. + * @throws SQLException if a database access error occurs. + */ public DatabaseDataSourceConnection(DataSource dataSource, String user, String password) throws SQLException { this(dataSource, null, user, password); } + /** + * Creates a connection using the given data source, in the given schema. + * + * @param dataSource the data source to adapt. + * @param schema the database schema. + * @throws SQLException if a database access error occurs. + */ public DatabaseDataSourceConnection(DataSource dataSource, String schema) throws SQLException { this(dataSource, schema, null, null); } + /** + * Creates a connection using the given data source, in the given schema, authenticating + * with the given credentials. + * + * @param dataSource the data source to adapt. + * @param schema the database schema. + * @param user the database user. + * @param password the database password. + * @throws SQLException if a database access error occurs. + */ public DatabaseDataSourceConnection(DataSource dataSource, String schema, String user, String password) throws SQLException { diff --git a/src/main/java/org/dbunit/database/DatabaseSequenceFilter.java b/src/main/java/org/dbunit/database/DatabaseSequenceFilter.java index fd22937e7..220984a01 100644 --- a/src/main/java/org/dbunit/database/DatabaseSequenceFilter.java +++ b/src/main/java/org/dbunit/database/DatabaseSequenceFilter.java @@ -63,6 +63,11 @@ public class DatabaseSequenceFilter extends SequenceTableFilter /** * Create a DatabaseSequenceFilter that only exposes specified table names. + * + * @param connection the database connection used to resolve table dependencies. + * @param tableNames the table names to expose, re-ordered to respect FK dependencies. + * @throws DataSetException if a table dependency cycle is detected. + * @throws SQLException if an exception is encountered in accessing the database. */ public DatabaseSequenceFilter(IDatabaseConnection connection, String[] tableNames) throws DataSetException, SQLException @@ -72,6 +77,10 @@ public DatabaseSequenceFilter(IDatabaseConnection connection, /** * Create a DatabaseSequenceFilter that exposes all the database tables. + * + * @param connection the database connection used to resolve table dependencies. + * @throws DataSetException if a table dependency cycle is detected. + * @throws SQLException if an exception is encountered in accessing the database. */ public DatabaseSequenceFilter(IDatabaseConnection connection) throws DataSetException, SQLException @@ -85,7 +94,7 @@ public DatabaseSequenceFilter(IDatabaseConnection connection) * * @param tableNames A string array of table names to be ordered. * @return The re-ordered array of table names. - * @throws DataSetException + * @throws DataSetException if a table dependency cycle is detected. * @throws SQLException If an exception is encountered in accessing the database. */ static String[] sortTableNames( diff --git a/src/main/java/org/dbunit/database/DatabaseTableIterator.java b/src/main/java/org/dbunit/database/DatabaseTableIterator.java index 33adc4f8d..df8248c61 100644 --- a/src/main/java/org/dbunit/database/DatabaseTableIterator.java +++ b/src/main/java/org/dbunit/database/DatabaseTableIterator.java @@ -49,6 +49,12 @@ public class DatabaseTableIterator implements ITableIterator private IResultSetTable _currentTable; private int _index = -1; + /** + * Creates an iterator over the given table names, resolved from the given dataset. + * + * @param tableNames the names of the tables to iterate, in order. + * @param dataSet the dataset to resolve tables from. + */ public DatabaseTableIterator(String[] tableNames, IDataSet dataSet) { _tableNames = tableNames; diff --git a/src/main/java/org/dbunit/database/DatabaseTableMetaData.java b/src/main/java/org/dbunit/database/DatabaseTableMetaData.java index 9aa7be0fe..ba77cc8dd 100644 --- a/src/main/java/org/dbunit/database/DatabaseTableMetaData.java +++ b/src/main/java/org/dbunit/database/DatabaseTableMetaData.java @@ -164,12 +164,12 @@ public class DatabaseTableMetaData extends AbstractTableMetaData } /** - * @param tableName - * @param resultSet - * @param dataTypeFactory + * @param tableName the name of the database table. + * @param resultSet the JDBC result set that is used to retrieve the columns. + * @param dataTypeFactory the data type factory used to resolve column data types. * @return The table metadata created for the given parameters - * @throws DataSetException - * @throws SQLException + * @throws DataSetException if metadata retrieval fails. + * @throws SQLException if a database access error occurs. * @deprecated since 2.3.0. use {@link ResultSetTableMetaData#ResultSetTableMetaData(String, ResultSet, IDataTypeFactory, boolean)} */ public static ITableMetaData createMetaData(String tableName, @@ -188,12 +188,12 @@ public static ITableMetaData createMetaData(String tableName, /** - * @param tableName - * @param resultSet - * @param connection + * @param tableName the name of the database table. + * @param resultSet the JDBC result set that is used to retrieve the columns. + * @param connection the connection which is needed to retrieve some configuration values. * @return The table metadata created for the given parameters - * @throws SQLException - * @throws DataSetException + * @throws SQLException if a database access error occurs. + * @throws DataSetException if metadata retrieval fails. * @deprecated since 2.3.0. use {@link org.dbunit.database.ResultSetTableMetaData#ResultSetTableMetaData(String, ResultSet, IDatabaseConnection, boolean)} */ public static ITableMetaData createMetaData(String tableName, diff --git a/src/main/java/org/dbunit/database/ForwardOnlyResultSetTable.java b/src/main/java/org/dbunit/database/ForwardOnlyResultSetTable.java index b81704411..987fb5c5f 100644 --- a/src/main/java/org/dbunit/database/ForwardOnlyResultSetTable.java +++ b/src/main/java/org/dbunit/database/ForwardOnlyResultSetTable.java @@ -49,18 +49,43 @@ public class ForwardOnlyResultSetTable extends AbstractResultSetTable private int _lastRow = -1; private boolean _eot = false; // End of table flag + /** + * Creates a table wrapping the given already-executed result set. + * + * @param metaData the table metadata. + * @param resultSet the result set backing this table's rows. + * @throws SQLException if statement creation or execution fails. + * @throws DataSetException if metadata retrieval fails. + */ public ForwardOnlyResultSetTable(ITableMetaData metaData, ResultSet resultSet) throws SQLException, DataSetException { super(metaData, resultSet); } + /** + * Creates a table from a metadata descriptor and a connection, using a forward-only result set. + * + * @param metaData the table metadata. + * @param connection the database connection. + * @throws DataSetException if metadata retrieval fails. + * @throws SQLException if statement creation or execution fails. + */ public ForwardOnlyResultSetTable(ITableMetaData metaData, IDatabaseConnection connection) throws DataSetException, SQLException { super(metaData, connection); } + /** + * Creates a table from a table name, SQL statement, and connection. + * + * @param tableName the table name. + * @param selectStatement the SQL select statement. + * @param connection the database connection. + * @throws DataSetException if metadata retrieval fails. + * @throws SQLException if statement creation or execution fails. + */ public ForwardOnlyResultSetTable(String tableName, String selectStatement, IDatabaseConnection connection) throws DataSetException, SQLException { diff --git a/src/main/java/org/dbunit/database/ForwardOnlyResultSetTableFactory.java b/src/main/java/org/dbunit/database/ForwardOnlyResultSetTableFactory.java index e4b9eebae..90fcaba67 100644 --- a/src/main/java/org/dbunit/database/ForwardOnlyResultSetTableFactory.java +++ b/src/main/java/org/dbunit/database/ForwardOnlyResultSetTableFactory.java @@ -75,7 +75,6 @@ public IResultSetTable createTable(String tableName, return createForwardOnlyResultSetTable(tableName, preparedStatement, connection); } - /** * Creates a new {@link ForwardOnlyResultSetTable} using the given {@link PreparedStatement} to * retrieve the data. @@ -104,5 +103,4 @@ ForwardOnlyResultSetTable createForwardOnlyResultSetTable(String tableName, return table; } - } diff --git a/src/main/java/org/dbunit/database/IMetadataHandler.java b/src/main/java/org/dbunit/database/IMetadataHandler.java index 13a390daf..055adce5c 100644 --- a/src/main/java/org/dbunit/database/IMetadataHandler.java +++ b/src/main/java/org/dbunit/database/IMetadataHandler.java @@ -43,7 +43,7 @@ public interface IMetadataHandler * @param schemaName The schema name * @param tableName The table name * @return The result set containing all columns - * @throws SQLException + * @throws SQLException if a database access error occurs. * @since 2.4.4 */ ResultSet getColumns(DatabaseMetaData databaseMetaData, String schemaName, String tableName) @@ -53,12 +53,12 @@ ResultSet getColumns(DatabaseMetaData databaseMetaData, String schemaName, Strin * Checks if the given resultSet matches the given schema and table name. * The comparison is case sensitive. * @param resultSet A result set produced via {@link DatabaseMetaData#getColumns(String, String, String, String)} - * @param schema - * @param table + * @param schema the schema name to check. + * @param table the table name to check. * @param caseSensitive Whether or not the comparison should be case sensitive * @return true if the column metadata of the given resultSet matches * the given schema and table parameters. - * @throws SQLException + * @throws SQLException if a database access error occurs. * @see #matches(ResultSet, String, String, String, String, boolean) * @since 2.4.4 */ @@ -76,7 +76,7 @@ public boolean matches(ResultSet resultSet, String schema, String table, boolean * @param caseSensitive Whether or not the comparison should be case sensitive * @return true if the column metadata of the given resultSet matches * the given schema and table parameters. - * @throws SQLException + * @throws SQLException if a database access error occurs. * @since 2.4.4 */ boolean matches(ResultSet resultSet, String catalog, String schema, @@ -87,6 +87,7 @@ boolean matches(ResultSet resultSet, String catalog, String schema, * @param resultSet The result set pointing to a valid record in the database that was returned * by {@link DatabaseMetaData#getTables(String, String, String, String[])}. * @return The name of the schema from the given result set + * @throws SQLException if a database access error occurs. * @since 2.4.4 */ String getSchema(ResultSet resultSet) throws SQLException; @@ -99,7 +100,7 @@ boolean matches(ResultSet resultSet, String catalog, String schema, * @param tableName The table name to be searched * @return Returns true if the given table exists in the given schema. * Else returns false. - * @throws SQLException + * @throws SQLException if a database access error occurs. * @since 2.4.5 */ boolean tableExists(DatabaseMetaData databaseMetaData, String schemaName, String tableName) @@ -111,18 +112,20 @@ boolean tableExists(DatabaseMetaData databaseMetaData, String schemaName, String * @param schemaName schema for which the tables should be retrieved; null returns all schemas * @param tableTypes a list of table types to include; null returns all types * @return The ResultSet which is retrieved using {@link DatabaseMetaData#getTables(String, String, String, String[])} - * @throws SQLException + * @throws SQLException if a database access error occurs. * @since 2.4.5 */ ResultSet getTables(DatabaseMetaData databaseMetaData, String schemaName, String[] tableTypes) throws SQLException; /** + * Returns the primary keys of the given table. + * * @param databaseMetaData The database meta data * @param schemaName schema for which the tables should be retrieved; null returns all schemas * @param tableName table for which the primary keys are retrieved * @return The ResultSet which is retrieved using {@link DatabaseMetaData#getPrimaryKeys(String, String, String)} - * @throws SQLException + * @throws SQLException if a database access error occurs. * @since 2.4.5 */ public ResultSet getPrimaryKeys(DatabaseMetaData databaseMetaData, String schemaName, String tableName) diff --git a/src/main/java/org/dbunit/database/IResultSetTable.java b/src/main/java/org/dbunit/database/IResultSetTable.java index 10dcd6c54..62185f1ba 100644 --- a/src/main/java/org/dbunit/database/IResultSetTable.java +++ b/src/main/java/org/dbunit/database/IResultSetTable.java @@ -33,5 +33,10 @@ */ public interface IResultSetTable extends ITable { + /** + * Closes the underlying result set and releases its resources. + * + * @throws DataSetException if closing the result set fails. + */ public void close() throws DataSetException; } diff --git a/src/main/java/org/dbunit/database/IResultSetTableFactory.java b/src/main/java/org/dbunit/database/IResultSetTableFactory.java index 425a603f8..52a907f34 100644 --- a/src/main/java/org/dbunit/database/IResultSetTableFactory.java +++ b/src/main/java/org/dbunit/database/IResultSetTableFactory.java @@ -35,18 +35,39 @@ */ public interface IResultSetTableFactory { + /** + * Creates a table from a table name and a SQL select statement. + * + * @param tableName the table name. + * @param selectStatement the SQL select statement. + * @param connection the database connection. + * @return The table based on the SQL result set. + * @throws SQLException if executing the query fails. + * @throws DataSetException if metadata retrieval fails. + */ public IResultSetTable createTable(String tableName, String selectStatement, IDatabaseConnection connection) throws SQLException, DataSetException; + /** + * Creates a table from a metadata descriptor and a connection. + * + * @param metaData the table metadata. + * @param connection the database connection. + * @return The table based on the SQL result set. + * @throws SQLException if executing the query fails. + * @throws DataSetException if metadata retrieval fails. + */ public IResultSetTable createTable(ITableMetaData metaData, IDatabaseConnection connection) throws SQLException, DataSetException; /** * Creates a table from a preparedStatement - * @param tableName - * @param preparedStatement - * @param connection + * @param tableName the table name. + * @param preparedStatement the prepared statement to execute. + * @param connection the database connection. * @return The table based on a SQL result set + * @throws SQLException if executing the statement fails. + * @throws DataSetException if metadata retrieval fails. * @since 2.4.4 */ public IResultSetTable createTable(String tableName, PreparedStatement preparedStatement, diff --git a/src/main/java/org/dbunit/database/PrimaryKeyFilter.java b/src/main/java/org/dbunit/database/PrimaryKeyFilter.java index 2d5bc1684..65833198c 100644 --- a/src/main/java/org/dbunit/database/PrimaryKeyFilter.java +++ b/src/main/java/org/dbunit/database/PrimaryKeyFilter.java @@ -67,6 +67,7 @@ public class PrimaryKeyFilter extends AbstractTableFilter { private final boolean reverseScan; + /** Logger for this class. */ protected final Logger logger = LoggerFactory.getLogger(getClass()); // cache the primary keys @@ -98,6 +99,11 @@ public PrimaryKeyFilter(IDatabaseConnection connection, PkTableMap allowedPKs, b this.pksToScanPerTable = new PkTableMap(allowedPKs); } + /** + * Records the given node as a known table name. + * + * @param node the table name node added to the dependency graph. + */ public void nodeAdded(Object node) { this.tableNames.add( node ); if ( this.logger.isDebugEnabled() ) { @@ -105,6 +111,11 @@ public void nodeAdded(Object node) { } } + /** + * Records the given foreign key relationship in the direct and reverse edge caches. + * + * @param edge the foreign key relationship added to the dependency graph. + */ public void edgeAdded(ForeignKeyRelationshipEdge edge) { if ( this.logger.isDebugEnabled() ) { this.logger.debug("edgeAdded: " + edge ); @@ -462,6 +473,9 @@ public static class PkTableMap private final LinkedHashMap pksPerTable; private final Logger logger = LoggerFactory.getLogger(PkTableMap.class); + /** + * Default constructor. + */ public PkTableMap() { this.pksPerTable = new LinkedHashMap(); @@ -469,7 +483,7 @@ public PkTableMap() /** * Copy constructor - * @param allowedPKs + * @param allowedPKs the map to copy. */ public PkTableMap(PkTableMap allowedPKs) { this.pksPerTable = new LinkedHashMap(); @@ -483,37 +497,83 @@ public PkTableMap(PkTableMap allowedPKs) { } } + /** + * Returns the number of tables in this map. + * + * @return the number of tables in this map. + */ public int size() { return pksPerTable.size(); } + /** + * Returns whether this map has no tables. + * + * @return {@code true} if this map has no tables. + */ public boolean isEmpty() { return pksPerTable.isEmpty(); } + /** + * Returns whether the given primary key is allowed for the given table. + * + * @param table the table name. + * @param pkObject the primary key value to check. + * @return {@code true} if the given primary key is allowed for the given table. + */ public boolean contains(String table, Object pkObject) { Set pksPerTable = this.get(table); return (pksPerTable != null && pksPerTable.contains(pkObject)); } + /** + * Removes the given table and its associated primary keys from this map. + * + * @param tableName the table name to remove. + */ public void remove(String tableName) { this.pksPerTable.remove(tableName); } + /** + * Associates the given table with the given primary keys, replacing any existing association. + * + * @param table the table name. + * @param pkObjects the primary keys to associate with the table. + */ public void put(String table, SortedSet pkObjects) { this.pksPerTable.put(table, pkObjects); } + /** + * Adds a single allowed primary key for the given table. + * + * @param tableName the table name. + * @param pkObject the primary key value to add. + */ public void add(String tableName, Object pkObject) { Set pksPerTable = getCreateIfNeeded(tableName); pksPerTable.add(pkObject); } + /** + * Adds the given allowed primary keys for the given table. + * + * @param tableName the table name. + * @param pkObjectsToAdd the primary key values to add. + */ public void addAll(String tableName, Set pkObjectsToAdd) { Set pksPerTable = this.getCreateIfNeeded(tableName); pksPerTable.addAll(pkObjectsToAdd); } + /** + * Returns the primary keys allowed for the given table. + * + * @param tableName the table name. + * @return the primary keys allowed for the given table, or {@code null} if the table is not present. + */ public SortedSet get(String tableName) { return (SortedSet) this.pksPerTable.get(tableName); } @@ -528,10 +588,20 @@ private SortedSet getCreateIfNeeded(String tableName){ return pksPerTable; } + /** + * Returns the table names in this map. + * + * @return the table names in this map. + */ public String[] getTableNames() { return (String[]) this.pksPerTable.keySet().toArray(new String[0]); } + /** + * Removes every table not in the given list, and every table whose allowed primary keys are empty. + * + * @param tableNames the table names to retain. + */ public void retainOnly(List tableNames) { List tablesToRemove = new ArrayList(); diff --git a/src/main/java/org/dbunit/database/QueryDataSet.java b/src/main/java/org/dbunit/database/QueryDataSet.java index e7fa60de1..626ce2dcb 100644 --- a/src/main/java/org/dbunit/database/QueryDataSet.java +++ b/src/main/java/org/dbunit/database/QueryDataSet.java @@ -85,7 +85,7 @@ public QueryDataSet(IDatabaseConnection connection, boolean caseSensitiveTableNa * @param tableName The name of the table * @param query The query to retrieve data with for this table. Can be null which will select * all data (see {@link #addTable(String)} for details) - * @throws AmbiguousTableNameException + * @throws AmbiguousTableNameException if the given table name was already added. */ public void addTable(String tableName, String query) throws AmbiguousTableNameException { @@ -97,7 +97,7 @@ public void addTable(String tableName, String query) throws AmbiguousTableNameEx * Adds a table with using 'SELECT * FROM tableName' as query. * * @param tableName The name of the table - * @throws AmbiguousTableNameException + * @throws AmbiguousTableNameException if the given table name was already added. */ public void addTable(String tableName) throws AmbiguousTableNameException { diff --git a/src/main/java/org/dbunit/database/QueryTableIterator.java b/src/main/java/org/dbunit/database/QueryTableIterator.java index 3642efec5..1b0cda9b2 100644 --- a/src/main/java/org/dbunit/database/QueryTableIterator.java +++ b/src/main/java/org/dbunit/database/QueryTableIterator.java @@ -55,6 +55,8 @@ public class QueryTableIterator implements ITableIterator private int _index = -1; /** + * Constructs an iterator over the given table entries. + * * @param tableEntries list of {@link TableEntry} objects * @param connection The database connection needed to load data */ @@ -96,6 +98,11 @@ public boolean next() throws DataSetException return _index < _tableEntries.size(); } + /** + * Advances to the next table without closing the current one. + * + * @return true if there is a next table. + */ public boolean nextWithoutClosing() { _index++; diff --git a/src/main/java/org/dbunit/database/ResultSetTableMetaData.java b/src/main/java/org/dbunit/database/ResultSetTableMetaData.java index 869c04025..d336561cb 100644 --- a/src/main/java/org/dbunit/database/ResultSetTableMetaData.java +++ b/src/main/java/org/dbunit/database/ResultSetTableMetaData.java @@ -87,15 +87,17 @@ public class ResultSetTableMetaData extends AbstractTableMetaData private boolean _caseSensitiveMetaData; /** + * Creates the metadata for a result set, resolving column data types via the given connection. + * * @param tableName The name of the database table * @param resultSet The JDBC result set that is used to retrieve the columns * @param connection The connection which is needed to retrieve some configuration values * @param caseSensitiveMetaData Whether or not the metadata is case sensitive - * @throws DataSetException - * @throws SQLException + * @throws DataSetException if metadata retrieval fails. + * @throws SQLException if a database access error occurs. */ public ResultSetTableMetaData(String tableName, - ResultSet resultSet, IDatabaseConnection connection, boolean caseSensitiveMetaData) + ResultSet resultSet, IDatabaseConnection connection, boolean caseSensitiveMetaData) throws DataSetException, SQLException { super(); @@ -107,14 +109,14 @@ public ResultSetTableMetaData(String tableName, /** * @param tableName The name of the database table * @param resultSet The JDBC result set that is used to retrieve the columns - * @param dataTypeFactory + * @param dataTypeFactory the data type factory used to resolve column data types. * @param caseSensitiveMetaData Whether or not the metadata is case sensitive - * @throws DataSetException - * @throws SQLException + * @throws DataSetException if metadata retrieval fails. + * @throws SQLException if a database access error occurs. * @deprecated since 2.4.4. use {@link ResultSetTableMetaData#ResultSetTableMetaData(String, ResultSet, IDatabaseConnection, boolean)} */ public ResultSetTableMetaData(String tableName, - ResultSet resultSet, IDataTypeFactory dataTypeFactory, boolean caseSensitiveMetaData) + ResultSet resultSet, IDataTypeFactory dataTypeFactory, boolean caseSensitiveMetaData) throws DataSetException, SQLException { super(); diff --git a/src/main/java/org/dbunit/database/ScrollableResultSetTable.java b/src/main/java/org/dbunit/database/ScrollableResultSetTable.java index ab6f6bb1e..7440e0c14 100644 --- a/src/main/java/org/dbunit/database/ScrollableResultSetTable.java +++ b/src/main/java/org/dbunit/database/ScrollableResultSetTable.java @@ -48,6 +48,14 @@ public class ScrollableResultSetTable extends AbstractResultSetTable private final int _rowCount; + /** + * Creates a table wrapping the given, already-scrolled result set. + * + * @param metaData the table's metadata. + * @param resultSet the scrollable result set to wrap. + * @throws SQLException if the result set is forward-only or a database access error occurs. + * @throws DataSetException if the row count cannot be determined. + */ public ScrollableResultSetTable(ITableMetaData metaData, ResultSet resultSet) throws SQLException, DataSetException { @@ -70,6 +78,14 @@ public ScrollableResultSetTable(ITableMetaData metaData, ResultSet resultSet) } } + /** + * Creates a table that runs the default query for the given metadata and connection. + * + * @param metaData the table's metadata. + * @param connection the database connection to query. + * @throws DataSetException if the row count cannot be determined. + * @throws SQLException if the result set is forward-only or a database access error occurs. + */ public ScrollableResultSetTable(ITableMetaData metaData, IDatabaseConnection connection) throws DataSetException, SQLException { @@ -92,6 +108,15 @@ public ScrollableResultSetTable(ITableMetaData metaData, } } + /** + * Creates a table that runs the given select statement. + * + * @param tableName the table's name. + * @param selectStatement the SQL select statement to run. + * @param connection the database connection to query. + * @throws DataSetException if the row count cannot be determined. + * @throws SQLException if the result set is forward-only or a database access error occurs. + */ public ScrollableResultSetTable(String tableName, String selectStatement, IDatabaseConnection connection) throws DataSetException, SQLException { diff --git a/src/main/java/org/dbunit/database/search/AbstractMetaDataBasedSearchCallback.java b/src/main/java/org/dbunit/database/search/AbstractMetaDataBasedSearchCallback.java index f6ae7aaa5..deaf344ab 100644 --- a/src/main/java/org/dbunit/database/search/AbstractMetaDataBasedSearchCallback.java +++ b/src/main/java/org/dbunit/database/search/AbstractMetaDataBasedSearchCallback.java @@ -73,24 +73,29 @@ public IDatabaseConnection getConnection() { return connection; } + /** Identifies a lookup of imported (incoming) foreign keys. */ protected static final int IMPORT = 0; + /** Identifies a lookup of exported (outgoing) foreign keys. */ protected static final int EXPORT = 1; - /** - * indexes of the column names on the MetaData result sets. + /** + * Indexes of the column names on the MetaData result sets. */ - protected static final int[] TABLENAME_INDEXES = { 3, 7 }; - protected static final int[] SCHEMANAME_INDEXES = { 2, 6 }; + protected static final int[] TABLENAME_INDEXES = { 3, 7 }; + /** Result set column indexes, by {@link #IMPORT}/{@link #EXPORT}, holding the schema name. */ + protected static final int[] SCHEMANAME_INDEXES = { 2, 6 }; + /** Result set column indexes, by {@link #IMPORT}/{@link #EXPORT}, holding the primary key column name. */ protected static final int[] PK_INDEXES = { 4, 4 }; + /** Result set column indexes, by {@link #IMPORT}/{@link #EXPORT}, holding the foreign key column name. */ protected static final int[] FK_INDEXES = { 8, 8 }; /** * Get the nodes using the direct foreign key dependency, i.e, if table A has * a FK for a table B, then getNodesFromImportedKeys(A) will return B. - * @param node table name + * @param node table name * @return tables with direct FK dependency from node - * @throws SearchException + * @throws SearchException if the database metadata query fails. */ protected SortedSet getNodesFromImportedKeys(Object node) throws SearchException { @@ -108,9 +113,9 @@ protected SortedSet getNodesFromImportedKeys(Object node) * or something similar, otherwise the generated sequence of tables might not * work when inserted in the database (as some tables might be missing). *
- * @param node table name + * @param node table name * @return tables with reverse FK dependency from node - * @throws SearchException + * @throws SearchException if the database metadata query fails. */ protected SortedSet getNodesFromExportedKeys(Object node) throws SearchException { @@ -123,9 +128,9 @@ protected SortedSet getNodesFromExportedKeys(Object node) * Get the nodes using the both direct and reverse foreign key dependency, i.e, * if table C has a FK for a table A and table A has a FK for a table B, then * getNodesFromImportAndExportedKeys(A) will return B and C. - * @param node table name + * @param node table name * @return tables with reverse and direct FK dependency from node - * @throws SearchException + * @throws SearchException if the database metadata query fails. */ protected SortedSet getNodesFromImportAndExportKeys(Object node) throws SearchException { diff --git a/src/main/java/org/dbunit/database/search/ExportedKeysSearchCallback.java b/src/main/java/org/dbunit/database/search/ExportedKeysSearchCallback.java index c993dc6d8..26af3a79c 100644 --- a/src/main/java/org/dbunit/database/search/ExportedKeysSearchCallback.java +++ b/src/main/java/org/dbunit/database/search/ExportedKeysSearchCallback.java @@ -44,6 +44,11 @@ public class ExportedKeysSearchCallback extends */ private static final Logger logger = LoggerFactory.getLogger(ExportedKeysSearchCallback.class); + /** + * Creates a callback that gets the nodes reachable via exported (reverse) foreign keys. + * + * @param connection connection where the edges will be calculated from. + */ public ExportedKeysSearchCallback(IDatabaseConnection connection) { super(connection); } diff --git a/src/main/java/org/dbunit/database/search/FKRelationshipEdge.java b/src/main/java/org/dbunit/database/search/FKRelationshipEdge.java index b4c977e99..fd4b886c2 100644 --- a/src/main/java/org/dbunit/database/search/FKRelationshipEdge.java +++ b/src/main/java/org/dbunit/database/search/FKRelationshipEdge.java @@ -38,16 +38,34 @@ public class FKRelationshipEdge extends Edge { private String fkColumn; private String pkColumn; + /** + * Creates an edge representing a FK. + * + * @param tableFrom table that has the FK. + * @param tableTo table that has the PK. + * @param fkColumn name of the FK column on tableFrom. + * @param pkColumn name of the PK column on tableTo. + */ public FKRelationshipEdge(String tableFrom, String tableTo, String fkColumn, String pkColumn) { super(tableFrom, tableTo); this.fkColumn = fkColumn; this.pkColumn = pkColumn; } + /** + * Gets the name of the foreign key column in the relationship. + * + * @return name of the foreign key column in the relationship. + */ public String getFKColumn() { return fkColumn; } - + + /** + * Gets the name of the primary key column in the relationship. + * + * @return name of the primary key column in the relationship. + */ public String getPKColumn() { return pkColumn; } diff --git a/src/main/java/org/dbunit/database/search/ImportedAndExportedKeysSearchCallback.java b/src/main/java/org/dbunit/database/search/ImportedAndExportedKeysSearchCallback.java index b436fd9cd..4e2d7ba2f 100644 --- a/src/main/java/org/dbunit/database/search/ImportedAndExportedKeysSearchCallback.java +++ b/src/main/java/org/dbunit/database/search/ImportedAndExportedKeysSearchCallback.java @@ -46,6 +46,11 @@ public class ImportedAndExportedKeysSearchCallback extends AbstractMetaDataBased */ private static final Logger logger = LoggerFactory.getLogger(ImportedAndExportedKeysSearchCallback.class); + /** + * Creates a callback that gets the nodes reachable via both imported and exported foreign keys. + * + * @param connection connection where the edges will be calculated from. + */ public ImportedAndExportedKeysSearchCallback(IDatabaseConnection connection) { super(connection); diff --git a/src/main/java/org/dbunit/database/search/ImportedKeysSearchCallback.java b/src/main/java/org/dbunit/database/search/ImportedKeysSearchCallback.java index fd82357a4..8e62d3510 100644 --- a/src/main/java/org/dbunit/database/search/ImportedKeysSearchCallback.java +++ b/src/main/java/org/dbunit/database/search/ImportedKeysSearchCallback.java @@ -43,6 +43,11 @@ public class ImportedKeysSearchCallback extends */ private static final Logger logger = LoggerFactory.getLogger(ImportedKeysSearchCallback.class); + /** + * Creates a callback that gets the nodes reachable via imported (direct) foreign keys. + * + * @param connection connection where the edges will be calculated from. + */ public ImportedKeysSearchCallback(IDatabaseConnection connection) { super(connection); } diff --git a/src/main/java/org/dbunit/database/search/TablesDependencyHelper.java b/src/main/java/org/dbunit/database/search/TablesDependencyHelper.java index b84f80906..e957d7423 100644 --- a/src/main/java/org/dbunit/database/search/TablesDependencyHelper.java +++ b/src/main/java/org/dbunit/database/search/TablesDependencyHelper.java @@ -153,7 +153,19 @@ public static String[] getAllDependentTables(IDatabaseConnection connection, Str // TODO: javadoc (and unit tests) from down here... - public static IDataSet getDataset(IDatabaseConnection connection,String rootTable, Set allowedIds) + /** + * Returns a dataset containing the given root table and all tables that depend on it, + * filtered to the given allowed primary key values of the root table. + * + * @param connection database connection. + * @param rootTable root table described above. + * @param allowedIds the allowed primary key values of the root table. + * @return a dataset containing the root table and its dependent tables, filtered by the allowed ids. + * @throws SearchException if an exception occurred while calculating the order. + * @throws SQLException if a database access error occurs. + * @throws DataSetException if the dataset cannot be created. + */ + public static IDataSet getDataset(IDatabaseConnection connection,String rootTable, Set allowedIds) throws SearchException, SQLException, DataSetException { if (logger.isDebugEnabled()) @@ -167,8 +179,19 @@ public static IDataSet getDataset(IDatabaseConnection connection,String rootTabl return getDataset(connection, map); } - public static IDataSet getDataset( IDatabaseConnection connection, PkTableMap rootTables ) - throws SearchException, SQLException, DataSetException + /** + * Returns a dataset containing the given root tables and all tables that depend on them, + * filtered to the given allowed primary key values. + * + * @param connection database connection. + * @param rootTables map of root tables to their allowed primary key values. + * @return a dataset containing the root tables and their dependent tables, filtered by the allowed ids. + * @throws SearchException if an exception occurred while calculating the order. + * @throws SQLException if a database access error occurs. + * @throws DataSetException if the dataset cannot be created. + */ + public static IDataSet getDataset( IDatabaseConnection connection, PkTableMap rootTables ) + throws SearchException, SQLException, DataSetException { logger.debug("getDataset(connection={}, rootTables={}) - start", connection, rootTables); @@ -183,8 +206,20 @@ public static IDataSet getDataset( IDatabaseConnection connection, PkTableMap ro return dataset; } - public static IDataSet getAllDataset( IDatabaseConnection connection, String rootTable, Set allowedPKs ) - throws SearchException, SQLException, DataSetException + /** + * Returns a dataset with the given root table plus every table that directly or transitively + * depends on or is depended on by it, filtered to the given allowed primary keys. + * + * @param connection The connection to be used for the database lookup. + * @param rootTable The table to start the search from. + * @param allowedPKs The primary keys of the root table to allow in the result. + * @return the resulting dataset. + * @throws SearchException if the search fails. + * @throws SQLException if a database access error occurs. + * @throws DataSetException if the resulting dataset cannot be built. + */ + public static IDataSet getAllDataset( IDatabaseConnection connection, String rootTable, Set allowedPKs ) + throws SearchException, SQLException, DataSetException { if (logger.isDebugEnabled()) { @@ -197,8 +232,19 @@ public static IDataSet getAllDataset( IDatabaseConnection connection, String roo return getAllDataset( connection, map ); } - public static IDataSet getAllDataset( IDatabaseConnection connection, PkTableMap rootTables ) - throws SearchException, SQLException, DataSetException + /** + * Returns a dataset with the given root tables plus every table that directly or transitively + * depends on or is depended on by them, filtered to the given allowed primary keys. + * + * @param connection The connection to be used for the database lookup. + * @param rootTables The tables to start the search from, mapped to their allowed primary keys. + * @return the resulting dataset. + * @throws SearchException if the search fails. + * @throws SQLException if a database access error occurs. + * @throws DataSetException if the resulting dataset cannot be built. + */ + public static IDataSet getAllDataset( IDatabaseConnection connection, PkTableMap rootTables ) + throws SearchException, SQLException, DataSetException { logger.debug("getAllDataset(connection={}, rootTables={}) - start", connection, rootTables); @@ -216,9 +262,9 @@ public static IDataSet getAllDataset( IDatabaseConnection connection, PkTableMap /** * Returns a set of tables on which the given table directly depends on. * @param connection The connection to be used for the database lookup. - * @param tableName + * @param tableName The table to look up direct dependencies for. * @return a set of tables on which the given table directly depends on. - * @throws SearchException + * @throws SearchException if the search fails. * @since 2.4 */ public static Set getDirectDependsOnTables(IDatabaseConnection connection, @@ -237,9 +283,9 @@ public static Set getDirectDependsOnTables(IDatabaseConnection connection, /** * Returns a set of tables which directly depend on the given table. * @param connection The connection to be used for the database lookup. - * @param tableName + * @param tableName The table to look up direct dependents for. * @return a set of tables on which the given table directly depends on. - * @throws SearchException + * @throws SearchException if the search fails. * @since 2.4 */ public static Set getDirectDependentTables(IDatabaseConnection connection, diff --git a/src/main/java/org/dbunit/database/statement/AbstractPreparedBatchStatement.java b/src/main/java/org/dbunit/database/statement/AbstractPreparedBatchStatement.java index 33d5a4343..6f673a0e1 100644 --- a/src/main/java/org/dbunit/database/statement/AbstractPreparedBatchStatement.java +++ b/src/main/java/org/dbunit/database/statement/AbstractPreparedBatchStatement.java @@ -43,6 +43,9 @@ public abstract class AbstractPreparedBatchStatement implements IPreparedBatchSt */ private static final Logger logger = LoggerFactory.getLogger(AbstractPreparedBatchStatement.class); + /** + * The prepared statement to which values are bound and batched. + */ protected final PreparedStatement _statement; AbstractPreparedBatchStatement(String sql, Connection connection) diff --git a/src/main/java/org/dbunit/database/statement/AbstractStatementFactory.java b/src/main/java/org/dbunit/database/statement/AbstractStatementFactory.java index 916d03370..202f225da 100644 --- a/src/main/java/org/dbunit/database/statement/AbstractStatementFactory.java +++ b/src/main/java/org/dbunit/database/statement/AbstractStatementFactory.java @@ -46,6 +46,10 @@ public abstract class AbstractStatementFactory implements IStatementFactory /** * Returns true if target database supports batch statement. + * + * @param connection the database connection to check. + * @return true if target database supports batch statement. + * @throws SQLException if checking the database metadata fails. */ protected boolean supportBatchStatement(IDatabaseConnection connection) throws SQLException diff --git a/src/main/java/org/dbunit/database/statement/AutomaticPreparedBatchStatement.java b/src/main/java/org/dbunit/database/statement/AutomaticPreparedBatchStatement.java index c7fdeb49d..b48cea69d 100644 --- a/src/main/java/org/dbunit/database/statement/AutomaticPreparedBatchStatement.java +++ b/src/main/java/org/dbunit/database/statement/AutomaticPreparedBatchStatement.java @@ -49,6 +49,12 @@ public class AutomaticPreparedBatchStatement implements IPreparedBatchStatement private int _threshold; private int _result = 0; + /** + * Creates a statement that automatically executes the batch once the given threshold is reached. + * + * @param statement the decorated statement to which batching is delegated. + * @param threshold the number of batched rows that triggers an automatic execution. + */ public AutomaticPreparedBatchStatement(IPreparedBatchStatement statement, int threshold) { _statement = statement; diff --git a/src/main/java/org/dbunit/database/statement/IPreparedBatchStatement.java b/src/main/java/org/dbunit/database/statement/IPreparedBatchStatement.java index f2ef34281..85142836c 100644 --- a/src/main/java/org/dbunit/database/statement/IPreparedBatchStatement.java +++ b/src/main/java/org/dbunit/database/statement/IPreparedBatchStatement.java @@ -36,15 +36,44 @@ */ public interface IPreparedBatchStatement { + /** + * Binds the given value, cast using the given data type, to the next parameter of the statement. + * + * @param value the value to bind. + * @param dataType the data type used to cast the value. + * @throws TypeCastException if the value cannot be cast to the given data type. + * @throws SQLException if binding the value to the statement fails. + */ void addValue(Object value, DataType dataType) throws TypeCastException, SQLException; + /** + * Adds the currently bound parameters as a new row to the batch. + * + * @throws SQLException if adding the batch row fails. + */ void addBatch() throws SQLException; + /** + * Executes all batched rows. + * + * @return the number of rows affected by each batched statement. + * @throws SQLException if executing the batch fails. + */ int executeBatch() throws SQLException; + /** + * Clears all batched rows. + * + * @throws SQLException if clearing the batch fails. + */ void clearBatch() throws SQLException; + /** + * Closes this statement. + * + * @throws SQLException if closing the statement fails. + */ void close() throws SQLException; } diff --git a/src/main/java/org/dbunit/database/statement/IStatementFactory.java b/src/main/java/org/dbunit/database/statement/IStatementFactory.java index a5a25672b..a431be869 100644 --- a/src/main/java/org/dbunit/database/statement/IStatementFactory.java +++ b/src/main/java/org/dbunit/database/statement/IStatementFactory.java @@ -34,9 +34,24 @@ */ public interface IStatementFactory { + /** + * Creates a batch statement for the given connection. + * + * @param connection the database connection to create the statement on. + * @return the new batch statement. + * @throws SQLException if creating the statement fails. + */ IBatchStatement createBatchStatement(IDatabaseConnection connection) throws SQLException; + /** + * Creates a prepared batch statement for the given SQL and connection. + * + * @param sql the SQL statement to prepare. + * @param connection the database connection to create the statement on. + * @return the new prepared batch statement. + * @throws SQLException if creating the statement fails. + */ IPreparedBatchStatement createPreparedBatchStatement(String sql, IDatabaseConnection connection) throws SQLException; } diff --git a/src/main/java/org/dbunit/database/statement/PreparedStatementFactory.java b/src/main/java/org/dbunit/database/statement/PreparedStatementFactory.java index 51a43f4fd..f6ec542c6 100644 --- a/src/main/java/org/dbunit/database/statement/PreparedStatementFactory.java +++ b/src/main/java/org/dbunit/database/statement/PreparedStatementFactory.java @@ -83,6 +83,3 @@ public IPreparedBatchStatement createPreparedBatchStatement(String sql, } } - - - diff --git a/src/main/java/org/dbunit/database/statement/SimplePreparedStatement.java b/src/main/java/org/dbunit/database/statement/SimplePreparedStatement.java index 4cd0b5d1e..b024d682c 100644 --- a/src/main/java/org/dbunit/database/statement/SimplePreparedStatement.java +++ b/src/main/java/org/dbunit/database/statement/SimplePreparedStatement.java @@ -50,6 +50,13 @@ public class SimplePreparedStatement extends AbstractPreparedBatchStatement private int _index; private int _result; + /** + * Creates a new SimplePreparedStatement. + * + * @param sql the SQL statement to prepare. + * @param connection the JDBC connection to prepare the statement on. + * @throws SQLException if preparing the statement fails. + */ public SimplePreparedStatement(String sql, Connection connection) throws SQLException { diff --git a/src/main/java/org/dbunit/database/statement/StatementFactory.java b/src/main/java/org/dbunit/database/statement/StatementFactory.java index 24821219e..fdda61b94 100644 --- a/src/main/java/org/dbunit/database/statement/StatementFactory.java +++ b/src/main/java/org/dbunit/database/statement/StatementFactory.java @@ -68,6 +68,3 @@ public IPreparedBatchStatement createPreparedBatchStatement(String sql, } - - - diff --git a/src/main/java/org/dbunit/dataset/AbstractTable.java b/src/main/java/org/dbunit/dataset/AbstractTable.java index 120c405ca..f00c7ebfc 100644 --- a/src/main/java/org/dbunit/dataset/AbstractTable.java +++ b/src/main/java/org/dbunit/dataset/AbstractTable.java @@ -39,6 +39,12 @@ public abstract class AbstractTable implements ITable { private static final Logger logger = LoggerFactory.getLogger(AbstractTable.class); + /** + * Validates that the given row index is within the bounds of this table. + * + * @param row the row index to validate. + * @throws DataSetException if the row index is out of bounds. + */ protected void assertValidRowIndex(int row) throws DataSetException { if (logger.isDebugEnabled()) { logger.debug("assertValidRowIndex(row={}) - start", Integer @@ -48,6 +54,13 @@ protected void assertValidRowIndex(int row) throws DataSetException { assertValidRowIndex(row, getRowCount()); } + /** + * Validates that the given row index is within the given row count. + * + * @param row the row index to validate. + * @param rowCount the number of rows to validate against. + * @throws DataSetException if the row index is out of bounds. + */ protected void assertValidRowIndex(int row, int rowCount) throws DataSetException { if (logger.isDebugEnabled()) { @@ -64,6 +77,12 @@ protected void assertValidRowIndex(int row, int rowCount) } } + /** + * Validates that the given column name exists in this table. + * + * @param columnName the column name to validate. + * @throws DataSetException if no column with the given name exists in this table. + */ protected void assertValidColumn(String columnName) throws DataSetException { logger.debug("assertValidColumn(columnName={}) - start", columnName); @@ -74,6 +93,13 @@ protected void assertValidColumn(String columnName) throws DataSetException { .getTableName()); } + /** + * Returns the index of the column with the given name. + * + * @param columnName the column name to look up. + * @return the index of the column with the given name. + * @throws DataSetException if no column with the given name exists in this table. + */ protected int getColumnIndex(String columnName) throws DataSetException { logger.debug("getColumnIndex(columnName={}) - start", columnName); diff --git a/src/main/java/org/dbunit/dataset/AbstractTableMetaData.java b/src/main/java/org/dbunit/dataset/AbstractTableMetaData.java index a74c9a674..8b614439d 100644 --- a/src/main/java/org/dbunit/dataset/AbstractTableMetaData.java +++ b/src/main/java/org/dbunit/dataset/AbstractTableMetaData.java @@ -75,8 +75,8 @@ public AbstractTableMetaData() } /** - * @param columns - * @param keyNames + * @param columns the columns to search. + * @param keyNames the names of the primary key columns to find. * @return The primary key columns * @deprecated since 2.3.0 - use {@link Columns#getColumns(String[], Column[])} */ @@ -87,9 +87,9 @@ protected static Column[] getPrimaryKeys(Column[] columns, String[] keyNames) } /** - * @param tableName - * @param columns - * @param columnFilter + * @param tableName the name of the table, used for filter invocation. + * @param columns the columns to search. + * @param columnFilter the filter used to accept primary key columns. * @return The filtered primary key columns * @deprecated since 2.3.0 - use {@link Columns#getColumns(String[], Column[])} */ @@ -107,7 +107,9 @@ protected static Column[] getPrimaryKeys(String tableName, Column[] columns, /** * Provides the index of the column with the given name within this table. * Uses method {@link ITableMetaData#getColumns()} to retrieve all available columns. - * @throws DataSetException + * @param columnName the name of the column to look up. + * @return the index of the column with the given name. + * @throws DataSetException if no column with the given name exists in this table. * @see org.dbunit.dataset.ITableMetaData#getColumnIndex(java.lang.String) */ public int getColumnIndex(String columnName) throws DataSetException @@ -189,9 +191,9 @@ private Map createExactColumnIndexesMap(Column[] columns, Map c * Validates and returns the datatype factory of the given connection * @param connection The connection providing the {@link IDataTypeFactory} * @return The datatype factory of the given connection - * @throws SQLException + * @throws SQLException if retrieving the database metadata fails. */ - public IDataTypeFactory getDataTypeFactory(IDatabaseConnection connection) + public IDataTypeFactory getDataTypeFactory(IDatabaseConnection connection) throws SQLException { DatabaseConfig config = connection.getConfig(); diff --git a/src/main/java/org/dbunit/dataset/CachedDataSet.java b/src/main/java/org/dbunit/dataset/CachedDataSet.java index 684bfaff2..8fdc4c995 100644 --- a/src/main/java/org/dbunit/dataset/CachedDataSet.java +++ b/src/main/java/org/dbunit/dataset/CachedDataSet.java @@ -42,6 +42,8 @@ public class CachedDataSet extends AbstractDataSet implements IDataSetConsumer /** * Default constructor. + * + * @throws DataSetException if initialization fails. */ public CachedDataSet() throws DataSetException { super(); @@ -50,6 +52,9 @@ public CachedDataSet() throws DataSetException { /** * Creates a copy of the specified dataset. + * + * @param dataSet the dataset to copy. + * @throws DataSetException if copying the dataset fails. */ public CachedDataSet(IDataSet dataSet) throws DataSetException { @@ -67,6 +72,9 @@ public CachedDataSet(IDataSet dataSet) throws DataSetException /** * Creates a CachedDataSet that synchronously consume the specified producer. + * + * @param producer the producer to consume. + * @throws DataSetException if consuming the producer fails. */ public CachedDataSet(IDataSetProducer producer) throws DataSetException { @@ -75,9 +83,9 @@ public CachedDataSet(IDataSetProducer producer) throws DataSetException /** * Creates a CachedDataSet that synchronously consume the specified producer. - * @param producer + * @param producer the producer to consume. * @param caseSensitiveTableNames Whether or not case sensitive table names should be used - * @throws DataSetException + * @throws DataSetException if consuming the producer fails. */ public CachedDataSet(IDataSetProducer producer, boolean caseSensitiveTableNames) throws DataSetException { diff --git a/src/main/java/org/dbunit/dataset/CachedTable.java b/src/main/java/org/dbunit/dataset/CachedTable.java index c2c8bbd6c..8a13ffbaf 100644 --- a/src/main/java/org/dbunit/dataset/CachedTable.java +++ b/src/main/java/org/dbunit/dataset/CachedTable.java @@ -33,12 +33,23 @@ */ public class CachedTable extends DefaultTable { + /** + * Creates a table that eagerly loads and caches all rows of the given table. + * + * @param table the source table to load into memory. + * @throws DataSetException if loading the rows fails. + */ public CachedTable(ITable table) throws DataSetException { super(table.getTableMetaData()); addTableRows(table); } + /** + * Creates an empty cached table with the given metadata. + * + * @param metaData the table metadata. + */ protected CachedTable(ITableMetaData metaData) { super(metaData); diff --git a/src/main/java/org/dbunit/dataset/CaseInsensitiveDataSet.java b/src/main/java/org/dbunit/dataset/CaseInsensitiveDataSet.java index 80c78b12a..71bb0eeab 100644 --- a/src/main/java/org/dbunit/dataset/CaseInsensitiveDataSet.java +++ b/src/main/java/org/dbunit/dataset/CaseInsensitiveDataSet.java @@ -49,6 +49,13 @@ public class CaseInsensitiveDataSet extends AbstractDataSet private final IDataSet _dataSet; private OrderedTableNameMap orderedTableMap; + /** + * Creates a case-insensitive view of the given dataset. + * + * @param dataSet the dataset to decorate. + * @throws AmbiguousTableNameException if two table names are equal case-insensitively. + * @throws DataSetException if reading the dataset's tables fails. + */ public CaseInsensitiveDataSet(IDataSet dataSet) throws AmbiguousTableNameException, DataSetException { _dataSet = dataSet; diff --git a/src/main/java/org/dbunit/dataset/CaseInsensitiveTable.java b/src/main/java/org/dbunit/dataset/CaseInsensitiveTable.java index bc60b6dc5..ab98819be 100644 --- a/src/main/java/org/dbunit/dataset/CaseInsensitiveTable.java +++ b/src/main/java/org/dbunit/dataset/CaseInsensitiveTable.java @@ -25,6 +25,8 @@ import org.slf4j.LoggerFactory; /** + * Decorates an {@link ITable}, resolving column names case-insensitively. + * * @author Manuel Laflamme * @version $Revision$ * @since Mar 27, 2002 @@ -40,6 +42,11 @@ public class CaseInsensitiveTable implements ITable private final ITable _table; + /** + * Creates a case-insensitive view of the given table. + * + * @param table the table to decorate. + */ public CaseInsensitiveTable(ITable table) { _table = table; diff --git a/src/main/java/org/dbunit/dataset/Column.java b/src/main/java/org/dbunit/dataset/Column.java index 4c03f2962..b7191c721 100644 --- a/src/main/java/org/dbunit/dataset/Column.java +++ b/src/main/java/org/dbunit/dataset/Column.java @@ -79,6 +79,10 @@ public Column(String columnName, DataType dataType) /** * Creates a Column object. + * + * @param columnName the column name. + * @param dataType the data type. + * @param nullable whether or not the column is nullable. */ public Column(String columnName, DataType dataType, Nullable nullable) { @@ -87,6 +91,11 @@ public Column(String columnName, DataType dataType, Nullable nullable) /** * Creates a Column object. + * + * @param columnName the column name. + * @param dataType the data type. + * @param sqlTypeName the SQL name of the column which comes from the JDBC driver. + * @param nullable whether or not the column is nullable. */ public Column(String columnName, DataType dataType, String sqlTypeName, Nullable nullable) @@ -152,18 +161,30 @@ public Column(String columnName, DataType dataType, String sqlTypeName, _generatedColumn = generatedColumn; } + /** + * Returns whether the database has a default value configured for this column. + * + * @return true if this column has a default value. + */ public boolean hasDefaultValue() { return _defaultValue != null; } - + + /** + * Returns whether this column definitely does not allow NULL values. + * + * @return true if this column is not nullable. + */ public boolean isNotNullable() { return _nullable== Column.NO_NULLS; } - + /** * Returns this column name. + * + * @return this column name. */ public String getColumnName() { @@ -172,6 +193,8 @@ public String getColumnName() /** * Returns this column data type. + * + * @return this column data type. */ public DataType getDataType() { @@ -180,6 +203,8 @@ public DataType getDataType() /** * Returns this column sql data type name. + * + * @return this column sql data type name. */ public String getSqlTypeName() { @@ -188,6 +213,8 @@ public String getSqlTypeName() /** * Returns true if this column is nullable. + * + * @return this column's nullability. */ public Nullable getNullable() { @@ -195,15 +222,19 @@ public Nullable getNullable() } /** - * @return The default value the database uses for this column + * Returns the default value the database uses for this column. + * + * @return The default value the database uses for this column * if not specified in the insert column list */ public String getDefaultValue() { return _defaultValue; } - + /** + * Returns the remarks set on the database for this column. + * * @return The remarks set on the database for this column * @since 2.4.3 */ @@ -211,8 +242,10 @@ public String getRemarks() { return _remarks; } - + /** + * Returns the auto-increment property for this column. + * * @return The auto-increment property for this column * @since 2.4.3 */ @@ -220,8 +253,10 @@ public AutoIncrement getAutoIncrement() { return _autoIncrement; } - + /** + * Returns whether the column is a generated column. + * * @return Whether the column is a generated column * @since 3.0.0 */ @@ -238,6 +273,7 @@ public Boolean getGeneratedColumn() * {@link java.sql.DatabaseMetaData#columnNoNulls}, * {@link java.sql.DatabaseMetaData#columnNullable}, * {@link java.sql.DatabaseMetaData#columnNullableUnknown} + * @return the corresponding Nullable constant. */ public static Nullable nullableValue(int nullable) { @@ -265,6 +301,7 @@ public static Nullable nullableValue(int nullable) * Returns the appropriate Nullable constant. * * @param nullable true if null is allowed + * @return the corresponding Nullable constant. */ public static Nullable nullableValue(boolean nullable) { @@ -376,10 +413,14 @@ public String toString() */ public static class AutoIncrement { + /** Indicates that the column is auto-incremented. */ public static final AutoIncrement YES = new AutoIncrement("YES"); + /** Indicates that the column is not auto-incremented. */ public static final AutoIncrement NO = new AutoIncrement("NO"); + /** Indicates that whether the column is auto-incremented is unknown. */ public static final AutoIncrement UNKNOWN = new AutoIncrement("UNKNOWN"); - + + /** * Logger for this class */ @@ -391,7 +432,12 @@ private AutoIncrement(String key) this.key = key; } - public String getKey() + /** + * Returns the key identifying this auto-increment value. + * + * @return the key identifying this auto-increment value. + */ + public String getKey() { return key; } diff --git a/src/main/java/org/dbunit/dataset/ColumnFilterTable.java b/src/main/java/org/dbunit/dataset/ColumnFilterTable.java index 5fef7cecf..b70da8b48 100644 --- a/src/main/java/org/dbunit/dataset/ColumnFilterTable.java +++ b/src/main/java/org/dbunit/dataset/ColumnFilterTable.java @@ -51,11 +51,13 @@ public class ColumnFilterTable implements ITable /** + * Creates a table that filters some columns out from the given table. + * * @param table The table from which some columns should be filtered * @param columnFilter The filter defining which columns to be filtered - * @throws DataSetException + * @throws DataSetException if the filtered metadata cannot be built. */ - public ColumnFilterTable(ITable table, IColumnFilter columnFilter) + public ColumnFilterTable(ITable table, IColumnFilter columnFilter) throws DataSetException { if (columnFilter == null) { @@ -93,7 +95,12 @@ public Object getValue(int row, String column) throws DataSetException return this.originalTable.getValue(row, column); } - public ITableMetaData getOriginalMetaData() + /** + * Returns the metadata of the original, unfiltered table. + * + * @return the metadata of the original, unfiltered table. + */ + public ITableMetaData getOriginalMetaData() { logger.debug("getOriginalMetaData() - start"); return this.originalTable.getTableMetaData(); diff --git a/src/main/java/org/dbunit/dataset/Columns.java b/src/main/java/org/dbunit/dataset/Columns.java index 7f0879b61..287b216b3 100644 --- a/src/main/java/org/dbunit/dataset/Columns.java +++ b/src/main/java/org/dbunit/dataset/Columns.java @@ -226,7 +226,7 @@ public static Column[] getColumns(String tableName, Column[] columns, * * @param metaData The metaData needed to get the columns to be sorted * @return The columns sorted by their column names, ignoring the case of the column names - * @throws DataSetException + * @throws DataSetException if the columns cannot be retrieved from the given metadata. */ public static Column[] getSortedColumns(ITableMetaData metaData) throws DataSetException @@ -303,10 +303,10 @@ public static Column[] mergeColumnsByName(Column[] referenceColumns, Column[] co /** * Returns the column difference of the two given {@link ITableMetaData} objects - * @param expectedMetaData - * @param actualMetaData + * @param expectedMetaData the metadata of the expected results table. + * @param actualMetaData the metadata of the actual results table. * @return The columns that differ in the both given {@link ITableMetaData} objects - * @throws DataSetException + * @throws DataSetException if the columns cannot be retrieved from the given metadata. */ public static ColumnDiff getColumnDiff(ITableMetaData expectedMetaData, ITableMetaData actualMetaData) @@ -374,7 +374,7 @@ public static class ColumnDiff * Creates the difference between the two metadata's columns * @param expectedMetaData The metadata of the expected results table * @param actualMetaData The metadata of the actual results table - * @throws DataSetException + * @throws DataSetException if the columns cannot be retrieved from the given metadata. */ public ColumnDiff(ITableMetaData expectedMetaData, ITableMetaData actualMetaData) @@ -430,6 +430,8 @@ private Column[] findMissingColumnsIn(ITableMetaData metaDataToCheck, } /** + * Returns whether there is a difference in the columns given in the constructor. + * * @return true if there is a difference in the columns given in the constructor */ public boolean hasDifference() @@ -438,6 +440,8 @@ public boolean hasDifference() } /** + * Returns the columns that exist in the expected result but not in the actual. + * * @return The columns that exist in the expected result but not in the actual */ public Column[] getExpected() { @@ -445,6 +449,8 @@ public Column[] getExpected() { } /** + * Returns the columns that exist in the actual result but not in the expected. + * * @return The columns that exist in the actual result but not in the expected */ public Column[] getActual() { @@ -452,6 +458,8 @@ public Column[] getActual() { } /** + * Returns {@link #getExpected()} as a formatted string. + * * @return The value of {@link #getExpected()} as formatted string * @see #getExpected() */ @@ -460,6 +468,8 @@ public String getExpectedAsString() { } /** + * Returns {@link #getActual()} as a formatted string. + * * @return The value of {@link #getActual()} as formatted string * @see #getActual() */ @@ -468,10 +478,12 @@ public String getActualAsString() { } /** + * Builds a pretty formatted message describing the column difference. + * * @return A pretty formatted message that can be used for user information - * @throws DataSetException + * @throws DataSetException if the columns cannot be retrieved from the given metadata. */ - public String getMessage() throws DataSetException + public String getMessage() throws DataSetException { logger.debug("getMessage() - start"); diff --git a/src/main/java/org/dbunit/dataset/CompositeDataSet.java b/src/main/java/org/dbunit/dataset/CompositeDataSet.java index 8ab3b4c77..b96d5d4f3 100644 --- a/src/main/java/org/dbunit/dataset/CompositeDataSet.java +++ b/src/main/java/org/dbunit/dataset/CompositeDataSet.java @@ -48,6 +48,9 @@ public class CompositeDataSet extends AbstractDataSet /** * Creates a composite dataset that combines specified datasets. * Tables having the same name are merged into one table. + * + * @param dataSets list of datasets + * @throws DataSetException if combining the datasets fails. */ public CompositeDataSet(IDataSet[] dataSets) throws DataSetException { @@ -62,6 +65,7 @@ public CompositeDataSet(IDataSet[] dataSets) throws DataSetException * @param combine * if true, tables having the same name are merged into * one table. + * @throws DataSetException if combining the datasets fails. */ public CompositeDataSet(IDataSet[] dataSets, boolean combine) throws DataSetException @@ -79,6 +83,7 @@ public CompositeDataSet(IDataSet[] dataSets, boolean combine) * one table. * @param caseSensitiveTableNames Whether or not table names are handled in a case sensitive * way over all datasets. + * @throws DataSetException if combining the datasets fails. * @since 2.4.2 */ public CompositeDataSet(IDataSet[] dataSets, boolean combine, boolean caseSensitiveTableNames) @@ -105,6 +110,10 @@ public CompositeDataSet(IDataSet[] dataSets, boolean combine, boolean caseSensit /** * Creates a composite dataset that combines the two specified datasets. * Tables having the same name are merged into one table. + * + * @param dataSet1 first dataset + * @param dataSet2 second dataset + * @throws DataSetException if combining the datasets fails. */ public CompositeDataSet(IDataSet dataSet1, IDataSet dataSet2) throws DataSetException @@ -122,6 +131,7 @@ public CompositeDataSet(IDataSet dataSet1, IDataSet dataSet2) * @param combine * if true, tables having the same name are merged into * one table. + * @throws DataSetException if combining the datasets fails. */ public CompositeDataSet(IDataSet dataSet1, IDataSet dataSet2, boolean combine) throws DataSetException @@ -138,7 +148,8 @@ public CompositeDataSet(IDataSet dataSet1, IDataSet dataSet2, boolean combine) * if true, tables having the same name are merged into * one table. * @deprecated This constructor is useless when the combine parameter is - * false. Use overload that doesn't have the combine argument. + * false. Use overload that doesn't have the combine argument. + * @throws DataSetException if combining the dataset's tables fails. */ public CompositeDataSet(IDataSet dataSet, boolean combine) throws DataSetException @@ -151,6 +162,7 @@ public CompositeDataSet(IDataSet dataSet, boolean combine) * * @param dataSet * the dataset + * @throws DataSetException if combining the dataset's tables fails. */ public CompositeDataSet(IDataSet dataSet) throws DataSetException { @@ -160,6 +172,9 @@ public CompositeDataSet(IDataSet dataSet) throws DataSetException /** * Creates a composite dataset that combines tables having identical name. * Tables having the same name are merged into one table. + * + * @param tables The tables to merge to one dataset + * @throws DataSetException if combining the tables fails. */ public CompositeDataSet(ITable[] tables) throws DataSetException { @@ -172,6 +187,7 @@ public CompositeDataSet(ITable[] tables) throws DataSetException * @param tables The tables to merge to one dataset * @param caseSensitiveTableNames Whether or not table names are handled in a case sensitive * way over all datasets. + * @throws DataSetException if combining the tables fails. * @since 2.4.2 */ public CompositeDataSet(ITable[] tables, boolean caseSensitiveTableNames) throws DataSetException diff --git a/src/main/java/org/dbunit/dataset/CompositeTable.java b/src/main/java/org/dbunit/dataset/CompositeTable.java index aceabc7ef..5d91a845f 100644 --- a/src/main/java/org/dbunit/dataset/CompositeTable.java +++ b/src/main/java/org/dbunit/dataset/CompositeTable.java @@ -48,6 +48,9 @@ public class CompositeTable extends AbstractTable { /** * Creates a composite table that combines the specified metadata with the * specified table. + * + * @param metaData the table metadata. + * @param table the table providing row data. */ public CompositeTable(ITableMetaData metaData, ITable table) { _metaData = metaData; @@ -57,6 +60,9 @@ public CompositeTable(ITableMetaData metaData, ITable table) { /** * Creates a composite table that combines the specified metadata with the * specified tables. + * + * @param metaData the table metadata. + * @param tables the tables providing row data. */ public CompositeTable(ITableMetaData metaData, ITable[] tables) { _metaData = metaData; @@ -66,6 +72,9 @@ public CompositeTable(ITableMetaData metaData, ITable[] tables) { /** * Creates a composite table that combines the specified specified tables. * The metadata from the first table is used as metadata for the new table. + * + * @param table1 the first table, whose metadata is used for the new table. + * @param table2 the second table. */ public CompositeTable(ITable table1, ITable table2) { _metaData = table1.getTableMetaData(); @@ -75,6 +84,10 @@ public CompositeTable(ITable table1, ITable table2) { /** * Creates a composite dataset that encapsulate the specified table with a * new name. + * + * @param newName the new table name. + * @param table the table to rename. + * @throws DataSetException if the new metadata cannot be built. */ public CompositeTable(String newName, ITable table) throws DataSetException { ITableMetaData metaData = table.getTableMetaData(); diff --git a/src/main/java/org/dbunit/dataset/DataSetException.java b/src/main/java/org/dbunit/dataset/DataSetException.java index 348b571d0..56048530a 100644 --- a/src/main/java/org/dbunit/dataset/DataSetException.java +++ b/src/main/java/org/dbunit/dataset/DataSetException.java @@ -33,20 +33,43 @@ */ public class DataSetException extends DatabaseUnitException { + /** + * Constructs a DataSetException with no detail + * message and no encapsulated exception. + */ public DataSetException() { } + /** + * Constructs a DataSetException with the specified detail + * message and no encapsulated exception. + * + * @param msg the detail message. + */ public DataSetException(String msg) { super(msg); } + /** + * Constructs a DataSetException with the specified detail + * message and encapsulated exception. + * + * @param msg the detail message. + * @param e the encapsulated exception. + */ public DataSetException(String msg, Throwable e) { super(msg, e); } + /** + * Constructs a DataSetException with the encapsulated + * exception and use string representation as detail message. + * + * @param e the encapsulated exception. + */ public DataSetException(Throwable e) { super(e); diff --git a/src/main/java/org/dbunit/dataset/DataSetUtils.java b/src/main/java/org/dbunit/dataset/DataSetUtils.java index 128a2eae8..710857f3c 100644 --- a/src/main/java/org/dbunit/dataset/DataSetUtils.java +++ b/src/main/java/org/dbunit/dataset/DataSetUtils.java @@ -56,6 +56,9 @@ private DataSetUtils() * the tables order. * * @deprecated Use Assertion.assertEquals + * @param expectedDataSet the dataset containing all expected results. + * @param actualDataSet the dataset containing all actual results. + * @throws Exception if an error occurs during comparison. */ public static void assertEquals(IDataSet expectedDataSet, IDataSet actualDataSet) throws Exception @@ -72,6 +75,9 @@ public static void assertEquals(IDataSet expectedDataSet, * keys. * * @deprecated Use Assertion.assertEquals + * @param expectedTable the table containing all expected results. + * @param actualTable the table containing all actual results. + * @throws Exception if an error occurs during comparison. */ public static void assertEquals(ITable expectedTable, ITable actualTable) throws Exception @@ -123,8 +129,10 @@ public static String getQualifiedName(String prefix, String name, } /** - * @param name - * @param escapePattern + * Escapes the given name using the given escape pattern. + * + * @param name the name to escape. + * @param escapePattern the escape pattern to apply, may be null. * @return The escaped name if the escape pattern is not null * @deprecated since 2.3.0. Prefer usage of {@link QualifiedTableName#getQualifiedName()} creating a new {@link QualifiedTableName} object */ @@ -142,6 +150,7 @@ public static String getEscapedName(String name, String escapePattern) * @param value the value * @param dataType the value data type * @return the SQL string value + * @throws TypeCastException if the value cannot be cast to a string using the given data type. */ public static String getSqlValueString(Object value, DataType dataType) throws TypeCastException @@ -219,6 +228,7 @@ public static Column getColumn(String columnName, Column[] columns) * @param names the names of the tables to search. * @param dataSet the dataset from which the tables must be searched. * @return the tables or an empty array if no tables are found. + * @throws DataSetException if a named table cannot be retrieved from the dataset. */ public static ITable[] getTables(String[] names, IDataSet dataSet) throws DataSetException @@ -237,6 +247,10 @@ public static ITable[] getTables(String[] names, IDataSet dataSet) /** * Returns the tables from the specified dataset. + * + * @param dataSet the dataset to get the tables from. + * @return the tables from the specified dataset. + * @throws DataSetException if the tables cannot be retrieved. */ public static ITable[] getTables(IDataSet dataSet) throws DataSetException { @@ -247,6 +261,10 @@ public static ITable[] getTables(IDataSet dataSet) throws DataSetException /** * Returns the tables from the specified iterator. + * + * @param iterator the iterator to get the tables from. + * @return the tables from the specified iterator. + * @throws DataSetException if the tables cannot be retrieved. */ public static ITable[] getTables(ITableIterator iterator) throws DataSetException { @@ -262,6 +280,10 @@ public static ITable[] getTables(ITableIterator iterator) throws DataSetExceptio /** * Returns the table names from the specified dataset in reverse order. + * + * @param dataSet the dataset to get the table names from. + * @return the table names from the specified dataset, in reverse order. + * @throws DataSetException if the table names cannot be retrieved. */ public static String[] getReverseTableNames(IDataSet dataSet) throws DataSetException @@ -272,7 +294,7 @@ public static String[] getReverseTableNames(IDataSet dataSet) /** * reverses a String array. - * @param array + * @param array the array to reverse. * @return String[] - reversed array. */ public static String[] reverseStringArray(String[] array) diff --git a/src/main/java/org/dbunit/dataset/DefaultDataSet.java b/src/main/java/org/dbunit/dataset/DefaultDataSet.java index 6663d6e03..2218554bc 100644 --- a/src/main/java/org/dbunit/dataset/DefaultDataSet.java +++ b/src/main/java/org/dbunit/dataset/DefaultDataSet.java @@ -43,6 +43,9 @@ public class DefaultDataSet extends AbstractDataSet */ private static final Logger logger = LoggerFactory.getLogger(DefaultDataSet.class); + /** + * Default constructor. + */ public DefaultDataSet() { super(); @@ -50,7 +53,7 @@ public DefaultDataSet() /** * Creates a default dataset which is empty initially - * @param caseSensitiveTableNames + * @param caseSensitiveTableNames Whether or not table names should be case sensitive * @since 2.4.2 */ public DefaultDataSet(boolean caseSensitiveTableNames) @@ -58,24 +61,45 @@ public DefaultDataSet(boolean caseSensitiveTableNames) super(caseSensitiveTableNames); } + /** + * Creates a default dataset consisting of the given table. + * + * @param table the table to add. + * @throws AmbiguousTableNameException never thrown for a single table. + */ public DefaultDataSet(ITable table) throws AmbiguousTableNameException { this(new ITable[]{table}); } + /** + * Creates a default dataset consisting of the given tables. + * + * @param table1 the first table to add. + * @param table2 the second table to add. + * @throws AmbiguousTableNameException if the two tables have the same name. + */ public DefaultDataSet(ITable table1, ITable table2) throws AmbiguousTableNameException { this(new ITable[] {table1, table2}); } + /** + * Creates a default dataset consisting of the given tables. + * + * @param tables the tables to add. + * @throws AmbiguousTableNameException if two tables have the same name. + */ public DefaultDataSet(ITable[] tables) throws AmbiguousTableNameException { this(tables, false); } - + /** * Creates a default dataset which consists of the given tables - * @param caseSensitiveTableNames + * @param tables the tables to add. + * @param caseSensitiveTableNames Whether or not table names should be case sensitive + * @throws AmbiguousTableNameException if two tables have the same name. * @since 2.4.2 */ public DefaultDataSet(ITable[] tables, boolean caseSensitiveTableNames) throws AmbiguousTableNameException @@ -90,19 +114,20 @@ public DefaultDataSet(ITable[] tables, boolean caseSensitiveTableNames) throws A /** * Add a new table in this dataset. - * @throws AmbiguousTableNameException + * @param table the table to add. + * @throws AmbiguousTableNameException if a table with the same name already exists. */ public void addTable(ITable table) throws AmbiguousTableNameException { logger.debug("addTable(table={}) - start", table); - + this.initialize(); - + super._orderedTableNameMap.add(table.getTableMetaData().getTableName(), table); } /** - * Initializes the {@link _orderedTableNameMap} of the parent class if it is not initialized yet. + * Initializes the {@link #_orderedTableNameMap} of the parent class if it is not initialized yet. * @since 2.4.6 */ protected void initialize() diff --git a/src/main/java/org/dbunit/dataset/DefaultTable.java b/src/main/java/org/dbunit/dataset/DefaultTable.java index 30113728c..a03cd57ac 100644 --- a/src/main/java/org/dbunit/dataset/DefaultTable.java +++ b/src/main/java/org/dbunit/dataset/DefaultTable.java @@ -47,6 +47,8 @@ public class DefaultTable extends AbstractTable /** * Creates a new empty table with specified metadata and values. + * @param metaData the table metadata. + * @param list the mutable row list backing this table. * @deprecated Use public mutators to initialize table values instead */ public DefaultTable(ITableMetaData metaData, List list) @@ -57,6 +59,7 @@ public DefaultTable(ITableMetaData metaData, List list) /** * Creates a new empty table having the specified name. + * @param tableName the table name. */ public DefaultTable(String tableName) { @@ -66,6 +69,9 @@ public DefaultTable(String tableName) /** * Creates a new empty table with specified metadata and values. + * @param tableName the table name. + * @param columns the table columns. + * @param list the mutable row list backing this table. * @deprecated Use public mutators to initialize table values instead */ public DefaultTable(String tableName, Column[] columns, List list) @@ -76,6 +82,8 @@ public DefaultTable(String tableName, Column[] columns, List list) /** * Creates a new empty table with specified metadata. + * @param tableName the table name. + * @param columns the table columns. */ public DefaultTable(String tableName, Column[] columns) { @@ -83,6 +91,10 @@ public DefaultTable(String tableName, Column[] columns) _rowList = new ArrayList(); } + /** + * Creates a new empty table with the specified metadata. + * @param metaData the table metadata. + */ public DefaultTable(ITableMetaData metaData) { _metaData = metaData; @@ -91,6 +103,7 @@ public DefaultTable(ITableMetaData metaData) /** * Inserts a new empty row. You can add values with {@link #setValue}. + * @throws DataSetException if the row cannot be added. */ public void addRow() throws DataSetException { @@ -105,6 +118,7 @@ public void addRow() throws DataSetException * @param values The array of values. Each value correspond to the column at the * same index from {@link ITableMetaData#getColumns}. * @see #getTableMetaData + * @throws DataSetException if the row cannot be added. */ public void addRow(Object[] values) throws DataSetException { @@ -116,6 +130,7 @@ public void addRow(Object[] values) throws DataSetException /** * Inserts all rows from the specified table. * @param table The source table. + * @throws DataSetException if the rows cannot be added. */ public void addTableRows(ITable table) throws DataSetException { diff --git a/src/main/java/org/dbunit/dataset/DefaultTableIterator.java b/src/main/java/org/dbunit/dataset/DefaultTableIterator.java index 61b89423f..39f116765 100644 --- a/src/main/java/org/dbunit/dataset/DefaultTableIterator.java +++ b/src/main/java/org/dbunit/dataset/DefaultTableIterator.java @@ -37,11 +37,22 @@ public class DefaultTableIterator implements ITableIterator private final ITable[] _tables; private int _index = -1; + /** + * Creates an iterator over the given tables, in their given order. + * + * @param tables the tables to iterate over. + */ public DefaultTableIterator(ITable[] tables) { _tables = tables; } + /** + * Creates an iterator over the given tables, optionally in reverse order. + * + * @param tables the tables to iterate over. + * @param reversed true to iterate in reverse order. + */ public DefaultTableIterator(ITable[] tables, boolean reversed) { if (reversed) diff --git a/src/main/java/org/dbunit/dataset/DefaultTableMetaData.java b/src/main/java/org/dbunit/dataset/DefaultTableMetaData.java index 86d332eeb..49253fe4e 100644 --- a/src/main/java/org/dbunit/dataset/DefaultTableMetaData.java +++ b/src/main/java/org/dbunit/dataset/DefaultTableMetaData.java @@ -39,12 +39,25 @@ public class DefaultTableMetaData extends AbstractTableMetaData private final Column[] _columns; private final Column[] _primaryKeys; + /** + * Creates metadata for a table with no primary keys. + * + * @param tableName the table name. + * @param columns the table columns. + */ public DefaultTableMetaData(String tableName, Column[] columns) //throws DataSetException { this(tableName, columns, new String[0]); } + /** + * Creates metadata for a table with the given primary key column names. + * + * @param tableName the table name. + * @param columns the table columns. + * @param primaryKeys the names of the primary key columns. + */ public DefaultTableMetaData(String tableName, Column[] columns, String[] primaryKeys) //throws DataSetException { @@ -53,6 +66,13 @@ public DefaultTableMetaData(String tableName, Column[] columns, _primaryKeys = Columns.getColumns(primaryKeys, columns); } + /** + * Creates metadata for a table with the given primary key columns. + * + * @param tableName the table name. + * @param columns the table columns. + * @param primaryKeys the primary key columns. + */ public DefaultTableMetaData(String tableName, Column[] columns, Column[] primaryKeys) //throws DataSetException { diff --git a/src/main/java/org/dbunit/dataset/FilteredDataSet.java b/src/main/java/org/dbunit/dataset/FilteredDataSet.java index 0d1551deb..3e4e1d7b4 100644 --- a/src/main/java/org/dbunit/dataset/FilteredDataSet.java +++ b/src/main/java/org/dbunit/dataset/FilteredDataSet.java @@ -56,6 +56,8 @@ public class FilteredDataSet extends AbstractDataSet * Creates a FilteredDataSet that decorates the specified dataset and * exposes only the specified tables using {@link SequenceTableFilter} as * filtering strategy. + * @param tableNames the names of the tables to expose, in the order they should be exposed. + * @param dataSet the dataset to decorate. * @throws AmbiguousTableNameException If the given tableNames array contains ambiguous names */ public FilteredDataSet(String[] tableNames, IDataSet dataSet) diff --git a/src/main/java/org/dbunit/dataset/FilteredTableMetaData.java b/src/main/java/org/dbunit/dataset/FilteredTableMetaData.java index a647cb58a..2bde7cc38 100644 --- a/src/main/java/org/dbunit/dataset/FilteredTableMetaData.java +++ b/src/main/java/org/dbunit/dataset/FilteredTableMetaData.java @@ -48,6 +48,13 @@ public class FilteredTableMetaData extends AbstractTableMetaData private final Column[] _columns; private final Column[] _primaryKeys; + /** + * Creates metadata exposing only the columns of the given metadata accepted by the given filter. + * + * @param metaData the metadata to filter. + * @param columnFilter the filter defining which columns to expose. + * @throws DataSetException if the given metadata's columns cannot be retrieved. + */ public FilteredTableMetaData(ITableMetaData metaData, IColumnFilter columnFilter) throws DataSetException { @@ -56,6 +63,14 @@ public FilteredTableMetaData(ITableMetaData metaData, _primaryKeys = getFilteredColumns(_tableName, metaData.getPrimaryKeys(), columnFilter); } + /** + * Returns the columns from the given array accepted by the given filter. + * + * @param tableName the name of the table the columns belong to, needed for the filter invocation. + * @param columns the columns to filter. + * @param columnFilter the filter defining which columns to accept. + * @return the accepted columns. + */ public static Column[] getFilteredColumns(String tableName, Column[] columns, IColumnFilter columnFilter) { diff --git a/src/main/java/org/dbunit/dataset/ForwardOnlyDataSet.java b/src/main/java/org/dbunit/dataset/ForwardOnlyDataSet.java index e37954910..0c6b2085c 100644 --- a/src/main/java/org/dbunit/dataset/ForwardOnlyDataSet.java +++ b/src/main/java/org/dbunit/dataset/ForwardOnlyDataSet.java @@ -42,6 +42,11 @@ public class ForwardOnlyDataSet extends AbstractDataSet private final IDataSet _dataSet; private int _iteratorCount; + /** + * Creates a forward-only decorator over the given dataset. + * + * @param dataSet the dataset to decorate. + */ public ForwardOnlyDataSet(IDataSet dataSet) { _dataSet = dataSet; diff --git a/src/main/java/org/dbunit/dataset/ForwardOnlyTable.java b/src/main/java/org/dbunit/dataset/ForwardOnlyTable.java index a1ca58295..c4eeb7338 100644 --- a/src/main/java/org/dbunit/dataset/ForwardOnlyTable.java +++ b/src/main/java/org/dbunit/dataset/ForwardOnlyTable.java @@ -42,6 +42,11 @@ public class ForwardOnlyTable implements ITable private final ITable _table; private int _lastRow = -1; + /** + * Creates a forward-only decorator over the given table. + * + * @param table the table to decorate. + */ public ForwardOnlyTable(ITable table) { _table = table; diff --git a/src/main/java/org/dbunit/dataset/IRowValueProvider.java b/src/main/java/org/dbunit/dataset/IRowValueProvider.java index aabd3a09e..36a6fccf1 100644 --- a/src/main/java/org/dbunit/dataset/IRowValueProvider.java +++ b/src/main/java/org/dbunit/dataset/IRowValueProvider.java @@ -35,7 +35,7 @@ public interface IRowValueProvider { * Returns the column value for the column with the given name of the currently processed row * @param columnName The db column name for which the value should be provided (current row's value) * @return The value of the given column in the current row - * @throws DataSetException + * @throws DataSetException if the value cannot be provided. */ public Object getColumnValue(String columnName) throws DataSetException; } diff --git a/src/main/java/org/dbunit/dataset/ITable.java b/src/main/java/org/dbunit/dataset/ITable.java index a73572a78..c235d87fe 100644 --- a/src/main/java/org/dbunit/dataset/ITable.java +++ b/src/main/java/org/dbunit/dataset/ITable.java @@ -31,15 +31,20 @@ */ public interface ITable { + /** Sentinel returned by {@link #getValue(int, String)} to distinguish "no value" from a null value. */ public static final Object NO_VALUE = new Object(); /** * Returns this table metadata. + * + * @return this table metadata. */ public ITableMetaData getTableMetaData(); /** * Returns this table row count. + * + * @return this table row count. */ public int getRowCount(); diff --git a/src/main/java/org/dbunit/dataset/ITableIterator.java b/src/main/java/org/dbunit/dataset/ITableIterator.java index 248d70252..4834494c3 100644 --- a/src/main/java/org/dbunit/dataset/ITableIterator.java +++ b/src/main/java/org/dbunit/dataset/ITableIterator.java @@ -37,16 +37,23 @@ public interface ITableIterator * * @return true if the new current table is valid; * false if there are no more table + * @throws DataSetException if advancing to the next table fails. */ public boolean next() throws DataSetException; /** * Returns the metadata of the current table. + * + * @return the metadata of the current table. + * @throws DataSetException if retrieving the metadata fails. */ public ITableMetaData getTableMetaData() throws DataSetException; /** * Returns the current table. + * + * @return the current table. + * @throws DataSetException if retrieving the table fails. */ public ITable getTable() throws DataSetException; } diff --git a/src/main/java/org/dbunit/dataset/LowerCaseDataSet.java b/src/main/java/org/dbunit/dataset/LowerCaseDataSet.java index a768c1e5d..6053eb03d 100644 --- a/src/main/java/org/dbunit/dataset/LowerCaseDataSet.java +++ b/src/main/java/org/dbunit/dataset/LowerCaseDataSet.java @@ -46,16 +46,34 @@ public class LowerCaseDataSet extends AbstractDataSet private final IDataSet _dataSet; + /** + * Creates a dataset that lower-cases the table and column names of the given table. + * + * @param table the table to decorate. + * @throws DataSetException if the dataset cannot be built. + */ public LowerCaseDataSet(ITable table) throws DataSetException { this(new DefaultDataSet(table)); } + /** + * Creates a dataset that lower-cases the table and column names of the given tables. + * + * @param tables the tables to decorate. + * @throws DataSetException if the dataset cannot be built. + */ public LowerCaseDataSet(ITable[] tables) throws DataSetException { this(new DefaultDataSet(tables)); } + /** + * Creates a dataset that lower-cases the table and column names of the given dataset. + * + * @param dataSet the dataset to decorate. + * @throws DataSetException if the dataset cannot be built. + */ public LowerCaseDataSet(IDataSet dataSet) throws DataSetException { _dataSet = dataSet; diff --git a/src/main/java/org/dbunit/dataset/LowerCaseTableMetaData.java b/src/main/java/org/dbunit/dataset/LowerCaseTableMetaData.java index fc2bd045a..55792a8b4 100644 --- a/src/main/java/org/dbunit/dataset/LowerCaseTableMetaData.java +++ b/src/main/java/org/dbunit/dataset/LowerCaseTableMetaData.java @@ -48,24 +48,50 @@ public class LowerCaseTableMetaData extends AbstractTableMetaData private final Column[] _columns; private final Column[] _primaryKeys; + /** + * Creates metadata with lower-cased table and column names, and no primary keys. + * + * @param tableName the table name. + * @param columns the table columns. + */ public LowerCaseTableMetaData(String tableName, Column[] columns) //throws DataSetException { this(tableName, columns, new Column[0]); } + /** + * Creates metadata with lower-cased table and column names, and the given primary key column names. + * + * @param tableName the table name. + * @param columns the table columns. + * @param primaryKeys the names of the primary key columns. + */ public LowerCaseTableMetaData(String tableName, Column[] columns, String[] primaryKeys) //throws DataSetException { this(tableName, columns, Columns.getColumns(primaryKeys, columns) ); } + /** + * Creates metadata with the lower-cased table and column names of the given metadata. + * + * @param metaData the metadata to lower-case. + * @throws DataSetException if the given metadata's columns cannot be retrieved. + */ public LowerCaseTableMetaData(ITableMetaData metaData) throws DataSetException { this(metaData.getTableName(), metaData.getColumns(), metaData.getPrimaryKeys()); } + /** + * Creates metadata with lower-cased table and column names, and the given primary key columns. + * + * @param tableName the table name. + * @param columns the table columns. + * @param primaryKeys the primary key columns. + */ public LowerCaseTableMetaData(String tableName, Column[] columns, Column[] primaryKeys) //throws DataSetException { diff --git a/src/main/java/org/dbunit/dataset/NoPrimaryKeyException.java b/src/main/java/org/dbunit/dataset/NoPrimaryKeyException.java index a3cfa755f..6bb7d814f 100644 --- a/src/main/java/org/dbunit/dataset/NoPrimaryKeyException.java +++ b/src/main/java/org/dbunit/dataset/NoPrimaryKeyException.java @@ -31,20 +31,43 @@ */ public class NoPrimaryKeyException extends DataSetException { + /** + * Constructs a NoPrimaryKeyException with no detail + * message and no encapsulated exception. + */ public NoPrimaryKeyException() { } + /** + * Constructs a NoPrimaryKeyException with the specified detail + * message and no encapsulated exception. + * + * @param msg the detail message. + */ public NoPrimaryKeyException(String msg) { super(msg); } + /** + * Constructs a NoPrimaryKeyException with the specified detail + * message and encapsulated exception. + * + * @param msg the detail message. + * @param e the encapsulated exception. + */ public NoPrimaryKeyException(String msg, Throwable e) { super(msg, e); } + /** + * Constructs a NoPrimaryKeyException with the encapsulated + * exception and use string representation as detail message. + * + * @param e the encapsulated exception. + */ public NoPrimaryKeyException(Throwable e) { super(e); diff --git a/src/main/java/org/dbunit/dataset/NoSuchColumnException.java b/src/main/java/org/dbunit/dataset/NoSuchColumnException.java index c350bf703..0ac8315aa 100644 --- a/src/main/java/org/dbunit/dataset/NoSuchColumnException.java +++ b/src/main/java/org/dbunit/dataset/NoSuchColumnException.java @@ -33,13 +33,18 @@ public class NoSuchColumnException extends DataSetException { /** + * Constructs a NoSuchColumnException with no detail message. + * * @deprecated since 2.3.0. Prefer constructor taking a table/columnName as argument */ public NoSuchColumnException() { } - + /** + * Constructs a NoSuchColumnException with the specified detail message. + * + * @param msg the detail message. * @deprecated since 2.3.0. Prefer constructor taking a table/columnName as argument */ public NoSuchColumnException(String msg) @@ -71,8 +76,10 @@ public NoSuchColumnException(String tableName, String columnName, String msg) } /** - * @param msg - * @param e + * Constructs a NoSuchColumnException with the specified detail message and cause. + * + * @param msg the detail message. + * @param e the cause. * @deprecated since 2.3.0. Prefer constructor taking a table/columnName as argument */ public NoSuchColumnException(String msg, Throwable e) @@ -81,7 +88,9 @@ public NoSuchColumnException(String msg, Throwable e) } /** - * @param e + * Constructs a NoSuchColumnException with the specified cause. + * + * @param e the cause. * @deprecated since 2.3.0. Prefer constructor taking a table/columnName as argument */ public NoSuchColumnException(Throwable e) diff --git a/src/main/java/org/dbunit/dataset/NoSuchTableException.java b/src/main/java/org/dbunit/dataset/NoSuchTableException.java index 55de11441..261bf9b16 100644 --- a/src/main/java/org/dbunit/dataset/NoSuchTableException.java +++ b/src/main/java/org/dbunit/dataset/NoSuchTableException.java @@ -31,20 +31,39 @@ */ public class NoSuchTableException extends DataSetException { + /** + * Default constructor. + */ public NoSuchTableException() { } + /** + * Constructs a NoSuchTableException with the specified detail message. + * + * @param msg the detail message. + */ public NoSuchTableException(String msg) { super(msg); } + /** + * Constructs a NoSuchTableException with the specified detail message and cause. + * + * @param msg the detail message. + * @param e the cause. + */ public NoSuchTableException(String msg, Throwable e) { super(msg, e); } + /** + * Constructs a NoSuchTableException with the specified cause. + * + * @param e the cause. + */ public NoSuchTableException(Throwable e) { super(e); diff --git a/src/main/java/org/dbunit/dataset/OrderedTableNameMap.java b/src/main/java/org/dbunit/dataset/OrderedTableNameMap.java index bda7d33aa..35c5430ff 100644 --- a/src/main/java/org/dbunit/dataset/OrderedTableNameMap.java +++ b/src/main/java/org/dbunit/dataset/OrderedTableNameMap.java @@ -115,7 +115,7 @@ public String[] getTableNames() /** * Checks if this map contains the given table name - * @param tableName + * @param tableName The table name to check * @return Returns true if the map of tables contains the given table name */ public boolean containsTable(String tableName) @@ -125,6 +125,8 @@ public boolean containsTable(String tableName) } /** + * Checks whether the given table name matches the last table added to this map. + * * @param tableName The table name to check * @return true if the given tableName matches the last table that has been added to this map. */ @@ -147,7 +149,9 @@ public boolean isLastTable(String tableName) } /** - * @return The name of the last table that has been added to this map. Returns null if no + * Returns the name of the last table added to this map. + * + * @return The name of the last table that has been added to this map. Returns null if no * table has been added yet. */ public String getLastTableName() @@ -172,7 +176,13 @@ public String getLastTableName() } - public void setLastTable(String tableName) throws NoSuchTableException + /** + * Overrides the table returned by {@link #getLastTableName()} to the given, already-added table name. + * + * @param tableName The table name to set as the last table. Must already exist in this map. + * @throws NoSuchTableException If the given table name does not exist in this map. + */ + public void setLastTable(String tableName) throws NoSuchTableException { if(LOGGER.isDebugEnabled()) LOGGER.debug("setLastTable(name{}) - start", tableName); @@ -214,9 +224,11 @@ public void add(String tableName, Object object) throws AmbiguousTableNameExcept } /** + * Returns the values of this map ordered in the sequence they have been added. + * * @return The values of this map ordered in the sequence they have been added */ - public Collection orderedValues() + public Collection orderedValues() { if(LOGGER.isDebugEnabled()) LOGGER.debug("orderedValues() - start"); diff --git a/src/main/java/org/dbunit/dataset/ReplacementDataSet.java b/src/main/java/org/dbunit/dataset/ReplacementDataSet.java index af5efe154..15a201b04 100644 --- a/src/main/java/org/dbunit/dataset/ReplacementDataSet.java +++ b/src/main/java/org/dbunit/dataset/ReplacementDataSet.java @@ -119,6 +119,9 @@ public void addReplacementSubstring(String originalSubstring, /** * Sets substring delimiters. + * + * @param startDelimiter the substring marking the start of a replaceable token. + * @param endDelimiter the substring marking the end of a replaceable token. */ public void setSubstringDelimiters(String startDelimiter, String endDelimiter) { diff --git a/src/main/java/org/dbunit/dataset/ReplacementTable.java b/src/main/java/org/dbunit/dataset/ReplacementTable.java index b902b1438..585c8c352 100644 --- a/src/main/java/org/dbunit/dataset/ReplacementTable.java +++ b/src/main/java/org/dbunit/dataset/ReplacementTable.java @@ -60,6 +60,15 @@ public ReplacementTable(ITable table) this(table, new HashMap(), new HashMap(), null, null); } + /** + * Create a new ReplacementTable object that decorates the specified table. + * + * @param table the decorated table. + * @param objectMap the object replacement mappings. + * @param substringMap the substring replacement mappings. + * @param startDelimiter the substring marking the start of a replaceable token, or null. + * @param endDelimiter the substring marking the end of a replaceable token, or null. + */ public ReplacementTable(ITable table, Map objectMap, Map substringMap, String startDelimiter, String endDelimiter) { @@ -118,6 +127,9 @@ public void addReplacementSubstring(String originalSubstring, /** * Sets substring delimiters. + * + * @param startDelimiter the substring marking the start of a replaceable token. + * @param endDelimiter the substring marking the end of a replaceable token. */ public void setSubstringDelimiters(String startDelimiter, String endDelimiter) { diff --git a/src/main/java/org/dbunit/dataset/RowFilterTable.java b/src/main/java/org/dbunit/dataset/RowFilterTable.java index cbe23742b..f2b34ea9e 100644 --- a/src/main/java/org/dbunit/dataset/RowFilterTable.java +++ b/src/main/java/org/dbunit/dataset/RowFilterTable.java @@ -74,7 +74,7 @@ public class RowFilterTable implements ITable, IRowValueProvider { * Creates a new {@link ITable} where some rows can be filtered out from the original table * @param table The table to be wrapped * @param rowFilter The row filter that checks for every row whether or not it should be filtered - * @throws DataSetException + * @throws DataSetException if building the filtered row set fails. */ public RowFilterTable(ITable table, IRowFilter rowFilter) throws DataSetException { if ( table == null || rowFilter == null ) { @@ -149,7 +149,7 @@ public Object getValue(int row, String column) throws DataSetException /** * Returns the column value for the column with the given name of the currently processed row - * @throws DataSetException + * @throws DataSetException if the value cannot be retrieved. * @see org.dbunit.dataset.IRowValueProvider#getColumnValue(java.lang.String) */ public Object getColumnValue(String columnName) throws DataSetException { diff --git a/src/main/java/org/dbunit/dataset/RowOutOfBoundsException.java b/src/main/java/org/dbunit/dataset/RowOutOfBoundsException.java index 86eb81551..b97426fa4 100644 --- a/src/main/java/org/dbunit/dataset/RowOutOfBoundsException.java +++ b/src/main/java/org/dbunit/dataset/RowOutOfBoundsException.java @@ -37,20 +37,39 @@ public class RowOutOfBoundsException extends DataSetException * serialization-compatible with 3.2.0 and stable across all releases from here on. */ private static final long serialVersionUID = 3366609800061836144L; + /** + * Default constructor. + */ public RowOutOfBoundsException() { } + /** + * Constructs a RowOutOfBoundsException with the specified detail message. + * + * @param msg the detail message. + */ public RowOutOfBoundsException(String msg) { super(msg); } + /** + * Constructs a RowOutOfBoundsException with the specified detail message and cause. + * + * @param msg the detail message. + * @param e the cause. + */ public RowOutOfBoundsException(String msg, Throwable e) { super(msg, e); } + /** + * Constructs a RowOutOfBoundsException with the specified cause. + * + * @param e the cause. + */ public RowOutOfBoundsException(Throwable e) { super(e); diff --git a/src/main/java/org/dbunit/dataset/SortedDataSet.java b/src/main/java/org/dbunit/dataset/SortedDataSet.java index 3fbf85b7c..f7cec98dc 100644 --- a/src/main/java/org/dbunit/dataset/SortedDataSet.java +++ b/src/main/java/org/dbunit/dataset/SortedDataSet.java @@ -42,6 +42,12 @@ public class SortedDataSet extends AbstractDataSet private final IDataSet _dataSet; + /** + * Creates a new SortedDataSet decorating the given dataset. + * + * @param dataSet the decorated dataset. + * @throws DataSetException if a table cannot be sorted. + */ public SortedDataSet(IDataSet dataSet) throws DataSetException { _dataSet = dataSet; diff --git a/src/main/java/org/dbunit/dataset/SortedTable.java b/src/main/java/org/dbunit/dataset/SortedTable.java index 36224ec2e..e75e795fa 100644 --- a/src/main/java/org/dbunit/dataset/SortedTable.java +++ b/src/main/java/org/dbunit/dataset/SortedTable.java @@ -63,7 +63,7 @@ public class SortedTable extends AbstractTable * decorated table * @param columns * columns to be used for sorting - * @throws DataSetException + * @throws DataSetException if a given column does not exist in the table. */ public SortedTable(final ITable table, final Column[] columns) throws DataSetException @@ -84,7 +84,7 @@ public SortedTable(final ITable table, final Column[] columns) * true to use the column definitions specified by the columns * parameter, false to use the column definitions from the * specified table's metadata. - * @throws DataSetException + * @throws DataSetException if a given column does not exist in the table. */ public SortedTable(final ITable table, final Column[] columns, final boolean useSpecifiedColumns) throws DataSetException @@ -111,7 +111,7 @@ public SortedTable(final ITable table, final Column[] columns, * decorated table * @param columnNames * names of columns to be used for sorting - * @throws DataSetException + * @throws DataSetException if a given column does not exist in the table. */ public SortedTable(final ITable table, final String[] columnNames) throws DataSetException @@ -130,7 +130,7 @@ public SortedTable(final ITable table, final String[] columnNames) * @param metaData * The metadata used to retrieve all columns which in turn are * used for sorting the table - * @throws DataSetException + * @throws DataSetException if a given column does not exist in the table. */ public SortedTable(final ITable table, final ITableMetaData metaData) throws DataSetException @@ -144,7 +144,7 @@ public SortedTable(final ITable table, final ITableMetaData metaData) * * @param table * The decorated table - * @throws DataSetException + * @throws DataSetException if a given column does not exist in the table. */ public SortedTable(final ITable table) throws DataSetException { @@ -196,6 +196,8 @@ private void initialize() } /** + * Returns the columns that are used for sorting the table. + * * @return The columns that are used for sorting the table */ public Column[] getSortColumns() @@ -300,7 +302,8 @@ private Comparator createPrecomputedKeyComparator(final int rowCount) * or not. Default value is false which means that the old * string comparison is used.
* - * @param useComparable + * @param useComparable true to compare using the column's Comparable + * implementation, false to compare using string values. * @since 2.3.0 */ public void setUseComparable(final boolean useComparable) @@ -400,6 +403,8 @@ public static abstract class AbstractRowComparator implements Comparator private final Column[] _sortColumns; /** + * Constructs a comparator sorting rows of the given table by the given columns. + * * @param table * The wrapped table to be sorted * @param sortColumns @@ -463,6 +468,8 @@ public int compare(final Object o1, final Object o2) } /** + * Compares the two given values of the given column. + * * @param column * The column to be compared * @param value1 @@ -470,7 +477,7 @@ public int compare(final Object o1, final Object o2) * @param value2 * The second value of the given column * @return 0 if both values are considered equal. - * @throws TypeCastException + * @throws TypeCastException if a value cannot be cast for comparison. */ protected abstract int compare(Column column, Object value1, Object value2) throws TypeCastException; @@ -490,6 +497,13 @@ protected static class RowComparator extends AbstractRowComparator private final Logger logger = LoggerFactory.getLogger(RowComparator.class); + /** + * Constructs a comparator sorting rows of the given table by the given columns, + * using each column's Comparable implementation. + * + * @param table the wrapped table to be sorted. + * @param sortColumns the columns to be used for sorting in the given order. + */ public RowComparator(final ITable table, final Column[] sortColumns) { super(table, sortColumns); @@ -524,6 +538,13 @@ protected static class RowComparatorByString extends AbstractRowComparator private final Logger logger = LoggerFactory.getLogger(RowComparatorByString.class); + /** + * Constructs a comparator sorting rows of the given table by the given columns, + * using each column's string value. + * + * @param table the wrapped table to be sorted. + * @param sortColumns the columns to be used for sorting in the given order. + */ public RowComparatorByString(final ITable table, final Column[] sortColumns) { diff --git a/src/main/java/org/dbunit/dataset/TableDecoratorDataSet.java b/src/main/java/org/dbunit/dataset/TableDecoratorDataSet.java index 874b6d84b..4905737ff 100644 --- a/src/main/java/org/dbunit/dataset/TableDecoratorDataSet.java +++ b/src/main/java/org/dbunit/dataset/TableDecoratorDataSet.java @@ -37,6 +37,12 @@ public class TableDecoratorDataSet extends AbstractDataSet private final IDataSet _dataSet; private final TableDecoratorFunction _decoratorFunction; + /** + * Creates a new TableDecoratorDataSet decorating each table of the given dataset. + * + * @param dataSet the decorated dataset. + * @param decoratorFunction the function applied to each table of the dataset. + */ public TableDecoratorDataSet(final IDataSet dataSet, final TableDecoratorFunction decoratorFunction) { @@ -80,9 +86,19 @@ public ITable getTable() throws DataSetException } } + /** + * A function that decorates a single {@link ITable}. + */ @FunctionalInterface public interface TableDecoratorFunction { + /** + * Applies this function to the given table. + * + * @param table the table to decorate. + * @return the decorated table. + * @throws DataSetException if the table cannot be decorated. + */ ITable apply(ITable table) throws DataSetException; } } diff --git a/src/main/java/org/dbunit/dataset/common/handlers/AbstractPipelineComponent.java b/src/main/java/org/dbunit/dataset/common/handlers/AbstractPipelineComponent.java index a3037ee6e..f18b4546b 100644 --- a/src/main/java/org/dbunit/dataset/common/handlers/AbstractPipelineComponent.java +++ b/src/main/java/org/dbunit/dataset/common/handlers/AbstractPipelineComponent.java @@ -44,6 +44,11 @@ public abstract class AbstractPipelineComponent implements PipelineComponent { private Helper helper; + /** + * Returns the next component in the pipeline to which unhandled characters are delegated. + * + * @return the successor component, or null if none is set. + */ protected PipelineComponent getSuccessor() { return successor; } @@ -57,6 +62,11 @@ public void setPipeline(Pipeline pipeline) { this.pipeline = pipeline; } + /** + * Returns the configuration of the pipeline this component belongs to. + * + * @return the pipeline configuration. + */ protected PipelineConfig getPipelineConfig() { if(this.getPipeline() != null) { return this.getPipeline().getPipelineConfig(); @@ -71,7 +81,6 @@ public void setSuccessor(PipelineComponent successor) { this.successor = successor; } - private StringBuilder getThePiece() { return getPipeline().getCurrentProduct(); } @@ -102,6 +111,13 @@ public boolean allowForNoMoreInput() { return getHelper().allowForNoMoreInput(); } + /** + * Links the given helper and handler to each other and returns the handler. + * + * @param handler the handler component to configure. + * @param helper the helper implementing the handler's character-handling behavior. + * @return the given handler, with its helper set. + */ protected static PipelineComponent createPipelineComponent(AbstractPipelineComponent handler, Helper helper) { logger.debug("createPipelineComponent(handler={}, helper={}) - start", handler, helper); helper.setHandler(handler); @@ -111,12 +127,17 @@ protected static PipelineComponent createPipelineComponent(AbstractPipelineCompo /** * Method invoked when the character should be accepted - * @param c + * @param c the character to accept. */ public void accept(char c) { getThePiece().append(c); } + /** + * Returns the helper currently handling characters for this component. + * + * @return the current helper. + */ protected Helper getHelper() { return helper; } @@ -126,13 +147,21 @@ private void setHelper(Helper helper) { this.helper = helper; } + /** + * Helper that silently discards the character it is given. + */ static protected class IGNORE extends Helper { + public void helpWith(char c) { // IGNORE } } + /** + * Helper that forwards the character to its handler's {@link #accept(char)} method. + */ static protected class ACCEPT extends Helper { + public void helpWith(char c) { if(logger.isDebugEnabled()) logger.debug("helpWith(c={}) - start", c); diff --git a/src/main/java/org/dbunit/dataset/common/handlers/AllHandler.java b/src/main/java/org/dbunit/dataset/common/handlers/AllHandler.java index 13bbff812..ca072994b 100644 --- a/src/main/java/org/dbunit/dataset/common/handlers/AllHandler.java +++ b/src/main/java/org/dbunit/dataset/common/handlers/AllHandler.java @@ -42,11 +42,21 @@ public class AllHandler extends AbstractPipelineComponent { private AllHandler () {} + /** + * Creates a handler that accepts every character it is given. + * + * @return a new accept-all pipeline component. + */ public static final PipelineComponent ACCEPT () { logger.debug("ACCEPT() - start"); return createPipelineComponent(new AllHandler(), new ACCEPT()); } + /** + * Creates a handler that ignores every character it is given. + * + * @return a new ignore-all pipeline component. + */ public static final PipelineComponent IGNORE () { logger.debug("IGNORE() - start"); return createPipelineComponent(new AllHandler() {}, new IGNORE()); diff --git a/src/main/java/org/dbunit/dataset/common/handlers/EnforceHandler.java b/src/main/java/org/dbunit/dataset/common/handlers/EnforceHandler.java index 6872fdfde..ec442f139 100644 --- a/src/main/java/org/dbunit/dataset/common/handlers/EnforceHandler.java +++ b/src/main/java/org/dbunit/dataset/common/handlers/EnforceHandler.java @@ -48,12 +48,24 @@ private EnforceHandler(PipelineComponent [] components) { } + /** + * Creates a handler that enforces the given component to handle the character. + * + * @param component the component that must handle the character. + * @return the new pipeline component. + */ public static final PipelineComponent ENFORCE(PipelineComponent component) { logger.debug("ENFORCE(component={}) - start", component); return EnforceHandler.ENFORCE(new PipelineComponent [] {component}); } + /** + * Creates a handler that enforces the first of the given components able to handle the character. + * + * @param components the components, tried in order, one of which must handle the character. + * @return the new pipeline component. + */ public static final PipelineComponent ENFORCE(PipelineComponent [] components) { logger.debug("ENFORCE(components={}) - start", (Object) components); @@ -83,12 +95,22 @@ public void setPipeline(Pipeline pipeline) { super.setPipeline(pipeline); } + /** + * Returns the components tried, in order, to handle a character. + * + * @return the components tried, in order, to handle a character. + */ protected PipelineComponent[] getEnforcedComponents() { logger.debug("getEnforcedComponents() - start"); return enforcedComponents; } + /** + * Sets the components tried, in order, to handle a character. + * + * @param enforcedComponents the components tried, in order, to handle a character. + */ protected void setEnforcedComponents(PipelineComponent[] enforcedComponents) { logger.debug("setEnforcedComponents(enforcedComponents={}) - start", (Object) enforcedComponents); diff --git a/src/main/java/org/dbunit/dataset/common/handlers/EscapeHandler.java b/src/main/java/org/dbunit/dataset/common/handlers/EscapeHandler.java index 42d281551..9d9bd3dd4 100644 --- a/src/main/java/org/dbunit/dataset/common/handlers/EscapeHandler.java +++ b/src/main/java/org/dbunit/dataset/common/handlers/EscapeHandler.java @@ -39,22 +39,39 @@ public class EscapeHandler extends AbstractPipelineComponent { */ private static final Logger logger = LoggerFactory.getLogger(EscapeHandler.class); + /** Default character used to escape the quote and escape characters themselves. */ public static final char DEFAULT_ESCAPE_CHAR = '\\'; private EscapeHandler() { } + /** + * Creates a handler that accepts the escape character. + * + * @return the new pipeline component. + */ public static final PipelineComponent ACCEPT() { logger.debug("ACCEPT() - start"); return createPipelineComponent(new EscapeHandler(), new ACCEPT()); } // @todo: make sense? + /** + * Creates a handler that ignores the escape character. + * + * @return the new pipeline component. + */ public static final PipelineComponent IGNORE() { logger.debug("IGNORE() - start"); return createPipelineComponent(new EscapeHandler(), new IGNORE()); } + /** + * Creates a handler that processes the escape character by enforcing the next character + * to be accepted literally. + * + * @return the new pipeline component. + */ public static final PipelineComponent ESCAPE() { logger.debug("ESCAPE() - start"); return createPipelineComponent(new EscapeHandler(), new ESCAPE()); diff --git a/src/main/java/org/dbunit/dataset/common/handlers/Handler.java b/src/main/java/org/dbunit/dataset/common/handlers/Handler.java index ac586c0d6..93831673f 100644 --- a/src/main/java/org/dbunit/dataset/common/handlers/Handler.java +++ b/src/main/java/org/dbunit/dataset/common/handlers/Handler.java @@ -32,8 +32,36 @@ * @since 2.2 (Sep 12, 2004) */ public interface Handler { + /** + * Handles the given character. + * + * @param c the character to handle. + * @throws IllegalInputCharacterException if the character is not valid in the current context. + * @throws PipelineException if the character cannot be processed by the pipeline. + */ public void handle(char c) throws IllegalInputCharacterException, PipelineException; + + /** + * Determines whether this handler can handle the given character. + * + * @param c the character to check. + * @return true if this handler can handle the character. + * @throws IllegalInputCharacterException if the character is not valid in the current context. + */ public boolean canHandle(char c) throws IllegalInputCharacterException; + + /** + * Notifies this handler that no more input will be provided. + * + * @throws IllegalStateException if this handler is not in a state where input can end. + */ public void noMoreInput() throws IllegalStateException; + + /** + * Determines whether this handler allows input to end at this point. + * + * @return true if ending input now is allowed. + * @throws IllegalStateException if the handler's state cannot be evaluated. + */ public boolean allowForNoMoreInput() throws IllegalStateException; } diff --git a/src/main/java/org/dbunit/dataset/common/handlers/Helper.java b/src/main/java/org/dbunit/dataset/common/handlers/Helper.java index 271e06a39..e7cbcc03a 100644 --- a/src/main/java/org/dbunit/dataset/common/handlers/Helper.java +++ b/src/main/java/org/dbunit/dataset/common/handlers/Helper.java @@ -24,7 +24,6 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; - /** * Abstract helper that assists a {@link PipelineComponent} in processing a character. * @@ -44,6 +43,13 @@ public abstract class Helper { abstract void helpWith(char c) throws PipelineException; + /** + * Returns whether this helper allows input to end while it is active. The default + * implementation always allows it. + * + * @return true if ending input now is allowed. + * @throws IllegalStateException if this helper's state cannot be evaluated. + */ public boolean allowForNoMoreInput() throws IllegalStateException { return true; } diff --git a/src/main/java/org/dbunit/dataset/common/handlers/IllegalInputCharacterException.java b/src/main/java/org/dbunit/dataset/common/handlers/IllegalInputCharacterException.java index 2293fc311..12b799a53 100644 --- a/src/main/java/org/dbunit/dataset/common/handlers/IllegalInputCharacterException.java +++ b/src/main/java/org/dbunit/dataset/common/handlers/IllegalInputCharacterException.java @@ -34,6 +34,11 @@ */ public class IllegalInputCharacterException extends DatabaseUnitRuntimeException { + /** + * Constructs an IllegalInputCharacterException with the specified detail message. + * + * @param message the detail message. + */ public IllegalInputCharacterException(String message) { super(message); } diff --git a/src/main/java/org/dbunit/dataset/common/handlers/IsAlnumHandler.java b/src/main/java/org/dbunit/dataset/common/handlers/IsAlnumHandler.java index 7e9d7c466..9aba8b987 100644 --- a/src/main/java/org/dbunit/dataset/common/handlers/IsAlnumHandler.java +++ b/src/main/java/org/dbunit/dataset/common/handlers/IsAlnumHandler.java @@ -43,16 +43,31 @@ private IsAlnumHandler() { } + /** + * Creates a handler that accepts alphanumeric characters. + * + * @return the new pipeline component. + */ public static final PipelineComponent ACCEPT () { logger.debug("ACCEPT() - start"); return createPipelineComponent(new IsAlnumHandler(), new ACCEPT()); } + /** + * Creates a handler that ignores alphanumeric characters. + * + * @return the new pipeline component. + */ public static final PipelineComponent IGNORE () { logger.debug("IGNORE() - start"); return createPipelineComponent(new IsAlnumHandler(), new IGNORE()); } + /** + * Creates a handler that starts a quoted field on an alphanumeric character. + * + * @return the new pipeline component. + */ public static final PipelineComponent QUOTE () { logger.debug("QUOTE() - start"); return createPipelineComponent(new IsAlnumHandler(), new QUOTE()); @@ -64,7 +79,6 @@ public static final PipelineComponent UNQUOTE () { } */ - public boolean canHandle(char c) throws IllegalInputCharacterException { if(logger.isDebugEnabled()) logger.debug("canHandle(c={}) - start", String.valueOf(c)); @@ -78,7 +92,10 @@ public boolean canHandle(char c) throws IllegalInputCharacterException { return false; } - + /** + * Helper that starts a quoted field, re-arranging the pipeline to accept characters + * literally until the closing quote. + */ static protected class QUOTE extends Helper { /** @@ -101,6 +118,9 @@ public void helpWith(char c) { } } + /** + * Helper that ends a quoted field, restoring the pipeline's pre-quote state. + */ static protected class UNQUOTE extends Helper { /** @@ -108,7 +128,6 @@ static protected class UNQUOTE extends Helper { */ private static final Logger logger = LoggerFactory.getLogger(UNQUOTE.class); - public void helpWith(char c) { if(logger.isDebugEnabled()) logger.debug("helpWith(c={}) - start", String.valueOf(c)); diff --git a/src/main/java/org/dbunit/dataset/common/handlers/NoHandler.java b/src/main/java/org/dbunit/dataset/common/handlers/NoHandler.java index f062b19cd..da4b72f1e 100644 --- a/src/main/java/org/dbunit/dataset/common/handlers/NoHandler.java +++ b/src/main/java/org/dbunit/dataset/common/handlers/NoHandler.java @@ -36,6 +36,11 @@ public class NoHandler extends AbstractPipelineComponent { private NoHandler() {} + /** + * Creates a handler that rejects every character. + * + * @return the new pipeline component. + */ public static final PipelineComponent IGNORE () { return createPipelineComponent(new NoHandler(), new ACCEPT()); } diff --git a/src/main/java/org/dbunit/dataset/common/handlers/Pipeline.java b/src/main/java/org/dbunit/dataset/common/handlers/Pipeline.java index b6e18ba98..e1f6ddc3e 100644 --- a/src/main/java/org/dbunit/dataset/common/handlers/Pipeline.java +++ b/src/main/java/org/dbunit/dataset/common/handlers/Pipeline.java @@ -51,6 +51,9 @@ public class Pipeline implements Handler { private PipelineComponent noHandler; private PipelineConfig pipelineConfig = new PipelineConfig(); + /** + * Default constructor. + */ public Pipeline() { setComponents(new LinkedList()); setProducts(new ArrayList()); @@ -69,12 +72,22 @@ public Pipeline() { putFront(TransparentHandler.IGNORE()); } + /** + * Returns the piece currently being accumulated. + * + * @return the piece currently being accumulated. + */ public StringBuilder getCurrentProduct() { logger.debug("getCurrentProduct() - start"); return currentProduct; } + /** + * Sets the piece currently being accumulated. + * + * @param currentProduct the piece currently being accumulated. + */ public void setCurrentProduct(StringBuilder currentProduct) { logger.debug("setCurrentProduct(currentProduct={}) - start", currentProduct); @@ -97,6 +110,9 @@ private void prepareNewPiece() { } + /** + * Completes the current piece, adding it to {@link #getProducts()} and starting a new one. + */ public void thePieceIsDone() { logger.debug("thePieceIsDone() - start"); @@ -104,12 +120,22 @@ public void thePieceIsDone() { prepareNewPiece(); } + /** + * Returns the completed pieces produced so far. + * + * @return the completed pieces produced so far. + */ public List getProducts() { logger.debug("getProducts() - start"); return products; } + /** + * Sets the completed pieces produced so far. + * + * @param products the completed pieces produced so far. + */ protected void setProducts(List products) { logger.debug("setProducts(products={}) - start", products); @@ -128,6 +154,11 @@ private void setComponents(LinkedList components) { this.components = components; } + /** + * Inserts the given component at the front of the pipeline. + * + * @param component the component to insert. + */ public void putFront(PipelineComponent component) { logger.debug("putFront(component={}) - start", component); @@ -136,6 +167,12 @@ public void putFront(PipelineComponent component) { getComponents().addFirst(component); } + /** + * Removes and returns the component at the front of the pipeline. + * + * @return the component that was at the front of the pipeline. + * @throws PipelineException if the front component is the last handler and cannot be removed. + */ public PipelineComponent removeFront() throws PipelineException { logger.debug("removeFront() - start"); @@ -144,6 +181,12 @@ public PipelineComponent removeFront() throws PipelineException { return first; } + /** + * Removes the given component from the pipeline. + * + * @param component the component to remove. + * @throws PipelineException if the component is the last handler, or is not present in the pipeline. + */ public void remove(PipelineComponent component) throws PipelineException { logger.debug("remove(component={}) - start", component); @@ -188,6 +231,9 @@ private void setNoHandler(PipelineComponent noHandler) { this.noHandler = noHandler; } + /** + * Clears the completed pieces produced so far. + */ public void resetProducts() { logger.debug("resetProducts() - start"); @@ -201,10 +247,20 @@ public void noMoreInput() { //thePieceIsDone(); } + /** + * Returns the configuration used by this pipeline's components. + * + * @return the configuration used by this pipeline's components. + */ public PipelineConfig getPipelineConfig() { return pipelineConfig; } + /** + * Sets the configuration used by this pipeline's components. + * + * @param pipelineConfig the configuration used by this pipeline's components. + */ public void setPipelineConfig(PipelineConfig pipelineConfig) { this.pipelineConfig = pipelineConfig; } diff --git a/src/main/java/org/dbunit/dataset/common/handlers/PipelineComponent.java b/src/main/java/org/dbunit/dataset/common/handlers/PipelineComponent.java index 340a075d2..9b3494ba2 100644 --- a/src/main/java/org/dbunit/dataset/common/handlers/PipelineComponent.java +++ b/src/main/java/org/dbunit/dataset/common/handlers/PipelineComponent.java @@ -31,8 +31,31 @@ * @since 2.2 (Sep 12, 2004) */ public interface PipelineComponent extends Handler { + /** + * Sets the next component to which unhandled characters are delegated. + * + * @param successor the successor component. + */ void setSuccessor(PipelineComponent successor); + + /** + * Accepts the given character as part of the current field value. + * + * @param c the character to accept. + */ void accept(char c); + + /** + * Sets the pipeline this component belongs to. + * + * @param line the owning pipeline. + */ void setPipeline (Pipeline line); + + /** + * Returns the pipeline this component belongs to. + * + * @return the owning pipeline. + */ Pipeline getPipeline(); } diff --git a/src/main/java/org/dbunit/dataset/common/handlers/PipelineConfig.java b/src/main/java/org/dbunit/dataset/common/handlers/PipelineConfig.java index c06bee245..5623835d5 100644 --- a/src/main/java/org/dbunit/dataset/common/handlers/PipelineConfig.java +++ b/src/main/java/org/dbunit/dataset/common/handlers/PipelineConfig.java @@ -35,19 +35,42 @@ public class PipelineConfig private char separatorChar = SeparatorHandler.DEFAULT_SEPARATOR_CHAR; private char escapeChar = EscapeHandler.DEFAULT_ESCAPE_CHAR; + /** + * Default constructor. + */ public PipelineConfig() { - + } - + + /** + * Returns the character that separates fields. + * + * @return the character that separates fields. + */ public char getSeparatorChar() { return separatorChar; } + /** + * Sets the character that separates fields. + * + * @param separatorChar the character that separates fields. + */ public void setSeparatorChar(char separatorChar) { this.separatorChar = separatorChar; } + /** + * Returns the character that escapes the next character. + * + * @return the character that escapes the next character. + */ public char getEscapeChar() { return escapeChar; } + /** + * Sets the character that escapes the next character. + * + * @param escapeChar the character that escapes the next character. + */ public void setEscapeChar(char escapeChar) { this.escapeChar = escapeChar; } diff --git a/src/main/java/org/dbunit/dataset/common/handlers/PipelineException.java b/src/main/java/org/dbunit/dataset/common/handlers/PipelineException.java index c3fb6c40c..48aaa3482 100644 --- a/src/main/java/org/dbunit/dataset/common/handlers/PipelineException.java +++ b/src/main/java/org/dbunit/dataset/common/handlers/PipelineException.java @@ -32,6 +32,11 @@ * @since 2.2 (Sep 12, 2004) */ public class PipelineException extends DatabaseUnitRuntimeException { + /** + * Constructs a PipelineException with the specified detail message. + * + * @param message the detail message. + */ public PipelineException(String message) { super(message); } diff --git a/src/main/java/org/dbunit/dataset/common/handlers/QuoteHandler.java b/src/main/java/org/dbunit/dataset/common/handlers/QuoteHandler.java index 0245c7da8..9bd0d4ecc 100644 --- a/src/main/java/org/dbunit/dataset/common/handlers/QuoteHandler.java +++ b/src/main/java/org/dbunit/dataset/common/handlers/QuoteHandler.java @@ -39,31 +39,50 @@ public class QuoteHandler extends AbstractPipelineComponent { */ private static final Logger logger = LoggerFactory.getLogger(QuoteHandler.class); + /** The character that delimits a quoted CSV field. */ public static final char QUOTE_CHAR = '"'; - - private QuoteHandler() { } + /** + * Creates a handler that accepts the quote character. + * + * @return the new pipeline component. + */ public static final PipelineComponent ACCEPT() { logger.debug("ACCEPT() - start"); return createPipelineComponent(new QuoteHandler(), new ACCEPT()); } + /** + * Creates a handler that ignores the quote character. + * + * @return the new pipeline component. + */ public static final PipelineComponent IGNORE() { logger.debug("IGNORE() - start"); return createPipelineComponent(new QuoteHandler(), new IGNORE()); } + /** + * Creates a handler that starts a quoted field on the quote character. + * + * @return the new pipeline component. + */ public static final PipelineComponent QUOTE() { logger.debug("QUOTE() - start"); return createPipelineComponent(new QuoteHandler(), new QUOTE()); } + /** + * Creates a handler that ends a quoted field on the quote character. + * + * @return the new pipeline component. + */ public static final PipelineComponent UNQUOTE() { logger.debug("UNQUOTE() - start"); @@ -80,7 +99,10 @@ public boolean canHandle(char c) throws IllegalInputCharacterException { return false; } - + /** + * Helper that starts a quoted field, re-arranging the pipeline to accept characters + * literally until the closing quote. + */ static protected class QUOTE extends Helper { /** @@ -102,6 +124,9 @@ public void helpWith(char c) { } + /** + * Helper that ends a quoted field, restoring the pipeline's pre-quote state. + */ static protected class UNQUOTE extends Helper { /** diff --git a/src/main/java/org/dbunit/dataset/common/handlers/SeparatorHandler.java b/src/main/java/org/dbunit/dataset/common/handlers/SeparatorHandler.java index ca2327afb..9b3094676 100644 --- a/src/main/java/org/dbunit/dataset/common/handlers/SeparatorHandler.java +++ b/src/main/java/org/dbunit/dataset/common/handlers/SeparatorHandler.java @@ -24,7 +24,6 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; - /** * {@link PipelineComponent} that matches the CSV field separator character. * @@ -35,6 +34,7 @@ */ public class SeparatorHandler extends AbstractPipelineComponent { + /** The default CSV field separator character. */ public static final char DEFAULT_SEPARATOR_CHAR = ','; /** @@ -42,22 +42,37 @@ public class SeparatorHandler extends AbstractPipelineComponent { */ private static final Logger logger = LoggerFactory.getLogger(SeparatorHandler.class); - private SeparatorHandler() + private SeparatorHandler() { } - + + /** + * Creates a handler that accepts the separator character. + * + * @return the new pipeline component. + */ public static final PipelineComponent ACCEPT () { logger.debug("ACCEPT() - start"); return createPipelineComponent(new SeparatorHandler(), new ACCEPT()); } + /** + * Creates a handler that ignores the separator character. + * + * @return the new pipeline component. + */ public static final PipelineComponent IGNORE () { logger.debug("IGNORE() - start"); return createPipelineComponent(new SeparatorHandler(), new IGNORE()); } + /** + * Creates a handler that ends the current field on the separator character. + * + * @return the new pipeline component. + */ public static final PipelineComponent ENDPIECE () { logger.debug("ENDPIECE() - start"); @@ -75,6 +90,9 @@ public boolean canHandle(char c) throws IllegalInputCharacterException { return false; //throw new IllegalInputCharacterException("Cannot handle character '" + c + "'"); } + /** + * Helper that ends the current field, notifying the pipeline the piece is done. + */ static protected class ENDPIECE extends Helper { /** diff --git a/src/main/java/org/dbunit/dataset/common/handlers/TransparentHandler.java b/src/main/java/org/dbunit/dataset/common/handlers/TransparentHandler.java index fdc14e254..e5927373d 100644 --- a/src/main/java/org/dbunit/dataset/common/handlers/TransparentHandler.java +++ b/src/main/java/org/dbunit/dataset/common/handlers/TransparentHandler.java @@ -42,6 +42,11 @@ public class TransparentHandler extends AbstractPipelineComponent { private TransparentHandler() {} + /** + * Creates a handler that accepts any character without altering the field being assembled. + * + * @return the new pipeline component. + */ public static final PipelineComponent IGNORE () { logger.debug("IGNORE() - start"); diff --git a/src/main/java/org/dbunit/dataset/common/handlers/UnquotedFieldAssembler.java b/src/main/java/org/dbunit/dataset/common/handlers/UnquotedFieldAssembler.java index 8f2820108..8bd7a0747 100644 --- a/src/main/java/org/dbunit/dataset/common/handlers/UnquotedFieldAssembler.java +++ b/src/main/java/org/dbunit/dataset/common/handlers/UnquotedFieldAssembler.java @@ -26,7 +26,6 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; - /** * {@link PipelineComponent} that assembles an unquoted CSV field value from its * constituent characters. @@ -45,6 +44,9 @@ public class UnquotedFieldAssembler extends AbstractPipelineComponent { LinkedList addedComponents; + /** + * Default constructor. + */ public UnquotedFieldAssembler() { setAddedComponents(new LinkedList()); getPipeline().putFront(SeparatorHandler.ENDPIECE()); @@ -71,6 +73,9 @@ public boolean canHandle(char c) throws IllegalInputCharacterException { return true; } + /** + * Helper that notifies the pipeline the current field is done. + */ static protected class ASSEMBLE extends Helper { /** diff --git a/src/main/java/org/dbunit/dataset/common/handlers/WhitespacesHandler.java b/src/main/java/org/dbunit/dataset/common/handlers/WhitespacesHandler.java index cb03878e8..95d98646e 100644 --- a/src/main/java/org/dbunit/dataset/common/handlers/WhitespacesHandler.java +++ b/src/main/java/org/dbunit/dataset/common/handlers/WhitespacesHandler.java @@ -41,12 +41,22 @@ public class WhitespacesHandler extends AbstractPipelineComponent { private WhitespacesHandler() {} + /** + * Creates a handler that ignores whitespace characters. + * + * @return the new pipeline component. + */ public static final PipelineComponent IGNORE () { logger.debug("IGNORE() - start"); return createPipelineComponent(new WhitespacesHandler(), new IGNORE()); } + /** + * Creates a handler that accepts whitespace characters. + * + * @return the new pipeline component. + */ public static final PipelineComponent ACCEPT () { logger.debug("ACCEPT() - start"); diff --git a/src/main/java/org/dbunit/dataset/csv/CsvDataSet.java b/src/main/java/org/dbunit/dataset/csv/CsvDataSet.java index 1a70ac2de..e0477ca16 100644 --- a/src/main/java/org/dbunit/dataset/csv/CsvDataSet.java +++ b/src/main/java/org/dbunit/dataset/csv/CsvDataSet.java @@ -35,10 +35,19 @@ * @since Sep 12, 2004 (pre 2.3) */ public class CsvDataSet extends CachedDataSet { + /** + * Name of the file listing the tables in load order. + */ public static final String TABLE_ORDERING_FILE = "table-ordering.txt"; - + // private File dir; - + + /** + * Creates a dataset from the CSV files in the given directory. + * + * @param dir the directory containing the CSV files. + * @throws DataSetException if reading the CSV files fails. + */ public CsvDataSet(File dir) throws DataSetException { super(new CsvProducer(dir)); // this.dir = dir; diff --git a/src/main/java/org/dbunit/dataset/csv/CsvDataSetWriter.java b/src/main/java/org/dbunit/dataset/csv/CsvDataSetWriter.java index 86687108b..4c4da8f7d 100644 --- a/src/main/java/org/dbunit/dataset/csv/CsvDataSetWriter.java +++ b/src/main/java/org/dbunit/dataset/csv/CsvDataSetWriter.java @@ -74,14 +74,30 @@ public class CsvDataSetWriter implements IDataSetConsumer { /** list of tables */ private List tableList; + /** + * Creates a writer that writes CSV files to the given directory. + * + * @param theDirectory the path of the directory to write CSV files to. + */ public CsvDataSetWriter(String theDirectory) { setTheDirectory(theDirectory); } + /** + * Creates a writer that writes CSV files to the given directory. + * + * @param theDirectory the directory to write CSV files to. + */ public CsvDataSetWriter(File theDirectory) { setTheDirectory(theDirectory.getAbsolutePath()); } + /** + * Writes the given dataset's tables and rows to CSV files. + * + * @param dataSet the dataset to write. + * @throws DataSetException if writing the dataset fails. + */ public void write(IDataSet dataSet) throws DataSetException { logger.debug("write(dataSet={}) - start", dataSet); @@ -226,6 +242,12 @@ private String quote(String stringValue) { return new StringBuilder(QUOTE).append(escape(stringValue)).append(QUOTE).toString(); } + /** + * Escapes quote and backslash characters in the given string by prefixing them with a backslash. + * + * @param stringValue the string to escape. + * @return the escaped string. + */ protected static String escape(String stringValue) { logger.debug("escape(stringValue={}) - start", stringValue); @@ -243,30 +265,53 @@ protected static String escape(String stringValue) { return buffer.toString(); } + /** + * Returns the writer for the currently active table. + * @return the writer for the currently active table. + */ public Writer getWriter() { logger.debug("getWriter() - start"); return writer; } + /** + * Sets the writer for the currently active table. + * @param writer the writer for the currently active table. + */ public void setWriter(Writer writer) { logger.debug("setWriter(writer={}) - start", writer); this.writer = writer; } + /** + * Returns the directory CSV files are written to. + * @return the directory CSV files are written to. + */ public String getTheDirectory() { logger.debug("getTheDirectory() - start"); return theDirectory; } + /** + * Sets the directory CSV files are written to. + * @param theDirectory the directory CSV files are written to. + */ public void setTheDirectory(String theDirectory) { logger.debug("setTheDirectory(theDirectory={}) - start", theDirectory); this.theDirectory = theDirectory; } + /** + * Writes the given dataset's tables and rows as CSV files to the given directory. + * + * @param dataset the dataset to write. + * @param dest the directory to write CSV files to. + * @throws DataSetException if writing the dataset fails. + */ public static void write(IDataSet dataset, File dest) throws DataSetException { logger.debug("write(dataset={}, dest={}) - start", dataset, dest); diff --git a/src/main/java/org/dbunit/dataset/csv/CsvParser.java b/src/main/java/org/dbunit/dataset/csv/CsvParser.java index 237c9bee0..b1ea023f6 100644 --- a/src/main/java/org/dbunit/dataset/csv/CsvParser.java +++ b/src/main/java/org/dbunit/dataset/csv/CsvParser.java @@ -37,7 +37,33 @@ * @since 2.2 (Sep 12, 2004) */ public interface CsvParser { + /** + * Parses the CSV content of the given file. + * + * @param file the file to parse. + * @return the parsed rows, each a list of field values, first row being the column names. + * @throws IOException if the file cannot be read. + * @throws CsvParserException if the CSV content is malformed. + */ List parse(File file) throws IOException, CsvParserException; + + /** + * Parses the CSV content at the given URL. + * + * @param url the URL to parse. + * @return the parsed rows, each a list of field values, first row being the column names. + * @throws IOException if the URL cannot be read. + * @throws CsvParserException if the CSV content is malformed. + */ List parse(URL url) throws IOException, CsvParserException; + + /** + * Parses a single line of CSV text into its individual field values. + * + * @param csv the line of CSV text to parse. + * @return the parsed field values. + * @throws PipelineException if the character-handling pipeline fails. + * @throws IllegalInputCharacterException if the input contains a character no handler accepts. + */ List parse(String csv) throws PipelineException, IllegalInputCharacterException; } diff --git a/src/main/java/org/dbunit/dataset/csv/CsvParserException.java b/src/main/java/org/dbunit/dataset/csv/CsvParserException.java index 01e99e516..5bca65f6e 100644 --- a/src/main/java/org/dbunit/dataset/csv/CsvParserException.java +++ b/src/main/java/org/dbunit/dataset/csv/CsvParserException.java @@ -32,6 +32,11 @@ * @since Sep 12, 2004 (pre 2.3) */ public class CsvParserException extends DatabaseUnitRuntimeException { + /** + * Constructs a CsvParserException with the specified detail message. + * + * @param message the detail message. + */ public CsvParserException(String message) { super(message); } diff --git a/src/main/java/org/dbunit/dataset/csv/CsvParserImpl.java b/src/main/java/org/dbunit/dataset/csv/CsvParserImpl.java index 902d52860..bfb09645d 100644 --- a/src/main/java/org/dbunit/dataset/csv/CsvParserImpl.java +++ b/src/main/java/org/dbunit/dataset/csv/CsvParserImpl.java @@ -64,6 +64,9 @@ public class CsvParserImpl implements CsvParser { private Pipeline pipeline; + /** + * Default constructor. + */ public CsvParserImpl() { resetThePipeline(); } @@ -118,6 +121,15 @@ public List parse(URL url) throws IOException, CsvParserException { } } + /** + * Parses the CSV content read from the given reader. + * + * @param reader the reader to parse. + * @param source a description of the source being read, used in error messages. + * @return the parsed rows, each a list of field values, first row being the column names. + * @throws IOException if the reader cannot be read. + * @throws CsvParserException if the CSV content is malformed. + */ public List parse(Reader reader, String source) throws IOException, CsvParserException { logger.debug("parse(reader={}, source={}) - start", reader, source); diff --git a/src/main/java/org/dbunit/dataset/csv/CsvProducer.java b/src/main/java/org/dbunit/dataset/csv/CsvProducer.java index 4bad7f21d..69ffb475d 100644 --- a/src/main/java/org/dbunit/dataset/csv/CsvProducer.java +++ b/src/main/java/org/dbunit/dataset/csv/CsvProducer.java @@ -63,10 +63,20 @@ public class CsvProducer implements IDataSetProducer { private IDataSetConsumer _consumer = EMPTY_CONSUMER; private String _theDirectory; + /** + * Creates a producer that reads CSV files from the given directory. + * + * @param theDirectory the path of the directory containing the CSV files. + */ public CsvProducer(String theDirectory) { _theDirectory = theDirectory; } + /** + * Creates a producer that reads CSV files from the given directory. + * + * @param theDirectory the directory containing the CSV files. + */ public CsvProducer(File theDirectory) { _theDirectory = theDirectory.getAbsolutePath(); } @@ -150,6 +160,8 @@ private void produceFromFile(File theDataFile) throws DataSetException, CsvParse /** * Get a list of tables that this producer will create + * @param base the base URL the table list file is resolved against. + * @param tableList the name of the file, relative to base, listing the tables in load order. * @return a list of Strings, where each item is a CSV file relative to the base URL * @throws IOException when IO on the base URL has issues. */ diff --git a/src/main/java/org/dbunit/dataset/csv/CsvURLDataSet.java b/src/main/java/org/dbunit/dataset/csv/CsvURLDataSet.java index 50b3669d0..832452654 100644 --- a/src/main/java/org/dbunit/dataset/csv/CsvURLDataSet.java +++ b/src/main/java/org/dbunit/dataset/csv/CsvURLDataSet.java @@ -43,6 +43,9 @@ public class CsvURLDataSet extends CachedDataSet { /** * Create a Data Set from CSV files, using the base URL provided to find data. + * + * @param base the base URL that CSV files and the table ordering file are resolved against. + * @throws DataSetException if reading the CSV files fails. */ public CsvURLDataSet(URL base) throws DataSetException { diff --git a/src/main/java/org/dbunit/dataset/csv/IllegalCharacterSeen.java b/src/main/java/org/dbunit/dataset/csv/IllegalCharacterSeen.java index 6a386befe..261da03f9 100644 --- a/src/main/java/org/dbunit/dataset/csv/IllegalCharacterSeen.java +++ b/src/main/java/org/dbunit/dataset/csv/IllegalCharacterSeen.java @@ -31,6 +31,11 @@ * @since Sep 12, 2004 (pre 2.3) */ public class IllegalCharacterSeen extends CsvParserException { + /** + * Constructs an IllegalCharacterSeen with the specified detail message. + * + * @param message the detail message. + */ public IllegalCharacterSeen(String message) { super(message); } diff --git a/src/main/java/org/dbunit/dataset/datatype/AbstractDataType.java b/src/main/java/org/dbunit/dataset/datatype/AbstractDataType.java index 767a10a24..79091f095 100644 --- a/src/main/java/org/dbunit/dataset/datatype/AbstractDataType.java +++ b/src/main/java/org/dbunit/dataset/datatype/AbstractDataType.java @@ -53,6 +53,14 @@ public abstract class AbstractDataType extends DataType private final Class _classType; private final boolean _isNumber; + /** + * Constructs a data type with the given SQL type mapping. + * + * @param name the data type name. + * @param sqlType the {@link java.sql.Types} constant this data type maps to. + * @param classType the Java class representing this data type's values. + * @param isNumber true if this data type represents a number. + */ public AbstractDataType(final String name, final int sqlType, final Class classType, final boolean isNumber) { @@ -223,12 +231,14 @@ public void setSqlValue(final Object value, final int column, } /** + * Loads the given class using the class loader of the given connection. + * * @param clazz * The fully qualified name of the class to be loaded * @param connection * The JDBC connection needed to load the given class * @return The loaded class - * @throws ClassNotFoundException + * @throws ClassNotFoundException if the class cannot be located by the class loader. */ protected final Class loadClass(final String clazz, final Connection connection) throws ClassNotFoundException @@ -239,12 +249,14 @@ protected final Class loadClass(final String clazz, } /** + * Loads the given class using the given class loader. + * * @param clazz * The fully qualified name of the class to be loaded * @param classLoader * The classLoader to be used to load the given class * @return The loaded class - * @throws ClassNotFoundException + * @throws ClassNotFoundException if the class cannot be located by the class loader. */ protected final Class loadClass(final String clazz, final ClassLoader classLoader) throws ClassNotFoundException diff --git a/src/main/java/org/dbunit/dataset/datatype/BigIntegerDataType.java b/src/main/java/org/dbunit/dataset/datatype/BigIntegerDataType.java index d348d68ab..1b93bef92 100644 --- a/src/main/java/org/dbunit/dataset/datatype/BigIntegerDataType.java +++ b/src/main/java/org/dbunit/dataset/datatype/BigIntegerDataType.java @@ -45,6 +45,9 @@ public class BigIntegerDataType extends AbstractDataType private static final Logger logger = LoggerFactory.getLogger(BigIntegerDataType.class); + /** + * Default constructor. + */ public BigIntegerDataType() { super("BIGINT", Types.BIGINT, BigInteger.class, true); diff --git a/src/main/java/org/dbunit/dataset/datatype/BinaryStreamDataType.java b/src/main/java/org/dbunit/dataset/datatype/BinaryStreamDataType.java index 2b011cfa1..940fc08a5 100644 --- a/src/main/java/org/dbunit/dataset/datatype/BinaryStreamDataType.java +++ b/src/main/java/org/dbunit/dataset/datatype/BinaryStreamDataType.java @@ -44,6 +44,12 @@ public class BinaryStreamDataType extends BytesDataType private static final Logger logger = LoggerFactory.getLogger(BinaryStreamDataType.class); + /** + * Constructs a data type with the given SQL type mapping. + * + * @param name the data type name. + * @param sqlType the {@link java.sql.Types} constant this data type maps to. + */ public BinaryStreamDataType(final String name, final int sqlType) { super(name, sqlType); diff --git a/src/main/java/org/dbunit/dataset/datatype/BlobDataType.java b/src/main/java/org/dbunit/dataset/datatype/BlobDataType.java index 7f4493a22..86c5a4f80 100644 --- a/src/main/java/org/dbunit/dataset/datatype/BlobDataType.java +++ b/src/main/java/org/dbunit/dataset/datatype/BlobDataType.java @@ -42,11 +42,20 @@ public class BlobDataType extends BytesDataType private static final Logger logger = LoggerFactory.getLogger(BlobDataType.class); + /** + * Default constructor. + */ public BlobDataType() { super("BLOB", Types.BLOB); } + /** + * Constructs a data type with the given SQL type mapping. + * + * @param name the data type name. + * @param sqlType the {@link java.sql.Types} constant this data type maps to. + */ public BlobDataType(final String name, final int sqlType) { super(name, sqlType); diff --git a/src/main/java/org/dbunit/dataset/datatype/BytesDataType.java b/src/main/java/org/dbunit/dataset/datatype/BytesDataType.java index b420759f9..0609d93b7 100644 --- a/src/main/java/org/dbunit/dataset/datatype/BytesDataType.java +++ b/src/main/java/org/dbunit/dataset/datatype/BytesDataType.java @@ -61,6 +61,12 @@ public class BytesDataType extends AbstractDataType private static final Pattern inputPattern = Pattern.compile("^\\[(.*?)](.*)"); + /** + * Constructs a data type with the given SQL type mapping. + * + * @param name the data type name. + * @param sqlType the {@link java.sql.Types} constant this data type maps to. + */ public BytesDataType(final String name, final int sqlType) { super(name, sqlType, byte[].class, false); @@ -101,6 +107,13 @@ private byte[] toByteArray(final InputStream in, final int length) return out.toByteArray(); } + /** + * Reads the entire contents of the given file into a byte array. + * + * @param filename the path of the file to read. + * @return the file's contents. + * @throws IOException if the file cannot be read. + */ public byte[] loadFile(final String filename) throws IOException { // Not an URL, try as file name @@ -108,6 +121,13 @@ public byte[] loadFile(final String filename) throws IOException return toByteArray(new FileInputStream(file), (int) file.length()); } + /** + * Reads the entire contents at the given URL into a byte array. + * + * @param urlAsString the URL to read from. + * @return the URL content. + * @throws IOException if the URL cannot be read. + */ public byte[] loadURL(final String urlAsString) throws IOException { // Not an URL, try as file name @@ -354,6 +374,15 @@ protected int compareNonNulls(final Object value1, final Object value2) } } + /** + * Lexicographically compares two byte arrays. + * + * @param v1 the first byte array. + * @param v2 the second byte array. + * @return a negative, zero, or positive value if v1 is less than, equal to, or greater + * than v2, respectively. + * @throws TypeCastException never thrown by this implementation. + */ public int compare(final byte[] v1, final byte[] v2) throws TypeCastException { diff --git a/src/main/java/org/dbunit/dataset/datatype/ClobDataType.java b/src/main/java/org/dbunit/dataset/datatype/ClobDataType.java index a8624a967..5ce933ff5 100644 --- a/src/main/java/org/dbunit/dataset/datatype/ClobDataType.java +++ b/src/main/java/org/dbunit/dataset/datatype/ClobDataType.java @@ -44,6 +44,9 @@ public class ClobDataType extends StringDataType private static final Logger logger = LoggerFactory.getLogger(ClobDataType.class); + /** + * Default constructor. + */ public ClobDataType() { super("CLOB", Types.CLOB); diff --git a/src/main/java/org/dbunit/dataset/datatype/DataType.java b/src/main/java/org/dbunit/dataset/datatype/DataType.java index d3887d70e..a019a3fac 100644 --- a/src/main/java/org/dbunit/dataset/datatype/DataType.java +++ b/src/main/java/org/dbunit/dataset/datatype/DataType.java @@ -50,31 +50,44 @@ public abstract class DataType private static final Logger logger = LoggerFactory.getLogger(DataType.class); + /** The unrecognized/unmapped data type. */ public static final DataType UNKNOWN = new UnknownDataType(); + /** Maps the SQL CHAR type. */ public static final DataType CHAR = new StringDataType("CHAR", Types.CHAR); + /** Maps the SQL VARCHAR type. */ public static final DataType VARCHAR = new StringDataType("VARCHAR", Types.VARCHAR); + /** Maps the SQL LONGVARCHAR type. */ public static final DataType LONGVARCHAR = new StringDataType("LONGVARCHAR", Types.LONGVARCHAR); + /** Maps the SQL CLOB type. */ public static final DataType CLOB = new ClobDataType(); + /** Maps the SQL NUMERIC type. */ public static final DataType NUMERIC = new NumberDataType("NUMERIC", Types.NUMERIC); + /** Maps the SQL DECIMAL type. */ public static final DataType DECIMAL = new NumberDataType("DECIMAL", Types.DECIMAL); + /** Maps the SQL BOOLEAN type. */ public static final DataType BOOLEAN = new BooleanDataType(); + /** Maps the SQL BIT type. */ public static final DataType BIT = new BitDataType(); + /** Maps the SQL TINYINT type. */ public static final DataType TINYINT = new IntegerDataType("TINYINT", Types.TINYINT); + /** Maps the SQL SMALLINT type. */ public static final DataType SMALLINT = new IntegerDataType("SMALLINT", Types.SMALLINT); + /** Maps the SQL INTEGER type. */ public static final DataType INTEGER = new IntegerDataType("INTEGER", Types.INTEGER); // public static final DataType BIGINT = new LongDataType(); + /** Maps the SQL BIGINT type. */ public static final DataType BIGINT = new BigIntegerDataType(); /** * Auxiliary for the BIGINT type using a long. Is currently only needed for @@ -82,35 +95,49 @@ public abstract class DataType */ public static final DataType BIGINT_AUX_LONG = new LongDataType(); + /** Maps the SQL REAL type. */ public static final DataType REAL = new FloatDataType(); + /** Maps the SQL FLOAT type. */ public static final DataType FLOAT = new DoubleDataType("FLOAT", Types.FLOAT); + /** Maps the SQL DOUBLE type. */ public static final DataType DOUBLE = new DoubleDataType("DOUBLE", Types.DOUBLE); // To calculate consistent relative date and time. + /** Parser used to calculate consistent relative date and time values. */ public static final RelativeDateTimeParser RELATIVE_DATE_TIME_PARSER = new RelativeDateTimeParser(); + /** Maps the SQL DATE type. */ public static final DataType DATE = new DateDataType(); + /** Maps the SQL TIME type. */ public static final DataType TIME = new TimeDataType(); + /** Maps the SQL TIMESTAMP type. */ public static final DataType TIMESTAMP = new TimestampDataType(); + /** Maps the SQL BINARY type. */ public static final DataType BINARY = new UuidAwareBytesDataType("BINARY", Types.BINARY); + /** Maps the SQL VARBINARY type. */ public static final DataType VARBINARY = new UuidAwareBytesDataType("VARBINARY", Types.VARBINARY); + /** Maps the SQL LONGVARBINARY type. */ public static final DataType LONGVARBINARY = new UuidAwareBytesDataType("LONGVARBINARY", Types.LONGVARBINARY); + /** Maps the SQL BLOB type. */ public static final DataType BLOB = new BlobDataType(); // New JDBC 4.0 types: // todo: ROWID = -8, NCLOB = 2011, SQLXML = 2009. + /** Maps the SQL NCHAR type. */ public static final DataType NCHAR = new StringDataType("NCHAR", -15); + /** Maps the SQL NVARCHAR type. */ public static final DataType NVARCHAR = new StringDataType("NVARCHAR", -9); + /** Maps the SQL LONGNVARCHAR type. */ public static final DataType LONGNVARCHAR = new StringDataType("LONGNVARCHAR", -16); diff --git a/src/main/java/org/dbunit/dataset/datatype/DataTypeException.java b/src/main/java/org/dbunit/dataset/datatype/DataTypeException.java index 3ed124ea1..6577f11c6 100644 --- a/src/main/java/org/dbunit/dataset/datatype/DataTypeException.java +++ b/src/main/java/org/dbunit/dataset/datatype/DataTypeException.java @@ -33,21 +33,42 @@ public class DataTypeException extends DataSetException { + /** + * Constructs a DataTypeException with no detail message and no encapsulated + * exception. + */ public DataTypeException() { super(); } + /** + * Constructs a DataTypeException with the specified detail message. + * + * @param msg the detail message. + */ public DataTypeException(String msg) { super(msg); } + /** + * Constructs a DataTypeException with the encapsulated exception. + * + * @param e the encapsulated exception. + */ public DataTypeException(Throwable e) { super(e); } + /** + * Constructs a DataTypeException with the specified detail message and + * encapsulated exception. + * + * @param msg the detail message. + * @param e the encapsulated exception. + */ public DataTypeException(String msg, Throwable e) { super(msg, e); diff --git a/src/main/java/org/dbunit/dataset/datatype/DefaultDataTypeFactory.java b/src/main/java/org/dbunit/dataset/datatype/DefaultDataTypeFactory.java index 3e7c6a765..f7a17abf0 100644 --- a/src/main/java/org/dbunit/dataset/datatype/DefaultDataTypeFactory.java +++ b/src/main/java/org/dbunit/dataset/datatype/DefaultDataTypeFactory.java @@ -131,6 +131,8 @@ public DataType createDataType(int sqlType, String sqlTypeName, } /** + * Returns the tolerated delta objects configured on this factory. + * * @return The whole map of tolerated delta objects that have been set until * now * @since 2.3.0 diff --git a/src/main/java/org/dbunit/dataset/datatype/IDataTypeFactory.java b/src/main/java/org/dbunit/dataset/datatype/IDataTypeFactory.java index f472aed23..bea3b1110 100644 --- a/src/main/java/org/dbunit/dataset/datatype/IDataTypeFactory.java +++ b/src/main/java/org/dbunit/dataset/datatype/IDataTypeFactory.java @@ -37,6 +37,8 @@ public interface IDataTypeFactory * SQL type from {@link java.sql.Types} * @param sqlTypeName * Data source dependent type name + * @return the {@link DataType} corresponding to the given SQL type. + * @throws DataTypeException if the corresponding {@link DataType} cannot be determined. */ public DataType createDataType(int sqlType, String sqlTypeName) throws DataTypeException; @@ -59,7 +61,9 @@ public DataType createDataType(int sqlType, String sqlTypeName) * @param columnName * The database column in the given table for which the type is * created - * + * @return the {@link DataType} corresponding to the given SQL type, honoring any configured + * tolerance for the given table/column. + * @throws DataTypeException if the corresponding {@link DataType} cannot be determined. * @since 2.3.0 */ public DataType createDataType(int sqlType, String sqlTypeName, diff --git a/src/main/java/org/dbunit/dataset/datatype/NumberTolerantDataType.java b/src/main/java/org/dbunit/dataset/datatype/NumberTolerantDataType.java index f941cdec3..a7b1c9f7c 100644 --- a/src/main/java/org/dbunit/dataset/datatype/NumberTolerantDataType.java +++ b/src/main/java/org/dbunit/dataset/datatype/NumberTolerantDataType.java @@ -56,8 +56,8 @@ public class NumberTolerantDataType extends NumberDataType /** * Creates a new number tolerant datatype * - * @param name - * @param sqlType + * @param name the data type name. + * @param sqlType the SQL type code. * @param delta * The tolerated delta to be used for the comparison */ @@ -73,6 +73,11 @@ public class NumberTolerantDataType extends NumberDataType this.toleratedDelta = delta; } + /** + * Returns the tolerated delta used for the comparison. + * + * @return the tolerated delta used for the comparison. + */ public Precision getToleratedDelta() { return toleratedDelta; @@ -168,8 +173,8 @@ protected int compareNonNulls(Object value1cast, Object value2cast) /** * Checks if the given value is zero. - * - * @param value + * + * @param value the value to check. * @return true if and only if the given value is zero. */ public static final boolean isZero(BigDecimal value) diff --git a/src/main/java/org/dbunit/dataset/datatype/StringDataType.java b/src/main/java/org/dbunit/dataset/datatype/StringDataType.java index de379df80..01b6485f5 100644 --- a/src/main/java/org/dbunit/dataset/datatype/StringDataType.java +++ b/src/main/java/org/dbunit/dataset/datatype/StringDataType.java @@ -45,6 +45,12 @@ public class StringDataType extends AbstractDataType private static final Logger logger = LoggerFactory.getLogger(StringDataType.class); + /** + * Creates a new StringDataType. + * + * @param name the data type name. + * @param sqlType the SQL type code. + */ public StringDataType(final String name, final int sqlType) { super(name, sqlType, String.class, false); diff --git a/src/main/java/org/dbunit/dataset/datatype/StringIgnoreCaseDataType.java b/src/main/java/org/dbunit/dataset/datatype/StringIgnoreCaseDataType.java index 047de550f..db60fc09c 100644 --- a/src/main/java/org/dbunit/dataset/datatype/StringIgnoreCaseDataType.java +++ b/src/main/java/org/dbunit/dataset/datatype/StringIgnoreCaseDataType.java @@ -39,6 +39,12 @@ public class StringIgnoreCaseDataType extends StringDataType private static final Logger logger = LoggerFactory.getLogger(StringIgnoreCaseDataType.class); + /** + * Creates a new StringIgnoreCaseDataType. + * + * @param name the data type name. + * @param sqlType the SQL type code. + */ public StringIgnoreCaseDataType(String name, int sqlType) { super(name, sqlType); diff --git a/src/main/java/org/dbunit/dataset/datatype/ToleratedDeltaMap.java b/src/main/java/org/dbunit/dataset/datatype/ToleratedDeltaMap.java index d75d31803..9a4d606c0 100644 --- a/src/main/java/org/dbunit/dataset/datatype/ToleratedDeltaMap.java +++ b/src/main/java/org/dbunit/dataset/datatype/ToleratedDeltaMap.java @@ -50,9 +50,9 @@ public class ToleratedDeltaMap /** * Lookup a tolerated delta object by tableName and ColumnName. - * - * @param tableName - * @param columnName + * + * @param tableName the name of the table. + * @param columnName the name of the column. * @return The object from the map or null if no such object * was found */ @@ -75,6 +75,11 @@ private final Map getToleratedDeltasNullSafe() return res; } + /** + * Returns the map of tolerated deltas. + * + * @return the map of tolerated deltas. + */ public Map getToleratedDeltas() { return _toleratedDeltas; @@ -148,6 +153,8 @@ public static class ToleratedDelta private Precision toleratedDelta; /** + * Creates a tolerated delta for the given table/column, expressed as a double. + * * @param tableName * The name of the table * @param columnName @@ -166,6 +173,8 @@ public ToleratedDelta(String tableName, String columnName, } /** + * Creates a tolerated delta for the given table/column, expressed as a BigDecimal. + * * @param tableName * The name of the table * @param columnName @@ -183,6 +192,8 @@ public ToleratedDelta(String tableName, String columnName, } /** + * Creates a tolerated delta for the given table/column, optionally as a percentage. + * * @param tableName * The name of the table * @param columnName @@ -204,6 +215,8 @@ public ToleratedDelta(String tableName, String columnName, } /** + * Creates a tolerated delta for the given table/column. + * * @param tableName * The name of the table * @param columnName @@ -223,16 +236,31 @@ public ToleratedDelta(String tableName, String columnName, this.toleratedDelta = toleratedDelta; } + /** + * Returns the name of the table. + * + * @return the name of the table. + */ public String getTableName() { return tableName; } + /** + * Returns the name of the column. + * + * @return the name of the column. + */ public String getColumnName() { return columnName; } + /** + * Returns the tolerated delta. + * + * @return the tolerated delta. + */ public Precision getToleratedDelta() { return toleratedDelta; @@ -241,9 +269,9 @@ public Precision getToleratedDelta() /** * Checks whether or not the tableName and the * columnName match the ones of this object. - * - * @param tableName - * @param columnName + * + * @param tableName the table name to check. + * @param columnName the column name to check. * @return true if both given values match those of this * object. */ @@ -286,6 +314,8 @@ public static class Precision private final BigDecimal delta; /** + * Creates a non-percentage precision with the given tolerated delta. + * * @param delta * The allowed/tolerated difference */ @@ -295,6 +325,8 @@ public Precision(BigDecimal delta) } /** + * Creates a precision with the given tolerated delta. + * * @param delta * The allowed/tolerated difference * @param percentage @@ -315,11 +347,21 @@ public Precision(BigDecimal delta, boolean percentage) this.percentage = percentage; } + /** + * Returns whether the delta is interpreted as a percentage. + * + * @return whether the delta is interpreted as a percentage. + */ public boolean isPercentage() { return percentage; } + /** + * Returns the allowed/tolerated difference. + * + * @return the allowed/tolerated difference. + */ public BigDecimal getDelta() { return delta; diff --git a/src/main/java/org/dbunit/dataset/datatype/TypeCastException.java b/src/main/java/org/dbunit/dataset/datatype/TypeCastException.java index 44bbdeb91..f88346c4b 100644 --- a/src/main/java/org/dbunit/dataset/datatype/TypeCastException.java +++ b/src/main/java/org/dbunit/dataset/datatype/TypeCastException.java @@ -39,21 +39,45 @@ public class TypeCastException extends DataTypeException // super(msg); // } + /** + * Constructs a TypeCastException with the specified cause. + * + * @param e the cause. + */ public TypeCastException(Throwable e) { super(e); } + /** + * Constructs a TypeCastException with the specified detail message and cause. + * + * @param msg the detail message. + * @param e the cause. + */ public TypeCastException(String msg, Throwable e) { super(msg, e); } + /** + * Constructs a TypeCastException for the given value and target data type. + * + * @param value the value that could not be cast. + * @param dataType the target data type. + */ public TypeCastException(Object value, DataType dataType) { super(buildMessage(value, dataType)); } + /** + * Constructs a TypeCastException for the given value and target data type, with a cause. + * + * @param value the value that could not be cast. + * @param dataType the target data type. + * @param e the cause. + */ public TypeCastException(Object value, DataType dataType, Throwable e) { super(buildMessage(value, dataType), e); diff --git a/src/main/java/org/dbunit/dataset/excel/XlsDataSet.java b/src/main/java/org/dbunit/dataset/excel/XlsDataSet.java index 05c13f041..09e4f3428 100644 --- a/src/main/java/org/dbunit/dataset/excel/XlsDataSet.java +++ b/src/main/java/org/dbunit/dataset/excel/XlsDataSet.java @@ -62,6 +62,10 @@ public class XlsDataSet extends AbstractDataSet /** * Creates a new XlsDataSet object that loads the specified Excel document. + * + * @param file the Excel document to load. + * @throws IOException if the file cannot be read. + * @throws DataSetException if the document cannot be parsed. */ public XlsDataSet(File file) throws IOException, DataSetException { @@ -76,6 +80,10 @@ public XlsDataSet(File file) throws IOException, DataSetException /** * Creates a new XlsDataSet object that loads the specified Excel document. + * + * @param in the Excel document to load. + * @throws IOException if the stream cannot be read. + * @throws DataSetException if the document cannot be parsed. */ public XlsDataSet(InputStream in) throws IOException, DataSetException { @@ -108,6 +116,11 @@ private void loadSheets(Workbook workbook) throws DataSetException /** * Write the specified dataset to the specified Excel document. + * + * @param dataSet the dataset to write. + * @param out the stream to write the Excel document to. + * @throws IOException if writing to the stream fails. + * @throws DataSetException if the dataset cannot be read. */ public static void write(IDataSet dataSet, OutputStream out) throws IOException, DataSetException diff --git a/src/main/java/org/dbunit/dataset/excel/XlsDataSetWriter.java b/src/main/java/org/dbunit/dataset/excel/XlsDataSetWriter.java index 48202f83b..51040f717 100644 --- a/src/main/java/org/dbunit/dataset/excel/XlsDataSetWriter.java +++ b/src/main/java/org/dbunit/dataset/excel/XlsDataSetWriter.java @@ -55,7 +55,7 @@ * @version $Revision$ $Date$ * @since 2.4.0 */ -public class XlsDataSetWriter +public class XlsDataSetWriter { private static final Logger logger = LoggerFactory.getLogger(XlsDataSetWriter.class); @@ -101,6 +101,11 @@ public class XlsDataSetWriter /** * Write the specified dataset to the specified Excel document. + * + * @param dataSet the dataset to write. + * @param out the stream to write the Excel document to. + * @throws IOException if writing to the stream fails. + * @throws DataSetException if the dataset cannot be read. */ public void write(IDataSet dataSet, OutputStream out) throws IOException, DataSetException @@ -187,12 +192,25 @@ else if(value instanceof Long){ } } + /** + * Returns the cell style used to render {@link Date} values stored as numbers. + * + * @param workbook the workbook to create the style in. + * @return the cell style used to render {@link Date} values stored as numbers. + */ protected static CellStyle createDateCellStyle(Workbook workbook) { DataFormat format = workbook.createDataFormat(); short dateFormatCode = format.getFormat(DATE_FORMAT_AS_NUMBER_DBUNIT); return getCellStyle(workbook, dateFormatCode); } + /** + * Returns the cell style for the given format code, creating and caching one if absent. + * + * @param workbook the workbook to find or create the style in. + * @param formatCode the data format code the style must have. + * @return the cell style for the given format code. + */ protected static CellStyle getCellStyle(Workbook workbook, short formatCode) { Map map = findWorkbookCellStyleMap(workbook); @@ -201,12 +219,27 @@ protected static CellStyle getCellStyle(Workbook workbook, short formatCode) return cellStyle; } + /** + * Returns the cell style cache for the given workbook, creating one if absent. + * + * @param workbook the workbook to find or create the cell style cache for. + * @return the cell style cache for the given workbook. + */ protected static Map findWorkbookCellStyleMap( Workbook workbook) { return cellStyleMap.computeIfAbsent(workbook, k -> new HashMap()); } + /** + * Returns the cell style for the given format code from the given cache, creating and + * caching one if absent. + * + * @param workbook the workbook to create a new style in, if needed. + * @param formatCode the data format code the style must have. + * @param map the cell style cache to look up and populate. + * @return the cell style for the given format code. + */ protected static CellStyle findCellStyle(Workbook workbook, Short formatCode, Map map) { @@ -221,7 +254,14 @@ protected static CellStyle findCellStyle(Workbook workbook, return cellStyle; } - protected void setDateCell(Cell cell, Date value, Workbook workbook) + /** + * Sets the given cell to the given date value, stored as a number. + * + * @param cell the cell to set. + * @param value the date value to set. + * @param workbook the workbook the cell belongs to. + */ + protected void setDateCell(Cell cell, Date value, Workbook workbook) { // double excelDateValue = HSSFDateUtil.getExcelDate(value); // cell.setCellValue(excelDateValue); @@ -283,6 +323,13 @@ protected void setDateCell(Cell cell, Date value, Workbook workbook) } + /** + * Sets the given cell to the given numeric value, preserving its scale. + * + * @param cell the cell to set. + * @param value the numeric value to set. + * @param workbook the workbook the cell belongs to. + */ protected void setNumericCell(Cell cell, BigDecimal value, Workbook workbook) { if(logger.isDebugEnabled()) @@ -346,6 +393,11 @@ private static String createZeros(int count) { return new String(zeros); } + /** + * Creates the workbook written to by {@link #write(IDataSet, OutputStream)}. + * + * @return the new workbook. + */ protected Workbook createWorkbook() { return new HSSFWorkbook(); } diff --git a/src/main/java/org/dbunit/dataset/filter/AbstractTableFilter.java b/src/main/java/org/dbunit/dataset/filter/AbstractTableFilter.java index 3f219b55b..7e051e9c6 100644 --- a/src/main/java/org/dbunit/dataset/filter/AbstractTableFilter.java +++ b/src/main/java/org/dbunit/dataset/filter/AbstractTableFilter.java @@ -53,6 +53,10 @@ public abstract class AbstractTableFilter implements ITableFilter * Returns true if specified table is allowed by this filter. * This legacy method, now replaced by accept, still exist for compatibily * with older environment + * + * @param tableName the name of the table to check. + * @return true if specified table is allowed by this filter. + * @throws DataSetException if the check fails. */ public abstract boolean isValidName(String tableName) throws DataSetException; diff --git a/src/main/java/org/dbunit/dataset/filter/DefaultColumnFilter.java b/src/main/java/org/dbunit/dataset/filter/DefaultColumnFilter.java index 121b623dc..92444fc9d 100644 --- a/src/main/java/org/dbunit/dataset/filter/DefaultColumnFilter.java +++ b/src/main/java/org/dbunit/dataset/filter/DefaultColumnFilter.java @@ -62,6 +62,7 @@ public void includeColumn(String columnPattern) /** * Add specified columns to accepted column name list. + * @param columns the columns to accept. */ public void includeColumns(Column[] columns) { @@ -78,6 +79,7 @@ public void includeColumns(Column[] columns) * The following wildcard characters are supported: * '*' matches zero or more characters, * '?' matches one character. + * @param columnPattern The column pattern to be refused. */ public void excludeColumn(String columnPattern) { @@ -88,6 +90,7 @@ public void excludeColumn(String columnPattern) /** * Add specified columns to excluded column name list. + * @param columns the columns to exclude. */ public void excludeColumns(Column[] columns) { @@ -102,6 +105,10 @@ public void excludeColumns(Column[] columns) /** * Returns a table backed by the specified table that only exposes specified * columns. + * @param table the table to filter. + * @param columnNames the names of the columns to expose. + * @return the filtered table. + * @throws DataSetException if the filtered metadata cannot be built. */ public static ITable includedColumnsTable(ITable table, String[] columnNames) throws DataSetException @@ -121,6 +128,10 @@ public static ITable includedColumnsTable(ITable table, String[] columnNames) /** * Returns a table backed by the specified table that only exposes specified * columns. + * @param table the table to filter. + * @param columns the columns to expose. + * @return the filtered table. + * @throws DataSetException if the filtered metadata cannot be built. */ public static ITable includedColumnsTable(ITable table, Column[] columns) throws DataSetException @@ -136,6 +147,10 @@ public static ITable includedColumnsTable(ITable table, Column[] columns) /** * Returns a table backed by the specified table but with specified * columns excluded. + * @param table the table to filter. + * @param columnNames the names of the columns to exclude. + * @return the filtered table. + * @throws DataSetException if the filtered metadata cannot be built. */ public static ITable excludedColumnsTable(ITable table, String[] columnNames) throws DataSetException @@ -155,6 +170,10 @@ public static ITable excludedColumnsTable(ITable table, String[] columnNames) /** * Returns a table backed by the specified table but with specified * columns excluded. + * @param table the table to filter. + * @param columns the columns to exclude. + * @return the filtered table. + * @throws DataSetException if the filtered metadata cannot be built. */ public static ITable excludedColumnsTable(ITable table, Column[] columns) throws DataSetException @@ -182,7 +201,6 @@ public boolean accept(String tableName, Column column) return false; } - public String toString() { final StringBuilder sb = new StringBuilder(); diff --git a/src/main/java/org/dbunit/dataset/filter/DefaultTableFilter.java b/src/main/java/org/dbunit/dataset/filter/DefaultTableFilter.java index a76ce7725..b001afed9 100644 --- a/src/main/java/org/dbunit/dataset/filter/DefaultTableFilter.java +++ b/src/main/java/org/dbunit/dataset/filter/DefaultTableFilter.java @@ -50,6 +50,7 @@ public class DefaultTableFilter extends AbstractTableFilter implements ITableFil * The following wildcard characters are supported: * '*' matches zero or more characters, * '?' matches one character. + * @param patternName the table name pattern to accept. */ public void includeTable(String patternName) { @@ -63,6 +64,7 @@ public void includeTable(String patternName) * The following wildcard characters are supported: * '*' matches zero or more characters, * '?' matches one character. + * @param patternName the table name pattern to refuse. */ public void excludeTable(String patternName) { diff --git a/src/main/java/org/dbunit/dataset/filter/ExcludeTableFilter.java b/src/main/java/org/dbunit/dataset/filter/ExcludeTableFilter.java index f780bbf1a..41ca446e8 100644 --- a/src/main/java/org/dbunit/dataset/filter/ExcludeTableFilter.java +++ b/src/main/java/org/dbunit/dataset/filter/ExcludeTableFilter.java @@ -55,6 +55,7 @@ public ExcludeTableFilter() /** * Create a new ExcludeTableFilter which prevent access to specified tables. + * @param tableNames the names of the tables to hide. */ public ExcludeTableFilter(String[] tableNames) { @@ -70,6 +71,7 @@ public ExcludeTableFilter(String[] tableNames) * The following wildcard characters are supported: * '*' matches zero or more characters, * '?' matches one character. + * @param patternName the table name pattern to hide. */ public void excludeTable(String patternName) { @@ -78,6 +80,10 @@ public void excludeTable(String patternName) _patternMatcher.addPattern(patternName); } + /** + * Returns whether no tables have been excluded yet. + * @return true if no tables have been excluded yet. + */ public boolean isEmpty() { logger.debug("isEmpty() - start"); diff --git a/src/main/java/org/dbunit/dataset/filter/GeneratedColumnFilter.java b/src/main/java/org/dbunit/dataset/filter/GeneratedColumnFilter.java index 43c7d3fec..f16c2f61e 100644 --- a/src/main/java/org/dbunit/dataset/filter/GeneratedColumnFilter.java +++ b/src/main/java/org/dbunit/dataset/filter/GeneratedColumnFilter.java @@ -31,6 +31,7 @@ */ public class GeneratedColumnFilter implements IColumnFilter { + @Override public boolean accept(final String tableName, final Column column) { diff --git a/src/main/java/org/dbunit/dataset/filter/ITableFilter.java b/src/main/java/org/dbunit/dataset/filter/ITableFilter.java index dead21550..b6dff6445 100644 --- a/src/main/java/org/dbunit/dataset/filter/ITableFilter.java +++ b/src/main/java/org/dbunit/dataset/filter/ITableFilter.java @@ -39,6 +39,8 @@ public interface ITableFilter extends ITableFilterSimple * Returns the table names allowed by this filter from the specified dataset. * * @param dataSet the filtered dataset + * @return the table names allowed by this filter. + * @throws DataSetException if retrieving the table names fails. */ public String[] getTableNames(IDataSet dataSet) throws DataSetException; @@ -46,6 +48,9 @@ public interface ITableFilter extends ITableFilterSimple * Returns iterator of tables allowed by this filter from the specified dataset. * * @param dataSet the filtered dataset + * @param reversed true to iterate in reverse order. + * @return the iterator of tables allowed by this filter. + * @throws DataSetException if creating the iterator fails. */ public ITableIterator iterator(IDataSet dataSet, boolean reversed) throws DataSetException; diff --git a/src/main/java/org/dbunit/dataset/filter/ITableFilterSimple.java b/src/main/java/org/dbunit/dataset/filter/ITableFilterSimple.java index df881f062..3acb654e3 100644 --- a/src/main/java/org/dbunit/dataset/filter/ITableFilterSimple.java +++ b/src/main/java/org/dbunit/dataset/filter/ITableFilterSimple.java @@ -34,6 +34,10 @@ public interface ITableFilterSimple { /** * Returns true if specified table is allowed by this filter. + * + * @param tableName the name of the table to check. + * @return true if specified table is allowed by this filter. + * @throws DataSetException if the check fails. */ public boolean accept(String tableName) throws DataSetException; diff --git a/src/main/java/org/dbunit/dataset/filter/IncludeTableFilter.java b/src/main/java/org/dbunit/dataset/filter/IncludeTableFilter.java index c6fc40d0a..c8b158bfc 100644 --- a/src/main/java/org/dbunit/dataset/filter/IncludeTableFilter.java +++ b/src/main/java/org/dbunit/dataset/filter/IncludeTableFilter.java @@ -53,6 +53,7 @@ public IncludeTableFilter() /** * Create a new IncludeTableFilter which allow access to specified tables. + * @param tableNames the names of the tables to allow. */ public IncludeTableFilter(String[] tableNames) { @@ -68,6 +69,7 @@ public IncludeTableFilter(String[] tableNames) * The following wildcard characters are supported: * '*' matches zero or more characters, * '?' matches one character. + * @param patternName the table name pattern to allow. */ public void includeTable(String patternName) { @@ -76,6 +78,10 @@ public void includeTable(String patternName) _patternMatcher.addPattern(patternName); } + /** + * Returns whether no tables have been included yet. + * @return true if no tables have been included yet. + */ public boolean isEmpty() { logger.debug("isEmpty() - start"); diff --git a/src/main/java/org/dbunit/dataset/filter/SequenceTableFilter.java b/src/main/java/org/dbunit/dataset/filter/SequenceTableFilter.java index f7006f605..e61acf560 100644 --- a/src/main/java/org/dbunit/dataset/filter/SequenceTableFilter.java +++ b/src/main/java/org/dbunit/dataset/filter/SequenceTableFilter.java @@ -58,9 +58,10 @@ public class SequenceTableFilter implements ITableFilter /** * Creates a new SequenceTableFilter with specified table names sequence. + * @param tableNames the table names, in the sequence they should be exposed. * @throws AmbiguousTableNameException If the given array contains ambiguous names */ - public SequenceTableFilter(String[] tableNames) + public SequenceTableFilter(String[] tableNames) throws AmbiguousTableNameException { this(tableNames, false); @@ -68,8 +69,8 @@ public SequenceTableFilter(String[] tableNames) /** * Creates a new SequenceTableFilter with specified table names sequence. - * @param tableNames - * @param caseSensitiveTableNames + * @param tableNames the table names, in the sequence they should be exposed. + * @param caseSensitiveTableNames whether table names are handled in a case sensitive way. * @throws AmbiguousTableNameException If the given array contains ambiguous names * @since 2.4.2 */ diff --git a/src/main/java/org/dbunit/dataset/filter/SequenceTableIterator.java b/src/main/java/org/dbunit/dataset/filter/SequenceTableIterator.java index c8e0c2cda..0ca9f2f79 100644 --- a/src/main/java/org/dbunit/dataset/filter/SequenceTableIterator.java +++ b/src/main/java/org/dbunit/dataset/filter/SequenceTableIterator.java @@ -49,6 +49,12 @@ public class SequenceTableIterator implements ITableIterator private final IDataSet _dataSet; private int _index = -1; + /** + * Creates an iterator that returns the given dataset's tables in the given name order. + * + * @param tableNames the table names, in the order they should be returned. + * @param dataSet the dataset providing the tables. + */ public SequenceTableIterator(String[] tableNames, IDataSet dataSet) { _tableNames = tableNames; diff --git a/src/main/java/org/dbunit/dataset/sqlloader/SqlLoaderControlParser.java b/src/main/java/org/dbunit/dataset/sqlloader/SqlLoaderControlParser.java index 60d89187c..6b6eb7481 100644 --- a/src/main/java/org/dbunit/dataset/sqlloader/SqlLoaderControlParser.java +++ b/src/main/java/org/dbunit/dataset/sqlloader/SqlLoaderControlParser.java @@ -40,36 +40,41 @@ public interface SqlLoaderControlParser { /** * Parse. - * + * * @param file the file * @return the list - * - * @throws IOException - * @throws SqlLoaderControlParserException + * + * @throws IOException if the file cannot be read. + * @throws SqlLoaderControlParserException if the control file is malformed. */ List parse(File file) throws IOException, SqlLoaderControlParserException; /** * Parse. - * + * * @param url the URL * @return the list - * - * @throws IOException - * @throws SqlLoaderControlParserException + * + * @throws IOException if the URL cannot be read. + * @throws SqlLoaderControlParserException if the control file is malformed. */ List parse(URL url) throws IOException, SqlLoaderControlParserException; /** * Parse. - * + * * @param csv the CSV data * @return the list - * - * @throws IllegalInputCharacterException - * @throws PipelineException + * + * @throws IllegalInputCharacterException if the CSV data contains an unexpected character. + * @throws PipelineException if the CSV data cannot be parsed. */ List parse(String csv) throws PipelineException, IllegalInputCharacterException; + /** + * Returns the name of the table parsed from the control file. + * + * @return the name of the table parsed from the control file. + */ String getTableName(); } diff --git a/src/main/java/org/dbunit/dataset/sqlloader/SqlLoaderControlParserImpl.java b/src/main/java/org/dbunit/dataset/sqlloader/SqlLoaderControlParserImpl.java index 5a4c2c0fd..997559072 100644 --- a/src/main/java/org/dbunit/dataset/sqlloader/SqlLoaderControlParserImpl.java +++ b/src/main/java/org/dbunit/dataset/sqlloader/SqlLoaderControlParserImpl.java @@ -58,6 +58,7 @@ */ public class SqlLoaderControlParserImpl implements SqlLoaderControlParser { + /** The character that separates fields in the SQLLoader control file. */ public static final char SEPARATOR_CHAR = ';'; /** The pipeline. */ @@ -235,8 +236,16 @@ private File resolveFile(File parentDir, String fileName) { return dataFile; } - protected String parseForRegexp(String controlFileContent, String regexp) - throws IOException + /** + * Returns the first capture group of the given regexp matched against the given content. + * + * @param controlFileContent the content to search. + * @param regexp the regular expression to match, with a single capture group. + * @return the matched capture group, or null if the regexp does not match. + * @throws IOException never thrown by this implementation. + */ + protected String parseForRegexp(String controlFileContent, String regexp) + throws IOException { logger.debug("parseForRegexp(controlFileContent={}, regexp={}) - start", controlFileContent, regexp); diff --git a/src/main/java/org/dbunit/dataset/sqlloader/SqlLoaderControlProducer.java b/src/main/java/org/dbunit/dataset/sqlloader/SqlLoaderControlProducer.java index 322f09f54..e69990a2d 100644 --- a/src/main/java/org/dbunit/dataset/sqlloader/SqlLoaderControlProducer.java +++ b/src/main/java/org/dbunit/dataset/sqlloader/SqlLoaderControlProducer.java @@ -81,9 +81,9 @@ public class SqlLoaderControlProducer implements IDataSetProducer { * * @param controlFilesDir the control files directory * @param tableOrderFile the table order file - * @throws DataSetException + * @throws DataSetException if the table order file cannot be read. */ - public SqlLoaderControlProducer(String controlFilesDir, String tableOrderFile) + public SqlLoaderControlProducer(String controlFilesDir, String tableOrderFile) throws DataSetException { this(new File(controlFilesDir), new File(tableOrderFile)); @@ -94,9 +94,9 @@ public SqlLoaderControlProducer(String controlFilesDir, String tableOrderFile) * * @param controlFilesDir the control files directory * @param tableOrderFile the table order file - * @throws DataSetException + * @throws DataSetException if the table order file cannot be read. */ - public SqlLoaderControlProducer(File controlFilesDir, File tableOrderFile) + public SqlLoaderControlProducer(File controlFilesDir, File tableOrderFile) throws DataSetException { this.controlFilesDir = controlFilesDir; diff --git a/src/main/java/org/dbunit/dataset/stream/BufferedConsumer.java b/src/main/java/org/dbunit/dataset/stream/BufferedConsumer.java index 40cf5ba1d..dac209e1c 100644 --- a/src/main/java/org/dbunit/dataset/stream/BufferedConsumer.java +++ b/src/main/java/org/dbunit/dataset/stream/BufferedConsumer.java @@ -64,9 +64,12 @@ public class BufferedConsumer implements IDataSetConsumer { /** + * Creates a consumer that buffers all data until {@link #endDataSet()}, then flushes it + * to the given wrapped consumer. + * * @param wrappedConsumer The consumer that is wrapped */ - public BufferedConsumer(IDataSetConsumer wrappedConsumer) + public BufferedConsumer(IDataSetConsumer wrappedConsumer) { if (wrappedConsumer == null) { throw new NullPointerException( diff --git a/src/main/java/org/dbunit/dataset/stream/DataSetProducerAdapter.java b/src/main/java/org/dbunit/dataset/stream/DataSetProducerAdapter.java index 410926ebd..637a34976 100644 --- a/src/main/java/org/dbunit/dataset/stream/DataSetProducerAdapter.java +++ b/src/main/java/org/dbunit/dataset/stream/DataSetProducerAdapter.java @@ -53,11 +53,22 @@ public class DataSetProducerAdapter implements IDataSetProducer private final ITableIterator _iterator; private IDataSetConsumer _consumer = EMPTY_CONSUMER; + /** + * Creates a producer that reports the tables of the given iterator. + * + * @param iterator the iterator providing the tables to produce. + */ public DataSetProducerAdapter(ITableIterator iterator) { _iterator = iterator; } + /** + * Creates a producer that reports the tables of the given dataset. + * + * @param dataSet the dataset providing the tables to produce. + * @throws DataSetException if the dataset's iterator cannot be created. + */ public DataSetProducerAdapter(IDataSet dataSet) throws DataSetException { _iterator = dataSet.iterator(); diff --git a/src/main/java/org/dbunit/dataset/stream/DefaultConsumer.java b/src/main/java/org/dbunit/dataset/stream/DefaultConsumer.java index 8262578fc..eb78be9e6 100644 --- a/src/main/java/org/dbunit/dataset/stream/DefaultConsumer.java +++ b/src/main/java/org/dbunit/dataset/stream/DefaultConsumer.java @@ -33,6 +33,7 @@ */ public class DefaultConsumer implements IDataSetConsumer { + public void startDataSet() throws DataSetException { // no op diff --git a/src/main/java/org/dbunit/dataset/stream/IDataSetConsumer.java b/src/main/java/org/dbunit/dataset/stream/IDataSetConsumer.java index db0807cbf..24f06a7b3 100644 --- a/src/main/java/org/dbunit/dataset/stream/IDataSetConsumer.java +++ b/src/main/java/org/dbunit/dataset/stream/IDataSetConsumer.java @@ -36,12 +36,14 @@ public interface IDataSetConsumer /** * Receive notification of the beginning of a dataset. This method is * invoked only once, before any other methods in this interface. + * @throws DataSetException if the notification cannot be processed. */ public void startDataSet() throws DataSetException; /** * Receive notification of the end of a dataset. This method is invoked only * once, and it will be the last method invoked in this interface. + * @throws DataSetException if the notification cannot be processed. */ public void endDataSet() throws DataSetException; @@ -51,11 +53,13 @@ public interface IDataSetConsumer * corresponding {@link #endDataSet} event for every startTable * event (even when the table is empty). * @param metaData the table metadata + * @throws DataSetException if the notification cannot be processed. */ public void startTable(ITableMetaData metaData) throws DataSetException; /** * Receive notification of the end of a table. + * @throws DataSetException if the notification cannot be processed. */ public void endTable() throws DataSetException; @@ -63,6 +67,7 @@ public interface IDataSetConsumer * Receive notification of a table row. This method is invoked to report * each row of a table. * @param values The row values. + * @throws DataSetException if the notification cannot be processed. */ public void row(Object[] values) throws DataSetException; } diff --git a/src/main/java/org/dbunit/dataset/stream/IDataSetProducer.java b/src/main/java/org/dbunit/dataset/stream/IDataSetProducer.java index 8c5c5f252..f36c0aa05 100644 --- a/src/main/java/org/dbunit/dataset/stream/IDataSetProducer.java +++ b/src/main/java/org/dbunit/dataset/stream/IDataSetProducer.java @@ -32,6 +32,12 @@ */ public interface IDataSetProducer { + /** + * Sets the consumer notified of this producer's dataset content. + * + * @param consumer the consumer to notify. + * @throws DataSetException if the consumer cannot be set. + */ public void setConsumer(IDataSetConsumer consumer) throws DataSetException; /** @@ -42,6 +48,8 @@ public interface IDataSetProducer * This method is synchronous: it will not return until processing has ended. * If a client application wants to terminate parsing early, it should * throw an exception from the listener. + * + * @throws DataSetException if processing the dataset source fails. */ public void produce() throws DataSetException; } diff --git a/src/main/java/org/dbunit/dataset/stream/StreamingDataSet.java b/src/main/java/org/dbunit/dataset/stream/StreamingDataSet.java index f7919bb88..97daf467a 100644 --- a/src/main/java/org/dbunit/dataset/stream/StreamingDataSet.java +++ b/src/main/java/org/dbunit/dataset/stream/StreamingDataSet.java @@ -47,6 +47,11 @@ public class StreamingDataSet extends AbstractDataSet private IDataSetProducer _source; private int _iteratorCount; + /** + * Creates a dataset that asynchronously consumes the given producer. + * + * @param source the producer to consume. + */ public StreamingDataSet(IDataSetProducer source) { _source = source; @@ -81,7 +86,7 @@ protected ITableIterator createIterator(boolean reversed) /** * Not supported. - * @throws UnsupportedOperationException + * @throws UnsupportedOperationException always. */ public String[] getTableNames() throws DataSetException { @@ -90,7 +95,7 @@ public String[] getTableNames() throws DataSetException /** * Not supported. - * @throws UnsupportedOperationException + * @throws UnsupportedOperationException always. */ public ITableMetaData getTableMetaData(String tableName) throws DataSetException { @@ -101,7 +106,7 @@ public ITableMetaData getTableMetaData(String tableName) throws DataSetException /** * Not supported. - * @throws UnsupportedOperationException + * @throws UnsupportedOperationException always. */ public ITable getTable(String tableName) throws DataSetException { diff --git a/src/main/java/org/dbunit/dataset/stream/StreamingIterator.java b/src/main/java/org/dbunit/dataset/stream/StreamingIterator.java index 6bba4c535..bbc7101ab 100644 --- a/src/main/java/org/dbunit/dataset/stream/StreamingIterator.java +++ b/src/main/java/org/dbunit/dataset/stream/StreamingIterator.java @@ -71,7 +71,8 @@ public class StreamingIterator implements ITableIterator * the given source in an asynchronous way. Therefore a Thread is * created. * @param source The source of the data - * @throws DataSetException + * @throws DataSetException if the asynchronous producer thread is interrupted before + * producing its first element. */ public StreamingIterator(IDataSetProducer source) throws DataSetException { diff --git a/src/main/java/org/dbunit/dataset/xml/FlatDtdDataSet.java b/src/main/java/org/dbunit/dataset/xml/FlatDtdDataSet.java index 1f733fda0..57b60390c 100644 --- a/src/main/java/org/dbunit/dataset/xml/FlatDtdDataSet.java +++ b/src/main/java/org/dbunit/dataset/xml/FlatDtdDataSet.java @@ -60,21 +60,44 @@ public class FlatDtdDataSet extends AbstractDataSet implements IDataSetConsumer private boolean _ready = false; + /** + * Default constructor. + */ public FlatDtdDataSet() { initialize(); } + /** + * Creates a dataset from the DTD content of the given input stream. + * + * @param in the input stream to read the DTD from. + * @throws DataSetException if the DTD content is invalid. + * @throws IOException if the input stream cannot be read. + */ public FlatDtdDataSet(InputStream in) throws DataSetException, IOException { this(new FlatDtdProducer(new InputSource(in))); } + /** + * Creates a dataset from the DTD content of the given reader. + * + * @param reader the reader to read the DTD from. + * @throws DataSetException if the DTD content is invalid. + * @throws IOException if the reader cannot be read. + */ public FlatDtdDataSet(Reader reader) throws DataSetException, IOException { this(new FlatDtdProducer(new InputSource(reader))); } + /** + * Creates a dataset that synchronously consumes the specified producer. + * + * @param producer the producer to consume. + * @throws DataSetException if consuming the producer fails. + */ public FlatDtdDataSet(IDataSetProducer producer) throws DataSetException { initialize(); @@ -93,6 +116,11 @@ protected void initialize() * Writes the specified dataset to the specified output stream as DTD, * encoded in UTF-8, matching what the {@code InputStream} constructor's * SAX parsing assumes absent an explicit encoding declaration. + * + * @param dataSet the dataset to write a DTD for. + * @param out the stream to write to. + * @throws IOException if writing fails. + * @throws DataSetException if reading the dataset fails. * @see FlatDtdWriter */ public static void write(IDataSet dataSet, OutputStream out) @@ -105,6 +133,11 @@ public static void write(IDataSet dataSet, OutputStream out) /** * Write the specified dataset to the specified writer as DTD. + * + * @param dataSet the dataset to write a DTD for. + * @param out the writer to write to. + * @throws IOException if writing fails. + * @throws DataSetException if reading the dataset fails. * @see FlatDtdWriter */ public static void write(IDataSet dataSet, Writer out) diff --git a/src/main/java/org/dbunit/dataset/xml/FlatDtdProducer.java b/src/main/java/org/dbunit/dataset/xml/FlatDtdProducer.java index 5fc13a3fb..30fe73c48 100644 --- a/src/main/java/org/dbunit/dataset/xml/FlatDtdProducer.java +++ b/src/main/java/org/dbunit/dataset/xml/FlatDtdProducer.java @@ -109,15 +109,31 @@ public class FlatDtdProducer implements IDataSetProducer, EntityResolver, DeclHa private String _rootModel; private final Map _columnListMap = new HashMap(); + /** + * Default constructor. + */ public FlatDtdProducer() { } + /** + * Creates a producer that reads the DTD from the given input source. + * + * @param inputSource the DTD input source. + */ public FlatDtdProducer(final InputSource inputSource) { _inputSource = inputSource; } + /** + * Registers the given handler as the given XML reader's declaration handler. + * + * @param xmlReader the XML reader to configure. + * @param handler the declaration handler to register. + * @throws SAXNotRecognizedException if the reader does not recognize the declaration-handler property. + * @throws SAXNotSupportedException if the reader does not support the declaration-handler property. + */ public static void setDeclHandler(final XMLReader xmlReader, final DeclHandler handler) throws SAXNotRecognizedException, SAXNotSupportedException { @@ -125,6 +141,14 @@ public static void setDeclHandler(final XMLReader xmlReader, final DeclHandler h xmlReader.setProperty(DECL_HANDLER_PROPERTY_NAME, handler); } + /** + * Registers the given handler as the given XML reader's lexical handler. + * + * @param xmlReader the XML reader to configure. + * @param handler the lexical handler to register. + * @throws SAXNotRecognizedException if the reader does not recognize the lexical-handler property. + * @throws SAXNotSupportedException if the reader does not support the lexical-handler property. + */ public static void setLexicalHandler(final XMLReader xmlReader, final LexicalHandler handler) throws SAXNotRecognizedException, SAXNotSupportedException { @@ -337,6 +361,13 @@ private Column[] getColumns(final String tableName) throws DataSetException return columns; } + /** + * Strips DTD content-model syntax (parentheses, occurrence indicators) from the given + * table name, as parsed from an ELEMENT declaration. + * + * @param tableName the raw table name to clean up. + * @return the cleaned-up table name. + */ protected String cleanupTableName(final String tableName) { String cleaned = tableName; diff --git a/src/main/java/org/dbunit/dataset/xml/FlatDtdWriter.java b/src/main/java/org/dbunit/dataset/xml/FlatDtdWriter.java index 91538f930..c3045e726 100644 --- a/src/main/java/org/dbunit/dataset/xml/FlatDtdWriter.java +++ b/src/main/java/org/dbunit/dataset/xml/FlatDtdWriter.java @@ -45,24 +45,42 @@ public class FlatDtdWriter //implements IDataSetConsumer */ private static final Logger logger = LoggerFactory.getLogger(FlatDtdWriter.class); + /** Content model rendering child elements as a sequence, e.g. (A, B, C). */ public static final ContentModel SEQUENCE = new SequenceModel(); + /** Content model rendering child elements as a choice, e.g. (A | B | C). */ public static final ContentModel CHOICE = new ChoiceModel(); private Writer _writer; private ContentModel _contentModel; + /** + * Creates a writer that writes DTD content to the given writer, using the sequence content model. + * + * @param writer the writer to write to. + */ public FlatDtdWriter(Writer writer) { _writer = writer; _contentModel = SEQUENCE; } + /** + * Sets the content model used to render tables' child elements. + * + * @param contentModel the content model to use. + */ public void setContentModel(ContentModel contentModel) { logger.debug("setContentModel(contentModel={}) - start", contentModel); _contentModel = contentModel; } + /** + * Writes a DTD describing the given dataset's tables and columns. + * + * @param dataSet the dataset to write a DTD for. + * @throws DataSetException if reading the dataset fails. + */ public void write(IDataSet dataSet) throws DataSetException { logger.debug("write(dataSet={}) - start", dataSet); @@ -149,6 +167,14 @@ public String toString() return _name; } + /** + * Writes the given table's content-model declaration. + * + * @param writer the writer to write to. + * @param tableName the table name. + * @param tableIndex the index of the table among tableCount, used to decide separators. + * @param tableCount the total number of tables being written. + */ public abstract void write(PrintWriter writer, String tableName, int tableIndex, int tableCount); } diff --git a/src/main/java/org/dbunit/dataset/xml/FlatXmlDataSet.java b/src/main/java/org/dbunit/dataset/xml/FlatXmlDataSet.java index 6ed6e5224..eac806d8f 100644 --- a/src/main/java/org/dbunit/dataset/xml/FlatXmlDataSet.java +++ b/src/main/java/org/dbunit/dataset/xml/FlatXmlDataSet.java @@ -101,7 +101,7 @@ public class FlatXmlDataSet extends CachedDataSet /** * Creates a new {@link FlatXmlDataSet} with the data of the given producer. * @param flatXmlProducer The producer that provides the {@link FlatXmlDataSet} content - * @throws DataSetException + * @throws DataSetException if the dataset cannot be built. * @since 2.4.7 */ public FlatXmlDataSet(FlatXmlProducer flatXmlProducer) throws DataSetException @@ -111,6 +111,9 @@ public FlatXmlDataSet(FlatXmlProducer flatXmlProducer) throws DataSetException /** * Creates an FlatXmlDataSet object with the specified InputSource. + * @param source the XML input source. + * @throws IOException if the input cannot be read. + * @throws DataSetException if the dataset cannot be built. * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet} */ public FlatXmlDataSet(InputSource source) throws IOException, DataSetException @@ -123,6 +126,8 @@ public FlatXmlDataSet(InputSource source) throws IOException, DataSetException * Relative DOCTYPE uri are resolved from the xml file path. * * @param xmlFile the xml file + * @throws IOException if the input cannot be read. + * @throws DataSetException if the dataset cannot be built. * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet} */ public FlatXmlDataSet(File xmlFile) throws IOException, DataSetException @@ -136,6 +141,8 @@ public FlatXmlDataSet(File xmlFile) throws IOException, DataSetException * * @param xmlFile the xml file * @param dtdMetadata if false do not use DTD as metadata + * @throws IOException if the input cannot be read. + * @throws DataSetException if the dataset cannot be built. * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet} */ public FlatXmlDataSet(File xmlFile, boolean dtdMetadata) @@ -152,6 +159,8 @@ public FlatXmlDataSet(File xmlFile, boolean dtdMetadata) * @param dtdMetadata if false do not use DTD as metadata * @param columnSensing Whether or not the columns should be sensed automatically. Every XML row * is scanned for columns that have not been there in a previous column. + * @throws IOException if the input cannot be read. + * @throws DataSetException if the dataset cannot be built. * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet} */ public FlatXmlDataSet(File xmlFile, boolean dtdMetadata, boolean columnSensing) @@ -169,6 +178,8 @@ public FlatXmlDataSet(File xmlFile, boolean dtdMetadata, boolean columnSensing) * @param columnSensing Whether or not the columns should be sensed automatically. Every XML row * is scanned for columns that have not been there in a previous column. * @param caseSensitiveTableNames Whether or not this dataset should use case sensitive table names + * @throws IOException if the input cannot be read. + * @throws DataSetException if the dataset cannot be built. * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet} */ public FlatXmlDataSet(File xmlFile, boolean dtdMetadata, boolean columnSensing, boolean caseSensitiveTableNames) @@ -182,6 +193,8 @@ public FlatXmlDataSet(File xmlFile, boolean dtdMetadata, boolean columnSensing, * Relative DOCTYPE uri are resolved from the xml file path. * * @param xmlUrl the xml URL + * @throws IOException if the input cannot be read. + * @throws DataSetException if the dataset cannot be built. * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet} */ public FlatXmlDataSet(URL xmlUrl) throws IOException, DataSetException @@ -195,6 +208,8 @@ public FlatXmlDataSet(URL xmlUrl) throws IOException, DataSetException * * @param xmlUrl the xml URL * @param dtdMetadata if false do not use DTD as metadata + * @throws IOException if the input cannot be read. + * @throws DataSetException if the dataset cannot be built. * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet} */ public FlatXmlDataSet(URL xmlUrl, boolean dtdMetadata) @@ -212,6 +227,8 @@ public FlatXmlDataSet(URL xmlUrl, boolean dtdMetadata) * @param dtdMetadata if false do not use DTD as metadata * @param columnSensing Whether or not the columns should be sensed automatically. Every XML row * is scanned for columns that have not been there in a previous column. + * @throws IOException if the input cannot be read. + * @throws DataSetException if the dataset cannot be built. * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet} */ public FlatXmlDataSet(URL xmlUrl, boolean dtdMetadata, boolean columnSensing) @@ -230,6 +247,8 @@ public FlatXmlDataSet(URL xmlUrl, boolean dtdMetadata, boolean columnSensing) * @param columnSensing Whether or not the columns should be sensed automatically. Every XML row * is scanned for columns that have not been there in a previous column. * @param caseSensitiveTableNames Whether or not this dataset should use case sensitive table names + * @throws IOException if the input cannot be read. + * @throws DataSetException if the dataset cannot be built. * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet} */ public FlatXmlDataSet(URL xmlUrl, boolean dtdMetadata, boolean columnSensing, boolean caseSensitiveTableNames) @@ -245,6 +264,8 @@ public FlatXmlDataSet(URL xmlUrl, boolean dtdMetadata, boolean columnSensing, bo * Relative DOCTYPE uri are resolved from the current working directory. * * @param xmlReader the xml reader + * @throws IOException if the input cannot be read. + * @throws DataSetException if the dataset cannot be built. * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet} */ public FlatXmlDataSet(Reader xmlReader) throws IOException, DataSetException @@ -258,6 +279,8 @@ public FlatXmlDataSet(Reader xmlReader) throws IOException, DataSetException * * @param xmlReader the xml reader * @param dtdMetadata if false do not use DTD as metadata + * @throws IOException if the input cannot be read. + * @throws DataSetException if the dataset cannot be built. * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet} */ public FlatXmlDataSet(Reader xmlReader, boolean dtdMetadata) @@ -276,6 +299,8 @@ public FlatXmlDataSet(Reader xmlReader, boolean dtdMetadata) * is scanned for columns that have not been there in a previous column. * @param caseSensitiveTableNames Whether or not this dataset should use case sensitive table names * @since 2.4.3 + * @throws IOException if the input cannot be read. + * @throws DataSetException if the dataset cannot be built. * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet} */ public FlatXmlDataSet(Reader xmlReader, boolean dtdMetadata, boolean columnSensing, boolean caseSensitiveTableNames) @@ -290,6 +315,8 @@ public FlatXmlDataSet(Reader xmlReader, boolean dtdMetadata, boolean columnSensi * * @param xmlReader the xml reader * @param dtdReader the dtd reader + * @throws IOException if the input cannot be read. + * @throws DataSetException if the dataset cannot be built. * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet} */ public FlatXmlDataSet(Reader xmlReader, Reader dtdReader) @@ -303,6 +330,8 @@ public FlatXmlDataSet(Reader xmlReader, Reader dtdReader) * * @param xmlReader the xml reader * @param metaDataSet the dataset used as metadata source. + * @throws IOException if the input cannot be read. + * @throws DataSetException if the dataset cannot be built. * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet} */ public FlatXmlDataSet(Reader xmlReader, IDataSet metaDataSet) @@ -316,6 +345,8 @@ public FlatXmlDataSet(Reader xmlReader, IDataSet metaDataSet) * Relative DOCTYPE uri are resolved from the current working directory. * * @param xmlStream the xml input stream + * @throws IOException if the input cannot be read. + * @throws DataSetException if the dataset cannot be built. * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet} */ public FlatXmlDataSet(InputStream xmlStream) throws IOException, DataSetException @@ -329,6 +360,8 @@ public FlatXmlDataSet(InputStream xmlStream) throws IOException, DataSetExceptio * * @param xmlStream the xml input stream * @param dtdMetadata if false do not use DTD as metadata + * @throws IOException if the input cannot be read. + * @throws DataSetException if the dataset cannot be built. * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet} */ public FlatXmlDataSet(InputStream xmlStream, boolean dtdMetadata) @@ -343,6 +376,8 @@ public FlatXmlDataSet(InputStream xmlStream, boolean dtdMetadata) * * @param xmlStream the xml input stream * @param dtdStream the dtd input stream + * @throws IOException if the input cannot be read. + * @throws DataSetException if the dataset cannot be built. * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet} */ public FlatXmlDataSet(InputStream xmlStream, InputStream dtdStream) @@ -356,6 +391,8 @@ public FlatXmlDataSet(InputStream xmlStream, InputStream dtdStream) * * @param xmlStream the xml input stream * @param metaDataSet the dataset used as metadata source. + * @throws IOException if the input cannot be read. + * @throws DataSetException if the dataset cannot be built. * @deprecated since 2.4.7 - use {@link FlatXmlDataSetBuilder} to create a {@link FlatXmlDataSet} */ public FlatXmlDataSet(InputStream xmlStream, IDataSet metaDataSet) @@ -366,6 +403,11 @@ public FlatXmlDataSet(InputStream xmlStream, IDataSet metaDataSet) /** * Write the specified dataset to the specified output stream as xml. + * + * @param dataSet the dataset to write. + * @param out the stream to write to. + * @throws IOException if writing fails. + * @throws DataSetException if reading the dataset fails. */ public static void write(IDataSet dataSet, OutputStream out) throws IOException, DataSetException @@ -379,6 +421,11 @@ public static void write(IDataSet dataSet, OutputStream out) /** * Write the specified dataset to the specified writer as xml. + * + * @param dataSet the dataset to write. + * @param writer the writer to write to. + * @throws IOException if writing fails. + * @throws DataSetException if reading the dataset fails. */ public static void write(IDataSet dataSet, Writer writer) throws IOException, DataSetException @@ -389,6 +436,12 @@ public static void write(IDataSet dataSet, Writer writer) /** * Write the specified dataset to the specified writer as xml. + * + * @param dataSet the dataset to write. + * @param writer the writer to write to. + * @param charset the charset to declare in the XML prolog, may be null. + * @throws IOException if writing fails. + * @throws DataSetException if reading the dataset fails. */ public static void write(IDataSet dataSet, Writer writer, Charset charset) throws IOException, DataSetException @@ -403,6 +456,11 @@ public static void write(IDataSet dataSet, Writer writer, Charset charset) /** * Write a DTD for the specified dataset to the specified output. + * + * @param dataSet the dataset to write a DTD for. + * @param out the stream to write to. + * @throws IOException if writing fails. + * @throws DataSetException if reading the dataset fails. * @deprecated use {@link FlatDtdDataSet#write} */ public static void writeDtd(IDataSet dataSet, OutputStream out) diff --git a/src/main/java/org/dbunit/dataset/xml/FlatXmlDataSetBuilder.java b/src/main/java/org/dbunit/dataset/xml/FlatXmlDataSetBuilder.java index fb5f1eb8f..db13af6e5 100644 --- a/src/main/java/org/dbunit/dataset/xml/FlatXmlDataSetBuilder.java +++ b/src/main/java/org/dbunit/dataset/xml/FlatXmlDataSetBuilder.java @@ -91,7 +91,7 @@ public FlatXmlDataSetBuilder() * Sets the flat XML input source from which the {@link FlatXmlDataSet} is to be built * @param inputSource The flat XML input as {@link InputSource} * @return The created {@link FlatXmlDataSet} - * @throws DataSetException + * @throws DataSetException if the dataset cannot be built. */ public FlatXmlDataSet build(InputSource inputSource) throws DataSetException { @@ -102,7 +102,8 @@ public FlatXmlDataSet build(InputSource inputSource) throws DataSetException * Sets the flat XML input source from which the {@link FlatXmlDataSet} is to be built * @param xmlInputFile The flat XML input as {@link File} * @return The created {@link FlatXmlDataSet} - * @throws DataSetException + * @throws MalformedURLException if the file's path cannot be converted to a URL. + * @throws DataSetException if the dataset cannot be built. */ public FlatXmlDataSet build(File xmlInputFile) throws MalformedURLException, DataSetException { @@ -115,7 +116,7 @@ public FlatXmlDataSet build(File xmlInputFile) throws MalformedURLException, Dat * Sets the flat XML input source from which the {@link FlatXmlDataSet} is to be built * @param xmlInputUrl The flat XML input as {@link URL} * @return The created {@link FlatXmlDataSet} - * @throws DataSetException + * @throws DataSetException if the dataset cannot be built. */ public FlatXmlDataSet build(URL xmlInputUrl) throws DataSetException { @@ -127,7 +128,7 @@ public FlatXmlDataSet build(URL xmlInputUrl) throws DataSetException * Sets the flat XML input source from which the {@link FlatXmlDataSet} is to be built * @param xmlReader The flat XML input as {@link Reader} * @return The created {@link FlatXmlDataSet} - * @throws DataSetException + * @throws DataSetException if the dataset cannot be built. */ public FlatXmlDataSet build(Reader xmlReader) throws DataSetException { @@ -139,7 +140,7 @@ public FlatXmlDataSet build(Reader xmlReader) throws DataSetException * Sets the flat XML input source from which the {@link FlatXmlDataSet} is to be built * @param xmlInputStream The flat XML input as {@link InputStream} * @return The created {@link FlatXmlDataSet} - * @throws DataSetException + * @throws DataSetException if the dataset cannot be built. */ public FlatXmlDataSet build(InputStream xmlInputStream) throws DataSetException { @@ -161,10 +162,10 @@ private InputSource createInputSourceFromUrl(URL xmlInputUrl) /** * Set the metadata information (column info etc.) to be used. May come from a DTD. * This has precedence to the other builder's properties. - * @param metaDataSet + * @param metaDataSet the metadata source. * @return this */ - public FlatXmlDataSetBuilder setMetaDataSet(IDataSet metaDataSet) + public FlatXmlDataSetBuilder setMetaDataSet(IDataSet metaDataSet) { this.metaDataSet = metaDataSet; return this; @@ -174,8 +175,8 @@ public FlatXmlDataSetBuilder setMetaDataSet(IDataSet metaDataSet) * Set the metadata information (column info etc.) to be used from the given DTD input. * This has precedence to the other builder's properties. * @param dtdReader A reader that provides the DTD content - * @throws DataSetException - * @throws IOException + * @throws DataSetException if the DTD content is invalid. + * @throws IOException if the reader cannot be read. * @return this */ public FlatXmlDataSetBuilder setMetaDataSetFromDtd(Reader dtdReader) throws DataSetException, IOException @@ -187,9 +188,9 @@ public FlatXmlDataSetBuilder setMetaDataSetFromDtd(Reader dtdReader) throws Data /** * Set the metadata information (column info etc.) to be used from the given DTD input. * This has precedence to the other builder's properties. - * @param dtdStream - * @throws DataSetException - * @throws IOException + * @param dtdStream A stream that provides the DTD content + * @throws DataSetException if the DTD content is invalid. + * @throws IOException if the stream cannot be read. * @return this */ public FlatXmlDataSetBuilder setMetaDataSetFromDtd(InputStream dtdStream) throws DataSetException, IOException @@ -198,13 +199,17 @@ public FlatXmlDataSetBuilder setMetaDataSetFromDtd(InputStream dtdStream) throws return this; } + /** + * Whether or not DTD metadata is available to parse via a DTD handler. + * @return whether or not DTD metadata is available to parse via a DTD handler. + */ public boolean isDtdMetadata() { return dtdMetadata; } /** * Whether or not DTD metadata is available to parse via a DTD handler. - * @param dtdMetadata + * @param dtdMetadata whether or not DTD metadata is available to parse via a DTD handler. * @return this */ public FlatXmlDataSetBuilder setDtdMetadata(boolean dtdMetadata) { @@ -212,6 +217,10 @@ public FlatXmlDataSetBuilder setDtdMetadata(boolean dtdMetadata) { return this; } + /** + * Whether or not column sensing is enabled. + * @return whether or not column sensing is enabled. + */ public boolean isColumnSensing() { return columnSensing; } @@ -219,7 +228,7 @@ public boolean isColumnSensing() { /** * Since DBUnit 2.3.0 there is a functionality called "column sensing" which basically * reads in the whole XML into a buffer and dynamically adds new columns as they appear. - * @param columnSensing + * @param columnSensing whether or not column sensing is enabled. * @return this */ public FlatXmlDataSetBuilder setColumnSensing(boolean columnSensing) { @@ -227,13 +236,17 @@ public FlatXmlDataSetBuilder setColumnSensing(boolean columnSensing) { return this; } + /** + * Whether or not the created dataset should use case sensitive table names. + * @return whether or not the created dataset should use case sensitive table names. + */ public boolean isCaseSensitiveTableNames() { return caseSensitiveTableNames; } /** * Whether or not the created dataset should use case sensitive table names - * @param caseSensitiveTableNames + * @param caseSensitiveTableNames whether or not the created dataset should use case sensitive table names. * @return this */ public FlatXmlDataSetBuilder setCaseSensitiveTableNames(boolean caseSensitiveTableNames) { @@ -265,10 +278,13 @@ private FlatXmlDataSet buildInternal(InputSource inputSource) throws DataSetExce } /** + * Creates the producer used to build the {@link FlatXmlDataSet}, using this builder's + * configured metadata source or properties. + * * @param inputSource The XML input to be built * @return The producer which is used to create the {@link FlatXmlDataSet} */ - protected FlatXmlProducer createProducer(InputSource inputSource) + protected FlatXmlProducer createProducer(InputSource inputSource) { logger.trace("createProducer(inputSource={}) - start", inputSource); diff --git a/src/main/java/org/dbunit/dataset/xml/FlatXmlProducer.java b/src/main/java/org/dbunit/dataset/xml/FlatXmlProducer.java index 47de7c681..adbbf8ec7 100644 --- a/src/main/java/org/dbunit/dataset/xml/FlatXmlProducer.java +++ b/src/main/java/org/dbunit/dataset/xml/FlatXmlProducer.java @@ -121,16 +121,34 @@ public class FlatXmlProducer extends DefaultHandler implements IDataSetProducer, private Set _activeColumnNamesUpperCase; + /** + * Creates a producer that reads the given XML source, with DTD metadata enabled. + * + * @param xmlSource The input datasource + */ public FlatXmlProducer(InputSource xmlSource) { this(xmlSource, true); } + /** + * Creates a producer that reads the given XML source. + * + * @param xmlSource The input datasource + * @param dtdMetadata Whether or not DTD metadata is available to parse via a DTD handler + */ public FlatXmlProducer(InputSource xmlSource, boolean dtdMetadata) { this(xmlSource, dtdMetadata, false); } + /** + * Creates a producer that reads the given XML source, using the given dataset as + * the source of metadata instead of parsing a DTD. + * + * @param xmlSource The input datasource + * @param metaDataSet the dataset used as metadata source. + */ public FlatXmlProducer(InputSource xmlSource, IDataSet metaDataSet) { _inputSource = xmlSource; @@ -140,14 +158,23 @@ public FlatXmlProducer(InputSource xmlSource, IDataSet metaDataSet) initialize(false); } + /** + * Creates a producer that reads the given XML source, with DTD metadata enabled and + * resolved using the given entity resolver. + * + * @param xmlSource The input datasource + * @param resolver the entity resolver used to resolve the DTD. + */ public FlatXmlProducer(InputSource xmlSource, EntityResolver resolver) { _inputSource = xmlSource; _resolver = resolver; initialize(true); } - + /** + * Creates a producer that reads the given XML source. + * * @param xmlSource The input datasource * @param dtdMetadata Whether or not DTD metadata is available to parse via a DTD handler * @param columnSensing Whether or not the column sensing feature should be used (see FAQ) @@ -156,8 +183,10 @@ public FlatXmlProducer(InputSource xmlSource, boolean dtdMetadata, boolean colum { this(xmlSource, dtdMetadata, columnSensing, false); } - + /** + * Creates a producer that reads the given XML source. + * * @param xmlSource The input datasource * @param dtdMetadata Whether or not DTD metadata is available to parse via a DTD handler * @param columnSensing Whether or not the column sensing feature should be used (see FAQ) @@ -184,6 +213,8 @@ private void initialize(boolean dtdMetadata) } /** + * Returns whether or not this producer works case sensitively. + * * @return Whether or not this producer works case sensitively * @since 2.4.7 */ @@ -217,7 +248,7 @@ private ITableMetaData createTableMetaData(String tableName, Attributes attribut * merges the existing columns with the potentially new ones. * @param columnsToMerge List of extra columns found, which need to be merge back into the metadata. * @return ITableMetaData The merged metadata object containing the new columns - * @throws DataSetException + * @throws DataSetException if the metadata cannot be merged. */ private ITableMetaData mergeTableMetaData(List columnsToMerge, ITableMetaData originalMetaData) throws DataSetException { @@ -298,7 +329,7 @@ private void rebuildActiveColumnNames(ITableMetaData metaData) throws DataSetExc * * * @param attributes Attributed for the current row. - * @throws DataSetException + * @throws DataSetException if the metadata cannot be merged. */ protected void handleMissingColumns(Attributes attributes) throws DataSetException @@ -348,11 +379,21 @@ protected void handleMissingColumns(Attributes attributes) } } + /** + * Sets whether or not the column sensing feature should be used. + * + * @param columnSensing whether or not the column sensing feature should be used. + */ public void setColumnSensing(boolean columnSensing) { _columnSensing = columnSensing; } + /** + * Sets whether or not the XML parser should validate against its DTD. + * + * @param validating whether or not the XML parser should validate against its DTD. + */ public void setValidating(boolean validating) { _validating = validating; @@ -512,6 +553,17 @@ public void startElement(String uri, String localName, String qName, } } + /** + * Resolves the given attribute's column index in the active metadata and stores its value + * at that index in rowValues. + * + * @param attributes the current row's attributes. + * @param activeMetaData the active table metadata. + * @param rowValues the row value array to populate. + * @param i the index, into attributes, of the attribute to process. + * @throws DataSetException if resolving the column index fails. + * @throws NoSuchColumnException if the attribute has no corresponding column. + */ protected void determineAndSetRowValue(Attributes attributes, ITableMetaData activeMetaData, Object[] rowValues, int i) throws DataSetException, NoSuchColumnException diff --git a/src/main/java/org/dbunit/dataset/xml/FlatXmlWriter.java b/src/main/java/org/dbunit/dataset/xml/FlatXmlWriter.java index b41adc19a..2b33696b7 100644 --- a/src/main/java/org/dbunit/dataset/xml/FlatXmlWriter.java +++ b/src/main/java/org/dbunit/dataset/xml/FlatXmlWriter.java @@ -62,12 +62,20 @@ public class FlatXmlWriter implements IDataSetConsumer private boolean _includeEmptyTable = false; private String _systemId = null; + /** + * Creates a writer that writes XML to the given output stream, using the platform default charset. + * + * @param out the stream to write to. + * @throws IOException if the writer cannot be created. + */ public FlatXmlWriter(OutputStream out) throws IOException { this(out, null); } /** + * Creates a writer that writes XML to the given output stream. + * * @param outputStream The stream to which the XML will be written. * @param charset The character set to be used for the {@link XmlWriter}. * Can be null. See {@link XmlWriter#XmlWriter(OutputStream, Charset)}. @@ -78,23 +86,44 @@ public FlatXmlWriter(OutputStream outputStream, Charset charset) _xmlWriter.enablePrettyPrint(true); } + /** + * Creates a writer that writes XML to the given writer. + * + * @param writer the writer to write to. + */ public FlatXmlWriter(Writer writer) { _xmlWriter = new XmlWriter(writer); _xmlWriter.enablePrettyPrint(true); } + /** + * Creates a writer that writes XML to the given writer. + * + * @param writer the writer to write to. + * @param charset the charset to declare in the XML prolog, may be null. + */ public FlatXmlWriter(Writer writer, Charset charset) { _xmlWriter = new XmlWriter(writer, charset); _xmlWriter.enablePrettyPrint(true); } + /** + * Sets whether or not empty tables are included in the output. + * + * @param includeEmptyTable whether or not empty tables are included in the output. + */ public void setIncludeEmptyTable(boolean includeEmptyTable) { _includeEmptyTable = includeEmptyTable; } + /** + * Sets the DOCTYPE system id to declare in the output. + * + * @param systemId the DOCTYPE system id. + */ public void setDocType(String systemId) { _systemId = systemId; @@ -114,7 +143,7 @@ public void setPrettyPrint(boolean enabled) /** * Writes the given {@link IDataSet} using this writer. * @param dataSet The {@link IDataSet} to be written - * @throws DataSetException + * @throws DataSetException if reading the dataset fails. */ public void write(IDataSet dataSet) throws DataSetException { diff --git a/src/main/java/org/dbunit/dataset/xml/XmlDataSet.java b/src/main/java/org/dbunit/dataset/xml/XmlDataSet.java index 50ba04e6c..8376630d7 100644 --- a/src/main/java/org/dbunit/dataset/xml/XmlDataSet.java +++ b/src/main/java/org/dbunit/dataset/xml/XmlDataSet.java @@ -68,6 +68,9 @@ public class XmlDataSet extends CachedDataSet /** * Creates an XmlDataSet with the specified xml reader. + * + * @param reader the reader to load the xml document from. + * @throws DataSetException if the document cannot be parsed. */ public XmlDataSet(Reader reader) throws DataSetException { @@ -76,6 +79,9 @@ public XmlDataSet(Reader reader) throws DataSetException /** * Creates an XmlDataSet with the specified xml input stream. + * + * @param in the stream to load the xml document from. + * @throws DataSetException if the document cannot be parsed. */ public XmlDataSet(InputStream in) throws DataSetException { @@ -84,6 +90,11 @@ public XmlDataSet(InputStream in) throws DataSetException /** * Write the specified dataset to the specified output stream as xml. + * + * @param dataSet the dataset to write. + * @param out the stream to write the xml document to. + * @throws IOException if writing to the stream fails. + * @throws DataSetException if the dataset cannot be read. */ public static void write(IDataSet dataSet, OutputStream out) throws IOException, DataSetException @@ -94,6 +105,12 @@ public static void write(IDataSet dataSet, OutputStream out) /** * Write the specified dataset to the specified output stream as xml (using specified encoding). + * + * @param dataSet the dataset to write. + * @param out the stream to write the xml document to. + * @param charset the character encoding to write the document in. + * @throws IOException if writing to the stream fails. + * @throws DataSetException if the dataset cannot be read. */ public static void write(IDataSet dataSet, OutputStream out, Charset charset) throws IOException, DataSetException @@ -107,6 +124,11 @@ public static void write(IDataSet dataSet, OutputStream out, Charset charset) /** * Write the specified dataset to the specified writer as xml. + * + * @param dataSet the dataset to write. + * @param writer the writer to write the xml document to. + * @throws IOException if writing to the writer fails. + * @throws DataSetException if the dataset cannot be read. */ public static void write(IDataSet dataSet, Writer writer) throws IOException, DataSetException @@ -117,6 +139,12 @@ public static void write(IDataSet dataSet, Writer writer) /** * Write the specified dataset to the specified writer as xml. + * + * @param dataSet the dataset to write. + * @param writer the writer to write the xml document to. + * @param charset the character encoding to write the document in. + * @throws IOException if writing to the writer fails. + * @throws DataSetException if the dataset cannot be read. */ public static void write(IDataSet dataSet, Writer writer, Charset charset) throws IOException, DataSetException diff --git a/src/main/java/org/dbunit/dataset/xml/XmlDataSetWriter.java b/src/main/java/org/dbunit/dataset/xml/XmlDataSetWriter.java index 33d03ec79..9a9225e5d 100644 --- a/src/main/java/org/dbunit/dataset/xml/XmlDataSetWriter.java +++ b/src/main/java/org/dbunit/dataset/xml/XmlDataSetWriter.java @@ -74,6 +74,8 @@ public class XmlDataSetWriter implements IDataSetConsumer /** + * Creates a new XmlDataSetWriter. + * * @param outputStream The stream to which the XML will be written. * @param charset The character set to be used for the {@link XmlWriter}. * Can be null. See {@link XmlWriter#XmlWriter(OutputStream, Charset)}. @@ -84,12 +86,23 @@ public XmlDataSetWriter(OutputStream outputStream, Charset charset) _xmlWriter.enablePrettyPrint(true); } + /** + * Creates a new XmlDataSetWriter. + * + * @param writer The writer to which the XML will be written. + */ public XmlDataSetWriter(Writer writer) { _xmlWriter = new XmlWriter(writer); _xmlWriter.enablePrettyPrint(true); } + /** + * Creates a new XmlDataSetWriter. + * + * @param writer The writer to which the XML will be written. + * @param charset The character set to be used for the {@link XmlWriter}. + */ public XmlDataSetWriter(Writer writer, Charset charset) { _xmlWriter = new XmlWriter(writer, charset); @@ -119,7 +132,7 @@ public void setIncludeColumnComments(boolean includeColumnComments) /** * Writes the given {@link IDataSet} using this writer. * @param dataSet The {@link IDataSet} to be written - * @throws DataSetException + * @throws DataSetException if the dataset cannot be read. */ public void write(IDataSet dataSet) throws DataSetException { @@ -317,7 +330,7 @@ private void flushWriterQuietly() * Can be overridden to add custom behavior. * This implementation just invokes {@link XmlWriter#writeCData(String)} * @param stringValue The value to be written - * @throws IOException + * @throws IOException if writing to the underlying stream fails. * @since 2.4.4 */ protected void writeValueCData(String stringValue) throws IOException @@ -331,7 +344,7 @@ protected void writeValueCData(String stringValue) throws IOException * Can be overridden to add custom behavior. * This implementation just invokes {@link XmlWriter#writeText(String)}. * @param stringValue The value to be written - * @throws IOException + * @throws IOException if writing to the underlying stream fails. * @since 2.4.4 */ protected void writeValue(String stringValue) throws IOException @@ -341,6 +354,8 @@ protected void writeValue(String stringValue) throws IOException } /** + * Returns the {@link XmlWriter} that is used for writing out XML. + * * @return The {@link XmlWriter} that is used for writing out XML. * @since 2.4.4 */ diff --git a/src/main/java/org/dbunit/dataset/xml/XmlProducer.java b/src/main/java/org/dbunit/dataset/xml/XmlProducer.java index 9687dd058..4a62f0a5c 100644 --- a/src/main/java/org/dbunit/dataset/xml/XmlProducer.java +++ b/src/main/java/org/dbunit/dataset/xml/XmlProducer.java @@ -89,6 +89,11 @@ public class XmlProducer extends DefaultHandler private StringBuilder _activeCharacters; private List _activeRowValues; + /** + * Creates a producer reading XML from the given source. + * + * @param inputSource the source to read XML from. + */ public XmlProducer(InputSource inputSource) { _inputSource = inputSource; @@ -108,6 +113,11 @@ private ITableMetaData createMetaData(String tableName, List columnNames) return metaData; } + /** + * Sets whether the XML parser validates the document against its DTD. + * + * @param validating true to validate the document against its DTD. + */ public void setValidating(boolean validating) { _validating = validating; diff --git a/src/main/java/org/dbunit/dataset/yaml/YamlDataSet.java b/src/main/java/org/dbunit/dataset/yaml/YamlDataSet.java index e392b1e8c..db166cbee 100644 --- a/src/main/java/org/dbunit/dataset/yaml/YamlDataSet.java +++ b/src/main/java/org/dbunit/dataset/yaml/YamlDataSet.java @@ -74,6 +74,10 @@ public class YamlDataSet extends CachedDataSet /** * Creates a YAML dataset based on a yaml file + * + * @param file the YAML file to load. + * @throws IOException if the file cannot be read. + * @throws DataSetException if the document cannot be parsed. */ public YamlDataSet(File file) throws IOException, DataSetException { @@ -84,6 +88,7 @@ public YamlDataSet(File file) throws IOException, DataSetException * Creates a YAML dataset based on an inputstream * * @param inputStream An inputstream pointing to a YAML dataset + * @throws DataSetException if the document cannot be parsed. */ public YamlDataSet(InputStream inputStream) throws DataSetException { @@ -93,6 +98,10 @@ public YamlDataSet(InputStream inputStream) throws DataSetException /** * Writes the specified dataset to the specified output stream as YAML, * encoded in UTF-8, matching what {@link YamlProducer} decodes. + * + * @param dataSet the dataset to write. + * @param out the stream to write the YAML document to. + * @throws DataSetException if the dataset cannot be read. */ public static void write(IDataSet dataSet, OutputStream out) throws DataSetException @@ -103,6 +112,10 @@ public static void write(IDataSet dataSet, OutputStream out) /** * Write the specified dataset to the specified writer as YAML. + * + * @param dataSet the dataset to write. + * @param out the writer to write the YAML document to. + * @throws DataSetException if the dataset cannot be read. */ public static void write(IDataSet dataSet, Writer out) throws DataSetException diff --git a/src/main/java/org/dbunit/dataset/yaml/YamlProducer.java b/src/main/java/org/dbunit/dataset/yaml/YamlProducer.java index 1ff37d580..6eb97fc45 100644 --- a/src/main/java/org/dbunit/dataset/yaml/YamlProducer.java +++ b/src/main/java/org/dbunit/dataset/yaml/YamlProducer.java @@ -67,11 +67,22 @@ public class YamlProducer implements IDataSetProducer private Yaml _yaml; + /** + * Creates a producer reading YAML from the given file. + * + * @param file the YAML file to read. + * @throws IOException if the file cannot be opened. + */ public YamlProducer(File file) throws IOException { this(new FileInputStream(file)); } + /** + * Creates a producer reading YAML from the given stream. + * + * @param inputStream the stream to read YAML from. + */ public YamlProducer(InputStream inputStream) { this._inputStream = inputStream; diff --git a/src/main/java/org/dbunit/ext/db2/Db2Connection.java b/src/main/java/org/dbunit/ext/db2/Db2Connection.java index 3d8dd98ab..0c59d7a10 100644 --- a/src/main/java/org/dbunit/ext/db2/Db2Connection.java +++ b/src/main/java/org/dbunit/ext/db2/Db2Connection.java @@ -39,6 +39,14 @@ public class Db2Connection extends DatabaseConnection { + /** + * Creates a DB2 connection, pre-configuring the DB2-specific data type factory and + * metadata handler. + * + * @param connection the adapted JDBC connection. + * @param schema the database schema. + * @throws DatabaseUnitException if the connection cannot be adapted. + */ public Db2Connection(Connection connection, String schema) throws DatabaseUnitException { super(connection, schema); diff --git a/src/main/java/org/dbunit/ext/db2/Db2MetadataHandler.java b/src/main/java/org/dbunit/ext/db2/Db2MetadataHandler.java index e19e03cbc..601844c98 100644 --- a/src/main/java/org/dbunit/ext/db2/Db2MetadataHandler.java +++ b/src/main/java/org/dbunit/ext/db2/Db2MetadataHandler.java @@ -42,6 +42,9 @@ public class Db2MetadataHandler extends DefaultMetadataHandler { private static final Logger logger = LoggerFactory.getLogger(Db2MetadataHandler.class); + /** + * Default constructor. + */ public Db2MetadataHandler() { super(); } diff --git a/src/main/java/org/dbunit/ext/h2/H2Connection.java b/src/main/java/org/dbunit/ext/h2/H2Connection.java index 1c3f03827..c46418a04 100644 --- a/src/main/java/org/dbunit/ext/h2/H2Connection.java +++ b/src/main/java/org/dbunit/ext/h2/H2Connection.java @@ -37,6 +37,13 @@ */ public class H2Connection extends DatabaseConnection { + /** + * Creates an H2 connection, pre-configuring the H2-specific data type factory. + * + * @param connection the adapted JDBC connection. + * @param schema the database schema. + * @throws DatabaseUnitException if the connection cannot be adapted. + */ public H2Connection(Connection connection, String schema) throws DatabaseUnitException { super(connection, schema); diff --git a/src/main/java/org/dbunit/ext/hsqldb/HsqldbConnection.java b/src/main/java/org/dbunit/ext/hsqldb/HsqldbConnection.java index 71ea1fde9..85f8dc09e 100644 --- a/src/main/java/org/dbunit/ext/hsqldb/HsqldbConnection.java +++ b/src/main/java/org/dbunit/ext/hsqldb/HsqldbConnection.java @@ -37,6 +37,13 @@ */ public class HsqldbConnection extends DatabaseConnection { + /** + * Creates an HSQLDB connection, pre-configuring the HSQLDB-specific data type factory. + * + * @param connection the adapted JDBC connection. + * @param schema the database schema. + * @throws DatabaseUnitException if the connection cannot be adapted. + */ public HsqldbConnection(Connection connection, String schema) throws DatabaseUnitException { super(connection, schema); diff --git a/src/main/java/org/dbunit/ext/mckoi/MckoiConnection.java b/src/main/java/org/dbunit/ext/mckoi/MckoiConnection.java index dcff5128f..549146210 100644 --- a/src/main/java/org/dbunit/ext/mckoi/MckoiConnection.java +++ b/src/main/java/org/dbunit/ext/mckoi/MckoiConnection.java @@ -39,6 +39,13 @@ public class MckoiConnection extends DatabaseConnection { + /** + * Creates a new MckoiConnection. + * + * @param connection the adapted JDBC connection. + * @param schema the database schema. + * @throws DatabaseUnitException if setting up the connection fails. + */ public MckoiConnection(Connection connection, String schema) throws DatabaseUnitException { super(connection, schema); diff --git a/src/main/java/org/dbunit/ext/mckoi/MckoiDataTypeFactory.java b/src/main/java/org/dbunit/ext/mckoi/MckoiDataTypeFactory.java index 9a9c643d6..2362d40d0 100644 --- a/src/main/java/org/dbunit/ext/mckoi/MckoiDataTypeFactory.java +++ b/src/main/java/org/dbunit/ext/mckoi/MckoiDataTypeFactory.java @@ -45,7 +45,6 @@ public class MckoiDataTypeFactory extends DefaultDataTypeFactory { */ private static final Logger logger = LoggerFactory.getLogger(MckoiDataTypeFactory.class); - /** * Database product names supported. */ @@ -59,7 +58,6 @@ public Collection getValidDbProducts() return DATABASE_PRODUCTS; } - public DataType createDataType(int sqlType, String sqlTypeName) throws DataTypeException { DataType retValue = super.createDataType(sqlType, sqlTypeName); @@ -103,5 +101,3 @@ public DataType createDataType(int sqlType, String sqlTypeName) throws DataTypeE } } - - diff --git a/src/main/java/org/dbunit/ext/mssql/DateTimeOffsetType.java b/src/main/java/org/dbunit/ext/mssql/DateTimeOffsetType.java index 3ffb82707..5559a9b56 100644 --- a/src/main/java/org/dbunit/ext/mssql/DateTimeOffsetType.java +++ b/src/main/java/org/dbunit/ext/mssql/DateTimeOffsetType.java @@ -40,12 +40,16 @@ */ public class DateTimeOffsetType extends AbstractDataType { + /** JDBC SQL type code for Microsoft SQL Server's DATETIMEOFFSET type. */ public static final int TYPE = -155; /** @see https://docs.microsoft.com/en-us/sql/t-sql/data-types/datetimeoffset-transact-sql?view=sql-server-2017 */ private static final DateTimeFormatter SQL_SERVER_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss[.n] xxx"); + /** + * Default constructor. + */ public DateTimeOffsetType() { super("datetimeoffset", TYPE, OffsetDateTime.class, false); diff --git a/src/main/java/org/dbunit/ext/mssql/InsertIdentityOperation.java b/src/main/java/org/dbunit/ext/mssql/InsertIdentityOperation.java index 915e29ad0..6a0bc14ca 100644 --- a/src/main/java/org/dbunit/ext/mssql/InsertIdentityOperation.java +++ b/src/main/java/org/dbunit/ext/mssql/InsertIdentityOperation.java @@ -69,13 +69,16 @@ public class InsertIdentityOperation extends AbstractOperation */ private static final Logger logger = LoggerFactory.getLogger(InsertIdentityOperation.class); + /** {@link DatabaseOperation#INSERT}, decorated to enable MS SQL identity insert. */ public static final DatabaseOperation INSERT = new InsertIdentityOperation(DatabaseOperation.INSERT); + /** {@link DatabaseOperation#DELETE_ALL} followed by {@link #INSERT}. */ public static final DatabaseOperation CLEAN_INSERT = new CompositeOperation(DatabaseOperation.DELETE_ALL, new InsertIdentityOperation(DatabaseOperation.INSERT)); + /** {@link DatabaseOperation#REFRESH}, decorated to enable MS SQL identity insert. */ public static final DatabaseOperation REFRESH = new InsertIdentityOperation(DatabaseOperation.REFRESH); @@ -124,6 +127,8 @@ public boolean accept(String tableName, Column column) /** * Creates a new InsertIdentityOperation object that decorates the * specified operation. + * + * @param operation the operation to decorate. */ public InsertIdentityOperation(DatabaseOperation operation) { diff --git a/src/main/java/org/dbunit/ext/mssql/MsSqlConnection.java b/src/main/java/org/dbunit/ext/mssql/MsSqlConnection.java index 997b4414b..ef6e54f44 100644 --- a/src/main/java/org/dbunit/ext/mssql/MsSqlConnection.java +++ b/src/main/java/org/dbunit/ext/mssql/MsSqlConnection.java @@ -59,7 +59,7 @@ public class MsSqlConnection extends DatabaseConnection * * @param connection the adapted JDBC connection * @param schema the database schema - * @throws DatabaseUnitException + * @throws DatabaseUnitException if setting up the connection fails. */ public MsSqlConnection(Connection connection, String schema) throws DatabaseUnitException { @@ -72,7 +72,7 @@ public MsSqlConnection(Connection connection, String schema) throws DatabaseUnit * Creates a new MsSqlConnection. * * @param connection the adapted JDBC connection - * @throws DatabaseUnitException + * @throws DatabaseUnitException if setting up the connection fails. */ public MsSqlConnection(Connection connection) throws DatabaseUnitException { diff --git a/src/main/java/org/dbunit/ext/mssql/MsSqlDataTypeFactory.java b/src/main/java/org/dbunit/ext/mssql/MsSqlDataTypeFactory.java index 5f3ea9ce6..41a4faa42 100644 --- a/src/main/java/org/dbunit/ext/mssql/MsSqlDataTypeFactory.java +++ b/src/main/java/org/dbunit/ext/mssql/MsSqlDataTypeFactory.java @@ -51,11 +51,15 @@ public class MsSqlDataTypeFactory extends DefaultDataTypeFactory private static final DateTimeOffsetType DATE_TIME_OFFSET_TYPE = new DateTimeOffsetType(); + /** JDBC type code for MS SQL Server's nchar type. */ public static final int NCHAR = -8; + /** JDBC type code for MS SQL Server's nvarchar type. */ public static final int NVARCHAR = -9; + /** JDBC type code for MS SQL Server's ntext type. */ public static final int NTEXT = -10; + /** JDBC type code for MS SQL Server 2005's ntext type. */ public static final int NTEXT_MSSQL_2005 = -16; - + /** * @see org.dbunit.dataset.datatype.IDbProductRelatable#getValidDbProducts() */ diff --git a/src/main/java/org/dbunit/ext/mssql/UniqueIdentifierType.java b/src/main/java/org/dbunit/ext/mssql/UniqueIdentifierType.java index 79c567492..3e63af181 100644 --- a/src/main/java/org/dbunit/ext/mssql/UniqueIdentifierType.java +++ b/src/main/java/org/dbunit/ext/mssql/UniqueIdentifierType.java @@ -39,6 +39,9 @@ public class UniqueIdentifierType extends AbstractDataType { static final String UNIQUE_IDENTIFIER_TYPE = "uniqueidentifier"; + /** + * Default constructor. + */ public UniqueIdentifierType() { super(UNIQUE_IDENTIFIER_TYPE, Types.CHAR, UUID.class, false); } diff --git a/src/main/java/org/dbunit/ext/mysql/MySqlConnection.java b/src/main/java/org/dbunit/ext/mysql/MySqlConnection.java index 60f0fde0d..19fdc6578 100644 --- a/src/main/java/org/dbunit/ext/mysql/MySqlConnection.java +++ b/src/main/java/org/dbunit/ext/mysql/MySqlConnection.java @@ -36,6 +36,13 @@ */ public class MySqlConnection extends DatabaseConnection { + /** + * Creates a new MySqlConnection. + * + * @param connection the adapted JDBC connection. + * @param schema the database schema. + * @throws DatabaseUnitException if setting up the connection fails. + */ public MySqlConnection(Connection connection, String schema) throws DatabaseUnitException { super(connection, schema); diff --git a/src/main/java/org/dbunit/ext/mysql/MySqlDataTypeFactory.java b/src/main/java/org/dbunit/ext/mysql/MySqlDataTypeFactory.java index ae388af3b..7248812f8 100644 --- a/src/main/java/org/dbunit/ext/mysql/MySqlDataTypeFactory.java +++ b/src/main/java/org/dbunit/ext/mysql/MySqlDataTypeFactory.java @@ -40,7 +40,9 @@ */ public class MySqlDataTypeFactory extends DefaultDataTypeFactory { + /** Suffix MySQL appends to unsigned numeric type names, e.g. "INT UNSIGNED". */ public static final String UNSIGNED_SUFFIX = " UNSIGNED"; + /** SQL type name reported by MySQL for an unsigned TINYINT column. */ public static final String SQL_TYPE_NAME_TINYINT_UNSIGNED = "TINYINT" + UNSIGNED_SUFFIX; /** @@ -51,6 +53,7 @@ public class MySqlDataTypeFactory extends DefaultDataTypeFactory * Database product names supported. */ private static final Collection DATABASE_PRODUCTS = Arrays.asList(new String[] {"mysql"}); + /** * @see org.dbunit.dataset.datatype.IDbProductRelatable#getValidDbProducts() */ @@ -87,7 +90,6 @@ else if("bit".equalsIgnoreCase(sqlTypeName)) return DataType.TINYINT; } - // Special handling for "TINYINT UNSIGNED" if(SQL_TYPE_NAME_TINYINT_UNSIGNED.equalsIgnoreCase(sqlTypeName)){ return DataType.TINYINT; // It is a bit of a waste here - we could better use a "Short" instead of an "Integer" type diff --git a/src/main/java/org/dbunit/ext/netezza/NetezzaDataTypeFactory.java b/src/main/java/org/dbunit/ext/netezza/NetezzaDataTypeFactory.java index f89bcc927..e43c4431a 100644 --- a/src/main/java/org/dbunit/ext/netezza/NetezzaDataTypeFactory.java +++ b/src/main/java/org/dbunit/ext/netezza/NetezzaDataTypeFactory.java @@ -42,32 +42,59 @@ public class NetezzaDataTypeFactory extends DefaultDataTypeFactory */ private static final Logger logger = LoggerFactory.getLogger(NetezzaDataTypeFactory.class); + /** JDBC type code for Netezza's RECADDR type. */ public static final int RECADDR = 1; + /** JDBC type code for Netezza's NUMERIC type. */ public static final int NUMERIC = 2; + /** JDBC type code for Netezza's DECIMAL type. */ public static final int DECIMAL = 3; + /** JDBC type code for Netezza's INTEGER type. */ public static final int INTEGER = 4; + /** JDBC type code for Netezza's SMALLINT type. */ public static final int SMALLINT = 5; + /** JDBC type code for Netezza's DOUBLE type. */ public static final int DOUBLE = 8; + /** JDBC type code for Netezza's INTERVAL type. */ public static final int INTERVAL = 10; + /** JDBC type code for Netezza's BOOLEAN type. */ public static final int BOOLEAN = -7; + /** JDBC type code for Netezza's CHAR type. */ public static final int CHAR = -1; + /** JDBC type code for Netezza's FLOAT type. */ public static final int FLOAT = 6; + /** JDBC type code for Netezza's REAL type. */ public static final int REAL = 7; + /** JDBC type code for Netezza's VARCHAR type. */ public static final int VARCHAR = 12; + /** JDBC type code for Netezza's DATE type. */ public static final int DATE = 91; + /** JDBC type code for Netezza's TIME type. */ public static final int TIME = 92; + /** JDBC type code for Netezza's TIMESTAMP type. */ public static final int TIMESTAMP = 93; + /** JDBC type code for Netezza's TIMETZ type. */ public static final int TIMETZ = 1266; + /** JDBC type code for Netezza's UNKNOWN type. */ public static final int UNKNOWN = 18; + /** JDBC type code for Netezza's BYTEINT type. */ public static final int BYTEINT = -6; + /** JDBC type code for Netezza's INT8 type. */ public static final int INT8 = 20; + /** JDBC type code for Netezza's VARFIXEDCHAR type. */ public static final int VARFIXEDCHAR = 21; + /** JDBC type code for Netezza's NUCL type. */ public static final int NUCL = 22; + /** JDBC type code for Netezza's PROT type. */ public static final int PROT = 23; + /** JDBC type code for Netezza's BLOB type. */ public static final int BLOB = 24; + /** JDBC type code for Netezza's BIGINT type. */ public static final int BIGINT = -5; + /** JDBC type code for Netezza's NCHAR type. */ public static final int NCHAR = -8; + /** JDBC type code for Netezza's NVARCHAR type. */ public static final int NVARCHAR = -9; + /** JDBC type code for Netezza's NTEXT type. */ public static final int NTEXT = 27; public DataType createDataType(int sqlType, String sqlTypeName) throws DataTypeException @@ -122,4 +149,3 @@ public DataType createDataType(int sqlType, String sqlTypeName) throws DataTypeE } } - diff --git a/src/main/java/org/dbunit/ext/netezza/NetezzaMetadataHandler.java b/src/main/java/org/dbunit/ext/netezza/NetezzaMetadataHandler.java index 72a1bd4d9..d7a99530d 100644 --- a/src/main/java/org/dbunit/ext/netezza/NetezzaMetadataHandler.java +++ b/src/main/java/org/dbunit/ext/netezza/NetezzaMetadataHandler.java @@ -45,6 +45,9 @@ public class NetezzaMetadataHandler implements IMetadataHandler */ private static final Logger logger = LoggerFactory.getLogger(NetezzaMetadataHandler.class); + /** + * Default constructor. + */ public NetezzaMetadataHandler() { logger.debug("Created object of metadatahandler"); diff --git a/src/main/java/org/dbunit/ext/oracle/Oracle10DataTypeFactory.java b/src/main/java/org/dbunit/ext/oracle/Oracle10DataTypeFactory.java index 582d1116a..6c476b493 100644 --- a/src/main/java/org/dbunit/ext/oracle/Oracle10DataTypeFactory.java +++ b/src/main/java/org/dbunit/ext/oracle/Oracle10DataTypeFactory.java @@ -50,8 +50,9 @@ public class Oracle10DataTypeFactory extends OracleDataTypeFactory */ private static final Logger logger = LoggerFactory.getLogger(Oracle10DataTypeFactory.class); - + /** Data type used for CLOB columns, handled as a character stream. */ protected static final DataType CLOB_AS_STRING = new StringDataType("CLOB", Types.CLOB); + /** Data type used for BLOB columns, handled as a binary stream. */ protected static final DataType BLOB_AS_STREAM = new BinaryStreamDataType("BLOB", Types.BLOB); public DataType createDataType(int sqlType, String sqlTypeName) throws DataTypeException diff --git a/src/main/java/org/dbunit/ext/oracle/OracleBlobDataType.java b/src/main/java/org/dbunit/ext/oracle/OracleBlobDataType.java index e4fa1e046..4c020a218 100644 --- a/src/main/java/org/dbunit/ext/oracle/OracleBlobDataType.java +++ b/src/main/java/org/dbunit/ext/oracle/OracleBlobDataType.java @@ -103,7 +103,6 @@ private Object getBlob(Object value, Connection connection) throws TypeCastExcep return tempBlob; } - private void freeTemporaryBlob(oracle.sql.BLOB tempBlob) throws TypeCastException { logger.debug("freeTemporaryBlob(tempBlob={}) - start", tempBlob); diff --git a/src/main/java/org/dbunit/ext/oracle/OracleClobDataType.java b/src/main/java/org/dbunit/ext/oracle/OracleClobDataType.java index 78bf740dd..4d923bb48 100644 --- a/src/main/java/org/dbunit/ext/oracle/OracleClobDataType.java +++ b/src/main/java/org/dbunit/ext/oracle/OracleClobDataType.java @@ -71,6 +71,14 @@ public void setSqlValue(final Object value, final int column, statement.setObject(column, getClob(value, statement.getConnection())); } + /** + * Writes the given value into a temporary CLOB on the given connection. + * + * @param value the value to write, cast to a String. + * @param connection the connection to create the temporary CLOB on. + * @return the populated temporary CLOB. + * @throws TypeCastException if the value cannot be cast or writing fails. + */ protected Object getClob(final Object value, final Connection connection) throws TypeCastException { diff --git a/src/main/java/org/dbunit/ext/oracle/OracleConnection.java b/src/main/java/org/dbunit/ext/oracle/OracleConnection.java index ef25eceb7..dc4a2b644 100644 --- a/src/main/java/org/dbunit/ext/oracle/OracleConnection.java +++ b/src/main/java/org/dbunit/ext/oracle/OracleConnection.java @@ -40,9 +40,9 @@ public class OracleConnection extends DatabaseConnection /** * Creates a oracle connection. Beware that the given schema is passed in to the parent class * as "upper case" string. - * @param connection + * @param connection the adapted JDBC connection. * @param schema The schema name - * @throws DatabaseUnitException + * @throws DatabaseUnitException if setting up the connection fails. */ public OracleConnection(Connection connection, String schema) throws DatabaseUnitException { diff --git a/src/main/java/org/dbunit/ext/oracle/OracleDataTypeFactory.java b/src/main/java/org/dbunit/ext/oracle/OracleDataTypeFactory.java index 9730a1197..3024dbfe6 100644 --- a/src/main/java/org/dbunit/ext/oracle/OracleDataTypeFactory.java +++ b/src/main/java/org/dbunit/ext/oracle/OracleDataTypeFactory.java @@ -50,15 +50,22 @@ public class OracleDataTypeFactory extends DefaultDataTypeFactory */ private static final Collection DATABASE_PRODUCTS = Arrays.asList(new String[] {"oracle"}); + /** Data type for Oracle BLOB columns. */ public static final DataType ORACLE_BLOB = new OracleBlobDataType(); + /** Data type for Oracle CLOB columns. */ public static final DataType ORACLE_CLOB = new OracleClobDataType(); + /** Data type for Oracle NCLOB columns. */ public static final DataType ORACLE_NCLOB = new OracleNClobDataType(); + /** Data type for Oracle XMLTYPE columns. */ public static final DataType ORACLE_XMLTYPE = new OracleXMLTypeDataType(); + /** Data type for Oracle SDO_GEOMETRY columns. */ public static final DataType ORACLE_SDO_GEOMETRY_TYPE = new OracleSdoGeometryDataType(); - + + /** Data type for Oracle LONG RAW columns. */ public static final DataType LONG_RAW = new BinaryStreamDataType( "LONG RAW", Types.LONGVARBINARY); - + + /** Data type for Oracle ROWID columns. */ public static final DataType ROWID_TYPE = new StringDataType("ROWID", Types.OTHER); /** @@ -163,4 +170,3 @@ public DataType createDataType(int sqlType, String sqlTypeName) throws DataTypeE } } - diff --git a/src/main/java/org/dbunit/ext/oracle/OracleSdoElemInfoArray.java b/src/main/java/org/dbunit/ext/oracle/OracleSdoElemInfoArray.java index 013b8623a..7473ec130 100644 --- a/src/main/java/org/dbunit/ext/oracle/OracleSdoElemInfoArray.java +++ b/src/main/java/org/dbunit/ext/oracle/OracleSdoElemInfoArray.java @@ -42,21 +42,36 @@ */ public class OracleSdoElemInfoArray implements ORAData, ORADataFactory { + /** The Oracle SQL type name backing this array, MDSYS.SDO_ELEM_INFO_ARRAY. */ public static final String _SQL_NAME = "MDSYS.SDO_ELEM_INFO_ARRAY"; + /** The Oracle JDBC type code backing this array, {@link OracleTypes#ARRAY}. */ public static final int _SQL_TYPECODE = OracleTypes.ARRAY; MutableArray _array; private static final OracleSdoElemInfoArray _OracleSdoElemInfoArrayFactory = new OracleSdoElemInfoArray(); + /** + * Returns the shared {@link ORADataFactory} for this class. + * + * @return the shared {@link ORADataFactory} for this class. + */ public static ORADataFactory getORADataFactory() { return _OracleSdoElemInfoArrayFactory; } /* constructors */ + /** + * Default constructor. + */ public OracleSdoElemInfoArray() { this((java.math.BigDecimal[])null); } + /** + * Constructs an array wrapping the given elements. + * + * @param a the element values. + */ public OracleSdoElemInfoArray(java.math.BigDecimal[] a) { _array = new MutableArray(2, a, null); @@ -71,58 +86,123 @@ public Datum toDatum(Connection c) throws SQLException /* ORADataFactory interface */ public ORAData create(Datum d, int sqlType) throws SQLException { - if (d == null) return null; + if (d == null) return null; OracleSdoElemInfoArray a = new OracleSdoElemInfoArray(); a._array = new MutableArray(2, (ARRAY) d, null); return a; } + /** + * Returns the number of elements in the array. + * + * @return the number of elements in the array. + * @throws SQLException if the underlying array cannot be read. + */ public int length() throws SQLException { return _array.length(); } + /** + * Returns the JDBC type code of the array's base element type. + * + * @return the JDBC type code of the array's base element type. + * @throws SQLException if the underlying array cannot be read. + */ public int getBaseType() throws SQLException { return _array.getBaseType(); } + /** + * Returns the SQL type name of the array's base element type. + * + * @return the SQL type name of the array's base element type. + * @throws SQLException if the underlying array cannot be read. + */ public String getBaseTypeName() throws SQLException { return _array.getBaseTypeName(); } + /** + * Returns the descriptor of the underlying Oracle array. + * + * @return the descriptor of the underlying Oracle array. + * @throws SQLException if the underlying array cannot be read. + */ public ArrayDescriptor getDescriptor() throws SQLException { return _array.getDescriptor(); } /* array accessor methods */ + /** + * Returns the array's elements. + * + * @return the array's elements. + * @throws SQLException if the underlying array cannot be read. + */ public java.math.BigDecimal[] getArray() throws SQLException { return (java.math.BigDecimal[]) _array.getObjectArray(); } + /** + * Returns a range of the array's elements. + * + * @param index the index of the first element to return. + * @param count the number of elements to return. + * @return the requested range of the array's elements. + * @throws SQLException if the underlying array cannot be read. + */ public java.math.BigDecimal[] getArray(long index, int count) throws SQLException { return (java.math.BigDecimal[]) _array.getObjectArray(index, count); } + /** + * Replaces the array's elements. + * + * @param a the new element values. + * @throws SQLException if the underlying array cannot be written. + */ public void setArray(java.math.BigDecimal[] a) throws SQLException { _array.setObjectArray(a); } + /** + * Replaces a range of the array's elements starting at the given index. + * + * @param a the new element values. + * @param index the index of the first element to replace. + * @throws SQLException if the underlying array cannot be written. + */ public void setArray(java.math.BigDecimal[] a, long index) throws SQLException { _array.setObjectArray(a, index); } + /** + * Returns a single element of the array. + * + * @param index the index of the element to return. + * @return the element at the given index. + * @throws SQLException if the underlying array cannot be read. + */ public java.math.BigDecimal getElement(long index) throws SQLException { return (java.math.BigDecimal) _array.getObjectElement(index); } + /** + * Replaces a single element of the array. + * + * @param a the new element value. + * @param index the index of the element to replace. + * @throws SQLException if the underlying array cannot be written. + */ public void setElement(java.math.BigDecimal a, long index) throws SQLException { _array.setObjectElement(a, index); diff --git a/src/main/java/org/dbunit/ext/oracle/OracleSdoGeometry.java b/src/main/java/org/dbunit/ext/oracle/OracleSdoGeometry.java index 4b2124fc6..a3af97a66 100644 --- a/src/main/java/org/dbunit/ext/oracle/OracleSdoGeometry.java +++ b/src/main/java/org/dbunit/ext/oracle/OracleSdoGeometry.java @@ -41,12 +41,17 @@ */ public class OracleSdoGeometry implements ORAData, ORADataFactory { + /** The Oracle SQL type name backing this struct, MDSYS.SDO_GEOMETRY. */ public static final String _SQL_NAME = "MDSYS.SDO_GEOMETRY"; + /** The Oracle JDBC type code backing this struct, {@link OracleTypes#STRUCT}. */ public static final int _SQL_TYPECODE = OracleTypes.STRUCT; + /** The underlying mutable struct holding this geometry's attribute values. */ protected MutableStruct _struct; + /** The JDBC type codes of this struct's attributes, in declaration order. */ protected static int[] _sqlType = { 2,2,2002,2003,2003 }; + /** The {@link ORADataFactory} for each struct-typed attribute, indexed by attribute position. */ protected static ORADataFactory[] _factory = new ORADataFactory[5]; static { @@ -54,15 +59,39 @@ public class OracleSdoGeometry implements ORAData, ORADataFactory _factory[3] = OracleSdoElemInfoArray.getORADataFactory(); _factory[4] = OracleSdoOrdinateArray.getORADataFactory(); } + /** The shared {@link ORADataFactory} instance for this class. */ protected static final OracleSdoGeometry _OracleSdoGeometryFactory = new OracleSdoGeometry(); + /** + * Returns the shared {@link ORADataFactory} for this class. + * + * @return the shared {@link ORADataFactory} for this class. + */ public static ORADataFactory getORADataFactory() { return _OracleSdoGeometryFactory; } /* constructors */ + /** + * Initializes {@link #_struct} when requested. + * + * @param init {@code true} to (re)create {@link #_struct}. + */ protected void _init_struct(boolean init) { if (init) _struct = new MutableStruct(new Object[5], _sqlType, _factory); } + /** + * Default constructor. + */ public OracleSdoGeometry() { _init_struct(true); } + /** + * Constructs a geometry with the given attribute values. + * + * @param sdoGtype the SDO_GTYPE attribute. + * @param sdoSrid the SDO_SRID attribute. + * @param sdoPoint the SDO_POINT attribute. + * @param sdoElemInfo the SDO_ELEM_INFO attribute. + * @param sdoOrdinates the SDO_ORDINATES attribute. + * @throws SQLException if setting an attribute fails. + */ public OracleSdoGeometry(java.math.BigDecimal sdoGtype, java.math.BigDecimal sdoSrid, OracleSdoPointType sdoPoint, OracleSdoElemInfoArray sdoElemInfo, OracleSdoOrdinateArray sdoOrdinates) throws SQLException { _init_struct(true); setSdoGtype(sdoGtype); @@ -82,45 +111,114 @@ public Datum toDatum(Connection c) throws SQLException /* ORADataFactory interface */ public ORAData create(Datum d, int sqlType) throws SQLException { return create(null, d, sqlType); } + /** + * Populates (or creates) an {@code OracleSdoGeometry} from the given datum. + * + * @param o the instance to populate, or {@code null} to create a new one. + * @param d the source datum, or {@code null} to return {@code null}. + * @param sqlType the JDBC type code of the source datum. + * @return the populated instance, or {@code null} if {@code d} is {@code null}. + * @throws SQLException if reading the datum fails. + */ protected ORAData create(OracleSdoGeometry o, Datum d, int sqlType) throws SQLException { - if (d == null) return null; + if (d == null) return null; if (o == null) o = new OracleSdoGeometry(); o._struct = new MutableStruct((STRUCT) d, _sqlType, _factory); return o; } /* accessor methods */ + /** + * Returns the SDO_GTYPE attribute. + * + * @return the SDO_GTYPE attribute. + * @throws SQLException if the underlying struct cannot be read. + */ public java.math.BigDecimal getSdoGtype() throws SQLException { return (java.math.BigDecimal) _struct.getAttribute(0); } + /** + * Sets the SDO_GTYPE attribute. + * + * @param sdoGtype the new SDO_GTYPE attribute value. + * @throws SQLException if the underlying struct cannot be written. + */ public void setSdoGtype(java.math.BigDecimal sdoGtype) throws SQLException { _struct.setAttribute(0, sdoGtype); } + /** + * Returns the SDO_SRID attribute. + * + * @return the SDO_SRID attribute. + * @throws SQLException if the underlying struct cannot be read. + */ public java.math.BigDecimal getSdoSrid() throws SQLException { return (java.math.BigDecimal) _struct.getAttribute(1); } + /** + * Sets the SDO_SRID attribute. + * + * @param sdoSrid the new SDO_SRID attribute value. + * @throws SQLException if the underlying struct cannot be written. + */ public void setSdoSrid(java.math.BigDecimal sdoSrid) throws SQLException { _struct.setAttribute(1, sdoSrid); } + /** + * Returns the SDO_POINT attribute. + * + * @return the SDO_POINT attribute. + * @throws SQLException if the underlying struct cannot be read. + */ public OracleSdoPointType getSdoPoint() throws SQLException { return (OracleSdoPointType) _struct.getAttribute(2); } + /** + * Sets the SDO_POINT attribute. + * + * @param sdoPoint the new SDO_POINT attribute value. + * @throws SQLException if the underlying struct cannot be written. + */ public void setSdoPoint(OracleSdoPointType sdoPoint) throws SQLException { _struct.setAttribute(2, sdoPoint); } + /** + * Returns the SDO_ELEM_INFO attribute. + * + * @return the SDO_ELEM_INFO attribute. + * @throws SQLException if the underlying struct cannot be read. + */ public OracleSdoElemInfoArray getSdoElemInfo() throws SQLException { return (OracleSdoElemInfoArray) _struct.getAttribute(3); } + /** + * Sets the SDO_ELEM_INFO attribute. + * + * @param sdoElemInfo the new SDO_ELEM_INFO attribute value. + * @throws SQLException if the underlying struct cannot be written. + */ public void setSdoElemInfo(OracleSdoElemInfoArray sdoElemInfo) throws SQLException { _struct.setAttribute(3, sdoElemInfo); } + /** + * Returns the SDO_ORDINATES attribute. + * + * @return the SDO_ORDINATES attribute. + * @throws SQLException if the underlying struct cannot be read. + */ public OracleSdoOrdinateArray getSdoOrdinates() throws SQLException { return (OracleSdoOrdinateArray) _struct.getAttribute(4); } + /** + * Sets the SDO_ORDINATES attribute. + * + * @param sdoOrdinates the new SDO_ORDINATES attribute value. + * @throws SQLException if the underlying struct cannot be written. + */ public void setSdoOrdinates(OracleSdoOrdinateArray sdoOrdinates) throws SQLException { _struct.setAttribute(4, sdoOrdinates); } diff --git a/src/main/java/org/dbunit/ext/oracle/OracleSdoOrdinateArray.java b/src/main/java/org/dbunit/ext/oracle/OracleSdoOrdinateArray.java index 297deaef3..ef73dc76f 100644 --- a/src/main/java/org/dbunit/ext/oracle/OracleSdoOrdinateArray.java +++ b/src/main/java/org/dbunit/ext/oracle/OracleSdoOrdinateArray.java @@ -42,21 +42,36 @@ */ public class OracleSdoOrdinateArray implements ORAData, ORADataFactory { + /** The Oracle SQL type name backing this array, MDSYS.SDO_ORDINATE_ARRAY. */ public static final String _SQL_NAME = "MDSYS.SDO_ORDINATE_ARRAY"; + /** The Oracle JDBC type code backing this array, {@link OracleTypes#ARRAY}. */ public static final int _SQL_TYPECODE = OracleTypes.ARRAY; MutableArray _array; private static final OracleSdoOrdinateArray _OracleSdoOrdinateArrayFactory = new OracleSdoOrdinateArray(); + /** + * Returns the shared {@link ORADataFactory} for this class. + * + * @return the shared {@link ORADataFactory} for this class. + */ public static ORADataFactory getORADataFactory() { return _OracleSdoOrdinateArrayFactory; } /* constructors */ + /** + * Default constructor. + */ public OracleSdoOrdinateArray() { this((java.math.BigDecimal[])null); } + /** + * Constructs an array wrapping the given elements. + * + * @param a the element values. + */ public OracleSdoOrdinateArray(java.math.BigDecimal[] a) { _array = new MutableArray(2, a, null); @@ -71,58 +86,123 @@ public Datum toDatum(Connection c) throws SQLException /* ORADataFactory interface */ public ORAData create(Datum d, int sqlType) throws SQLException { - if (d == null) return null; + if (d == null) return null; OracleSdoOrdinateArray a = new OracleSdoOrdinateArray(); a._array = new MutableArray(2, (ARRAY) d, null); return a; } + /** + * Returns the number of elements in the array. + * + * @return the number of elements in the array. + * @throws SQLException if the underlying array cannot be read. + */ public int length() throws SQLException { return _array.length(); } + /** + * Returns the JDBC type code of the array's base element type. + * + * @return the JDBC type code of the array's base element type. + * @throws SQLException if the underlying array cannot be read. + */ public int getBaseType() throws SQLException { return _array.getBaseType(); } + /** + * Returns the SQL type name of the array's base element type. + * + * @return the SQL type name of the array's base element type. + * @throws SQLException if the underlying array cannot be read. + */ public String getBaseTypeName() throws SQLException { return _array.getBaseTypeName(); } + /** + * Returns the descriptor of the underlying Oracle array. + * + * @return the descriptor of the underlying Oracle array. + * @throws SQLException if the underlying array cannot be read. + */ public ArrayDescriptor getDescriptor() throws SQLException { return _array.getDescriptor(); } /* array accessor methods */ + /** + * Returns the array's elements. + * + * @return the array's elements. + * @throws SQLException if the underlying array cannot be read. + */ public java.math.BigDecimal[] getArray() throws SQLException { return (java.math.BigDecimal[]) _array.getObjectArray(); } + /** + * Returns a range of the array's elements. + * + * @param index the index of the first element to return. + * @param count the number of elements to return. + * @return the requested range of the array's elements. + * @throws SQLException if the underlying array cannot be read. + */ public java.math.BigDecimal[] getArray(long index, int count) throws SQLException { return (java.math.BigDecimal[]) _array.getObjectArray(index, count); } + /** + * Replaces the array's elements. + * + * @param a the new element values. + * @throws SQLException if the underlying array cannot be written. + */ public void setArray(java.math.BigDecimal[] a) throws SQLException { _array.setObjectArray(a); } + /** + * Replaces a range of the array's elements starting at the given index. + * + * @param a the new element values. + * @param index the index of the first element to replace. + * @throws SQLException if the underlying array cannot be written. + */ public void setArray(java.math.BigDecimal[] a, long index) throws SQLException { _array.setObjectArray(a, index); } + /** + * Returns a single element of the array. + * + * @param index the index of the element to return. + * @return the element at the given index. + * @throws SQLException if the underlying array cannot be read. + */ public java.math.BigDecimal getElement(long index) throws SQLException { return (java.math.BigDecimal) _array.getObjectElement(index); } + /** + * Replaces a single element of the array. + * + * @param a the new element value. + * @param index the index of the element to replace. + * @throws SQLException if the underlying array cannot be written. + */ public void setElement(java.math.BigDecimal a, long index) throws SQLException { _array.setObjectElement(a, index); diff --git a/src/main/java/org/dbunit/ext/oracle/OracleSdoPointType.java b/src/main/java/org/dbunit/ext/oracle/OracleSdoPointType.java index 6454e4009..c9827f180 100644 --- a/src/main/java/org/dbunit/ext/oracle/OracleSdoPointType.java +++ b/src/main/java/org/dbunit/ext/oracle/OracleSdoPointType.java @@ -41,22 +41,49 @@ */ public class OracleSdoPointType implements ORAData, ORADataFactory { + /** The Oracle SQL type name backing this struct, MDSYS.SDO_POINT_TYPE. */ public static final String _SQL_NAME = "MDSYS.SDO_POINT_TYPE"; + /** The Oracle JDBC type code backing this struct, {@link OracleTypes#STRUCT}. */ public static final int _SQL_TYPECODE = OracleTypes.STRUCT; + /** The underlying mutable struct holding this point's attribute values. */ protected MutableStruct _struct; + /** The JDBC type codes of this struct's attributes, in declaration order. */ protected static int[] _sqlType = { 2,2,2 }; + /** The {@link ORADataFactory} for each struct-typed attribute, indexed by attribute position. */ protected static ORADataFactory[] _factory = new ORADataFactory[3]; + /** The shared {@link ORADataFactory} instance for this class. */ protected static final OracleSdoPointType _OracleSdoPointTypeFactory = new OracleSdoPointType(); + /** + * Returns the shared {@link ORADataFactory} for this class. + * + * @return the shared {@link ORADataFactory} for this class. + */ public static ORADataFactory getORADataFactory() { return _OracleSdoPointTypeFactory; } /* constructors */ + /** + * Initializes {@link #_struct} when requested. + * + * @param init {@code true} to (re)create {@link #_struct}. + */ protected void _init_struct(boolean init) { if (init) _struct = new MutableStruct(new Object[3], _sqlType, _factory); } + /** + * Default constructor. + */ public OracleSdoPointType() { _init_struct(true); } + /** + * Constructs a point with the given coordinate values. + * + * @param x the X attribute. + * @param y the Y attribute. + * @param z the Z attribute. + * @throws SQLException if setting an attribute fails. + */ public OracleSdoPointType(java.math.BigDecimal x, java.math.BigDecimal y, java.math.BigDecimal z) throws SQLException { _init_struct(true); setX(x); @@ -74,31 +101,76 @@ public Datum toDatum(Connection c) throws SQLException /* ORADataFactory interface */ public ORAData create(Datum d, int sqlType) throws SQLException { return create(null, d, sqlType); } + /** + * Populates (or creates) an {@code OracleSdoPointType} from the given datum. + * + * @param o the instance to populate, or {@code null} to create a new one. + * @param d the source datum, or {@code null} to return {@code null}. + * @param sqlType the JDBC type code of the source datum. + * @return the populated instance, or {@code null} if {@code d} is {@code null}. + * @throws SQLException if reading the datum fails. + */ protected ORAData create(OracleSdoPointType o, Datum d, int sqlType) throws SQLException { - if (d == null) return null; + if (d == null) return null; if (o == null) o = new OracleSdoPointType(); o._struct = new MutableStruct((STRUCT) d, _sqlType, _factory); return o; } /* accessor methods */ + /** + * Returns the X attribute. + * + * @return the X attribute. + * @throws SQLException if the underlying struct cannot be read. + */ public java.math.BigDecimal getX() throws SQLException { return (java.math.BigDecimal) _struct.getAttribute(0); } + /** + * Sets the X attribute. + * + * @param x the new X attribute value. + * @throws SQLException if the underlying struct cannot be written. + */ public void setX(java.math.BigDecimal x) throws SQLException { _struct.setAttribute(0, x); } + /** + * Returns the Y attribute. + * + * @return the Y attribute. + * @throws SQLException if the underlying struct cannot be read. + */ public java.math.BigDecimal getY() throws SQLException { return (java.math.BigDecimal) _struct.getAttribute(1); } + /** + * Sets the Y attribute. + * + * @param y the new Y attribute value. + * @throws SQLException if the underlying struct cannot be written. + */ public void setY(java.math.BigDecimal y) throws SQLException { _struct.setAttribute(1, y); } + /** + * Returns the Z attribute. + * + * @return the Z attribute. + * @throws SQLException if the underlying struct cannot be read. + */ public java.math.BigDecimal getZ() throws SQLException { return (java.math.BigDecimal) _struct.getAttribute(2); } + /** + * Sets the Z attribute. + * + * @param z the new Z attribute value. + * @throws SQLException if the underlying struct cannot be written. + */ public void setZ(java.math.BigDecimal z) throws SQLException { _struct.setAttribute(2, z); } diff --git a/src/main/java/org/dbunit/ext/postgresql/CitextType.java b/src/main/java/org/dbunit/ext/postgresql/CitextType.java index 62954d20d..84ddd07eb 100644 --- a/src/main/java/org/dbunit/ext/postgresql/CitextType.java +++ b/src/main/java/org/dbunit/ext/postgresql/CitextType.java @@ -50,6 +50,9 @@ public class CitextType */ private static final Logger logger = LoggerFactory.getLogger(CitextType.class); + /** + * Default constructor. + */ public CitextType() { super("citext", Types.OTHER, String.class, false); } diff --git a/src/main/java/org/dbunit/ext/postgresql/GenericEnumType.java b/src/main/java/org/dbunit/ext/postgresql/GenericEnumType.java index 03914c766..5fef29b2f 100644 --- a/src/main/java/org/dbunit/ext/postgresql/GenericEnumType.java +++ b/src/main/java/org/dbunit/ext/postgresql/GenericEnumType.java @@ -54,10 +54,12 @@ public class GenericEnumType extends AbstractDataType { private final String sqlTypeName; /** + * Creates a data type adapter for the given Postgres enum type. + * * @param sqlTypeName The name of the enum type needed to invoke the "setType()" method on * the PGObject class. */ - public GenericEnumType(String sqlTypeName) + public GenericEnumType(String sqlTypeName) { super(sqlTypeName, Types.OTHER, String.class, false); diff --git a/src/main/java/org/dbunit/ext/postgresql/GeometryType.java b/src/main/java/org/dbunit/ext/postgresql/GeometryType.java index 90665ef92..58278ffd8 100644 --- a/src/main/java/org/dbunit/ext/postgresql/GeometryType.java +++ b/src/main/java/org/dbunit/ext/postgresql/GeometryType.java @@ -11,7 +11,16 @@ import org.dbunit.dataset.datatype.AbstractDataType; import org.dbunit.dataset.datatype.TypeCastException; +/** + * Adapter to handle conversion between PostGIS + * native geometry type and Strings. + * + * @since 2.4.6 + */ public class GeometryType extends AbstractDataType { + /** + * Default constructor. + */ public GeometryType() { super("geometry", Types.OTHER, String.class, false); } diff --git a/src/main/java/org/dbunit/ext/postgresql/InetType.java b/src/main/java/org/dbunit/ext/postgresql/InetType.java index 53dc08d0a..ab13733c6 100644 --- a/src/main/java/org/dbunit/ext/postgresql/InetType.java +++ b/src/main/java/org/dbunit/ext/postgresql/InetType.java @@ -48,6 +48,9 @@ public class InetType */ private static final Logger logger = LoggerFactory.getLogger(InetType.class); + /** + * Default constructor. + */ public InetType() { super("inet", Types.OTHER, String.class, false); } diff --git a/src/main/java/org/dbunit/ext/postgresql/IntervalType.java b/src/main/java/org/dbunit/ext/postgresql/IntervalType.java index 8f11d8952..3bc50eb6d 100644 --- a/src/main/java/org/dbunit/ext/postgresql/IntervalType.java +++ b/src/main/java/org/dbunit/ext/postgresql/IntervalType.java @@ -51,6 +51,9 @@ public class IntervalType extends AbstractDataType { private static final Logger logger = LoggerFactory.getLogger(IntervalType.class); + /** + * Default constructor. + */ public IntervalType() { super("interval", Types.OTHER, String.class, false); } diff --git a/src/main/java/org/dbunit/ext/postgresql/PostgreSQLOidDataType.java b/src/main/java/org/dbunit/ext/postgresql/PostgreSQLOidDataType.java index 943d056bc..f8fbe4c60 100644 --- a/src/main/java/org/dbunit/ext/postgresql/PostgreSQLOidDataType.java +++ b/src/main/java/org/dbunit/ext/postgresql/PostgreSQLOidDataType.java @@ -16,6 +16,11 @@ import java.sql.Statement; import java.sql.Types; +/** + * {@link BytesDataType} specialization for PostgreSQL's oid large object columns. + * + * @since 2.7.0 + */ public class PostgreSQLOidDataType extends BytesDataType { @@ -24,6 +29,9 @@ public class PostgreSQLOidDataType */ private static final Logger logger = LoggerFactory.getLogger(PostgreSQLOidDataType.class); + /** + * Default constructor. + */ public PostgreSQLOidDataType() { super("OID", Types.BIGINT); } diff --git a/src/main/java/org/dbunit/ext/postgresql/PostgresqlDataTypeFactory.java b/src/main/java/org/dbunit/ext/postgresql/PostgresqlDataTypeFactory.java index 662f75cc6..07f2d3b44 100644 --- a/src/main/java/org/dbunit/ext/postgresql/PostgresqlDataTypeFactory.java +++ b/src/main/java/org/dbunit/ext/postgresql/PostgresqlDataTypeFactory.java @@ -63,6 +63,11 @@ public Collection getValidDbProducts() return DATABASE_PRODUCTS; } + /** + * Returns the database product names supported by this factory. + * + * @return the database product names supported by this factory. + */ public static Collection getDatabaseProducts() { return DATABASE_PRODUCTS; diff --git a/src/main/java/org/dbunit/ext/postgresql/UuidType.java b/src/main/java/org/dbunit/ext/postgresql/UuidType.java index b5c7edc5e..e92d0c51f 100644 --- a/src/main/java/org/dbunit/ext/postgresql/UuidType.java +++ b/src/main/java/org/dbunit/ext/postgresql/UuidType.java @@ -50,6 +50,9 @@ public class UuidType */ private static final Logger logger = LoggerFactory.getLogger(UuidType.class); + /** + * Default constructor. + */ public UuidType() { super("uuid", Types.OTHER, String.class, false); } diff --git a/src/main/java/org/dbunit/operation/AbstractOperation.java b/src/main/java/org/dbunit/operation/AbstractOperation.java index 63e4c1167..90dddba62 100644 --- a/src/main/java/org/dbunit/operation/AbstractOperation.java +++ b/src/main/java/org/dbunit/operation/AbstractOperation.java @@ -51,6 +51,15 @@ public abstract class AbstractOperation extends DatabaseOperation */ private static final Logger logger = LoggerFactory.getLogger(AbstractOperation.class); + /** + * Qualifies the given table or column name with the given schema/catalog prefix, + * applying the connection's configured escape pattern. + * + * @param prefix the schema or catalog prefix. + * @param name the table or column name to qualify. + * @param connection the database connection providing the escape pattern configuration. + * @return the qualified name. + */ protected String getQualifiedName(String prefix, String name, IDatabaseConnection connection) { if (logger.isDebugEnabled()) diff --git a/src/main/java/org/dbunit/operation/CloseConnectionOperation.java b/src/main/java/org/dbunit/operation/CloseConnectionOperation.java index 7134d4758..7e237bae0 100644 --- a/src/main/java/org/dbunit/operation/CloseConnectionOperation.java +++ b/src/main/java/org/dbunit/operation/CloseConnectionOperation.java @@ -50,6 +50,8 @@ public class CloseConnectionOperation extends DatabaseOperation /** * Creates a CloseConnectionOperation object that decorates the specified * operation. + * + * @param operation the operation to decorate. */ public CloseConnectionOperation(DatabaseOperation operation) { diff --git a/src/main/java/org/dbunit/operation/CompositeOperation.java b/src/main/java/org/dbunit/operation/CompositeOperation.java index cea4d5c6b..ee0381643 100644 --- a/src/main/java/org/dbunit/operation/CompositeOperation.java +++ b/src/main/java/org/dbunit/operation/CompositeOperation.java @@ -51,6 +51,9 @@ public class CompositeOperation extends DatabaseOperation /** * Creates a new composite operation combining the two specified operations. + * + * @param action1 the first operation to execute. + * @param action2 the second operation to execute. */ public CompositeOperation(DatabaseOperation action1, DatabaseOperation action2) { @@ -59,6 +62,8 @@ public CompositeOperation(DatabaseOperation action1, DatabaseOperation action2) /** * Creates a new composite operation combining the specified operations. + * + * @param actions the operations to execute, in order. */ public CompositeOperation(DatabaseOperation[] actions) { diff --git a/src/main/java/org/dbunit/operation/DatabaseOperation.java b/src/main/java/org/dbunit/operation/DatabaseOperation.java index 7c887ce79..f2b1399b1 100644 --- a/src/main/java/org/dbunit/operation/DatabaseOperation.java +++ b/src/main/java/org/dbunit/operation/DatabaseOperation.java @@ -36,6 +36,7 @@ */ public abstract class DatabaseOperation { + /** * No-op that does nothing to the database. * @see DummyOperation diff --git a/src/main/java/org/dbunit/operation/DeleteAllOperation.java b/src/main/java/org/dbunit/operation/DeleteAllOperation.java index e7c54386b..91f331198 100644 --- a/src/main/java/org/dbunit/operation/DeleteAllOperation.java +++ b/src/main/java/org/dbunit/operation/DeleteAllOperation.java @@ -66,11 +66,24 @@ public class DeleteAllOperation extends AbstractOperation { } + /** + * Returns the SQL command prefix used to delete all rows of a table. + * + * @return the SQL command prefix used to delete all rows of a table. + */ protected String getDeleteAllCommand() { return "delete from "; } + /** + * Returns a suffix appended to the delete-all SQL statement for the given connection. + * The default implementation returns an empty string. + * + * @param connection the database connection the statement will be executed on. + * @return the SQL statement suffix. + * @throws SQLException if determining the suffix requires a database access that fails. + */ protected String getDeleteAllCommandSuffix(IDatabaseConnection connection) throws SQLException { return ""; diff --git a/src/main/java/org/dbunit/operation/ExclusiveTransactionException.java b/src/main/java/org/dbunit/operation/ExclusiveTransactionException.java index 60573ee49..e98bcd5bf 100644 --- a/src/main/java/org/dbunit/operation/ExclusiveTransactionException.java +++ b/src/main/java/org/dbunit/operation/ExclusiveTransactionException.java @@ -35,20 +35,43 @@ public class ExclusiveTransactionException extends DatabaseUnitException { private static final long serialVersionUID = 1L; + /** + * Constructs an ExclusiveTransactionException with no detail + * message and no encapsulated exception. + */ public ExclusiveTransactionException() { } + /** + * Constructs an ExclusiveTransactionException with the specified detail + * message and no encapsulated exception. + * + * @param msg the detail message. + */ public ExclusiveTransactionException(String msg) { super(msg); } + /** + * Constructs an ExclusiveTransactionException with the specified detail + * message and encapsulated exception. + * + * @param msg the detail message. + * @param e the encapsulated exception. + */ public ExclusiveTransactionException(String msg, Throwable e) { super(msg, e); } + /** + * Constructs an ExclusiveTransactionException with the encapsulated + * exception and use its message as detail message. + * + * @param e the encapsulated exception. + */ public ExclusiveTransactionException(Throwable e) { super(e); diff --git a/src/main/java/org/dbunit/operation/OperationData.java b/src/main/java/org/dbunit/operation/OperationData.java index 6010da5ea..7c046dc6d 100644 --- a/src/main/java/org/dbunit/operation/OperationData.java +++ b/src/main/java/org/dbunit/operation/OperationData.java @@ -39,8 +39,10 @@ public class OperationData private final Column[] _columns; /** - * @param sql - * @param columns + * Constructs an OperationData pairing the given SQL statement with its bound columns. + * + * @param sql the SQL statement. + * @param columns the columns whose values are bound as the statement's parameters. */ public OperationData(String sql, Column[] columns) { @@ -48,11 +50,21 @@ public OperationData(String sql, Column[] columns) _columns = columns; } + /** + * Returns the SQL statement. + * + * @return the SQL statement. + */ public String getSql() { return _sql; } + /** + * Returns the columns whose values are bound as the statement's parameters. + * + * @return the columns whose values are bound as the statement's parameters. + */ public Column[] getColumns() { return _columns; diff --git a/src/main/java/org/dbunit/operation/TransactionOperation.java b/src/main/java/org/dbunit/operation/TransactionOperation.java index f7dda7702..89ac3de45 100644 --- a/src/main/java/org/dbunit/operation/TransactionOperation.java +++ b/src/main/java/org/dbunit/operation/TransactionOperation.java @@ -49,6 +49,8 @@ public class TransactionOperation extends DatabaseOperation /** * Creates a TransactionOperation that decorates the specified operation. + * + * @param operation the operation to decorate. */ public TransactionOperation(DatabaseOperation operation) { diff --git a/src/main/java/org/dbunit/util/Base64.java b/src/main/java/org/dbunit/util/Base64.java index 9059ec492..8d43a08d0 100644 --- a/src/main/java/org/dbunit/util/Base64.java +++ b/src/main/java/org/dbunit/util/Base64.java @@ -132,7 +132,10 @@ private Base64() } - /** Testing. */ + /** + * Testing. + * @param args command-line arguments (unused). + */ public static void main(String[] args) { logger.debug("main(args=" + args + ") - start"); @@ -349,6 +352,7 @@ public static String encodeObject(java.io.Serializable serializableObject) * encodeBytes( source, 0, source.length ) * * @param source The data to convert + * @return the Base64-encoded string. * @since 1.4 */ public static String encodeBytes(byte[] source) @@ -366,6 +370,7 @@ public static String encodeBytes(byte[] source) * @param source The data to convert * @param off Offset in array where conversion should begin * @param len Length of data to convert + * @return the Base64-encoded string. * @since 1.4 */ public static String encodeBytes(byte[] source, int off, int len) diff --git a/src/main/java/org/dbunit/util/FileHelper.java b/src/main/java/org/dbunit/util/FileHelper.java index 08ec1024f..16352dc55 100644 --- a/src/main/java/org/dbunit/util/FileHelper.java +++ b/src/main/java/org/dbunit/util/FileHelper.java @@ -98,6 +98,13 @@ public static boolean deleteDirectory(File directory) return success; } + /** + * Creates an {@link InputSource} for the given file. + * + * @param file the file to create an {@link InputSource} for. + * @return the input source for the given file. + * @throws MalformedURLException if the file's path cannot be converted to a URL. + */ public static InputSource createInputSource(File file) throws MalformedURLException { String uri = file/*.getAbsoluteFile()*/.toURI().toURL().toString(); @@ -111,7 +118,7 @@ public static InputSource createInputSource(File file) throws MalformedURLExcept * * @param srcFile the src file * @param destFile the dest file - * @throws IOException + * @throws IOException if copying the file fails. */ public static void copyFile(File srcFile, File destFile) throws IOException { @@ -134,7 +141,7 @@ public static void copyFile(File srcFile, File destFile) throws IOException * * @param theFile the file to be read * @return a list of Strings, each one representing one line from the given file - * @throws IOException + * @throws IOException if the file cannot be read. */ public static List readLines(File theFile) throws IOException { diff --git a/src/main/java/org/dbunit/util/QualifiedTableName.java b/src/main/java/org/dbunit/util/QualifiedTableName.java index f447ca5e4..28ef68e05 100644 --- a/src/main/java/org/dbunit/util/QualifiedTableName.java +++ b/src/main/java/org/dbunit/util/QualifiedTableName.java @@ -105,6 +105,8 @@ private void parseFullTableName(String fullTableName, String defaultSchema) } /** + * Returns the schema name given in the constructor, if any. + * * @return The schema name which can be null if no schema has been given in the constructor */ public String getSchema() { @@ -112,6 +114,8 @@ public String getSchema() { } /** + * Returns the plain, unqualified table name. + * * @return The name of the plain, unqualified table */ public String getTable() { @@ -119,9 +123,11 @@ public String getTable() { } /** + * Returns the table name qualified with its schema, if any. + * * @return The qualified table name with the prepended schema if a schema is available */ - public String getQualifiedName() + public String getQualifiedName() { logger.debug("getQualifiedName() - start"); @@ -133,6 +139,7 @@ public String getQualifiedName() * The qualified table name is only returned if the feature * {@link DatabaseConfig#FEATURE_QUALIFIED_TABLE_NAMES} is set. Otherwise the given * name is returned unqualified (i.e. without prepending the prefix/schema). + * @param config the configuration providing the {@link DatabaseConfig#FEATURE_QUALIFIED_TABLE_NAMES} feature flag. * @return The qualified table name with the prepended schema if a schema is available. * The qualified table name is only returned if the feature * {@link DatabaseConfig#FEATURE_QUALIFIED_TABLE_NAMES} is set in the given config. diff --git a/src/main/java/org/dbunit/util/RelativeDateTimeParser.java b/src/main/java/org/dbunit/util/RelativeDateTimeParser.java index 7af6e7a75..f2d92f694 100644 --- a/src/main/java/org/dbunit/util/RelativeDateTimeParser.java +++ b/src/main/java/org/dbunit/util/RelativeDateTimeParser.java @@ -76,18 +76,32 @@ public class RelativeDateTimeParser private Clock clock; private LocalDateTime now; + /** + * Default constructor. + */ public RelativeDateTimeParser() { // Use fixed clock to provide consistent 'now' values. this(Clock.fixed(Instant.now(), ZoneId.systemDefault())); } + /** + * Constructs a parser resolving [now] relative to the given clock. + * + * @param clock the clock used to resolve [now]. + */ public RelativeDateTimeParser(Clock clock) { this.clock = clock; cacheLocalDateTime(clock); } + /** + * Parses a relative datetime expression such as [now-1d]. + * + * @param input the relative datetime expression to parse. + * @return the resolved date and time. + */ public LocalDateTime parse(String input) { if (input == null || input.isEmpty()) @@ -125,11 +139,21 @@ public LocalDateTime parse(String input) return datetime; } + /** + * Returns the clock used to resolve [now]. + * + * @return the clock used to resolve [now]. + */ public Clock getClock() { return clock; } + /** + * Sets the clock used to resolve [now]. + * + * @param clock the clock used to resolve [now]. + */ public void setClock(Clock clock) { this.clock = clock; diff --git a/src/main/java/org/dbunit/util/SQLHelper.java b/src/main/java/org/dbunit/util/SQLHelper.java index bb6b9f3e0..d94290104 100644 --- a/src/main/java/org/dbunit/util/SQLHelper.java +++ b/src/main/java/org/dbunit/util/SQLHelper.java @@ -115,8 +115,8 @@ public static void close(Statement stmt) throws SQLException { /** * Closes the given result set in a null-safe way - * @param resultSet - * @throws SQLException + * @param resultSet the result set to close, may be null. + * @throws SQLException if closing the result set fails. */ public static void close(ResultSet resultSet) throws SQLException { logger.debug("close(resultSet={}) - start", resultSet); @@ -131,7 +131,7 @@ public static void close(ResultSet resultSet) throws SQLException { * @param connection The connection to a database * @param schema The schema to be searched * @return Returns true if the given schema exists for the given connection. - * @throws SQLException + * @throws SQLException if a database access error occurs. * @since 2.3.0 */ public static boolean schemaExists(Connection connection, String schema) @@ -218,7 +218,7 @@ private static boolean catalogExists(Connection connection, String catalog) thro * @param tableName The table name to be searched * @return Returns true if the given table exists in the given schema. * Else returns false. - * @throws SQLException + * @throws SQLException if a database access error occurs. * @since 2.3.0 * @deprecated since 2.4.5 - use {@link IMetadataHandler#tableExists(DatabaseMetaData, String, String)} */ @@ -239,9 +239,9 @@ public static boolean tableExists(DatabaseMetaData metaData, String schema, /** * Utility method for debugging to print all tables of the given metadata on the given stream - * @param metaData - * @param outputStream - * @throws SQLException + * @param metaData the database metadata to print the tables of. + * @param outputStream the stream to print to. + * @throws SQLException if a database access error occurs. */ public static void printAllTables(DatabaseMetaData metaData, PrintStream outputStream) throws SQLException { @@ -344,7 +344,7 @@ public String wrappedCall(DatabaseMetaData metaData) throws Exception { * Prints the database and JDBC driver information to the given output stream * @param metaData The JDBC database metadata needed to retrieve database information * @param outputStream The stream to which the information is printed - * @throws SQLException + * @throws SQLException if a database access error occurs. */ public static void printDatabaseInfo(DatabaseMetaData metaData, PrintStream outputStream) throws SQLException { @@ -362,7 +362,7 @@ public static void printDatabaseInfo(DatabaseMetaData metaData, PrintStream outp * or not. * @param metaData The metadata to be checked whether it is a Sybase connection * @return true if and only if the given metadata belongs to a Sybase database. - * @throws SQLException + * @throws SQLException if a database access error occurs. */ public static boolean isSybaseDb(DatabaseMetaData metaData) throws SQLException { @@ -381,8 +381,8 @@ public static boolean isSybaseDb(DatabaseMetaData metaData) throws SQLException * be created because of an unknown datatype. * @return The {@link Column} or null if the column could not be initialized because of an * unknown datatype. - * @throws SQLException - * @throws DataTypeException + * @throws SQLException if a database access error occurs. + * @throws DataTypeException if the column's data type cannot be determined. * @since 2.4.0 */ public static final Column createColumn(ResultSet resultSet, @@ -440,7 +440,7 @@ public static final Column createColumn(ResultSet resultSet, * @param caseSensitive Whether or not the comparison should be case sensitive or not * @return true if the column metadata of the given resultSet matches * the given schema and table parameters. - * @throws SQLException + * @throws SQLException if a database access error occurs. * @since 2.4.0 * @deprecated since 2.4.4 - use {@link IMetadataHandler#matches(ResultSet, String, String, String, String, boolean)} */ @@ -463,7 +463,7 @@ public static boolean matches(ResultSet resultSet, * @param caseSensitive Whether or not the comparison should be case sensitive or not * @return true if the column metadata of the given resultSet matches * the given schema and table parameters. - * @throws SQLException + * @throws SQLException if a database access error occurs. * @since 2.4.0 * @deprecated since 2.4.4 - use {@link IMetadataHandler#matches(ResultSet, String, String, String, String, boolean)} */ @@ -499,6 +499,7 @@ public static boolean matches(ResultSet resultSet, * for this specific case. * @param value1 The first value to compare. Is ignored if null or empty String * @param value2 The second value to be compared + * @param caseSensitive Whether or not the comparison should be case sensitive. * @return true if both values are equal or if the first value * is null or empty string. * @since 2.4.4 diff --git a/src/main/java/org/dbunit/util/TableFormatter.java b/src/main/java/org/dbunit/util/TableFormatter.java index 7a570bc83..f6dc2d7fa 100644 --- a/src/main/java/org/dbunit/util/TableFormatter.java +++ b/src/main/java/org/dbunit/util/TableFormatter.java @@ -37,6 +37,9 @@ public class TableFormatter { + /** + * Default constructor. + */ public TableFormatter() { @@ -47,9 +50,9 @@ public TableFormatter() * given * length. * - * @param s - * @param length - * @param padChar + * @param s the string to pad. + * @param length the desired length of the resulting string. + * @param padChar the character to pad with. * @return The padded string */ public static final String padLeft(String s, int length, char padChar) @@ -67,9 +70,9 @@ public static final String padLeft(String s, int length, char padChar) * Pads the given String with the given padChar up to the given * length. * - * @param s - * @param length - * @param padChar + * @param s the string to pad. + * @param length the desired length of the resulting string. + * @param padChar the character to pad with. * @return The padded string */ public static final String padRight(String s, int length, char padChar) @@ -121,7 +124,7 @@ private static final String pad(String s, char[] padArray, boolean padLeft) * @param table * The table to be formatted in a beautiful way * @return The table data as a formatted String - * @throws DataSetException + * @throws DataSetException if the table data cannot be read. */ public String format(ITable table) throws DataSetException { diff --git a/src/main/java/org/dbunit/util/concurrent/BoundedBuffer.java b/src/main/java/org/dbunit/util/concurrent/BoundedBuffer.java index 27fe665b6..e31c1b1c0 100644 --- a/src/main/java/org/dbunit/util/concurrent/BoundedBuffer.java +++ b/src/main/java/org/dbunit/util/concurrent/BoundedBuffer.java @@ -36,12 +36,17 @@ public class BoundedBuffer implements BoundedChannel { */ private static final Logger logger = LoggerFactory.getLogger(BoundedBuffer.class); + /** The elements. */ protected final Object[] array_; // the elements + /** Circular index of the next element to take. */ protected int takePtr_ = 0; // circular indices - protected int putPtr_ = 0; + /** Circular index of the next slot to put into. */ + protected int putPtr_ = 0; + /** Number of occupied slots (the buffer's length). */ protected int usedSlots_ = 0; // length + /** Number of free slots (capacity - length). */ protected int emptySlots_; // capacity - length /** @@ -51,6 +56,7 @@ public class BoundedBuffer implements BoundedChannel { /** * Create a BoundedBuffer with the given capacity. + * @param capacity the maximum number of elements the buffer can hold. * @exception IllegalArgumentException if capacity less or equal to zero **/ public BoundedBuffer(int capacity) throws IllegalArgumentException { @@ -67,10 +73,11 @@ public BoundedBuffer() { this(DefaultChannelCapacity.get()); } - /** + /** * Return the number of elements in the buffer. * This is only a snapshot value, that may change * immediately after returning. + * @return the number of elements in the buffer. **/ public synchronized int size() { return usedSlots_; @@ -80,6 +87,7 @@ public int capacity() { return array_.length; } + /** Increments the empty-slot count and wakes a thread waiting to put. */ protected void incEmptySlots() { synchronized(putMonitor_) { ++emptySlots_; @@ -87,11 +95,16 @@ protected void incEmptySlots() { } } + /** Increments the used-slot count and wakes a thread waiting to take. */ protected synchronized void incUsedSlots() { ++usedSlots_; notify(); } + /** + * Inserts the given element into the buffer at putPtr_. + * @param x the element to insert. + */ protected final void insert(Object x) { logger.debug("insert(x={}) - start", x); // mechanics of put @@ -100,6 +113,10 @@ protected final void insert(Object x) { if (++putPtr_ >= array_.length) putPtr_ = 0; } + /** + * Removes and returns the element at takePtr_. + * @return the removed element. + */ protected final Object extract() { logger.debug("extract() - start"); // mechanics of take diff --git a/src/main/java/org/dbunit/util/concurrent/BoundedLinkedQueue.java b/src/main/java/org/dbunit/util/concurrent/BoundedLinkedQueue.java index f8a460def..86676a8b1 100644 --- a/src/main/java/org/dbunit/util/concurrent/BoundedLinkedQueue.java +++ b/src/main/java/org/dbunit/util/concurrent/BoundedLinkedQueue.java @@ -118,6 +118,7 @@ public class BoundedLinkedQueue implements BoundedChannel { /** * Create a queue with the given capacity + * @param capacity the maximum number of elements the queue can hold. * @exception IllegalArgumentException if capacity less or equal to zero **/ public BoundedLinkedQueue(int capacity) { @@ -137,9 +138,10 @@ public BoundedLinkedQueue() { } /** - * Move put permits from take side to put side; + * Move put permits from take side to put side; * return the number of put side permits that are available. * Call only under synch on puGuard_ AND this. + * @return the number of put side permits that are available. **/ protected final int reconcilePutPermits() { logger.debug("reconcilePutPermits() - start"); @@ -162,6 +164,7 @@ public synchronized int capacity() { * of changing. The returned value will be unreliable in the presence of * active puts and takes, and should only be used as a heuristic * estimate, for example for resource monitoring purposes. + * @return the number of elements in the queue. **/ public synchronized int size() { logger.debug("size() - start"); @@ -182,6 +185,7 @@ public synchronized int size() { * existing elements are NOT removed, but * incoming puts will not proceed until the number of elements * is less than the new capacity. + * @param newCapacity the new capacity. * @exception IllegalArgumentException if capacity less or equal to zero **/ @@ -202,7 +206,10 @@ public void setCapacity(int newCapacity) { } - /** Main mechanics for take/poll **/ + /** + * Main mechanics for take/poll + * @return the removed element, or null if the queue is empty. + **/ protected synchronized Object extract() { logger.debug("extract() - start"); @@ -304,6 +311,7 @@ protected final void allowTake() { /** * Create and insert a node. * Call only under synch on putGuard_ + * @param x the element to insert. **/ protected void insert(Object x) { logger.debug("insert(x=" + x + ") - start"); @@ -400,6 +408,10 @@ public boolean offer(Object x, long msecs) throws InterruptedException { return true; } + /** + * Returns whether the queue currently has no elements. + * @return true if the queue currently has no elements. + */ public boolean isEmpty() { logger.debug("isEmpty() - start"); diff --git a/src/main/java/org/dbunit/util/concurrent/Channel.java b/src/main/java/org/dbunit/util/concurrent/Channel.java index 7e06c38e5..52d15d6e3 100644 --- a/src/main/java/org/dbunit/util/concurrent/Channel.java +++ b/src/main/java/org/dbunit/util/concurrent/Channel.java @@ -301,6 +301,7 @@ public interface Channel extends Puttable, Takable { /** * Return, but do not remove object at head of Channel, * or null if it is empty. + * @return the object at the head of the channel, or null if it is empty. **/ public Object peek(); diff --git a/src/main/java/org/dbunit/util/concurrent/DefaultChannelCapacity.java b/src/main/java/org/dbunit/util/concurrent/DefaultChannelCapacity.java index aeb46886c..8ae181682 100644 --- a/src/main/java/org/dbunit/util/concurrent/DefaultChannelCapacity.java +++ b/src/main/java/org/dbunit/util/concurrent/DefaultChannelCapacity.java @@ -46,6 +46,7 @@ public class DefaultChannelCapacity { * Set the default capacity used in * default (no-argument) constructor for BoundedChannels * that otherwise require a capacity argument. + * @param capacity the new default capacity. * @exception IllegalArgumentException if capacity less or equal to zero */ public static void set(int capacity) { @@ -60,6 +61,7 @@ public static void set(int capacity) { * that otherwise require a capacity argument. * Initial value is INITIAL_DEFAULT_CAPACITY * @see #INITIAL_DEFAULT_CAPACITY + * @return the current default capacity. */ public static int get() { return defaultCapacity_.get(); diff --git a/src/main/java/org/dbunit/util/concurrent/Executor.java b/src/main/java/org/dbunit/util/concurrent/Executor.java index 788036e82..874c95d7b 100644 --- a/src/main/java/org/dbunit/util/concurrent/Executor.java +++ b/src/main/java/org/dbunit/util/concurrent/Executor.java @@ -64,6 +64,9 @@ public interface Executor { * Further, the general contract of the method is to avoid, * suppress, or abort execution if interruption is detected * in any controllable context surrounding execution. + * @param command the command to execute. + * @throws InterruptedException if the current thread is interrupted before execution + * could be arranged. **/ public void execute(Runnable command) throws InterruptedException; diff --git a/src/main/java/org/dbunit/util/concurrent/LinkedNode.java b/src/main/java/org/dbunit/util/concurrent/LinkedNode.java index 1ecc4cc8f..02e66b9f0 100644 --- a/src/main/java/org/dbunit/util/concurrent/LinkedNode.java +++ b/src/main/java/org/dbunit/util/concurrent/LinkedNode.java @@ -23,10 +23,29 @@ * @version $Revision$ $Date$ * @since ? (pre 2.1) */ -public class LinkedNode { +public class LinkedNode { + /** The value held by this node. */ public Object value; + /** The next node in the list, or {@code null} if this is the last node. */ public LinkedNode next; + + /** + * Default constructor. + */ public LinkedNode() {} + + /** + * Constructs a node holding the given value. + * + * @param x the value held by this node. + */ public LinkedNode(Object x) { value = x; } + + /** + * Constructs a node holding the given value and linked to the given next node. + * + * @param x the value held by this node. + * @param n the next node in the list. + */ public LinkedNode(Object x, LinkedNode n) { value = x; next = n; } } diff --git a/src/main/java/org/dbunit/util/concurrent/LinkedQueue.java b/src/main/java/org/dbunit/util/concurrent/LinkedQueue.java index 1d32060c4..6bfe2c9af 100644 --- a/src/main/java/org/dbunit/util/concurrent/LinkedQueue.java +++ b/src/main/java/org/dbunit/util/concurrent/LinkedQueue.java @@ -69,15 +69,22 @@ public class LinkedQueue implements Channel { **/ protected int waitingForTake_ = 0; + /** + * Default constructor. + */ public LinkedQueue() { - head_ = new LinkedNode(null); + head_ = new LinkedNode(null); last_ = head_; } - /** Main mechanics for put/offer **/ + /** + * Main mechanics for put/offer. + * + * @param x the value to insert. + **/ protected void insert(Object x) { logger.debug("insert(x=" + x + ") - start"); - + synchronized(putLock_) { LinkedNode p = new LinkedNode(x); synchronized(last_) { @@ -89,7 +96,11 @@ protected void insert(Object x) { } } - /** Main mechanics for take/poll **/ + /** + * Main mechanics for take/poll. + * + * @return the extracted value, or {@code null} if the queue is empty. + **/ protected synchronized Object extract() { logger.debug("extract() - start"); @@ -168,6 +179,11 @@ public Object peek() { } + /** + * Returns whether the queue is empty. + * + * @return {@code true} if the queue is empty, {@code false} otherwise. + */ public boolean isEmpty() { logger.debug("isEmpty() - start"); diff --git a/src/main/java/org/dbunit/util/concurrent/PropertyChangeMulticaster.java b/src/main/java/org/dbunit/util/concurrent/PropertyChangeMulticaster.java index d2df630d8..49c9be263 100644 --- a/src/main/java/org/dbunit/util/concurrent/PropertyChangeMulticaster.java +++ b/src/main/java/org/dbunit/util/concurrent/PropertyChangeMulticaster.java @@ -110,6 +110,9 @@ public class PropertyChangeMulticaster implements Serializable { /** * Return the child associated with property, or null if no such + * + * @param propertyName the property name. + * @return the child multicaster associated with the property, or {@code null} if none. **/ protected synchronized PropertyChangeMulticaster getChild(String propertyName) { @@ -314,8 +317,10 @@ public void removePropertyChangeListener(String propertyName, /** - * Helper method to relay evt to all listeners. + * Helper method to relay evt to all listeners. * Called by all public firePropertyChange methods. + * + * @param evt the event to relay to all listeners. **/ protected void multicast(PropertyChangeEvent evt) { @@ -466,6 +471,10 @@ else if (propertyName == null || children == null) /** + * Serializes this instance, writing only the serializable listeners. + * + * @param s the stream to write to. + * @throws IOException if writing to the stream fails. * @serialData Null terminated list of PropertyChangeListeners. *

* At serialization time we skip non-serializable listeners and @@ -476,16 +485,23 @@ private synchronized void writeObject(ObjectOutputStream s) throws IOException { logger.debug("writeObject(s={}) - start", s); s.defaultWriteObject(); - - for (int i = 0; i < listeners.length; i++) { + + for (int i = 0; i < listeners.length; i++) { if (listeners[i] instanceof Serializable) { s.writeObject(listeners[i]); } } s.writeObject(null); } - - + + + /** + * Deserializes this instance, restoring the listeners written by {@link #writeObject(ObjectOutputStream)}. + * + * @param s the stream to read from. + * @throws ClassNotFoundException if a serialized listener's class cannot be found. + * @throws IOException if reading from the stream fails. + */ private void readObject(ObjectInputStream s) throws ClassNotFoundException, IOException { logger.debug("readObject(s={}) - start", s); diff --git a/src/main/java/org/dbunit/util/concurrent/Semaphore.java b/src/main/java/org/dbunit/util/concurrent/Semaphore.java index b7d0d139b..64c23d67d 100644 --- a/src/main/java/org/dbunit/util/concurrent/Semaphore.java +++ b/src/main/java/org/dbunit/util/concurrent/Semaphore.java @@ -108,6 +108,8 @@ public class Semaphore implements Sync { * Using a seed of one makes the semaphore act as a mutual exclusion lock. * Negative seeds are also allowed, in which case no acquires will proceed * until the number of releases has pushed the number of permits past 0. + * + * @param initialPermits the initial number of permits. **/ public Semaphore(long initialPermits) { permits_ = initialPermits; } @@ -185,6 +187,7 @@ public synchronized void release() { * *

* But may be more efficient in some semaphore implementations. + * @param n the number of permits to release. * @exception IllegalArgumentException if n is negative. **/ public synchronized void release(long n) { @@ -200,6 +203,8 @@ public synchronized void release(long n) { * Return the current number of available permits. * Returns an accurate, but possibly unstable value, * that may change immediately after returning. + * + * @return the current number of available permits. **/ public synchronized long permits() { return permits_; diff --git a/src/main/java/org/dbunit/util/concurrent/SemaphoreControlledChannel.java b/src/main/java/org/dbunit/util/concurrent/SemaphoreControlledChannel.java index f650ef08b..12730ebdf 100644 --- a/src/main/java/org/dbunit/util/concurrent/SemaphoreControlledChannel.java +++ b/src/main/java/org/dbunit/util/concurrent/SemaphoreControlledChannel.java @@ -38,17 +38,21 @@ public abstract class SemaphoreControlledChannel implements BoundedChannel { */ private static final Logger logger = LoggerFactory.getLogger(SemaphoreControlledChannel.class); + /** Guards puts, holding one permit per free slot. */ protected final Semaphore putGuard_; + /** Guards takes, holding one permit per filled slot. */ protected final Semaphore takeGuard_; + /** The channel's fixed capacity. */ protected int capacity_; /** * Create a channel with the given capacity and default * semaphore implementation + * @param capacity the channel's fixed capacity. * @exception IllegalArgumentException if capacity less or equal to zero **/ - public SemaphoreControlledChannel(int capacity) + public SemaphoreControlledChannel(int capacity) throws IllegalArgumentException { if (capacity <= 0) throw new IllegalArgumentException(); capacity_ = capacity; @@ -58,8 +62,10 @@ public SemaphoreControlledChannel(int capacity) /** - * Create a channel with the given capacity and + * Create a channel with the given capacity and * semaphore implementations instantiated from the supplied class + * @param capacity the channel's fixed capacity. + * @param semaphoreClass the {@link Semaphore} subclass to instantiate for the put/take guards. * @exception IllegalArgumentException if capacity less or equal to zero. * @exception NoSuchMethodException If class does not have constructor * that intializes permits @@ -91,10 +97,12 @@ public int capacity() { logger.debug("capacity() - start"); return capacity_; } - /** + /** * Return the number of elements in the buffer. * This is only a snapshot value, that may change * immediately after returning. + * + * @return the number of elements in the buffer. **/ public int size() { @@ -103,11 +111,15 @@ public int size() { /** * Internal mechanics of put. + * + * @param x the value to insert. **/ protected abstract void insert(Object x); /** * Internal mechanics of take. + * + * @return the extracted value. **/ protected abstract Object extract(); diff --git a/src/main/java/org/dbunit/util/concurrent/Slot.java b/src/main/java/org/dbunit/util/concurrent/Slot.java index f7b6aba89..b72298971 100644 --- a/src/main/java/org/dbunit/util/concurrent/Slot.java +++ b/src/main/java/org/dbunit/util/concurrent/Slot.java @@ -46,7 +46,8 @@ public class Slot extends SemaphoreControlledChannel { /** * Create a buffer with the given capacity, using * the supplied Semaphore class for semaphores. - * @exception NoSuchMethodException If class does not have constructor + * @param semaphoreClass the {@link Semaphore} subclass to instantiate for the put/take guards. + * @exception NoSuchMethodException If class does not have constructor * that intializes permits * @exception SecurityException if constructor information * not accessible diff --git a/src/main/java/org/dbunit/util/concurrent/Sync.java b/src/main/java/org/dbunit/util/concurrent/Sync.java index 0c5121a2e..fcc1d1232 100644 --- a/src/main/java/org/dbunit/util/concurrent/Sync.java +++ b/src/main/java/org/dbunit/util/concurrent/Sync.java @@ -268,6 +268,8 @@ public interface Sync { * been acquired, and that no * corresponding release should be performed. Conversely, * a normal return guarantees that the acquire was successful. + * + * @throws InterruptedException if interrupted while waiting. **/ public void acquire() throws InterruptedException; @@ -287,13 +289,14 @@ public interface Sync { * will return at all without blocking indefinitely when used in * unintended ways. For example, deadlocks may be encountered * when called in an unintended context. - *

+ * * @param msecs the number of milleseconds to wait. - * An argument less than or equal to zero means not to wait at all. + * An argument less than or equal to zero means not to wait at all. * However, this may still require * access to a synchronization lock, which can impose unbounded * delay if there is a lot of contention among threads. * @return true if acquired + * @throws InterruptedException if interrupted while waiting. **/ public boolean attempt(long msecs) throws InterruptedException; diff --git a/src/main/java/org/dbunit/util/concurrent/SynchronizedInt.java b/src/main/java/org/dbunit/util/concurrent/SynchronizedInt.java index fff779af4..3845ce0c0 100644 --- a/src/main/java/org/dbunit/util/concurrent/SynchronizedInt.java +++ b/src/main/java/org/dbunit/util/concurrent/SynchronizedInt.java @@ -33,35 +33,44 @@ public class SynchronizedInt extends SynchronizedVariable implements Comparable, */ private static final Logger logger = LoggerFactory.getLogger(SynchronizedInt.class); + /** The current value. */ protected int value_; - /** + /** * Make a new SynchronizedInt with the given initial value, * and using its own internal lock. + * + * @param initialValue the initial value. **/ - public SynchronizedInt(int initialValue) { - super(); - value_ = initialValue; + public SynchronizedInt(int initialValue) { + super(); + value_ = initialValue; } - /** + /** * Make a new SynchronizedInt with the given initial value, * and using the supplied lock. + * + * @param initialValue the initial value. + * @param lock the synchronization lock to use. **/ - public SynchronizedInt(int initialValue, Object lock) { - super(lock); - value_ = initialValue; + public SynchronizedInt(int initialValue, Object lock) { + super(lock); + value_ = initialValue; } - /** - * Return the current value + /** + * Return the current value + * + * @return the current value. **/ public final int get() { synchronized(lock_) { return value_; } } - /** + /** * Set to newValue. - * @return the old value + * @param newValue the new value. + * @return the old value **/ public int set(int newValue) { @@ -76,6 +85,8 @@ public int set(int newValue) { /** * Set value to newValue only if it is currently assumedValue. + * @param assumedValue the value the current value must equal for the update to happen. + * @param newValue the new value. * @return true if successful **/ public boolean commit(int assumedValue, int newValue) { @@ -95,7 +106,8 @@ public boolean commit(int assumedValue, int newValue) { * (Note: Ordering via identyHashCode is not strictly guaranteed * by the language specification to return unique, orderable * values, but in practice JVMs rely on them being unique.) - * @return the new value + * @param other the SynchronizedInt to swap values with. + * @return the new value **/ public int swap(SynchronizedInt other) { @@ -138,7 +150,8 @@ public int decrement() { /** * Add amount to value (i.e., set value += amount) - * @return the new value + * @param amount the amount to add. + * @return the new value **/ public int add(int amount) { synchronized (lock_) { @@ -148,7 +161,8 @@ public int add(int amount) { /** * Subtract amount from value (i.e., set value -= amount) - * @return the new value + * @param amount the amount to subtract. + * @return the new value **/ public int subtract(int amount) { synchronized (lock_) { @@ -158,7 +172,8 @@ public int subtract(int amount) { /** * Multiply value by factor (i.e., set value *= factor) - * @return the new value + * @param factor the factor to multiply by. + * @return the new value **/ public synchronized int multiply(int factor) { synchronized (lock_) { @@ -168,7 +183,8 @@ public synchronized int multiply(int factor) { /** * Divide value by factor (i.e., set value /= factor) - * @return the new value + * @param factor the factor to divide by. + * @return the new value **/ public int divide(int factor) { synchronized (lock_) { @@ -200,7 +216,8 @@ public int complement() { /** * Set value to value & b. - * @return the new value + * @param b the value to AND with. + * @return the new value **/ public int and(int b) { synchronized (lock_) { @@ -211,7 +228,8 @@ public int and(int b) { /** * Set value to value | b. - * @return the new value + * @param b the value to OR with. + * @return the new value **/ public int or(int b) { synchronized (lock_) { @@ -223,7 +241,8 @@ public int or(int b) { /** * Set value to value ^ b. - * @return the new value + * @param b the value to XOR with. + * @return the new value **/ public int xor(int b) { synchronized (lock_) { @@ -232,12 +251,26 @@ public int xor(int b) { } } + /** + * Compares the current value to the given int. + * + * @param other the value to compare against. + * @return a negative, zero, or positive integer as the current value is less than, equal to, + * or greater than other. + */ public int compareTo(int other) { logger.debug("compareTo(other={}) - start", String.valueOf(other)); int val = get(); return (val < other)? -1 : (val == other)? 0 : 1; } + /** + * Compares the current value to another {@code SynchronizedInt}'s value. + * + * @param other the instance to compare against. + * @return a negative, zero, or positive integer as the current value is less than, equal to, + * or greater than other's value. + */ public int compareTo(SynchronizedInt other) { logger.debug("compareTo(other={}) - start", other); return compareTo(other.get()); diff --git a/src/main/java/org/dbunit/util/concurrent/SynchronizedVariable.java b/src/main/java/org/dbunit/util/concurrent/SynchronizedVariable.java index 2735f15f4..f383d1e9b 100644 --- a/src/main/java/org/dbunit/util/concurrent/SynchronizedVariable.java +++ b/src/main/java/org/dbunit/util/concurrent/SynchronizedVariable.java @@ -182,9 +182,14 @@ public class SynchronizedVariable implements Executor { */ private static final Logger logger = LoggerFactory.getLogger(SynchronizedVariable.class); + /** The lock used for all synchronization for this object. */ protected final Object lock_; - /** Create a SynchronizedVariable using the supplied lock **/ + /** + * Create a SynchronizedVariable using the supplied lock + * + * @param lock the synchronization lock to use. + **/ public SynchronizedVariable(Object lock) { lock_ = lock; } /** Create a SynchronizedVariable using itself as the lock **/ @@ -192,6 +197,8 @@ public class SynchronizedVariable implements Executor { /** * Return the lock used for all synchronization for this object + * + * @return the lock used for all synchronization for this object. **/ public Object getLock() { return lock_; diff --git a/src/main/java/org/dbunit/util/concurrent/SynchronousChannel.java b/src/main/java/org/dbunit/util/concurrent/SynchronousChannel.java index 4f303dc41..d418d2ab2 100644 --- a/src/main/java/org/dbunit/util/concurrent/SynchronousChannel.java +++ b/src/main/java/org/dbunit/util/concurrent/SynchronousChannel.java @@ -89,29 +89,43 @@ protected static class Queue { */ private static final Logger logger = LoggerFactory.getLogger(Queue.class); + /** The first node in the queue, or {@code null} if empty. */ protected LinkedNode head; + /** The last node in the queue, or {@code null} if empty. */ protected LinkedNode last; + /** + * Appends the given node to the end of the queue. + * + * @param p the node to append. + */ protected void enq(LinkedNode p) { logger.debug("enq(p={}) - start", p); - - if (last == null) + + if (last == null) last = head = p; - else + else last = last.next = p; } + /** + * Removes and returns the node at the front of the queue. + * + * @return the node that was at the front of the queue, or {@code null} if empty. + */ protected LinkedNode deq() { logger.debug("deq() - start"); LinkedNode p = head; - if (p != null && (head = p.next) == null) + if (p != null && (head = p.next) == null) last = null; return p; } } + /** Queue of nodes for puts waiting for a taker. */ protected final Queue waitingPuts = new Queue(); + /** Queue of nodes for takes waiting for a putter. */ protected final Queue waitingTakes = new Queue(); /** @@ -130,7 +144,6 @@ public Object peek() { logger.debug("peek() - start"); return null; } - public void put(Object x) throws InterruptedException { logger.debug("put(x={}) - start", x); @@ -263,7 +276,6 @@ public Object take() throws InterruptedException { Offer and poll are just like put and take, except even messier. */ - public boolean offer(Object x, long msecs) throws InterruptedException { if(logger.isDebugEnabled()) logger.debug("offer(x={}, msecs={}) - start", x, String.valueOf(msecs)); diff --git a/src/main/java/org/dbunit/util/concurrent/TimeoutException.java b/src/main/java/org/dbunit/util/concurrent/TimeoutException.java index a2bf13689..d4aacc87e 100644 --- a/src/main/java/org/dbunit/util/concurrent/TimeoutException.java +++ b/src/main/java/org/dbunit/util/concurrent/TimeoutException.java @@ -36,6 +36,8 @@ public class TimeoutException extends InterruptedException { public final long duration; /** * Constructs a TimeoutException with given duration value. + * + * @param time the approximate time the operation lasted before timing out. **/ public TimeoutException(long time) { duration = time; @@ -44,6 +46,9 @@ public TimeoutException(long time) { /** * Constructs a TimeoutException with the * specified duration value and detail message. + * + * @param time the approximate time the operation lasted before timing out. + * @param message the detail message. */ public TimeoutException(long time, String message) { super(message); diff --git a/src/main/java/org/dbunit/util/search/AbstractExcludeNodesSearchCallback.java b/src/main/java/org/dbunit/util/search/AbstractExcludeNodesSearchCallback.java index 023efcecb..61f788530 100644 --- a/src/main/java/org/dbunit/util/search/AbstractExcludeNodesSearchCallback.java +++ b/src/main/java/org/dbunit/util/search/AbstractExcludeNodesSearchCallback.java @@ -33,11 +33,21 @@ public abstract class AbstractExcludeNodesSearchCallback extends AbstractNodesFilterSearchCallback { + /** + * Creates a callback that excludes the given denied nodes. + * + * @param deniedNodes the nodes to exclude from traversal. + */ public AbstractExcludeNodesSearchCallback(Set deniedNodes) { super(); setDeniedNodes(deniedNodes); } + /** + * Creates a callback that excludes the given denied nodes. + * + * @param deniedNodes the nodes to exclude from traversal. + */ public AbstractExcludeNodesSearchCallback(Object[] deniedNodes) { super(); setDeniedNodes(deniedNodes); diff --git a/src/main/java/org/dbunit/util/search/AbstractIncludeNodesSearchCallback.java b/src/main/java/org/dbunit/util/search/AbstractIncludeNodesSearchCallback.java index 1fb1f576f..c350dddf5 100644 --- a/src/main/java/org/dbunit/util/search/AbstractIncludeNodesSearchCallback.java +++ b/src/main/java/org/dbunit/util/search/AbstractIncludeNodesSearchCallback.java @@ -33,11 +33,21 @@ public abstract class AbstractIncludeNodesSearchCallback extends AbstractNodesFilterSearchCallback { + /** + * Creates a callback that restricts traversal to the given allowed nodes. + * + * @param allowedNodes the nodes to allow during traversal. + */ public AbstractIncludeNodesSearchCallback(Set allowedNodes) { super(); setAllowedNodes(allowedNodes); } + /** + * Creates a callback that restricts traversal to the given allowed nodes. + * + * @param allowedNodes the nodes to allow during traversal. + */ public AbstractIncludeNodesSearchCallback(Object[] allowedNodes) { super(); setAllowedNodes(allowedNodes); diff --git a/src/main/java/org/dbunit/util/search/AbstractNodesFilterSearchCallback.java b/src/main/java/org/dbunit/util/search/AbstractNodesFilterSearchCallback.java index c0a1b7909..ad878d643 100644 --- a/src/main/java/org/dbunit/util/search/AbstractNodesFilterSearchCallback.java +++ b/src/main/java/org/dbunit/util/search/AbstractNodesFilterSearchCallback.java @@ -51,11 +51,17 @@ public abstract class AbstractNodesFilterSearchCallback implements ISearchCallback { + /** + * Logger for this class. + */ protected final Logger logger = LoggerFactory.getLogger(getClass()); // internal modes + /** No nodes are allowed or denied; {@link #searchNode(Object)} always returns true. */ protected static final int NO_MODE = 0; + /** Only nodes set via {@link #setAllowedNodes(Set)} are allowed. */ protected static final int ALLOW_MODE = 1; + /** Only nodes set via {@link #setDeniedNodes(Set)} are denied. */ protected static final int DENY_MODE = 2; private int filteringMode = NO_MODE; diff --git a/src/main/java/org/dbunit/util/search/DepthFirstSearch.java b/src/main/java/org/dbunit/util/search/DepthFirstSearch.java index 5893372b6..a459e120c 100644 --- a/src/main/java/org/dbunit/util/search/DepthFirstSearch.java +++ b/src/main/java/org/dbunit/util/search/DepthFirstSearch.java @@ -49,6 +49,9 @@ public class DepthFirstSearch implements ISearchAlgorithm { private Set scannedNodes; private Set reverseScannedNodes; + /** + * Logger for this class. + */ protected final Logger logger = LoggerFactory.getLogger(getClass()); // result of the search @@ -93,6 +96,10 @@ public DepthFirstSearch(int searchDepth) /** * Alternative option to search() that takes an array of nodes as input (instead of a Set) + * @param nodesFrom the nodes to start the search from. + * @param callback the callback used to help the search. + * @return the set of nodes found by the search, including the input nodes and their dependencies. + * @throws SearchException if an exception occurs while getting the edges. * @see ISearchAlgorithm */ public Set search(Object[] nodesFrom, ISearchCallback callback) diff --git a/src/main/java/org/dbunit/util/search/Edge.java b/src/main/java/org/dbunit/util/search/Edge.java index 3a7a746d4..1d2e3a0ac 100644 --- a/src/main/java/org/dbunit/util/search/Edge.java +++ b/src/main/java/org/dbunit/util/search/Edge.java @@ -42,8 +42,10 @@ public class Edge implements IEdge { private final Comparable nodeTo; /** - * @param nodeFrom - * @param nodeTo + * Creates an edge between the given nodes. + * + * @param nodeFrom the 'from' node. + * @param nodeTo the 'to' node. */ public Edge(final Comparable nodeFrom, final Comparable nodeTo) { if (nodeFrom == null) { diff --git a/src/main/java/org/dbunit/util/search/SearchException.java b/src/main/java/org/dbunit/util/search/SearchException.java index 319574152..9f99b674e 100644 --- a/src/main/java/org/dbunit/util/search/SearchException.java +++ b/src/main/java/org/dbunit/util/search/SearchException.java @@ -34,17 +34,36 @@ public class SearchException extends DatabaseUnitException { private static final long serialVersionUID = -8369726048539373231L; + /** + * Default constructor. + */ public SearchException() { } + /** + * Constructs a SearchException with the specified detail message. + * + * @param msg the detail message. + */ public SearchException(String msg) { super(msg); } + /** + * Constructs a SearchException with the specified detail message and cause. + * + * @param msg the detail message. + * @param e the cause. + */ public SearchException(String msg, Throwable e) { super(msg, e); } + /** + * Constructs a SearchException with the specified cause. + * + * @param e the cause. + */ public SearchException(Throwable e) { super(e); } diff --git a/src/main/java/org/dbunit/util/xml/XmlWriter.java b/src/main/java/org/dbunit/util/xml/XmlWriter.java index 1bbb31cb5..a3fee7f08 100644 --- a/src/main/java/org/dbunit/util/xml/XmlWriter.java +++ b/src/main/java/org/dbunit/util/xml/XmlWriter.java @@ -95,6 +95,7 @@ public class XmlWriter */ public static final String DEFAULT_ENCODING = "UTF-8"; + /** Default charset, {@value #DEFAULT_ENCODING}. */ public static final Charset DEFAULT_CHARSET = StandardCharsets.UTF_8; /** @@ -149,6 +150,8 @@ public class XmlWriter /** * Create an XmlWriter on top of an existing java.io.Writer. + * + * @param writer the writer to write to. */ public XmlWriter(final Writer writer) { @@ -157,6 +160,9 @@ public XmlWriter(final Writer writer) /** * Create an XmlWriter on top of an existing java.io.Writer. + * + * @param writer the writer to write to. + * @param charset the charset to declare in the XML prolog, may be null. */ public XmlWriter(final Writer writer, final Charset charset) { @@ -166,7 +172,7 @@ public XmlWriter(final Writer writer, final Charset charset) /** * Create an XmlWriter on top of an existing {@link java.io.OutputStream}. * - * @param outputStream + * @param outputStream the stream to write to. * @param charset * The charset to be used for writing to the given output stream. * Can be null. If it is null the @@ -240,6 +246,8 @@ public void setNewline(final String newline) * String name of tag * @param text * String of text to go inside the tag + * @return this writer. + * @throws IOException if writing fails. */ public XmlWriter writeElementWithText(final String name, final String text) throws IOException @@ -257,6 +265,8 @@ public XmlWriter writeElementWithText(final String name, final String text) * * @param name * String name of tag + * @return this writer. + * @throws IOException if writing fails. */ public XmlWriter writeEmptyElement(final String name) throws IOException { @@ -272,6 +282,8 @@ public XmlWriter writeEmptyElement(final String name) throws IOException * * @param name * String name of tag + * @return this writer. + * @throws IOException if writing fails. */ public XmlWriter writeElement(final String name) throws IOException { @@ -352,6 +364,8 @@ private void writeAttributes() throws IOException * name of attribute. * @param value * value of attribute. + * @return this writer. + * @throws IOException if writing fails. * @see #writeAttribute(String, String, boolean) */ public XmlWriter writeAttribute(final String attr, final String value) @@ -374,6 +388,8 @@ public XmlWriter writeAttribute(final String attr, final String value) * If the writer should be literally on the given value which * means that meta characters will also be preserved by escaping * them. Mainly preserves newlines and tabs. + * @return this writer. + * @throws IOException if writing fails. */ public XmlWriter writeAttribute(final String attr, final String value, final boolean literally) throws IOException @@ -411,6 +427,9 @@ public XmlWriter writeAttribute(final String attr, final String value, /** * End the current element. This will throw an exception if it is called * when there is not a currently open element. + * + * @return this writer. + * @throws IOException if there is no currently open element, or writing fails. */ public XmlWriter endElement() throws IOException { @@ -455,6 +474,8 @@ public XmlWriter endElement() throws IOException /** * Close this writer. It does not close the underlying writer, but does * throw an exception if there are as yet unclosed tags. + * + * @throws IOException if there are unclosed tags, or flushing fails. */ public void close() throws IOException { @@ -488,7 +509,7 @@ public void flush() throws IOException * @param text * The text to be written * @return This writer - * @throws IOException + * @throws IOException if writing fails. * @see #writeText(String, boolean) */ public XmlWriter writeText(final String text) throws IOException @@ -507,7 +528,7 @@ public XmlWriter writeText(final String text) throws IOException * means that meta characters will also be preserved by escaping * them. Mainly preserves newlines and tabs. * @return This writer - * @throws IOException + * @throws IOException if writing fails. */ public XmlWriter writeText(final String text, final boolean literally) throws IOException @@ -532,6 +553,8 @@ public XmlWriter writeText(final String text, final boolean literally) * * @param cdata * of CDATA text. + * @return this writer. + * @throws IOException if writing fails. */ public XmlWriter writeCData(String cdata) throws IOException { @@ -576,6 +599,8 @@ public XmlWriter writeCData(String cdata) throws IOException * * @param comment * of text to comment. + * @return this writer. + * @throws IOException if writing fails. */ public XmlWriter writeComment(final String comment) throws IOException { @@ -612,6 +637,12 @@ private void writeChunk(final String data) throws IOException // Two example methods. They should output the same XML: // 425343 + /** + * Runs {@link #test1()} and {@link #test2()}, printing their output for manual inspection. + * + * @param args ignored. + * @throws IOException if writing the example XML fails. + */ static public void main(final String[] args) throws IOException { logger.debug("main(args={}) - start", (Object) args); @@ -620,6 +651,11 @@ static public void main(final String[] args) throws IOException test2(); } + /** + * Writes an example XML document using the fluent {@link #writeElement(String)} style. + * + * @throws IOException if writing the example XML fails. + */ static public void test1() throws IOException { logger.debug("test1() - start"); @@ -635,6 +671,11 @@ static public void test1() throws IOException System.err.println(writer.toString()); } + /** + * Writes the same example XML document as {@link #test1()}, using the step-by-step style. + * + * @throws IOException if writing the example XML fails. + */ static public void test2() throws IOException { logger.debug("test2() - start"); @@ -758,6 +799,14 @@ private String escapeXml(final String str, final boolean literally) return buffer.toString(); } + /** + * Returns the XML entity for the given character, if any. + * + * @param currentChar the character to convert. + * @param literally whether the character was written via a "literal" write method, + * which affects which characters are converted. + * @return the XML entity for the given character, or null if it needs no entity. + */ protected String convertCharacterToEntity(final char currentChar, final boolean literally) { @@ -895,6 +944,12 @@ final public void setWriter(final Writer writer, final String encoding) setWriter(writer, Charset.forName(encoding)); } + /** + * Sets the writer and character set to write to. + * + * @param writer the writer to write to. + * @param charset the character set to encode the declaration with. + */ final public void setWriter(final Writer writer, final Charset charset) { logger.debug("setWriter(writer={}, charset={}) - start", writer, @@ -916,6 +971,12 @@ final public void setWriter(final Writer writer, final Charset charset) } } + /** + * Writes the XML declaration, if an encoding is set. + * + * @return this writer, for chaining. + * @throws IOException if writing to the underlying stream fails. + */ public XmlWriter writeDeclaration() throws IOException { logger.debug("writeDeclaration() - start"); @@ -931,6 +992,14 @@ public XmlWriter writeDeclaration() throws IOException return this; } + /** + * Writes a DOCTYPE declaration for the dataset, if a system or public id is given. + * + * @param systemId the DTD's system id, or null. + * @param publicId the DTD's public id, or null. + * @return this writer, for chaining. + * @throws IOException if writing to the underlying stream fails. + */ public XmlWriter writeDoctype(final String systemId, final String publicId) throws IOException { diff --git a/src/test/java/org/dbunit/DatabaseEnvironment.java b/src/test/java/org/dbunit/DatabaseEnvironment.java index e31b104ba..9df6eac07 100644 --- a/src/test/java/org/dbunit/DatabaseEnvironment.java +++ b/src/test/java/org/dbunit/DatabaseEnvironment.java @@ -76,8 +76,6 @@ public class DatabaseEnvironment *

* Following is a few properties as an example of the content of * "dbunit.properties": - *

- * * 

      * database.profile=h2
      * dbunit.profile.driverClass=org.hsqldb.jdbcDriver