Author: tfischer
Date: Wed May 9 13:17:37 2012
New Revision: 1336179
URL: http://svn.apache.org/viewvc?rev=1336179&view=rev
Log:
improve javadoc
use final for unmodified fields
Modified:
db/torque/torque4/trunk/torque-runtime/src/main/java/org/apache/torque/adapter/AbstractDBAdapter.java
db/torque/torque4/trunk/torque-runtime/src/main/java/org/apache/torque/adapter/DB.java
Modified:
db/torque/torque4/trunk/torque-runtime/src/main/java/org/apache/torque/adapter/AbstractDBAdapter.java
URL:
http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-runtime/src/main/java/org/apache/torque/adapter/AbstractDBAdapter.java?rev=1336179&r1=1336178&r2=1336179&view=diff
==============================================================================
---
db/torque/torque4/trunk/torque-runtime/src/main/java/org/apache/torque/adapter/AbstractDBAdapter.java
(original)
+++
db/torque/torque4/trunk/torque-runtime/src/main/java/org/apache/torque/adapter/AbstractDBAdapter.java
Wed May 9 13:17:37 2012
@@ -44,17 +44,6 @@ import org.apache.torque.util.functions.
* <i>zero code changes</i> and minimal configuration file
* modifications.
*
- * <p>Torque uses the driver class name to find the right adapter.
- * A JDBC driver corresponding to your adapter must be added to the properties
- * file, using the fully-qualified class name of the driver. If no driver is
- * specified for your database, <code>driver.default</code> is used.
- *
- * <pre>
- * #### MySQL MM Driver
- * database.default.driver=org.gjt.mm.mysql.Driver
- * database.default.url=jdbc:mysql://localhost/DATABASENAME
- * </pre>
- *
* @author <a href="mailto:[email protected]";>Jon S. Stevens</a>
* @author <a href="mailto:[email protected]";>Brett McLaughlin</a>
* @author <a href="mailto:[email protected]";>Daniel Rall</a>
@@ -70,7 +59,7 @@ public abstract class AbstractDBAdapter
/**
* The default look up table for function classes.
*/
- private Map<FunctionEnum, Class<? extends SQLFunction>> functionClasses
+ private final Map<FunctionEnum, Class<? extends SQLFunction>>
functionClasses
= new Hashtable<FunctionEnum, Class<? extends SQLFunction>>();
/*
@@ -98,10 +87,14 @@ public abstract class AbstractDBAdapter
}
/**
- * This method is used to ignore case.
+ * Wraps the input string in a database function to change it to upper
case.
*
- * @param in The string to transform to upper case.
- * @return The upper case string.
+ * @param in The string to transform to upper case, may be a literal
string,
+ * a prepared statement replacement placeholder(*) or any other
+ * database expression.
+ *
+ * @return The wrapped input string, so that the database evaluates the
+ * returned expression to the upper case of the input.
*/
public abstract String toUpperCase(String in);
@@ -110,7 +103,7 @@ public abstract class AbstractDBAdapter
* a piece of text used in a SQL statement (generally a single
* quote).
*
- * @return The text delimeter.
+ * @return The text delimiter.
*/
public char getStringDelimiter()
{
@@ -141,6 +134,7 @@ public abstract class AbstractDBAdapter
*
* @param con The JDBC connection to use.
* @param table The name of the table to lock.
+ *
* @throws SQLException No Statement could be created or executed.
*/
public abstract void lockTable(Connection con, String table)
@@ -151,26 +145,34 @@ public abstract class AbstractDBAdapter
*
* @param con The JDBC connection to use.
* @param table The name of the table to unlock.
+ *
* @throws SQLException No Statement could be created or executed.
*/
public abstract void unlockTable(Connection con, String table)
throws SQLException;
/**
- * This method is used to ignore case.
+ * Wraps the input string in a database function to change it to
+ * a case-insensitive representation.
*
- * @param in The string whose case to ignore.
- * @return The string in a case that can be ignored.
+ * @param in The string to transform to a case-insensitive representation,
+ * may be a literal string, a prepared statement replacement
+ * placeholder(*) or any other database expression.
+ *
+ * @return The wrapped input string, so that the database evaluates the
+ * returned expression to a case-insensitive representation
+ * of the input.
*/
public abstract String ignoreCase(String in);
/**
* This method is used to ignore case in an ORDER BY clause.
* Usually it is the same as ignoreCase, but some databases
- * (Interbase for example) does not use the same SQL in ORDER BY
+ * (hsqldb for example) do not use the same SQL in ORDER BY
* and other clauses.
*
* @param in The string whose case to ignore.
+ *
* @return The string in a case that can be ignored.
*/
public String ignoreCaseInOrderBy(String in)
@@ -182,8 +184,8 @@ public abstract class AbstractDBAdapter
* This method is used to check whether the database natively
* supports limiting the size of the resultset.
*
- * @return True if the database natively supports limiting the
- * size of the resultset.
+ * @return true if the database natively supports limiting the
+ * size of the resultset.
*/
public boolean supportsNativeLimit()
{
@@ -195,8 +197,8 @@ public abstract class AbstractDBAdapter
* supports returning results starting at an offset position other
* than 0.
*
- * @return True if the database natively supports returning
- * results starting at an offset position other than 0.
+ * @return true if the database natively supports returning
+ * results starting at an offset position other than 0.
*/
public boolean supportsNativeOffset()
{
@@ -225,7 +227,7 @@ public abstract class AbstractDBAdapter
/**
* This method is for the SqlExpression.quoteAndEscape rules. The rule is,
* any string in a SqlExpression with a BACKSLASH will either be changed to
- * "\\" or left as "\". SapDB does not need the escape character.
+ * "\\" or left as "\".
*
* @return true if the database needs to escape text in SqlExpressions.
*/
Modified:
db/torque/torque4/trunk/torque-runtime/src/main/java/org/apache/torque/adapter/DB.java
URL:
http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-runtime/src/main/java/org/apache/torque/adapter/DB.java?rev=1336179&r1=1336178&r2=1336179&view=diff
==============================================================================
---
db/torque/torque4/trunk/torque-runtime/src/main/java/org/apache/torque/adapter/DB.java
(original)
+++
db/torque/torque4/trunk/torque-runtime/src/main/java/org/apache/torque/adapter/DB.java
Wed May 9 13:17:37 2012
@@ -45,18 +45,7 @@ import org.apache.torque.util.functions.
* All database adapters need to be thread safe, as they are instantiated
* only once fore a given configured database and may be accessed
* simultaneously from several threads.
- *
- * <p>Torque uses the driver class name to find the right adapter.
- * A JDBC driver corresponding to your adapter must be added to the properties
- * file, using the fully-qualified class name of the driver. If no driver is
- * specified for your database, <code>driver.default</code> is used.
- *
- * <pre>
- * #### MySQL MM Driver
- * database.default.driver=org.gjt.mm.mysql.Driver
- * database.default.url=jdbc:mysql://localhost/DATABASENAME
- * </pre>
- *
+ * *
* @author <a href="mailto:[email protected]";>Jon S. Stevens</a>
* @author <a href="mailto:[email protected]";>Brett McLaughlin</a>
* @author <a href="mailto:[email protected]";>Daniel Rall</a>
@@ -67,26 +56,24 @@ import org.apache.torque.util.functions.
*/
public interface DB extends Serializable, IDMethod
{
- /**
- * Key for the configuration which contains database adapters.
- */
+ /** Key for the configuration which contains database adapters. */
String ADAPTER_KEY = "adapter";
- /**
- * Key for the configuration which contains database drivers.
- */
+ /** Key for the configuration which contains database drivers. */
String DRIVER_KEY = "driver";
- /**
- * Special adapter for auto-detection.
- */
+ /** Special adapter for auto-detection. */
String AUTODETECT_ADAPTER = "auto";
/**
- * This method is used to ignore case.
+ * Wraps the input string in a database function to change it to upper
case.
*
- * @param in The string to transform to upper case.
- * @return The upper case string.
+ * @param in The string to transform to upper case, may be a literal
string,
+ * a prepared statement replacement placeholder(*) or any other
+ * database expression.
+ *
+ * @return The wrapped input string, so that the database evaluates the
+ * returned expression to the upper case of the input.
*/
String toUpperCase(String in);
@@ -95,7 +82,7 @@ public interface DB extends Serializable
* a piece of text used in a SQL statement (generally a single
* quote).
*
- * @return The text delimeter.
+ * @return The text delimiter.
*/
char getStringDelimiter();
@@ -114,6 +101,7 @@ public interface DB extends Serializable
* <code>null</code>.
*
* @param obj Information used for key generation.
+ *
* @return The most recently inserted database key.
*/
String getIDMethodSQL(Object obj);
@@ -123,6 +111,7 @@ public interface DB extends Serializable
*
* @param con The JDBC connection to use.
* @param table The name of the table to lock.
+ *
* @throws SQLException No Statement could be created or executed.
*/
void lockTable(Connection con, String table)
@@ -133,29 +122,34 @@ public interface DB extends Serializable
*
* @param con The JDBC connection to use.
* @param table The name of the table to unlock.
+ *
* @throws SQLException No Statement could be created or executed.
*/
void unlockTable(Connection con, String table)
throws SQLException;
/**
- * Modifies a SQL snippet such that its case is ignored by the database.
- * The SQL snippet can be a column name (like AURHOR.NAME), an
- * quoted explicit sql string (like 'abc') or any other sql value (like a
- * number etc.).
+ * Wraps the input string in a database function to change it to
+ * a case-insensitive representation.
*
- * @param in The SQL snippet whose case to ignore.
- * @return The string in a case that can be ignored.
+ * @param in The string to transform to a case-insensitive representation,
+ * may be a literal string, a prepared statement replacement
+ * placeholder(*) or any other database expression.
+ *
+ * @return The wrapped input string, so that the database evaluates the
+ * returned expression to a case-insensitive representation
+ * of the input.
*/
String ignoreCase(String in);
/**
* This method is used to ignore case in an ORDER BY clause.
* Usually it is the same as ignoreCase, but some databases
- * (Interbase for example) does not use the same SQL in ORDER BY
+ * (hsqldb for example) does not use the same SQL in ORDER BY
* and other clauses.
*
* @param in The string whose case to ignore.
+ *
* @return The string in a case that can be ignored.
*/
String ignoreCaseInOrderBy(String in);
@@ -164,8 +158,8 @@ public interface DB extends Serializable
* This method is used to check whether the database natively
* supports limiting the size of the resultset.
*
- * @return True if the database natively supports limiting the
- * size of the resultset.
+ * @return true if the database natively supports limiting the
+ * size of the resultset.
*/
boolean supportsNativeLimit();
@@ -174,8 +168,8 @@ public interface DB extends Serializable
* supports returning results starting at an offset position other
* than 0.
*
- * @return True if the database natively supports returning
- * results starting at an offset position other than 0.
+ * @return true if the database natively supports returning
+ * results starting at an offset position other than 0.
*/
boolean supportsNativeOffset();
@@ -193,14 +187,13 @@ public interface DB extends Serializable
throws TorqueException;
/**
- * Whether backslashes (\) should be escaped in explicit SQL strings.
- * If true is returned, a BACKSLASH will be changed to "\\". If false
- * is returned, a BACKSLASH will be left as "\".
+ * Determines whether backslashes (\) should be escaped in explicit SQL
+ * strings. If true is returned, a BACKSLASH will be changed to "\\".
+ * If false is returned, a BACKSLASH will be left as "\".
*
* @return true if the database needs to escape backslashes
* in SqlExpressions.
*/
-
boolean escapeText();
/**
@@ -225,9 +218,11 @@ public interface DB extends Serializable
* can be a single level inner class (or not).
*
* @param function The function to get the class for.
+ *
* @return The SQLFunction implementation for a function of this type that
* will work with this type of DB. Null indicates a class was not
* found.
+ *
* @see org.apache.torque.util.functions.AbstractFunction
* @see org.apache.torque.util.functions.Aggregate
* @see org.apache.torque.util.functions.SQLFunction
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
