You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@empire-db.apache.org by fr...@apache.org on 2009/02/24 00:32:56 UTC
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
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)
{