From: erik Date: Mon, 5 Jul 2010 15:03:29 +0000 (+0000) Subject: javadoc updates X-Git-Tag: wamblee-utils-0.3~115 X-Git-Url: http://wamblee.org/gitweb/?a=commitdiff_plain;h=225eac1b00a93006f7ecc714ec650e03d7bef9c8;p=utils javadoc updates --- diff --git a/test/enterprise/src/main/java/org/wamblee/support/ThreadSpecificProxyFactory.java b/test/enterprise/src/main/java/org/wamblee/support/ThreadSpecificProxyFactory.java index 02668cdc..26a76104 100644 --- a/test/enterprise/src/main/java/org/wamblee/support/ThreadSpecificProxyFactory.java +++ b/test/enterprise/src/main/java/org/wamblee/support/ThreadSpecificProxyFactory.java @@ -26,6 +26,12 @@ import java.lang.reflect.Proxy; * * It is used for instance to pass a transaction scoped entity manager around. * + * The {@link #set(Object)} method sets the current service instance for the current thread. + * The {@link #get()} method gets the current service instance for the current thread. + * The {@link #getProxy()} method gets a proxy that will delegate at runtime to the thread-specific + * instance. The result from this method can be passed at construction of an object that will be used + * by multiple threads. + * * @param T * Interface to proxy. * @author Erik Brakkee diff --git a/test/enterprise/src/main/java/org/wamblee/support/persistence/AbstractDatabase.java b/test/enterprise/src/main/java/org/wamblee/support/persistence/AbstractDatabase.java index 6eaba50b..12c82c41 100644 --- a/test/enterprise/src/main/java/org/wamblee/support/persistence/AbstractDatabase.java +++ b/test/enterprise/src/main/java/org/wamblee/support/persistence/AbstractDatabase.java @@ -28,6 +28,14 @@ import org.apache.commons.dbcp.PoolableConnectionFactory; import org.apache.commons.dbcp.PoolingDataSource; import org.apache.commons.pool.impl.GenericObjectPool; +/** + * Abstract database class providing the creation of the datasource, + * preventing duplicate starts of the same database, and checking + * for connection leaks when the database is stopped. + * + * @author Erik Brakkee + * + */ public abstract class AbstractDatabase implements Database { /** @@ -47,12 +55,21 @@ public abstract class AbstractDatabase implements Database { private boolean started; + /** + * Constructs the database. + */ protected AbstractDatabase() { started = false; } + /** + * To be implemented by subclasses to start the database. + */ protected abstract void doStart(); + /** + * To be implemented by subclasses to stop the database. + */ protected abstract void doStop(); /** @@ -83,6 +100,9 @@ public abstract class AbstractDatabase implements Database { // / BELOW THIS LINE IS NOT OF INTEREST TO SUBCLASSES. + /** + * Starts the database. + */ public final DataSource start() { if (started) { throw new RuntimeException("Database already started"); @@ -92,6 +112,11 @@ public abstract class AbstractDatabase implements Database { return getDatasource(); } + /** + * Stops the database and tests for connection leaks. + * In cast the system property with the name given by {@link #IGNORE_CONNECTION_LEAK_PROPERTY} + * is set then the connection leaks are not checked. + */ public final void stop() { if (!started) { return; // nothing to do. diff --git a/test/enterprise/src/main/java/org/wamblee/support/persistence/AbstractDatabaseProvider.java b/test/enterprise/src/main/java/org/wamblee/support/persistence/AbstractDatabaseProvider.java index 65cca2b0..b15d53b3 100644 --- a/test/enterprise/src/main/java/org/wamblee/support/persistence/AbstractDatabaseProvider.java +++ b/test/enterprise/src/main/java/org/wamblee/support/persistence/AbstractDatabaseProvider.java @@ -16,11 +16,21 @@ package org.wamblee.support.persistence; import java.util.List; - +/** + * Base class for database providers. + * + * @author Erik Brakkee + */ public abstract class AbstractDatabaseProvider implements DatabaseProvider { + /** + * @return List of database capabilities. + */ protected abstract List getCapabilities(); + /** + * Standard implementation of the capabalities check. + */ public final boolean supportsCapabilities(String[] aCapabilities) { for (String capability : aCapabilities) { if (!getCapabilities().contains(capability)) { diff --git a/test/enterprise/src/main/java/org/wamblee/support/persistence/CompositeJpaCustomizer.java b/test/enterprise/src/main/java/org/wamblee/support/persistence/CompositeJpaCustomizer.java index cdc264d7..3d8c7b8a 100644 --- a/test/enterprise/src/main/java/org/wamblee/support/persistence/CompositeJpaCustomizer.java +++ b/test/enterprise/src/main/java/org/wamblee/support/persistence/CompositeJpaCustomizer.java @@ -20,11 +20,21 @@ import java.util.Map; import org.dbunit.dataset.filter.ITableFilterSimple; +/** + * Composite JPA customizer that applies the customizations from several + * JPA customizers. + * + * @author Erik Brakkee + */ public class CompositeJpaCustomizer implements JpaCustomizer { private List customizers; private CompositeJpaTables tables; + /** + * Construcst the customizer. + * @param aCustomizers List of customizers. + */ public CompositeJpaCustomizer(List aCustomizers) { customizers = aCustomizers; tables = new CompositeJpaTables(); @@ -34,6 +44,9 @@ public class CompositeJpaCustomizer implements JpaCustomizer { } @Override + /** + * Applies all customizations in an undefined order. + */ public void customize(PersistenceUnitDescription aPersistenceUnit, Map aJpaProperties) { for (JpaCustomizer customizer : customizers) { diff --git a/test/enterprise/src/main/java/org/wamblee/support/persistence/CompositeJpaTables.java b/test/enterprise/src/main/java/org/wamblee/support/persistence/CompositeJpaTables.java index 25f4894d..b44ff7cc 100644 --- a/test/enterprise/src/main/java/org/wamblee/support/persistence/CompositeJpaTables.java +++ b/test/enterprise/src/main/java/org/wamblee/support/persistence/CompositeJpaTables.java @@ -21,14 +21,26 @@ import java.util.List; import org.dbunit.dataset.DataSetException; import org.dbunit.dataset.filter.ITableFilterSimple; +/** + * Composite JPA tables. Implements the logical or of several table filters. + * + * @author Erik Brakkee + */ public class CompositeJpaTables implements ITableFilterSimple { private List tables; + /** + * Construcst the tables. + */ public CompositeJpaTables() { tables = new ArrayList(); } + /** + * Adds a table filter. + * @param aFilter filter. + */ public void add(ITableFilterSimple aFilter) { tables.add(aFilter); } diff --git a/test/enterprise/src/main/java/org/wamblee/support/persistence/DatabaseBuilder.java b/test/enterprise/src/main/java/org/wamblee/support/persistence/DatabaseBuilder.java index d8807c38..6f495698 100644 --- a/test/enterprise/src/main/java/org/wamblee/support/persistence/DatabaseBuilder.java +++ b/test/enterprise/src/main/java/org/wamblee/support/persistence/DatabaseBuilder.java @@ -65,6 +65,9 @@ public class DatabaseBuilder { private static ServiceLoader LOADER = ServiceLoader.load(DatabaseProvider.class); + /** + * Constructs the database builder. + */ private DatabaseBuilder() { // Empty. } diff --git a/test/enterprise/src/main/java/org/wamblee/support/persistence/DatabaseStarter.java b/test/enterprise/src/main/java/org/wamblee/support/persistence/DatabaseStarter.java index 45e96499..1afefd80 100644 --- a/test/enterprise/src/main/java/org/wamblee/support/persistence/DatabaseStarter.java +++ b/test/enterprise/src/main/java/org/wamblee/support/persistence/DatabaseStarter.java @@ -16,7 +16,7 @@ package org.wamblee.support.persistence; /** - * This class is used for starting the database from ant. + * This class is used for starting the database as a main program. */ public class DatabaseStarter { diff --git a/test/enterprise/src/main/java/org/wamblee/support/persistence/DatabaseUtils.java b/test/enterprise/src/main/java/org/wamblee/support/persistence/DatabaseUtils.java index b57cd461..07dbca0f 100644 --- a/test/enterprise/src/main/java/org/wamblee/support/persistence/DatabaseUtils.java +++ b/test/enterprise/src/main/java/org/wamblee/support/persistence/DatabaseUtils.java @@ -45,15 +45,44 @@ import org.dbunit.operation.DatabaseOperation; */ public class DatabaseUtils { + /** + * Represents a set of tables. + * + * @author Erik Brakkee + */ public static interface TableSet { boolean contains(String aTableName); } + /** + * Represents a unit of work (transaction). + * + * @author Erik Brakkee + * + * @param Type of return value. + */ public static interface JdbcUnitOfWork { + /** + * Executes statement within a transaction. + * @param aConnection Connection. + * @return Result of the work. + * @throws Exception + */ T execute(Connection aConnection) throws Exception; } + /** + * Operation to be executed on a set of tables for each table + * individually. + * + * @author Erik Brakkee + */ public static interface TableSetOperation { + /** + * Executes on a table. + * @param aTable Table name. + * @throws Exception + */ void execute(String aTable) throws Exception; } @@ -108,10 +137,22 @@ public class DatabaseUtils { connections.clear(); } + /** + * Creates database tester. + * @param aTables Tables to create the tester for. + * @return Database tester. + * @throws Exception + */ public IDatabaseTester createDbTester(ITableFilterSimple aTables) throws Exception { return createDbTester(getTableNames(aTables)); } - + + /** + * Creates database tester. + * @param aTables Tables to create the tester for. + * @return Database tester. + * @throws Exception + */ public IDatabaseTester createDbTester(String[] aTables) throws Exception { IDatabaseConnection connection = dbtester.getConnection(); connections.add(connection); @@ -119,6 +160,12 @@ public class DatabaseUtils { return dbtester; } + /** + * Executes an operation on a set of tables. + * @param aTables Tables. + * @param aOperation Operation. + * @throws Exception + */ public void executeOnTables(ITableFilterSimple aTables, final TableSetOperation aOperation) throws Exception { final String[] tableNames = getTableNames(aTables); @@ -132,6 +179,12 @@ public class DatabaseUtils { }); } + /** + * Cleans a number of database tables. This means deleting the content not dropping the tables. + * This may fail in case of cyclic dependencies between the tables (current limitation). + * @param aSelection Tables. + * @throws Exception + */ public void cleanDatabase(ITableFilterSimple aSelection) throws Exception { final String[] tableNames = getTableNames(aSelection); @@ -151,12 +204,19 @@ public class DatabaseUtils { } - public T executeInTransaction(JdbcUnitOfWork aCallback) + /** + * Executes a unit of work within a transaction. + * @param Result type of th ework. + * @param aWork Unit of work. + * @return + * @throws Exception + */ + public T executeInTransaction(JdbcUnitOfWork aWork) throws Exception { Connection connection = dataSource.getConnection(); connection.setAutoCommit(false); try { - T value = aCallback.execute(connection); + T value = aWork.execute(connection); connection.commit(); return value; } finally { @@ -165,7 +225,10 @@ public class DatabaseUtils { } /** - * @throws SQLException + * Returns table names based on a table filter. + * @param aSelection Table filter. + * @return Table names. + * @throws Exception */ public String[] getTableNames(ITableFilterSimple aSelection) throws Exception { @@ -191,9 +254,9 @@ public class DatabaseUtils { } /** - * @return - * @throws SQLException + * Use {@link #cleanDatabase(ITableFilterSimple)} instead. */ + @Deprecated public void emptyTables(final ITableFilterSimple aSelection) throws Exception { executeOnTables(aSelection, new TableSetOperation() { @@ -204,13 +267,18 @@ public class DatabaseUtils { } /** - * @return - * @throws SQLException + * User {@link #cleanDatabase(ITableFilterSimple)} instead. */ + @Deprecated public void emptyTable(String aTable) throws Exception { executeSql("delete from " + aTable); } + /** + * Drops tables. This only works if there are no cyclic dependencies between the tables. + * @param aTables Tables to drop. + * @throws Exception + */ public void dropTables(ITableFilterSimple aTables) throws Exception { final String[] tableNames = getTableNames(aTables); String[] sortedTables = executeInTransaction(new JdbcUnitOfWork() { @@ -231,8 +299,9 @@ public class DatabaseUtils { } /** - * @return - * @throws SQLException + * Drops a table. + * @param aTable Table to drop. + * @throws Exception */ public void dropTable(final String aTable) throws Exception { executeInTransaction(new JdbcUnitOfWork() { @@ -343,6 +412,13 @@ public class DatabaseUtils { } } + /** + * Executes an update. + * @param aConnection Connection to use. + * @param aSql SQL update to use. + * @param aArgs Arguments to the update. + * @return Number of rows updated. + */ public int executeUpdate(Connection aConnection, final String aSql, final Object... aArgs) { try { @@ -400,7 +476,9 @@ public class DatabaseUtils { } /** - * @return + * Gets the table size. + * @param aTable Table. + * @return Table size. * @throws SQLException */ public int getTableSize(final String aTable) throws Exception { @@ -415,6 +493,12 @@ public class DatabaseUtils { } + /** + * Counts the results in a result set. + * @param aResultSet Resultset. + * @return Number of rows in the set. + * @throws SQLException + */ public int countResultSet(ResultSet aResultSet) throws SQLException { int count = 0; diff --git a/test/enterprise/src/main/java/org/wamblee/support/persistence/DerbyDatabaseProvider.java b/test/enterprise/src/main/java/org/wamblee/support/persistence/DerbyDatabaseProvider.java index 183a73db..119c8c55 100644 --- a/test/enterprise/src/main/java/org/wamblee/support/persistence/DerbyDatabaseProvider.java +++ b/test/enterprise/src/main/java/org/wamblee/support/persistence/DerbyDatabaseProvider.java @@ -19,9 +19,9 @@ import java.util.Arrays; import java.util.List; /** + * Derby database provider. * - * @author $author$ - * @version $Revision$ + * @author Erik Brakkee */ public class DerbyDatabaseProvider extends AbstractDatabaseProvider { /** diff --git a/test/enterprise/src/main/java/org/wamblee/support/persistence/ExternalDatabaseProvider.java b/test/enterprise/src/main/java/org/wamblee/support/persistence/ExternalDatabaseProvider.java index 9c131bfb..5f6e0416 100644 --- a/test/enterprise/src/main/java/org/wamblee/support/persistence/ExternalDatabaseProvider.java +++ b/test/enterprise/src/main/java/org/wamblee/support/persistence/ExternalDatabaseProvider.java @@ -18,6 +18,11 @@ package org.wamblee.support.persistence; import java.util.Arrays; import java.util.List; +/** + * Database provider for an external database. + * + * @author Erik Brakkee + */ public class ExternalDatabaseProvider extends AbstractDatabaseProvider { /** diff --git a/test/enterprise/src/main/java/org/wamblee/support/persistence/JpaCustomizer.java b/test/enterprise/src/main/java/org/wamblee/support/persistence/JpaCustomizer.java index 7c48cb24..9914e2a1 100644 --- a/test/enterprise/src/main/java/org/wamblee/support/persistence/JpaCustomizer.java +++ b/test/enterprise/src/main/java/org/wamblee/support/persistence/JpaCustomizer.java @@ -32,8 +32,17 @@ import org.dbunit.dataset.filter.ITableFilterSimple; */ public interface JpaCustomizer { + /** + * Customizes the persistence unit through properties. + * @param aPersistenceUnit Persistence unit. + * @param aJpaProperties Current properties. + */ void customize(PersistenceUnitDescription aPersistenceUnit, Map aJpaProperties); + /** + * Gets the tables specific to the JPA provider. + * @return Tables. + */ ITableFilterSimple getJpaTables(); } diff --git a/test/enterprise/src/main/java/org/wamblee/support/persistence/JpaCustomizerBuilder.java b/test/enterprise/src/main/java/org/wamblee/support/persistence/JpaCustomizerBuilder.java index 1f1884fe..564e8246 100644 --- a/test/enterprise/src/main/java/org/wamblee/support/persistence/JpaCustomizerBuilder.java +++ b/test/enterprise/src/main/java/org/wamblee/support/persistence/JpaCustomizerBuilder.java @@ -19,11 +19,20 @@ import java.util.ArrayList; import java.util.List; import java.util.ServiceLoader; +/** + * JPA customizer builder implements the {@link ServiceLoader} based mechanism for looking up + * JPA customizers. + */ public class JpaCustomizerBuilder { private static final ServiceLoader CUSTOMIZERS = ServiceLoader .load(JpaCustomizer.class); + /** + * Gets the customizer to use. This is a composite customizer that combines all customizers that + * were found. + * @return JPA customizer. + */ public static JpaCustomizer getCustomizer() { List customizers = new ArrayList(); for (JpaCustomizer customizer : CUSTOMIZERS) { diff --git a/test/enterprise/src/main/java/org/wamblee/support/persistence/JpaTester.java b/test/enterprise/src/main/java/org/wamblee/support/persistence/JpaTester.java index e74003f1..26bf6bbc 100644 --- a/test/enterprise/src/main/java/org/wamblee/support/persistence/JpaTester.java +++ b/test/enterprise/src/main/java/org/wamblee/support/persistence/JpaTester.java @@ -117,22 +117,42 @@ public class JpaTester { } } + /** + * Gets the database. + * @return Database. + */ public Database getDb() { return db; } + /** + * Gets the datasource. + * @return Datasource. + */ public DataSource getDataSource() { return dataSource; } + /** + * Gets the database utilities. + * @return Database utilities. + */ public DatabaseUtils getDbUtils() { return dbUtils; } + /** + * Gets the jpa builder. + * @return JPA builder. + */ public JpaBuilder getJpaBuilder() { return jpaBuilder; } + /** + * Gets the persistence unit. + * @return Persistence unit. + */ public PersistenceUnitDescription getPersistenceUnit() { return persistenceUnit; }