db-torque-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tfisc...@apache.org
Subject svn commit: r1336179 - in /db/torque/torque4/trunk/torque-runtime/src/main/java/org/apache/torque/adapter: AbstractDBAdapter.java DB.java
Date Wed, 09 May 2012 13:17:38 GMT
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:jon@latchkey.com">Jon S. Stevens</a>
  * @author <a href="mailto:bmclaugh@algx.net">Brett McLaughlin</a>
  * @author <a href="mailto:dlr@finemaltcoding.com">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:jon@latchkey.com">Jon S. Stevens</a>
  * @author <a href="mailto:bmclaugh@algx.net">Brett McLaughlin</a>
  * @author <a href="mailto:dlr@finemaltcoding.com">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: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org


Mime
View raw message