Return-Path: Delivered-To: apmail-incubator-empire-db-commits-archive@minotaur.apache.org Received: (qmail 97170 invoked from network); 23 Feb 2009 23:33:21 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 23 Feb 2009 23:33:21 -0000 Received: (qmail 70058 invoked by uid 500); 23 Feb 2009 23:33:21 -0000 Delivered-To: apmail-incubator-empire-db-commits-archive@incubator.apache.org Received: (qmail 70046 invoked by uid 500); 23 Feb 2009 23:33:21 -0000 Mailing-List: contact empire-db-commits-help@incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: empire-db-dev@incubator.apache.org Delivered-To: mailing list empire-db-commits@incubator.apache.org Received: (qmail 70035 invoked by uid 99); 23 Feb 2009 23:33:21 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 23 Feb 2009 15:33:21 -0800 X-ASF-Spam-Status: No, hits=-1997.5 required=10.0 tests=ALL_TRUSTED,FUZZY_PRICES X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 23 Feb 2009 23:33:18 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 1A7052388B11; Mon, 23 Feb 2009 23:32:57 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit 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 -0000 To: empire-db-commits@incubator.apache.org From: francisdb@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20090223233257.1A7052388B11@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org 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.
* ------ DO NOT CALL DIRECTLY! -------
* 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
*

* @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 null 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. - *

+ * * @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. *

* @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()
*

* @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. - *

* + * 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.
* 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
* This function is only useful in cases where records are partically loaded.
+ * + * @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) {