empire-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From franci...@apache.org
Subject svn commit: r747212 - in /incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db: DBColumnExpr.java DBDatabase.java DBDatabaseDriver.java DBRecord.java DBTable.java DBTableColumn.java
Date Mon, 23 Feb 2009 23:32:56 GMT
Author: francisdb
Date: Mon Feb 23 23:32:54 2009
New Revision: 747212

URL: http://svn.apache.org/viewvc?rev=747212&view=rev
Log:
javadoc cleanup, mostly adding missing parameter or return statements

Modified:
    incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBColumnExpr.java
    incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBDatabase.java
    incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBDatabaseDriver.java
    incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBRecord.java
    incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBTable.java
    incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBTableColumn.java

Modified: incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBColumnExpr.java
URL: http://svn.apache.org/viewvc/incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBColumnExpr.java?rev=747212&r1=747211&r2=747212&view=diff
==============================================================================
--- incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBColumnExpr.java
(original)
+++ incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBColumnExpr.java
Mon Feb 23 23:32:54 2009
@@ -172,6 +172,8 @@
 
     /**
      * Sets the title attribute.
+     * 
+     * @param title the column title
      */
     public final void setTitle(String title)
     { 
@@ -179,11 +181,11 @@
     }
 
     /**
-     * Returns the columns control type.
+     * Returns the column control type.
      * The control type is a client specific name for the type of input control 
      * that should be used to display and edit values for this column. 
      * 
-     * @return the columns control type
+     * @return the column control type
      */
     public final String getControlType()
     { 
@@ -192,7 +194,9 @@
     }
 
     /**
-     * Sets the title attribute.
+     * Sets the controlType attribute.
+     * 
+     * @param controlType the column control type
      */
     public final void setControlType(String controlType)
     { 
@@ -351,6 +355,7 @@
      * Creates and returns a new comparison object for the SQL "like" operator. 
      *
      * @param value the Object value
+     * @param escape the escape character
      * @return the new DBCompareColExpr object
      */
     public DBCompareColExpr like(String value, char escape)
@@ -632,6 +637,7 @@
      * Creates and returns a sql-expression for the substring(...) function.
      * 
      * @param pos the position number of the string
+     * 
      * @return the new DBFuncExpr object
      */
     public DBColumnExpr substring(DBExpr pos)
@@ -641,6 +647,10 @@
 
     /**
      * Overloaded. @see substring(DBExpr pos)
+     * 
+     * @param pos the position number of the string
+     * 
+     * @return the new DBFuncExpr object
      */
     public DBColumnExpr substring(int pos)
     {
@@ -652,6 +662,7 @@
      * 
      * @param pos the position number of the string
      * @param count the length of the substring
+     * 
      * @return the new DBFuncExpr object
      */
     public DBColumnExpr substring(DBExpr pos, DBExpr count)
@@ -661,6 +672,11 @@
 
     /**
      * Overloaded. @see substring(DBExpr pos, DBExpr count)
+     * 
+     * @param pos the position number of the string
+     * @param count the length of the substring
+     * 
+     * @return the new DBFuncExpr object
      */
     public DBColumnExpr substring(DBExpr pos, int count)
     {
@@ -669,6 +685,11 @@
 
     /**
      * Overloaded. @see substring(DBExpr pos, DBExpr count)
+     * 
+     * @param pos the position number of the string
+     * @param count the length of the substring
+     * 
+     * @return the new DBFuncExpr object
      */
     public DBColumnExpr substring(int pos, DBExpr count)
     {
@@ -677,6 +698,11 @@
 
     /**
      * Overloaded. @see substring(DBExpr pos, DBExpr count)
+     * 
+     * @param pos the position number of the string
+     * @param count the length of the substring
+     * 
+     * @return the new DBFuncExpr object
      */
     public DBColumnExpr substring(int pos, int count)
     {
@@ -770,6 +796,8 @@
 
     /**
      * Creates and returns a sql-expression that returns the position of a string in the
current column expression.
+     * 
+     * @param str the string to find the position of
      *
      * @return the new DBFuncExpr object
      */
@@ -780,6 +808,9 @@
 
     /**
      * Creates and returns a sql-expression that returns the position of a string in the
current column expression.
+     * 
+     * @param str the string to find the position of
+     * @param fromPos the start position for the search
      *
      * @return the new DBFuncExpr object
      */
@@ -790,6 +821,11 @@
 
     /**
      * Overloaded. @see indexOf(Object str, DBExpr fromPos) 
+     * 
+     * @param str the string to find the position of
+     * @param fromPos the start position for the search
+     * 
+     * @return the new DBFuncExpr object
      */
     public DBColumnExpr indexOf(Object str, int fromPos)
     {

Modified: incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBDatabase.java
URL: http://svn.apache.org/viewvc/incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBDatabase.java?rev=747212&r1=747211&r2=747212&view=diff
==============================================================================
--- incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBDatabase.java
(original)
+++ incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBDatabase.java
Mon Feb 23 23:32:54 2009
@@ -128,6 +128,11 @@
      * Sets the database driver for this database. <br>
      * ------ DO NOT CALL DIRECTLY! ------- <br>
      * This function is called internally by DBDatabaseDriver:openDatabase()
+     * 
+     * @param driver the databae driver
+     * @param conn the connection
+     * 
+     * @return true on succes
      */
     public boolean open(DBDatabaseDriver driver, Connection conn)
     {
@@ -145,7 +150,9 @@
     /**
      * closes this database object by detaching it from the driver
      * this is a shortcut for calling
-     *  getDriver().closeDatabase(db, conn) 
+     *  getDriver().closeDatabase(db, conn)
+     *   
+     * @param conn the connection to close
      */
     public void close(Connection conn)
     {
@@ -163,6 +170,8 @@
      * to create, alter or delete other database objects<BR>
      * <P>
      * @param driver The driver for which to create a DDL Script
+     * @param script the script object that will be completed
+     * 
      * @return the DLL script for creating the entire database schema
      */
     public synchronized boolean getCreateDDLScript(DBDatabaseDriver driver, DBSQLScript script)
@@ -210,6 +219,10 @@
 
     /**
      * Sets the schema for SQL statements.
+     * 
+     * @param schema the schema to set
+     * 
+     * @return true on succes
      */
     public boolean setSchema(String schema)
     {   // Database must not be open so far
@@ -249,6 +262,8 @@
      * Sets the name of the database link used to identify objects.
      * 
      * @param linkName the database link name
+     * 
+     * @return true on succes
      */
     public boolean setLinkName(String linkName)
     {   // Database must not be open so far
@@ -283,6 +298,7 @@
      * 
      * @param buf the string buffer to which to append the qualified object name
      * @param name the object's name
+     * @param quoteName use quotes or not
      */
     public void appendQualifiedName(StringBuilder buf, String name, boolean quoteName)
     {
@@ -469,7 +485,9 @@
     /**
      * Adds a foreign key relation to the database.
      * 
+     * @param name the relation name
      * @param references a list of source and target column pairs
+     * 
      * @return true if the relations was successfully created.
      */
     public boolean addReleation(String name, DBRelation.DBReference[] references)
@@ -580,6 +598,7 @@
     /**
      * Returns a timestamp that is used for record updates.
      * 
+     * @param conn the connection
      * @return the current date and time.
      */
     public java.sql.Timestamp getUpdateTimestamp(Connection conn)
@@ -606,8 +625,9 @@
      * 
      * @param sqlCmd the SQL-Command
      * @param conn a valid connection to the database.
-     * @exception java.sql.SQLException if a database access error occurs
-     * @return the first column in the current row as a Java object
+     * 
+     * @return the first column in the current row as a Java object 
+     *         or <code>null</code> if there was no value 
      */
 
     public Object querySingleValue(String sqlCmd, Connection conn)
@@ -684,7 +704,9 @@
      * Returns the value of the first row/column of a sql-query as a long.
      * 
      * @param sqlCmd the SQL statement
+     * @param defVal the default value
      * @param conn a valid connection to the database.
+     * 
      * @return the result as a long value, if no result the long value 0
      */
     public long querySingleLong(String sqlCmd, long defVal, Connection conn)
@@ -709,7 +731,9 @@
      * Returns the value of the first row/column of a sql-query as a double.
      * 
      * @param sqlCmd the SQL statement
+     * @param defVal the default value
      * @param conn a valid connection to the database.
+     * 
      * @return the result as a long value, if no result the long value 0
      */
     public double querySingleDouble(String sqlCmd, double defVal, Connection conn)
@@ -723,6 +747,7 @@
      * 
      * @param sqlCmd the SQL statement
      * @param conn a valid connection to the database.
+     * 
      * @return the result as a long value, if no result the long value 0
      */
     public final double querySingleDouble(String sqlCmd, Connection conn)
@@ -946,6 +971,7 @@
      * @param sqlCmd the SQL-Command
      * @param sqlParams a list of objects to replace sql parameters
      * @param conn a valid connection to the database.
+     * @param setGenKeys object to set the generated keys for
      * @return the row count for insert, update or delete or 0 for SQL statements that return
nothing
      */
     public int executeSQL(String sqlCmd, Object[] sqlParams, Connection conn, DBDatabaseDriver.DBSetGenKeys
setGenKeys)
@@ -1044,9 +1070,9 @@
      * Makes all changes made since the previous commit/rollback
      * permanent and releases any database locks currently held by the
      * Connection.
-     * <P>
+     * 
      * @param conn a valid database connection
-     * @exception java.sql.SQLException if a database access error occurs
+     * 
      * @return true if successful
      */
     public boolean commit(Connection conn)
@@ -1071,7 +1097,7 @@
      * Connection.
      * <P>
      * @param conn a valid database connection
-     * @exception java.sql.SQLException if a database access error occurs
+     * 
      * @return true if successful
      */
     public boolean rollback(Connection conn)
@@ -1115,7 +1141,6 @@
      * Use it instead of rset.close() and stmt.close()<BR> 
      * <P>
      * @param rset a ResultSet object
-     * @exception java.sql.SQLException if a database access error occurs
      */
     public void closeResultSet(ResultSet rset)
     {

Modified: incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBDatabaseDriver.java
URL: http://svn.apache.org/viewvc/incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBDatabaseDriver.java?rev=747212&r1=747211&r2=747212&view=diff
==============================================================================
--- incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBDatabaseDriver.java
(original)
+++ incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBDatabaseDriver.java
Mon Feb 23 23:32:54 2009
@@ -135,6 +135,9 @@
 
         /**
          * Constructor
+         * 
+         * @param tableName the table name
+         * @param db the database object
          */
         public DBSeqTable(String tableName, DBDatabase db)
         {
@@ -271,8 +274,10 @@
 
     /**
      * Appends a table, view or column name to an SQL phrase. 
+     * 
      * @param sql the StringBuilder containing the SQL phrase.
      * @param name the name of the object (table, view or column)
+     * @param useQuotes use quotes or not
      */
     public void appendElementName(StringBuilder sql, String name, boolean useQuotes)
     {
@@ -380,7 +385,10 @@
      * @param rset the sql Resultset with the current data row
      * @param columnIndex one based column Index of the desired column
      * @param dataType the required data type
+     * 
      * @return the value of the Column 
+     * 
+     * @throws SQLException if a database access error occurs
      */
     public Object getResultValue(ResultSet rset, int columnIndex, DataType dataType)
         throws SQLException
@@ -410,8 +418,11 @@
      * @param sqlCmd the SQL-Command
      * @param sqlParams array of sql command parameters used for prepared statements (Optional).
      * @param conn a valid connection to the database.
-     * @param seqValue allows to set the auto generated key of a record (INSERT statements
only)
+     * @param genKeys allows to set the auto generated key of a record (INSERT statements
only)
+     * 
      * @return the row count for insert, update or delete or 0 for SQL statements that return
nothing
+     * 
+     * @throws SQLException if a database access error occurs
      */
     public int executeSQL(String sqlCmd, Object[] sqlParams, Connection conn, DBSetGenKeys
genKeys)
         throws SQLException
@@ -602,6 +613,12 @@
 
     /**
      * Checks the database whether or not it is consistent with the description.
+     * 
+     * @param db the database
+     * @param owner the owner
+     * @param conn the connection
+     * 
+     * @return true if it is consistent with the description
      */
     public boolean checkDatabase(DBDatabase db, String owner, Connection conn)
     {
@@ -610,6 +627,12 @@
     
     /**
      * gets an SQL command for creating, modifying or deleting objects in the database (tables,
columns, constraints, etc.)
+     * 
+     * @param type the command type 
+     * @param dbo the databse object
+     * @param script the script to complete
+     * 
+     * @return true on succes 
      */
     public boolean getDDLScript(DBCmdType type, DBObject dbo, DBSQLScript script)
     {
@@ -636,6 +659,8 @@
     /**
      * Returns a timestamp that is used for record updates.
      * 
+     * @param conn the connection that might be used 
+     * 
      * @return the current date and time.
      */
     public java.sql.Timestamp getUpdateTimestamp(Connection conn)
@@ -645,7 +670,9 @@
         return new java.sql.Timestamp(date.getTime());
     }
 
-    /** this helper function doubles up single quotes for SQL */
+    /** 
+     * this helper function doubles up single quotes for SQL 
+     */
     protected void appendTextValue(StringBuilder buf, String value)
     {
         if (value.indexOf('\'') >= 0)

Modified: incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBRecord.java
URL: http://svn.apache.org/viewvc/incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBRecord.java?rev=747212&r1=747211&r2=747212&view=diff
==============================================================================
--- incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBRecord.java (original)
+++ incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBRecord.java Mon
Feb 23 23:32:54 2009
@@ -40,9 +40,8 @@
 
 
 /**
- * This class handles one record from a database table.
- * <P>
  * 
+ * This class handles one record from a database table. 
  *
  */
 public class DBRecord extends DBRecordData implements Record, Cloneable
@@ -53,9 +52,7 @@
     public static final int REC_MODIFIED = 2;
     public static final int REC_NEW      = 3;
 
-    // Logger
-    @SuppressWarnings("hiding")
-    protected static Log    log          = LogFactory.getLog(DBRecord.class);
+    protected static final Log    log          = LogFactory.getLog(DBRecord.class);
 
     // This is the record data
     private int             state;
@@ -282,6 +279,9 @@
 
     /**
      * Returns the DBColumn for the field at the given index.
+     * 
+     * @param index the field index 
+     * 
      * @return the index value
      */
     public DBColumn getDBColumn(int index)
@@ -311,6 +311,9 @@
     
     /**
      * Returns true if the field was modified.
+     * 
+     * @param index the field index
+     *  
      * @return true if the field was modified
      */
     public boolean wasModified(int index)
@@ -339,6 +342,9 @@
     /**
      * Sets the modified state of a column.<BR>
 	 * This will force the field to be updated in the database, if set to TRUE.
+	 * 
+     * @param column the column
+     * @param isModified modified or not
      */
     public void setModified(DBColumn column, boolean isModified)
     {
@@ -419,6 +425,9 @@
     /**
      * Returns whether a field value is provided i.e. the value is not DBRowSet.NO_VALUE<BR>
      * This function is only useful in cases where records are partically loaded.<BR>
+     * 
+     * @param index the filed index
+     *  
      * @return true if a valid value is supplied for the given field or false if value is
{@link ObjectUtils#NO_VALUE}  
      */
     public boolean isValueValid(int index)
@@ -437,6 +446,10 @@
 
     /**
      * Gets the possbile Options for a field in the context of the current record.
+     * 
+     * @param column the database field column
+     *  
+     * @return the field options 
      */
     public Options getFieldOptions(DBColumn column)
     {
@@ -537,6 +550,10 @@
     
     /**
      * returns whether a field is read only or not
+     * 
+     * @param column the database column 
+     * 
+     * @return true if the field is read only
      */
     public boolean isFieldReadOnly(DBColumn column)
     {
@@ -600,6 +617,9 @@
     }
 
     /**
+     * @param table 
+     * @param conn 
+     * @return true on succes
      * @deprecated use {@link DBRecord#create(DBRowSet, Connection)}
      */
     @Deprecated
@@ -609,6 +629,8 @@
     }
 
     /**
+     * @param table 
+     * @return true on succes
      * @deprecated use {@link DBRecord#create(DBRowSet)}
      */
     @Deprecated
@@ -833,7 +855,12 @@
     }
 
     /**
-     * Initialisieren the field with the values (NO_VALUE) of the vector 'field'.
+     * Set the record default value for the fields with 
+     * the value {@link ObjectUtils.NoValue}
+     * 
+     * @param conn the sql connection
+     *  
+     * @return the number of fields set to default
      */
     public int fillMissingDefaults(Connection conn)
     {

Modified: incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBTable.java
URL: http://svn.apache.org/viewvc/incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBTable.java?rev=747212&r1=747211&r2=747212&view=diff
==============================================================================
--- incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBTable.java (original)
+++ incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBTable.java Mon
Feb 23 23:32:54 2009
@@ -206,6 +206,8 @@
      * Sets the primary keys.
      * 
      * @param columns a array with one or more DBColumn objects
+     * 
+     * @return true on succes
      */
     public boolean setPrimaryKey(DBColumn[] columns)
     {
@@ -232,6 +234,9 @@
 
     /**
      * Adds two columns to the primary key list.
+     * 
+     * @param col1 the first column 
+     * @param col2 the second column
      */
     public final void setPrimaryKey(DBColumn col1, DBColumn col2)
     {
@@ -240,6 +245,10 @@
 
     /**
      * Adds three columns to the primary key list.
+     * 
+     * @param col1 the first column
+     * @param col2 the second column
+     * @param col3 the third column
      */
     public final void setPrimaryKey(DBColumn col1, DBColumn col2, DBColumn col3)
     {
@@ -248,6 +257,12 @@
 
     /**
      * Adds an index.
+     * 
+     * @param indexName the index name
+     * @param unique is this a unique index
+     * @param indexColumns the columns indexed by this index
+     * 
+     * @return true on succes
      */
     public boolean addIndex(String indexName, boolean unique, DBColumn[] indexColumns)
     {
@@ -262,6 +277,8 @@
      * Adds a timestamp column to the table used for optimistic locking.
      * 
      * @param columnName the column name
+     * 
+     * @return the timestamp table column object
      */
     public DBTableColumn addTimestampColumn(String columnName)
     {
@@ -302,6 +319,7 @@
      * 
      * @param rec the DBRecord object. contains all fields and the field properties
      * @param conn a valid connection to the database.
+     * 
      * @return true if successful
      */
     @Override
@@ -324,7 +342,9 @@
     }
 
     /**
-     *  Returns true if cascaded deletes are enabled or false otherwise.
+     * Returns true if cascaded deletes are enabled or false otherwise.
+     *  
+     * @return true if cascade deletes are enabled
      */
     public boolean isCascadeDelete()
     {
@@ -332,7 +352,9 @@
     }
 
     /**
-     *  Sets true if delete records will.
+     * Sets true if delete records will.
+     *  
+     * @param cascadeDelete use cascade deletes or not
      */
     public void setCascadeDelete(boolean cascadeDelete)
     {

Modified: incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBTableColumn.java
URL: http://svn.apache.org/viewvc/incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBTableColumn.java?rev=747212&r1=747211&r2=747212&view=diff
==============================================================================
--- incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBTableColumn.java
(original)
+++ incubator/empire-db/trunk/empire-db/src/main/java/org/apache/empire/db/DBTableColumn.java
Mon Feb 23 23:32:54 2009
@@ -49,6 +49,7 @@
     /**
      * Constructs a DBTableColumn object set the specified parameters to this object.
      * 
+     * @param table the table object to add the column to, set to null if you don't want
it added to a table
      * @param type the type of the column e.g. integer, text, date
      * @param name the column name
      * @param size the column width
@@ -318,6 +319,7 @@
      * Creates a foreign key relation for this column.
      * 
      * @param target the referenced primary key column
+     * @return the reference object
      */
     public DBRelation.DBReference referenceOn(DBTableColumn target)
     {



Mime
View raw message