[cvs] Expresso commit by lhamel: javadoc & cosmetic reformat AND
one apparent
JCorporate Ltd
jcorp at jcorp2.servlets.net
Sun Oct 3 21:59:04 PDT 2004
Log Message:
-----------
javadoc & cosmetic reformat AND one apparent bug in loadFromConnection where Date type was being mishandled.
Modified Files:
--------------
expresso/expresso-web/WEB-INF/src/com/jcorporate/expresso/core/dbobj:
DBObject.java
Revision Data
-------------
Index: DBObject.java
===================================================================
RCS file: /home/javacorp/.cvs/expresso/expresso/expresso-web/WEB-INF/src/com/jcorporate/expresso/core/dbobj/DBObject.java,v
retrieving revision 1.209
retrieving revision 1.210
diff -Lexpresso-web/WEB-INF/src/com/jcorporate/expresso/core/dbobj/DBObject.java -Lexpresso-web/WEB-INF/src/com/jcorporate/expresso/core/dbobj/DBObject.java -u -r1.209 -r1.210
--- expresso-web/WEB-INF/src/com/jcorporate/expresso/core/dbobj/DBObject.java
+++ expresso-web/WEB-INF/src/com/jcorporate/expresso/core/dbobj/DBObject.java
@@ -133,14 +133,14 @@
* <p>DBObjects are the core of Expresso's object-relational mapping. They are object-oriented
* wrappers for some sort of data. They are generally expected to be used in a single thread, like
* in processing a web query.</p>
- *
+ * <p/>
* <p>When making your own application, you derive your classes from DBObject or
- * SecuredDBObject.</p>
+ * SecuredDBObject.</p>
+ *
+ * @author Michael Nash
* @see com.jcorporate.expresso.core.dbobj.SecuredDBObject
* @see com.jcorporate.expresso.core.db.DBException
* @see com.jcorporate.expresso.core.db.DBConnection
- *
- * @author Michael Nash
* @since Expresso 1.0
*/
public abstract class DBObject
@@ -190,7 +190,7 @@
/**
* A static zero BIG DECIMAL object
- *
+ * <p/>
* author Peter Pilgrim <peterp at xenonsoft.demon.co.uk>
*
* @see #getFieldBigDecimal
@@ -201,6 +201,7 @@
/**
* DBChangeListener objects can ask to be notified when any
* change is made to objects of this type
+ *
* @todo move this static variable outside DBObject so we can wrap it for
* EJBs
*/
@@ -235,8 +236,8 @@
*/
transient private static ThreadLocal patternMatcher = new ThreadLocal() {
protected synchronized Object initialValue() {
- return new Perl5Matcher();
- }
+ return new Perl5Matcher();
+ }
};
private static Logger slog = null;
public static final String WHERE_KEYWORD = " WHERE ";
@@ -244,10 +245,11 @@
/**
* Retrieve a thread local instance of the Perl5 pattern matcher. Allows
* for optimization of # of instances of pattern matcher vs synchronization.
+ *
* @return PatternMatcher
*/
protected PatternMatcher getPatternMatcher() {
- return (PatternMatcher)patternMatcher.get();
+ return (PatternMatcher) patternMatcher.get();
}
@@ -303,7 +305,9 @@
*/
private ArrayList foundKeys = null;
- /** Attributes of this DB Object */
+ /**
+ * Attributes of this DB Object
+ */
private HashMap attributes = null;
/* The cache size of this particular DB object */
@@ -341,20 +345,18 @@
/**
* Hand a dbobject a connection that contains fields corresponding to
* what the dbobject expects, and it'll set itself.
- *
+ * <p/>
* Does not increment the result set in the DBConnection.
*
* @param connection The connection that currently has a dbobject ready to
- * be read in it's result set.
+ * be read in it's result set.
* @return The number of fields read. Depending on the SQL you sent to the connection
- * the DBObject might not have all fields in existence.
- * @throws DBException
+ * the DBObject might not have all fields in existence.
*/
public synchronized int loadFromConnection(DBConnection connection)
throws DBException {
- String oneFieldValue = null;
String oneFieldName = null;
- Object tmpData = null;
+ Object tmpData = null;
int fieldCount = 0;
JDBCObjectMetaData metadata = getJDBCMetaData();
for (Iterator it = metadata.getFieldListArray().iterator(); it.hasNext();) {
@@ -363,31 +365,31 @@
try {
DataFieldMetaData oneField = metadata.getFieldMetadata(oneFieldName);
if (oneField.isDateType()) {
- oneFieldValue = getCustomStringFieldValue(connection, oneFieldName);
+ tmpData = getCustomStringFieldValue(connection, oneFieldName);
} else {
- if (!oneField.isLongBinaryType() && !oneField.isLongCharacterType()) {
- if (connection.isStringNotTrim()) {
- tmpData = connection.getStringNoTrim(oneFieldName);
- } else {
- tmpData = connection.getString(oneFieldName);
- }
- } else {
- if (oneField.isLongBinaryType()) {
- tmpData = null;
- InputStream is = connection.getBinaryStream(oneFieldName);
- if (is != null) {
- byte[] bstr = new byte[LONGBINARY_READ_DEFAULT_SIZE];
- int j = is.read(bstr);
- if (j > 0) {
- byte[] content = new byte[j];
- System.arraycopy(bstr, 0, content, 0, j);
- tmpData = content;
- }
- }
- } else {
- tmpData = connection.getStringNoTrim(oneFieldName);
- }
- }
+ if (!oneField.isLongBinaryType() && !oneField.isLongCharacterType()) {
+ if (connection.isStringNotTrim()) {
+ tmpData = connection.getStringNoTrim(oneFieldName);
+ } else {
+ tmpData = connection.getString(oneFieldName);
+ }
+ } else {
+ if (oneField.isLongBinaryType()) {
+ tmpData = null;
+ InputStream is = connection.getBinaryStream(oneFieldName);
+ if (is != null) {
+ byte[] bstr = new byte[LONGBINARY_READ_DEFAULT_SIZE];
+ int j = is.read(bstr);
+ if (j > 0) {
+ byte[] content = new byte[j];
+ System.arraycopy(bstr, 0, content, 0, j);
+ tmpData = content;
+ }
+ }
+ } else {
+ tmpData = connection.getStringNoTrim(oneFieldName);
+ }
+ }
// if (connection.isStringNotTrimmed()) {
// oneFieldValue = connection.getStringNoTrim(oneFieldName);
@@ -406,13 +408,13 @@
//Failed to load this field, that's fine
} catch (Exception e) {
- if (log.isDebugEnabled()) {
- log.debug("Failed to load field.", e);
- }
-
- //Failed to load this field, that's fine
+ if (log.isDebugEnabled()) {
+ log.debug("Failed to load field.", e);
}
+ //Failed to load this field, that's fine
+ }
+
} /* for each retrieved field name */
@@ -427,8 +429,6 @@
* Default Constructor. This allows a DB object to be dynamically
* instantiated (e.g. loaded
* with Class.forName()) and does all of the required initializations.
- *
- * @throws DBException
*/
public DBObject()
throws DBException {
@@ -445,7 +445,6 @@
* connection pool and pass it to each of the DB objects in that section.
*
* @param newConnection The DBConnection to utilize
- * @throws DBException
*/
public DBObject(DBConnection newConnection)
throws DBException {
@@ -454,7 +453,7 @@
/**
- * <p>
+ * <p/>
* Constructor that sets a connection as the object is created - typically
* this is used when a particular DBConnection is required for the purposes of
* maintaining a database transaction. If a specific connection is not used,
@@ -466,10 +465,9 @@
* <p>This constructor is neceesary to work with otherDBMap and transaction
* capabilities</p>
*
- * @param newConnection The DBConnection to utilize
+ * @param newConnection The DBConnection to utilize
* @param setupTablesContext The data context that contains the setup (and
- * security) tables for this object
- * @throws DBException
+ * security) tables for this object
* @since Expresso 5.0.1
*/
public DBObject(DBConnection newConnection, String setupTablesContext)
@@ -497,6 +495,7 @@
/**
* Get the current locale for this dbobject
+ *
* @return The currently set locale or null if there is no locale set.
* @since Expresso 5.0.1
*/
@@ -506,6 +505,7 @@
/**
* Sets the locale to be used with this DBObject
+ *
* @param newLocale The new Locale to use with this object
* @since Expresso 5.0.1
*/
@@ -517,7 +517,6 @@
* Initialize this DBObject and set the db/context to the specified key
*
* @param newdbKey The database Context name
- * @throws DBException
*/
public DBObject(String newdbKey)
throws DBException {
@@ -532,8 +531,8 @@
* that are specified as "no nulls". This method also validates all referential
* integrity constraints specified by the object.
*
- * @throws DBException If the record cannot be added - this includes if the
- * record has a duplicate key
+ * @throws DBException If the record cannot be added - this includes if the
+ * record has a duplicate key
*/
public void add()
throws DBException {
@@ -578,6 +577,7 @@
* This is used internally by JDBC Exceutor's and JDBC Query when dealing
* with queries to the underlying datasource. Under normal conditions you
* would not used this function directly.
+ *
* @param fieldName the name of the fieldname found.
*/
public void addFoundKeys(String fieldName) {
@@ -593,10 +593,10 @@
* updates/adds/deletes occur to this DBObject, notify the registered object that
* the change has taken place. This only works between DB objects running in the
* same Virtual Machine (e.g. it is not a distribtued solution - yet)
- * @deprecated use CacheManager.getInstance().addCacheEventListener() which is called automatically from setLookupObject()
*
* @param senderClass class name to send from.
* @param newListener the target event listener.
+ * @deprecated use CacheManager.getInstance().addCacheEventListener() which is called automatically from setLookupObject()
*/
public static synchronized void addCacheEventListener(String senderClass,
CacheEventListener newListener) {
@@ -637,11 +637,10 @@
* Specify a new "detail" db object, and the fields in this object
* they specify the fields in the related object
*
- * @param objName The class name of the related object. There is assumed to be
- * a one to one or one to many relationship from this object to the specified object
- * @param keyFieldsLocal A pipe-delimited list of field names in this object
+ * @param objName The class name of the related object. There is assumed to be
+ * a one to one or one to many relationship from this object to the specified object
+ * @param keyFieldsLocal A pipe-delimited list of field names in this object
* @param keyFieldsForeign A pipe-delimieted list of field names in the other object
- * @throws DBException
*/
protected synchronized void addDetail(String objName,
String keyFieldsLocal,
@@ -654,15 +653,14 @@
* Add a field with more details: This version allows the user to specify a
* precision, for fields that use both a size and precision.
*
- * @param fieldName Name of the field
- * @param fieldType Type of the field - this is the internal Expresso type,
- * mapping in DBField to a specific database data type.
- * @param fieldSize Size of the field
- * @param fieldPrecision The precision of the field
- * @param allowNull Does this field allow nulls?
- * @param fieldDescription A longer description of this field
- * (user-understandable hopefully!)
- * @throws DBException
+ * @param fieldName Name of the field
+ * @param fieldType Type of the field - this is the internal Expresso type,
+ * mapping in DBField to a specific database data type.
+ * @param fieldSize Size of the field
+ * @param fieldPrecision The precision of the field
+ * @param allowNull Does this field allow nulls?
+ * @param fieldDescription A longer description of this field
+ * (user-understandable hopefully!)
*/
protected synchronized void addField(String fieldName, String fieldType,
int fieldSize, int fieldPrecision,
@@ -680,17 +678,16 @@
* when reporting errors to the user. This method is only used by the class that
* extends DB object, and typically only in the setupFields() method.
*
- * @param fieldName Name of the field
- * @param fieldType Type of the field - this is the "internal" Expresso type,
- * and is mapped to a specific type for the database depending on the
- * mappings in the properties file (if any). The DBField object contains
- * the default mappings.
- * @param fieldSize Size of this field, if specified for this type of field. For
- * fields that do not use a size (such as "date"), specify 0 for the size.
- * @param allowNull Does this field allow nulls?
- * @param fieldDescription A longer description of this field
- * (user-understandable hopefully!)
- * @throws DBException
+ * @param fieldName Name of the field
+ * @param fieldType Type of the field - this is the "internal" Expresso type,
+ * and is mapped to a specific type for the database depending on the
+ * mappings in the properties file (if any). The DBField object contains
+ * the default mappings.
+ * @param fieldSize Size of this field, if specified for this type of field. For
+ * fields that do not use a size (such as "date"), specify 0 for the size.
+ * @param allowNull Does this field allow nulls?
+ * @param fieldDescription A longer description of this field
+ * (user-understandable hopefully!)
*/
protected synchronized void addField(String fieldName, String fieldType,
int fieldSize, boolean allowNull,
@@ -705,7 +702,6 @@
* Determine if a record with this key exists already - if
* not, add a new record. Note that this method uses just the key
* fields to determine if the record already exists.
- * @throws DBException
*/
public synchronized void addIfNeeded()
throws DBException {
@@ -722,7 +718,8 @@
// warn user if they should not be using this method
if (value.length() == 0) {
- log.warn("a key field is empty, and yet DBObject.addIfNeeded() only uses primary-key fields for search; should you be using searchAndRetrieve() method instead? this addIfNeeded() will add ONLY if there is no other object of this type; after one object, it will always fail.");
+ log.warn(
+ "a key field is empty, and yet DBObject.addIfNeeded() only uses primary-key fields for search; should you be using searchAndRetrieve() method instead? this addIfNeeded() will add ONLY if there is no other object of this type; after one object, it will always fail.");
}
if (!oneField.isVirtual()) {
@@ -738,9 +735,10 @@
/**
* Use this in your derived checkField() class to add error messages to
* be associated with various fields.
- * @param fieldName The field name to add the error to
+ *
+ * @param fieldName The field name to add the error to
* @param errorMessage The custom error message to associate when there's
- * a problem with this field
+ * a problem with this field
*/
protected void addFieldError(String fieldName, String errorMessage) {
if (fieldErrors == null) {
@@ -755,8 +753,8 @@
*
* @param fieldName the fieldName to get the associated error message
* @return A string containing the field error message or NULL if there is
- * no error for this field. or POSSIBLY if no error message has been set
- * for this field.
+ * no error for this field. or POSSIBLY if no error message has been set
+ * for this field.
*/
public String getFieldErrorMessage(String fieldName) {
if (fieldErrors == null) {
@@ -773,6 +771,7 @@
/**
* Use this to check if a field is in error.
+ *
* @param fieldName Check if there's an error set for this field.
* @return true if an error is set for this field.
*/
@@ -801,6 +800,7 @@
/**
* Use this to check if any fields are in error.
+ *
* @return true if an error is set.
*/
public boolean hasErrors() {
@@ -813,6 +813,7 @@
/**
* Used to clear field error flags.
+ *
* @param fieldName the name of the field to clear the error flag
*/
protected void clearError(String fieldName) {
@@ -826,12 +827,11 @@
/**
* Add an index to the table.
*
- * @param indexName the name to give the index in the table; MUST CONTAIN NO SPACES--use underscores instead
+ * @param indexName the name to give the index in the table; MUST CONTAIN NO SPACES--use underscores instead
* @param fieldNames A comma delimited list of all fields in the index.
- * @param isUnique - True if this field is a unique index.
+ * @param isUnique - True if this field is a unique index.
* @throws IllegalArgumentException of fieldName is null or doesn't exist
- * or if indexName is null
- * @throws DBException
+ * or if indexName is null
*/
protected void addIndex(String indexName, String fieldNames,
boolean isUnique)
@@ -844,9 +844,9 @@
* object's key. Called after all of the "addField" calls in the setupFields()
* method to specify which fields make up the primary key of this object.
*
- * @param keyFieldName The name of the field to add as part of the key
- * @throws DBException if the field name is not valid or the field
- * allows nulls
+ * @param keyFieldName The name of the field to add as part of the key
+ * @throws DBException if the field name is not valid or the field
+ * allows nulls
*/
protected synchronized void addKey(String keyFieldName)
throws DBException {
@@ -857,7 +857,6 @@
/**
* Determine if a record with these fields exists already - if so, update. If
* not, add a new record.
- * @throws DBException
*/
public synchronized void addOrUpdate()
throws DBException {
@@ -906,6 +905,7 @@
/**
* ?????
+ *
* @param t unknown
* @throws DBException upon metadata retrieval error
*/
@@ -918,15 +918,14 @@
* Add a field with more details: This version allows the user to specify a
* precision, for fields that use both a size and precision.
*
- * @param fieldName Name of the field
- * @param fieldType Type of the field - this is the internal Expresso type,
- * mapping in DBField to a specific database data type.
- * @param fieldSize Size of the field
- * @param fieldPrecision The precision of the field
- * @param allowNull Does this field allow nulls?
- * @param fieldDescription A longer description of this field
- * (user-understandable hopefully!)
- * @throws DBException
+ * @param fieldName Name of the field
+ * @param fieldType Type of the field - this is the internal Expresso type,
+ * mapping in DBField to a specific database data type.
+ * @param fieldSize Size of the field
+ * @param fieldPrecision The precision of the field
+ * @param allowNull Does this field allow nulls?
+ * @param fieldDescription A longer description of this field
+ * (user-understandable hopefully!)
*/
protected synchronized void addVirtualField(String fieldName,
String fieldType,
@@ -944,17 +943,16 @@
* Add a field with more details: This version allows the user to specify a
* precision, for fields that use both a size and precision.
*
- * @param fieldName Name of the field
- * @param fieldType Type of the field - this is the internal Expresso type,
- * mapping in DBField to a specific database data type.
- * @param fieldSize Size of the field
- * @param fieldPrecision The precision of the field
- * @param allowNull Does this field allow nulls?
- * @param descripKey The key in the local language file for the
- * description of this field
- * @param fieldDescription A longer description of this field
- * (user-understandable hopefully!)
- * @throws DBException
+ * @param fieldName Name of the field
+ * @param fieldType Type of the field - this is the internal Expresso type,
+ * mapping in DBField to a specific database data type.
+ * @param fieldSize Size of the field
+ * @param fieldPrecision The precision of the field
+ * @param allowNull Does this field allow nulls?
+ * @param descripKey The key in the local language file for the
+ * description of this field
+ * @param fieldDescription A longer description of this field
+ * (user-understandable hopefully!)
*/
protected synchronized void addVirtualField(String fieldName,
String fieldType,
@@ -978,12 +976,11 @@
* an exception - getField and setField should be extended to handle the virtual
* fields for a particular object correctly.
*
- * @param fieldName Name of the field
- * @param fieldType Database type of the field
- * @param fieldSize Size of the field in characters
- * @param fieldDescription A longer description of this field
- * (user-understandable hopefully!)
- * @throws DBException
+ * @param fieldName Name of the field
+ * @param fieldType Database type of the field
+ * @param fieldSize Size of the field in characters
+ * @param fieldDescription A longer description of this field
+ * (user-understandable hopefully!)
*/
protected synchronized void addVirtualField(String fieldName,
String fieldType,
@@ -997,10 +994,11 @@
/**
* Parses the sort key string into useful values. This version forces full
* parsing of the input values to prevent SQL injection attacks.
+ *
* @param sortKeyString the pipe delimited string of field names with the optional 'ASC or DESC' keyword afterwords; null indicates no sorting
*/
protected void setSortKey(String sortKeyString) {
- if ( sortKeyString == null ) {
+ if (sortKeyString == null) {
if (sortKeys != null) sortKeys.clear();
return;
}
@@ -1046,9 +1044,10 @@
/**
* Add a field to be sorted in a search
+ *
* @param fieldString the name of the field to sort on
- * @param ascending true if using ascending sort order, false if descending
- * sort order.
+ * @param ascending true if using ascending sort order, false if descending
+ * sort order.
* @throws IllegalArgumentException if the fieldString does not exist
*/
public void addSortKey(String fieldString, boolean ascending) {
@@ -1073,6 +1072,7 @@
/**
* Clear the sort keys
+ *
* @see #addSortKey
*/
public void clearSortKeys() {
@@ -1087,14 +1087,13 @@
* an exception - getField and setField should be extended to handle the virtual
* fields for a particular object correctly.
*
- * @param fieldName Name of the field
- * @param fieldType Database type of the field
- * @param fieldSize Size of the field in characters
- * @param descripKey Key into the local langauge file for the
- * description of this field
- * @param fieldDescription A longer description of this field
- * (user-understandable hopefully!)
- * @throws DBException
+ * @param fieldName Name of the field
+ * @param fieldType Database type of the field
+ * @param fieldSize Size of the field in characters
+ * @param descripKey Key into the local langauge file for the
+ * description of this field
+ * @param fieldDescription A longer description of this field
+ * (user-understandable hopefully!)
*/
protected synchronized void addVirtualField(String fieldName,
String fieldType,
@@ -1111,10 +1110,9 @@
* Does the specified field allow Null?
*
* @param fieldName The name of the field name to check
- * @throws DBException
* @return true if this field allows null values
* @deprecated Since Expresso 5.1 Use DBObject.getMetaData().isAllowsNull(String fieldName)
- * instead
+ * instead
*/
public boolean allowsNull(String fieldName)
throws DBException {
@@ -1126,9 +1124,9 @@
* Find the average of the values in the specified field of records
* se;lected by the DBObject selection criteria.
*
- * @param fieldName String DBObject fieldName to average
- * @return double Average of the records matching the criteria
- * @throws DBException If the search could not be completed
+ * @param fieldName String DBObject fieldName to average
+ * @return double Average of the records matching the criteria
+ * @throws DBException If the search could not be completed
*/
public double average(String fieldName)
throws DBException {
@@ -1137,7 +1135,7 @@
/**
- * <p>
+ * <p/>
* A "simplified"e; version of add that can be used to do a basic
* INSERT statement into this table. Often used with data import
* facilities, when referential integrity and other validations
@@ -1145,10 +1143,10 @@
* <p><b>NOTE</b> BLOB Objects are not added with this function!
* <p><b>NOTE</b> this function does NOT handle auto-increment fields!
*
- * @throws DBException If the record cannot be added - this includes if the
- * record has a duplicate key
- *
- * Modify by Yves Henri AMAIZO <amy_amaizo at compuserve.com>
+ * @throws DBException If the record cannot be added - this includes if the
+ * record has a duplicate key
+ * <p/>
+ * Modify by Yves Henri AMAIZO <amy_amaizo at compuserve.com>
* @since $DatabaseSchema $Date$
*/
public synchronized void basicAdd()
@@ -1272,9 +1270,9 @@
* of SecuredDBObjects. The method is still here, however, so that
* it can be called by the cascading delete and any other methods
* as required
+ *
* @param function The appropriate function code. This is mainly used
- * in objects derived from SecuredDBObject
- * @throws DBException
+ * in objects derived from SecuredDBObject
* @return true if this function is alloed
*/
public boolean checkAllowed(String function)
@@ -1294,7 +1292,7 @@
* would not create invalid references in the "referring" objects - if it would,
* an exception is thrown, preventing the delete.
*
- * @throws DBException If the referential integrity is not correct
+ * @throws DBException If the referential integrity is not correct
*/
protected synchronized void checkAllReferredToBy()
throws DBException {
@@ -1310,8 +1308,8 @@
* Exception is thrown. See the checkRef method for the calls that should be made
* in this method.
*
- * @throws DBException If the update/add operation would result in an invalid
- * foreign key reference.
+ * @throws DBException If the update/add operation would result in an invalid
+ * foreign key reference.
*/
protected synchronized void checkAllRefs()
throws DBException {
@@ -1319,7 +1317,6 @@
/**
* public interface to checkAllRefs()
- * @throws DBException
*/
public synchronized void checkAllRefsPublic() throws DBException {
checkAllRefs();
@@ -1332,9 +1329,9 @@
* standard stuff. Every field is automatically checked by this method before the
* database is updated.
*
- * @param fieldName Name of the field to verify
- * @param fieldValue Value of the field to be evaluated
- * @throws DBException If the value is not valid
+ * @param fieldName Name of the field to verify
+ * @param fieldValue Value of the field to be evaluated
+ * @throws DBException If the value is not valid
*/
public synchronized void checkField(String fieldName, String fieldValue)
throws DBException {
@@ -1456,7 +1453,7 @@
// check for configuration (Setup) switch which turns off all relational integrity checking
String isCheckRelationalIntegrity = Setup.getValueUnrequired(getDataContext(), IS_CHECK_RELATIONAL_INTEGRITY);
boolean isCheck = true; // default is true for legacy; this is only a switch used by a minority of developers
- if ( isCheckRelationalIntegrity != null ) {
+ if (isCheckRelationalIntegrity != null) {
isCheck = StringUtil.toBoolean(isCheckRelationalIntegrity);
}
@@ -1494,10 +1491,11 @@
* Convenience method for checking a reference where blank is *not* allowed
* in the foreign key;
* This test can be turned off if you add
- * an Expresso setup (configuration) entry, 'isCheckRelationalIntegrity' set to false
+ * an Expresso setup (configuration) entry, 'isCheckRelationalIntegrity' set to false
+ *
* @param foreignKeyNames names of the foreign key fields
- * @param refObject The foreign DBObject to check against
- * @param errorMessage The custom error message to display if check fails
+ * @param refObject The foreign DBObject to check against
+ * @param errorMessage The custom error message to display if check fails
* @throws DBException if check fails
*/
protected synchronized void checkRef(String foreignKeyNames,
@@ -1519,12 +1517,12 @@
* Use of this method (and the checkAllRefs method) allow the referential
* constraints to be "declared", then automatically maintained for a dbobject.
*
- * @param foreignKeyNames A semicolon-sperated list of foreign
- * key fields from this object
- * @param refObject Another DBObject that we are to refer to
- * @param errorMessage Error string to throw if the check fails
- * @param allowBlank true if blank fields are allowed
- * @throws DBException If the referential integrity is not correct
+ * @param foreignKeyNames A semicolon-sperated list of foreign
+ * key fields from this object
+ * @param refObject Another DBObject that we are to refer to
+ * @param errorMessage Error string to throw if the check fails
+ * @param allowBlank true if blank fields are allowed
+ * @throws DBException If the referential integrity is not correct
*/
protected synchronized void checkRef(String foreignKeyNames,
DBObject refObject,
@@ -1539,7 +1537,7 @@
isCheck = StringUtil.toBoolean(isCheckRelationalIntegrity);
}
- if ( !isCheck ) return;
+ if (!isCheck) return;
refObject.setDataContext(getDataContext());
@@ -1596,7 +1594,7 @@
/**
* Set all fields to empty value & clear the last result set & clear sort keys and customWhereClause
*
- * @throws DBException If the fields cannot be cleared
+ * @throws DBException If the fields cannot be cleared
*/
public synchronized void clear()
throws DBException {
@@ -1630,12 +1628,11 @@
* This convenience method clears all the distinct flags of
* <code>DBFields</code> belonging to this
* <code>DBObject</code>
- *
+ * <p/>
* author Peter Pilgrim <peter.pilgrim at db.com>
*
* @see #getDistinctFieldCount()
* @see #isDistinct
- * @throws DBException
*/
public synchronized void clearDistinctFields()
throws DBException {
@@ -1648,12 +1645,10 @@
* This convenience method clears all the fileds to be retrieved
* <code>DBFields</code> belonging to this
* <code>DBObject</code>
- *
+ * <p/>
* author Yves Henri Amaizo <amy_amaizo at compuserve.com>
*
- *
* @see #isFieldsToRetrieve()
- * @throws DBException
*/
public synchronized void clearFieldsToRetrieve()
throws DBException {
@@ -1671,9 +1666,8 @@
* criteria for the database). The wild cards can be configured via the
* properties file.
*
- * @param fieldValue The field value to check for wild cards
- * @return True if the string does contain wild cards, False if it does not
- * @throws DBException
+ * @param fieldValue The field value to check for wild cards
+ * @return True if the string does contain wild cards, False if it does not
*/
protected synchronized boolean containsWildCards(String fieldValue)
throws DBException {
@@ -1685,8 +1679,8 @@
/**
* Just like find, but only retrieves the count, not the records themselves.
*
- * @return integer Count of the records matching the criteria
- * @throws DBException If the search could not be completed
+ * @return integer Count of the records matching the criteria
+ * @throws DBException If the search could not be completed
*/
public synchronized int count()
throws DBException {
@@ -1777,10 +1771,9 @@
* of delete also deletes associated detail records (e.g. performs a
* "cascading delete" of details.
*
- * @see DBObject#deleteAll to delete objects identified by non-key fields
- *
* @throws DBException If the delete fails or if the referential integrity
- * would be violated by the delete
+ * would be violated by the delete
+ * @see DBObject#deleteAll to delete objects identified by non-key fields
*/
public void delete()
throws DBException {
@@ -1790,12 +1783,10 @@
/**
* Delete this record, optionally deleting any associated detail
* records.
- * @see DBObject#deleteAll to delete objects identified by non-key fields
*
* @param deleteDetails Delete associated detail records if true
- * @throws DBException
- *
- * Modify by Yves Henri AMAIZO <amy_amaizo at compuserve.com>
+ * @throws DBException Modify by Yves Henri AMAIZO <amy_amaizo at compuserve.com>
+ * @see DBObject#deleteAll to delete objects identified by non-key fields
* @since $DatabaseSchema $Date$
*/
public synchronized void delete(boolean deleteDetails)
@@ -1928,6 +1919,7 @@
* Delete all of the records specified by the current search criteria. If
* you use a blank DBObject, then all the records in the table will be
* deleted
+ *
* @throws DBException upon error
*/
public synchronized void deleteAll()
@@ -2021,133 +2013,128 @@
// }
}
- /**
- * Delete all of the records specified by the current search criteria. If
- * you use a blank DBObject, then all the records in the table will be
- * deleted
- * @throws DBException upon error
- *
- * @author Yves Henri AMAIZO
- * @version $Revision$ on $Date$
- */
- public synchronized void deleteAll(boolean oneByOne)
- throws DBException{
+ /**
+ * Delete all of the records specified by the current search criteria. If
+ * you use a blank DBObject, then all the records in the table will be
+ * deleted
+ *
+ * @throws DBException upon error
+ */
+ public synchronized void deleteAll(boolean oneByOne)
+ throws DBException {
- if (oneByOne) {
- deleteAll();
- } else {
- doDeleteAll(true);
- }
- } /* deleteAll(boolean) */
+ if (oneByOne) {
+ deleteAll();
+ } else {
+ doDeleteAll(true);
+ }
+ } /* deleteAll(boolean) */
- /**
- * Delete all records inside the database.
- *
- * @see DBObject#deleteAll to delete objects identified by non-key fields
- *
- * @param deleteAllRecords Delete associated detail records if true
- * @throws DBException
+ /**
+ * Delete all records inside the database.
*
- * Modify by Yves Henri AMAIZO <amy_amaizo at compuserve.com>
+ * @param deleteAllRecords Delete associated detail records if true
+ * @throws DBException Modify by Yves Henri AMAIZO <amy_amaizo at compuserve.com>
+ * @see DBObject#deleteAll to delete objects identified by non-key fields
* @since $DatabaseSchema $Date$
- */
- public synchronized void doDeleteAll(boolean deleteAllRecords)
- throws DBException {
+ */
+ public synchronized void doDeleteAll(boolean deleteAllRecords)
+ throws DBException {
- FastStringBuffer sqlCommand = new FastStringBuffer(128);
- sqlCommand.append("DELETE FROM ");
- sqlCommand.append(getJDBCMetaData().getTargetSQLTable(getDataContext()));
+ FastStringBuffer sqlCommand = new FastStringBuffer(128);
+ sqlCommand.append("DELETE FROM ");
+ sqlCommand.append(getJDBCMetaData().getTargetSQLTable(getDataContext()));
- String whereClause;
+ String whereClause;
- if (customWhereClause != null) {
- if (appendCustomWhere) {
- whereClause = buildWhereClause(true) + customWhereClause;
- appendCustomWhere = false;
- } else {
- whereClause = customWhereClause;
- }
- sqlCommand.append(whereClause);
- customWhereClause = null;
+ if (customWhereClause != null) {
+ if (appendCustomWhere) {
+ whereClause = buildWhereClause(true) + customWhereClause;
+ appendCustomWhere = false;
+ } else {
+ whereClause = customWhereClause;
+ }
+ sqlCommand.append(whereClause);
+ customWhereClause = null;
+ } else {
+ FastStringBuffer fsb = FastStringBuffer.getInstance();
+ try {
+ // does this object have key fields?
+ if (this.getKeyFieldListIterator().hasNext()) {
+ // just use key fields to identify
+ sqlCommand.append(buildWhereClauseBuffer(false, fsb));
} else {
- FastStringBuffer fsb = FastStringBuffer.getInstance();
- try {
- // does this object have key fields?
- if (this.getKeyFieldListIterator().hasNext()) {
- // just use key fields to identify
- sqlCommand.append(buildWhereClauseBuffer(false, fsb));
- } else {
- // use all fields to identify
- sqlCommand.append(buildWhereClauseBuffer(true, fsb));
- }
- } finally {
- fsb.release();
- }
+ // use all fields to identify
+ sqlCommand.append(buildWhereClauseBuffer(true, fsb));
}
+ } finally {
+ fsb.release();
+ }
+ }
- String commandToExecute = sqlCommand.toString();
- DBConnection myConnection = null;
+ String commandToExecute = sqlCommand.toString();
+ DBConnection myConnection = null;
- try {
- if (localConnection != null) {
- myConnection = localConnection;
- } else {
- myConnection = this.getConnectionPool().getConnection(this.myClassName);
- }
+ try {
+ if (localConnection != null) {
+ myConnection = localConnection;
+ } else {
+ myConnection = this.getConnectionPool().getConnection(this.myClassName);
+ }
- if (myConnection == null) throw new DBException("null DB connection");
+ if (myConnection == null) throw new DBException("null DB connection");
- // this will commit details too if auto-commit is true;
- // otherwise, it is up to the calling routine to commit
- myConnection.executeUpdate(commandToExecute);
+ // this will commit details too if auto-commit is true;
+ // otherwise, it is up to the calling routine to commit
+ myConnection.executeUpdate(commandToExecute);
- } catch (DBException e) {
- /**
- * @todo will rollback here prevent rollback by calling routine?
- */
+ } catch (DBException e) {
+ /**
+ * @todo will rollback here prevent rollback by calling routine?
+ */
- throw ((DBException)e.fillInStackTrace());
- } finally {
- if (localConnection == null) {
- myConnection.release();
- }
- }
+ throw ((DBException) e.fillInStackTrace());
+ } finally {
+ if (localConnection == null) {
+ myConnection.release();
+ }
+ }
- if (myConnection.getUpdateCount() == 0) {
- log.debug("No record(s) deleted for SQL '" +
- sqlCommand.toString() + "'");
+ if (myConnection.getUpdateCount() == 0) {
+ log.debug("No record(s) deleted for SQL '" +
+ sqlCommand.toString() + "'");
// throw new DBException("No record(s) deleted.");
- }
+ }
// if (isCached()) {
// removeFromCache(this);
// }
- /* Now log the change if we are logging */
- if (getDef().isLoggingEnabled()) {
- ChangeLog myChangeLog = new ChangeLog();
- myChangeLog.setDataContext(getDataContext());
- myChangeLog.setField("ObjectChanged", this.myClassName);
- myChangeLog.setField("RecordKey", this.getMyKeys());
- myChangeLog.setField("Operation", "D");
- myChangeLog.setField("ChangedField", "ALL");
- myChangeLog.add();
+ /* Now log the change if we are logging */
+ if (getDef().isLoggingEnabled()) {
+ ChangeLog myChangeLog = new ChangeLog();
+ myChangeLog.setDataContext(getDataContext());
+ myChangeLog.setField("ObjectChanged", this.myClassName);
+ myChangeLog.setField("RecordKey", this.getMyKeys());
+ myChangeLog.setField("Operation", "D");
+ myChangeLog.setField("ChangedField", "ALL");
+ myChangeLog.add();
- /* We're done tracking changes */
- myUpdates = null;
- } /* if */
+ /* We're done tracking changes */
+ myUpdates = null;
+ } /* if */
// setStatus(BaseDataObject.STATUS_DELETED);
// notifyListeners("D");
- } /* doDeleteAll() */
+ } /* doDeleteAll() */
/**
* If this DB object has associated detail objects,
* locate the appropriate related detail records and
* delete them as well. This is a "cascading delete" process.
+ *
* @param detailConnection the DBConnection to use while retrieving details
- * @throws DBException
*/
protected void deleteDetails(DBConnection detailConnection)
throws DBException {
@@ -2174,11 +2161,9 @@
checkDeleteDetailPerm(detailObj);
- StringTokenizer stkLocal = new StringTokenizer(
- getJDBCMetaData().getDetailFieldsLocal(oneDet),
+ StringTokenizer stkLocal = new StringTokenizer(getJDBCMetaData().getDetailFieldsLocal(oneDet),
"|");
- StringTokenizer stkForeign = new StringTokenizer(
- getJDBCMetaData().getDetailFieldsForeign(oneDet),
+ StringTokenizer stkForeign = new StringTokenizer(getJDBCMetaData().getDetailFieldsForeign(oneDet),
"|");
boolean foundValues = false;
@@ -2215,6 +2200,7 @@
/**
* extracted for subclasses checking
+ *
* @param obj the dbobject to check it's permission
* @throws DBException upon error
*/
@@ -2234,9 +2220,9 @@
/**
* Disable change logging of this object
- * @throws DBException
+ *
* @deprecated Since Expresso 5.1
- * Use DBObject.getMetaData().disableLogging() instead.
+ * Use DBObject.getMetaData().disableLogging() instead.
*/
public synchronized void disableLogging()
throws DBException {
@@ -2249,9 +2235,9 @@
* the ChangeLog object every time an add, update, or delete is made to this
* object. It is used to track important tables, such as user information,
* account information, etc.
- * @throws DBException
+ *
* @deprecated Since Expresso 5.1
- * Use DBObject.getMetaData().disableLogging() instead.
+ * Use DBObject.getMetaData().disableLogging() instead.
*/
public synchronized void enableLogging()
throws DBException {
@@ -2266,10 +2252,10 @@
* are populated with the data in the record found after the call to find() if the
* find is successful.
*
- * @return boolean If the search resulted in a record
- * @throws DBException If the search could not be completed
- *
- * Modify by Yves Henri AMAIZO <amy_amaizo at compuserve.com>
+ * @return boolean If the search resulted in a record
+ * @throws DBException If the search could not be completed
+ * <p/>
+ * Modify by Yves Henri AMAIZO <amy_amaizo at compuserve.com>
* @since $DatabaseSchema $Date$
*/
public boolean find()
@@ -2377,7 +2363,7 @@
}
myStatement.append(" FROM ");
- myStatement.append(metadata.getTargetSQLTable(this.getDataContext()));
+ myStatement.append(metadata.getTargetSQLTable(this.getDataContext()));
if (customWhereClause != null) {
myStatement.append(customWhereClause);
@@ -2399,7 +2385,6 @@
}
DBConnection myConnection = null;
- Object tmpData = null;
try {
if (localConnection != null) {
@@ -2459,26 +2444,26 @@
// }
- if (myConnection.isStringNotTrim()) {
- oneFieldValue = myConnection.getStringNoTrim(i);
- } else {
- oneFieldValue = myConnection.getString(i);
- }
+ if (myConnection.isStringNotTrim()) {
+ oneFieldValue = myConnection.getStringNoTrim(i);
+ } else {
+ oneFieldValue = myConnection.getString(i);
+ }
}
} catch (DBException de1) {
throw new DBException("(" + myClassName +
- ") Error retrieving field '" +
- oneFieldName + "' index " + i +
- ":" + de1.getMessage(), de1.getDBMessage());
+ ") Error retrieving field '" +
+ oneFieldName + "' index " + i +
+ ":" + de1.getMessage(), de1.getDBMessage());
} catch (Exception e1) {
- throw new DBException("(" + this.myClassName +
- ") Error retrieving field '" +
- oneFieldName + "' index " + i +
- ":" + e1.getMessage(), e1.getMessage());
- }
+ throw new DBException("(" + this.myClassName +
+ ") Error retrieving field '" +
+ oneFieldName + "' index " + i +
+ ":" + e1.getMessage(), e1.getMessage());
+ }
i++;
- setField(oneFieldName, oneFieldValue);
+ setField(oneFieldName, oneFieldValue);
// set(oneFieldName, tmpData);
if (oneField.isKey()) {
@@ -2537,7 +2522,7 @@
* Return a string we can use in error messages to indicate the record
* that had the problem by including the key and the current database/context
*
- * @return String: A formatted string showing the key of this record
+ * @return String: A formatted string showing the key of this record
*/
public String forKey() {
@@ -2586,9 +2571,8 @@
* as appropriate for the current DBMS. Can be configured using property
* file values.
*
- * @return java.lang.String The formatted date time, ready for use in the DBMS
* @param fieldName java.lang.String The value for the date/time field.
- * @throws DBException
+ * @return java.lang.String The formatted date time, ready for use in the DBMS
*/
public String formatDateTime(String fieldName)
throws DBException {
@@ -2597,11 +2581,9 @@
/**
- *
* @return a map of all DBFields
- * @throws DBException
* @deprecated Since Expresso 5.1
- * Use DBObject.getMetaData.getAllDBFields() instead.
+ * Use DBObject.getMetaData.getAllDBFields() instead.
*/
protected HashMap getAllDBFields()
throws DBException {
@@ -2612,11 +2594,10 @@
/**
* Return the "allFields" Hashtable, which contains all of the DBField objects
* that make up this DB object.
- * @deprecated use getAllFieldsMap instead
- * @throws DBException
+ *
* @return a Hashtable containing all fields for this dbobject
* @deprecated Since Expresso 5.1
- * Use DBObject.getMetaData.getAllDBFields() instead.
+ * Use DBObject.getMetaData.getAllDBFields() instead.
*/
protected synchronized Hashtable getAllFields()
throws DBException {
@@ -2626,9 +2607,10 @@
/**
* <b>Non threadsafe</b> way to get an interator into the allFields objects
+ *
* @return an Iterator into the allFields HashMap
* @deprecated Use getMetaData().getAllFieldsMap().values().iterator()
- * instead [Since Expresso 5.1]
+ * instead [Since Expresso 5.1]
*/
public Iterator getAllFieldsIterator() {
return getJDBCMetaData().getAllFieldsMap().values().iterator();
@@ -2637,10 +2619,10 @@
/**
* Return the "allFields" Hashtable, which contains all of the DBField objects
* that make up this DB object.
- * @throws DBException
+ *
* @return a field HashMap
* @deprecated Since Expresso 5.1
- * Use DBObject.getMetaData.getAllFieldsMap() instead.
+ * Use DBObject.getMetaData.getAllFieldsMap() instead.
*/
protected synchronized HashMap getAllFieldsMap()
throws DBException {
@@ -2651,11 +2633,9 @@
* Return the "allKeys" hash, containing the DBField objects that make up
* the primary key for this db object.
*
- * @deprecated Use getAllKeysMap or getAllKeysIterator instead
* @return all DBObject Field keys in a hashmap.
- * @throws DBException
* @deprecated Since Expresso 5.1
- * Use DBObject.getMetaData.getAllKeysMap() instead.
+ * Use DBObject.getMetaData.getAllKeysMap() instead.
*/
protected synchronized Hashtable getAllKeys()
throws DBException {
@@ -2666,9 +2646,10 @@
/**
* <b> Non-threadsafe </b> way to get an interator into the allKeys data
* structure
+ *
* @return all Keyfields in an iterator
* @deprecated Since Expresso 5.1
- * Use DBObject.getMetaData.getAllKeysIterator() instead.
+ * Use DBObject.getMetaData.getAllKeysIterator() instead.
*/
public Iterator getAllKeysIterator() {
return getDef().getAllKeysIterator();
@@ -2679,10 +2660,9 @@
* Return the "allKeys" hash, containing the DBField objects that make up
* the primary key for this db object.
*
- * @throws DBException
* @return a HashMap of all keys
* @deprecated Since Expresso 5.1
- * Use DBObject.getMetaData.getAllKeysMap() instead.
+ * Use DBObject.getMetaData.getAllKeysMap() instead.
*/
protected synchronized HashMap getAllKeysMap()
throws DBException {
@@ -2707,12 +2687,12 @@
/**
* Retrieve the general-purpose attribute for a field
- * @param fieldName The fieldname to get the attribute for
+ *
+ * @param fieldName The fieldname to get the attribute for
* @param attribName The particular attribute for the field to retrieve
* @return the associated Object or null if there is no attribute
- * @throws DBException
* @deprecated Since Expresso 5.1
- * Use getDataField(fieldName).getMetaData.getAttribute(attribName) instead.
+ * Use getDataField(fieldName).getMetaData.getAttribute(attribName) instead.
*/
public Object getAttribute(String fieldName, String attribName)
throws DBException {
@@ -2721,9 +2701,9 @@
/**
* Get an iterator for all of the attributes specified for a field
+ *
* @param fieldName The field name to get the attirbutes for
* @return the Iterator for all attributes associated with this field
- * @throws DBException
*/
public Iterator getAttributesIterator(String fieldName)
throws DBException {
@@ -2731,7 +2711,7 @@
}
/**
- * Gets the set size of the cache for this DBOBject
+ * Gets the set size of the cache for this DBOBject
*
* @return The number of cache objects available for this object.
*/
@@ -2758,15 +2738,15 @@
} /* getCacheSize() */
/**
- * @deprecated - use getCacheStatsMap instead
* @return a Hashtable of all cache stats for this table
+ * @deprecated - use getCacheStatsMap instead
*/
public synchronized static Hashtable getCacheStats() {
return new Hashtable(sCacheStats);
}
/**
- *@return a HashMap of all cache stats
+ * @return a HashMap of all cache stats
*/
public synchronized static HashMap getCacheStatsMap() {
return new HashMap(sCacheStats);
@@ -2776,9 +2756,8 @@
* return the current object's character set
*
* @return The string containing the current characterset for this object
- * @throws DBException
* @deprecated Since Expresso 5.1
- * Use getMetaData().getCharSet() instead
+ * Use getMetaData().getCharSet() instead
*/
public synchronized String getCharset()
throws DBException {
@@ -2813,7 +2792,7 @@
*
* @return a String containing the name of the DBName to use.
* @deprecated since Expresso 5.1
- * Use getDataContext() instead
+ * Use getDataContext() instead
*/
public synchronized String getDBName() {
return getDataContext();
@@ -2823,11 +2802,11 @@
/**
* Return the default value for a field, if any. Return null
* if no default value specified.
+ *
* @param fieldName The field name to get the default value for
* @return the default value
- * @throws DBException
* @deprecated since Expresso 5.1
- * Use getMetaData().getDefaultValue(fieldName) instead
+ * Use getMetaData().getDefaultValue(fieldName) instead
*/
public String getDefaultValue(String fieldName)
throws DBException {
@@ -2839,9 +2818,8 @@
* been set, return the class name.
*
* @return A string describing this database object
- * @throws DBException
* @deprecated since Expresso 5.1
- * Use getMetaData().getDescription() instead
+ * Use getMetaData().getDescription() instead
*/
public String getDescription()
throws DBException {
@@ -2852,11 +2830,11 @@
/**
* Return the long description of a field, if available
*
- * @param fieldName The name of the field
- * @return String: The long description of the field (user-readable)
- * @throws DBException If there is no such field
+ * @param fieldName The name of the field
+ * @return String: The long description of the field (user-readable)
+ * @throws DBException If there is no such field
* @deprecated since Expresso 5.1
- * Use getMetaData().getDescription(fieldName) instead
+ * Use getMetaData().getDescription(fieldName) instead
*/
public String getDescription(String fieldName)
throws DBException {
@@ -2867,11 +2845,11 @@
/**
* Return a pipe-delimited list of field names in the named detail
* db object that have corresponding fields in this db object
- * @param detailName the classname of the detail object
+ *
+ * @param detailName the classname of the detail object
* @return java.lang.String
- * @throws DBException
* @deprecated since Expresso 5.1
- * Use getMetaData().getDetailFieldsForeign(detailName) instead
+ * Use getMetaData().getDetailFieldsForeign(detailName) instead
*/
public String getDetailFieldsForeign(String detailName)
throws DBException {
@@ -2882,11 +2860,11 @@
* Return a pipe-delimited list of field names in this db object
* that have corresponding fields in the specified detail
* db object.
+ *
* @param detailName The classname of the detail object
- * @throws DBException
* @return java.lang.String
* @deprecated since Expresso 5.1
- * Use getMetaData().getDetailFieldsLocal(detailName) instead
+ * Use getMetaData().getDetailFieldsLocal(detailName) instead
*/
public String getDetailFieldsLocal(String detailName)
throws DBException {
@@ -2896,8 +2874,8 @@
/**
* Get a list of all db objects that are specified as being "details"
* to this db object. Returns an empty enumeration if there are no details
+ *
* @return java.util.Enumeration containing all detail objects
- * @throws DBException
*/
public Enumeration getDetails()
throws DBException {
@@ -2911,9 +2889,8 @@
* <code>DBObject</code> that are set to <b>distinct</b>.
*
* @return int number of distinct fields.
- *
- * author Peter Pilgrim <peter.pilgrim at db.com>
- * @throws DBException
+ * <p/>
+ * author Peter Pilgrim <peter.pilgrim at db.com>
*/
public synchronized int getDistinctFieldCount()
throws DBException {
@@ -2939,12 +2916,11 @@
* Get a special <code>enumeration</code> object list of all
* of the fields in this object that are set to <b>distinct</b>
*
- * @return An enumerator of all of the
- * <b>distinct</b> fieldNames in this object
- *
+ * @return An enumerator of all of the
+ * <b>distinct</b> fieldNames in this object
* @throws DBException If the list cannot be retrieved
- *
- * author Peter Pilgrim <peter.pilgrim at db.com>
+ * <p/>
+ * author Peter Pilgrim <peter.pilgrim at db.com>
* @deprecated use getDistinctFieldArrayList() instead
*/
public Enumeration getDistinctFieldList()
@@ -2958,18 +2934,16 @@
* fields belonging to this <code>DBObject</code>
* returns an array of field names ( <code>String</code> )
* that are set to <b>distinct</b>.</p>
- *
+ * <p/>
* <p>If there are are no distinct fields then the method
* returns a <code>null</code> reference.</p>
*
* @return String array of <b>distinct</b> field names in this object.
- *
- * author Peter Pilgrim <peter.pilgrim at db.com>
- *
+ * <p/>
+ * author Peter Pilgrim <peter.pilgrim at db.com>
* @see #getDistinctFieldList()
* @see #getDistinctFieldCount()
* @see #isDistinct()
- * @throws DBException
*/
public String[] getDistinctFields()
throws DBException {
@@ -2999,10 +2973,10 @@
/**
* Get the string value of a field in this object as a string
*
- * @param fieldName Name of the field to fetch
- * @return The value of the given field as a string - if the field is null,
- * an empty string is returned.
- * @throws DBException If there is no such field or it's value cannot be accessed
+ * @param fieldName Name of the field to fetch
+ * @return The value of the given field as a string - if the field is null,
+ * an empty string is returned.
+ * @throws DBException If there is no such field or it's value cannot be accessed
*/
public synchronized String getField(String fieldName)
throws DBException {
@@ -3051,8 +3025,7 @@
}
try {
- return getDef().getFilterManager().filterString(
- returnValue,
+ return getDef().getFilterManager().filterString(returnValue,
filterclass,
((DBField) oneField).getFilterMethod());
} catch (Exception ex) {
@@ -3064,6 +3037,7 @@
/**
* Internal mechanism for getting the raw field data
+ *
* @param fieldName the name of the field to retrieve the data for
* @return java.lang.String or null if the fieldData doesn't exist in the map
*/
@@ -3087,10 +3061,10 @@
/**
* Boolean typesafe getField
- * @todo - Do databases localize "true and false" values in strings?
+ *
* @param fieldName to retrieve
* @return boolean true false
- * @throws DBException
+ * @todo - Do databases localize "true and false" values in strings?
*/
public boolean getFieldBoolean(String fieldName)
throws DBException {
@@ -3124,10 +3098,10 @@
/**
* Return the value of a field as a Date object
*
- * @param fieldName The field to be retrieved
- * @return The Date object equivilant to this field's value
- * @throws DBException If the field does not exist or it's value
- * is not a date or cannot be converted to a date
+ * @param fieldName The field to be retrieved
+ * @return The Date object equivilant to this field's value
+ * @throws DBException If the field does not exist or it's value
+ * is not a date or cannot be converted to a date
*/
public java.util.Date getFieldDate(String fieldName)
throws DBException {
@@ -3139,31 +3113,30 @@
/**
* Return the value of a field as a Date object
*
- * @param fieldName The field to be retrieved
- * @param formatPattern A formatting pattern according to java.text.DecimalFormat.
- * Leave null for the default format for this locale.
- * <pre>
- * Symbol Meaning
- * 0 a digit
- * # a digit, zero shows as absent
- * . placeholder for decimal separator
- * , placeholder for grouping separator.
- * E separates mantissa and exponent for exponential formats.
- * ; separates formats.
- * - default negative prefix.
- * % multiply by 100 and show as percentage
- * ? multiply by 1000 and show as per mille
- * � currency sign; replaced by currency symbol; if
- * doubled, replaced by international currency symbol.
- * If present in a pattern, the monetary decimal separator
- * is used instead of the decimal separator.
- * X any other characters can be used in the prefix or suffix
- * ' used to quote special characters in a prefix or suffix.
- * </pre>
- *
- * @return The Date object equivilant to this field's value
- * @throws DBException If the field does not exist or it's value
- * is not a date or cannot be converted to a date
+ * @param fieldName The field to be retrieved
+ * @param formatPattern A formatting pattern according to java.text.DecimalFormat.
+ * Leave null for the default format for this locale.
+ * <pre>
+ * Symbol Meaning
+ * 0 a digit
+ * # a digit, zero shows as absent
+ * . placeholder for decimal separator
+ * , placeholder for grouping separator.
+ * E separates mantissa and exponent for exponential formats.
+ * ; separates formats.
+ * - default negative prefix.
+ * % multiply by 100 and show as percentage
+ * ? multiply by 1000 and show as per mille
+ * � currency sign; replaced by currency symbol; if
+ * doubled, replaced by international currency symbol.
+ * If present in a pattern, the monetary decimal separator
+ * is used instead of the decimal separator.
+ * X any other characters can be used in the prefix or suffix
+ * ' used to quote special characters in a prefix or suffix.
+ * </pre>
+ * @return The Date object equivilant to this field's value
+ * @throws DBException If the field does not exist or it's value
+ * is not a date or cannot be converted to a date
* @see java.text.DecimalFormat
*/
public String getFieldDecimalFormatted(String fieldName,
@@ -3210,11 +3183,10 @@
* Get the primitive <code>float</code> value of a field in this object. we use the locale specified
* in the properties file directly to determine how to parse the field
*
- * @param fieldName Name of the field to be retrieved
- * @return float The value of the field as a float
- * @throws DBException If there is no such field or it's value
- * cannot be converted to a float
- *
+ * @param fieldName Name of the field to be retrieved
+ * @return float The value of the field as a float
+ * @throws DBException If there is no such field or it's value
+ * cannot be converted to a float
* @see #setField(String,double)
*/
public float getFieldFloat(String fieldName)
@@ -3264,11 +3236,10 @@
* Get the primitive <code>double</code> value of a field in this object. we use the locale specified
* in the properties file directly to determine how to parse the field
*
- * @param fieldName Name of the field to be retrieved
- * @return float The value of the field as a float
- * @throws DBException If there is no such field or it's value
- * cannot be converted to a float
- *
+ * @param fieldName Name of the field to be retrieved
+ * @return float The value of the field as a float
+ * @throws DBException If there is no such field or it's value
+ * cannot be converted to a float
* @see #setField(String,double)
*/
public double getFieldDouble(String fieldName)
@@ -3317,20 +3288,18 @@
* Get the <code>BigDecimal</code> value of a field in this object.
* We use the locale specified
* in the properties file directly to determine how to parse the field
- *
- * <p>
+ * <p/>
+ * <p/>
* NB: Corresponds to <code>java.sql.Type.DECIMAL</code> or <code>java.sql.Type.NUMERIC</code>
* </p>
*
- * @param fieldName Name of the field to be retrieved
- * @return BigDecimal The value of the field as a BigDecimal object
- * @throws DBException If there is no such field or it's value
- * cannot be converted to a BigDecimal
- *
- * author Peter Pilgrim <peterp at xenonsoft.demon.co.uk>
- *
+ * @param fieldName Name of the field to be retrieved
+ * @return BigDecimal The value of the field as a BigDecimal object
+ * @throws DBException If there is no such field or it's value
+ * cannot be converted to a BigDecimal
+ * <p/>
+ * author Peter Pilgrim <peterp at xenonsoft.demon.co.uk>
* @see "'JDBC API Tutorial and Reference', Second Edition, pg 944, by Catell, Hamilton et al; published by Addison Wesley"
- *
* @see #setField(String,BigDecimal)
*/
public BigDecimal getFieldBigDecimal(String fieldName)
@@ -3364,11 +3333,10 @@
* Get the primitive <code>byte</code> value of a field in this object.
* A convenience method for <code>getField</code>
*
- * @param fieldName Name of a field in this object
- * @return int The value of the field as a int
- * @throws DBException if there is no such field or it's value cannot be
- * converted to a byte integer.
- *
+ * @param fieldName Name of a field in this object
+ * @return int The value of the field as a int
+ * @throws DBException if there is no such field or it's value cannot be
+ * converted to a byte integer.
* @see #setField(String,byte)
*/
public byte getFieldByte(String fieldName)
@@ -3389,54 +3357,51 @@
}
}
- /**
- * Get the primitive <code>byteArray</code> value of a field in this object.
- * A convenience method for <code>getField</code>
- *
- * @param fieldName Name of a field in this object
- * @return int The value of the field as a byte{]
- * @throws DBException if there is no such field or it's value cannot be
- * get to a byte array.
- *
- * @see #setField(String,byte[])
- */
- public byte[] getFieldByteArray(String fieldName)
- throws DBException {
- DataFieldMetaData oneField = getFieldMetaData(fieldName);
- String strVal = null;
- try {
- if (fieldData == null) {
+ /**
+ * Get the primitive <code>byteArray</code> value of a field in this object.
+ * A convenience method for <code>getField</code>
+ *
+ * @param fieldName Name of a field in this object
+ * @return int The value of the field as a byte{]
+ * @throws DBException if there is no such field or it's value cannot be
+ * get to a byte array.
+ * @see #setField(String,byte[])
+ */
+ public byte[] getFieldByteArray(String fieldName)
+ throws DBException {
+ String strVal = null;
+ try {
+ if (fieldData == null) {
// fieldData = new HashMap();
- return null;
- }
+ return null;
+ }
- DataField df = (DataField) fieldData.get(fieldName);
- if (df == null) {
- return null;
- }
+ DataField df = (DataField) fieldData.get(fieldName);
+ if (df == null) {
+ return null;
+ }
- Object o = df.getValue();
- if (o == null) {
- return null;
- }
- return (byte[]) o;
- } catch (Exception ex) {
- throw new DBException("(" + this.myClassName +
- ") Unable to get a byte array value from field " +
- fieldName + " which contained '" + strVal +
- "'", ex.getMessage());
- }
+ Object o = df.getValue();
+ if (o == null) {
+ return null;
+ }
+ return (byte[]) o;
+ } catch (Exception ex) {
+ throw new DBException("(" + this.myClassName +
+ ") Unable to get a byte array value from field " +
+ fieldName + " which contained '" + strVal +
+ "'", ex.getMessage());
}
+ }
/**
* Get the primitive <code>integer</code> value of a field in this object.
* A convenience method for <code>getField</code>
*
- * @param fieldName Name of a field in this object
- * @return int The value of the field as a int
- * @throws DBException if there is no such field or it's value cannot be
- * converted to a short integer.
- *
+ * @param fieldName Name of a field in this object
+ * @return int The value of the field as a int
+ * @throws DBException if there is no such field or it's value cannot be
+ * converted to a short integer.
* @see #setField(String,short)
*/
public short getFieldShort(String fieldName)
@@ -3462,11 +3427,10 @@
* Get the primitive <code>integer</code> value of a field in this object.
* A convenience method for <code>getField</code>
*
- * @param fieldName Name of a field in this object
- * @return int The value of the field as a int; will return 0 if field is null; throw if underlying string is otherwise non-integer;
- * @throws DBException if there is no such field or it's value cannot be
- * converted to an integer.
- *
+ * @param fieldName Name of a field in this object
+ * @return int The value of the field as a int; will return 0 if field is null; throw if underlying string is otherwise non-integer;
+ * @throws DBException if there is no such field or it's value cannot be
+ * converted to an integer.
* @see #setField(String,int)
* @see #isFieldNull(java.lang.String) in order to know if 0 is 'real' or because of an underlying null
*/
@@ -3495,11 +3459,10 @@
* Get the prmitive <code>long</code> value of a field in this object.
* A convenience method for <code>getField</code>
*
- * @param fieldName Name of a field in this object
- * @return long The value of the field as a long
- * @throws DBException if there is no such field or it's value cannot be
- * converted to a long integer.
- *
+ * @param fieldName Name of a field in this object
+ * @return long The value of the field as a long
+ * @throws DBException if there is no such field or it's value cannot be
+ * converted to a long integer.
* @see #setField(String,long)
*/
public long getFieldLong(String fieldName)
@@ -3525,11 +3488,10 @@
/**
* Get a list of all of the fields in this object
*
- * @deprecated Use getFieldListArray or getFieldListIterator instead
- * @return A Vector of all of the fieldNames in this object
- * @throws DBException If the list cannot be retrieved
+ * @return A Vector of all of the fieldNames in this object
+ * @throws DBException If the list cannot be retrieved
* @deprecated since Expresso 5.1
- * Use getMetaData().getFieldListArray() instead
+ * Use getMetaData().getFieldListArray() instead
*/
public synchronized Enumeration getFieldList()
throws DBException {
@@ -3541,10 +3503,10 @@
* Get a list of all of the fields in this object This is threadsafe in that
* it makes a new copy of the fieldNamesInOrder ArrayList
*
- * @return A Vector of all of the fieldNames in this object
- * @throws DBException If the list cannot be retrieved
+ * @return A Vector of all of the fieldNames in this object
+ * @throws DBException If the list cannot be retrieved
* @deprecated since Expresso 5.1
- * Use getMetaData().getFieldListArray() instead
+ * Use getMetaData().getFieldListArray() instead
*/
public synchronized ArrayList getFieldListArray() throws DBException {
return getDef().getFieldListArray();
@@ -3554,9 +3516,9 @@
* Get a list of all of the fields in this object This iterator is not thread
* safe.
*
- * @return An iterator of the fieldNamesInOrder array list
+ * @return An iterator of the fieldNamesInOrder array list
* @deprecated since Expresso 5.1
- * Use getMetaData().getFieldListArray() instead
+ * Use getMetaData().getFieldListArray() instead
*/
public Iterator getFieldListIterator() {
return getDef().getFieldListIterator();
@@ -3569,14 +3531,15 @@
* significant memory impact. Because of this it's also recommended that
* for maximum performance you might want some sort of Persistant store
* cacheing scheme.
+ *
* @param fieldName the name of the field to retrieve
* @return an InputStream object that will contain the object to retrieve
* @throws DBException upon error
- * @deprecated since Expresso 5.1 Use LobField directly or
- * com.jcorporate.expresso.services.dbobj.MediaDBObject for BLOB storage since
- * they all require much less memory as well as provides more dynamic database
- * support.
* @see com.jcorporate.expresso.services.dbobj.MediaDBObject
+ * @deprecated since Expresso 5.1 Use LobField directly or
+ * com.jcorporate.expresso.services.dbobj.MediaDBObject for BLOB storage since
+ * they all require much less memory as well as provides more dynamic database
+ * support.
*/
public InputStream getBinaryField(String fieldName) throws DBException {
DBConnectionPool connectionPool = null;
@@ -3602,15 +3565,16 @@
/**
* Sets a BLOB file to this table.
- * @param fieldName The name of the field to save.
+ *
+ * @param fieldName The name of the field to save.
* @param incomingData the stream to write to the database table.
- * @param dataLength the total length of the incoming data stream. For
- * example, if you're saving a file, then the total length of the file.
+ * @param dataLength the total length of the incoming data stream. For
+ * example, if you're saving a file, then the total length of the file.
* @throws DBException upon error
* @deprecated since Expresso 5.1. Use LobField directly or
- * com.jcorporate.expresso.services.dbobj.MediaDBObject for BLOB storage since
- * they all require much less memory as well as provides more dynamic database
- * support.
+ * com.jcorporate.expresso.services.dbobj.MediaDBObject for BLOB storage since
+ * they all require much less memory as well as provides more dynamic database
+ * support.
*/
public void saveBinaryField(String fieldName,
InputStream incomingData,
@@ -3639,7 +3603,8 @@
/**
* Sets a byte array to the underlying data as a blob
- * @param fieldName The name of the field to save.
+ *
+ * @param fieldName The name of the field to save.
* @param incomingData the stream to write to the database table.
* @throws DBException upon error
*/
@@ -3672,13 +3637,13 @@
* fields belonging to this <code>DBObject</code>
* returns an array of field names ( <code>String</code> ).
* <p>Author: Peter Pilgrim</p>
+ *
* @return String array of all field names in this object.
* @see #getFieldList()
* @see #getDistinctFieldCount()
* @see #getDistinctFieldList()
- * @throws DBException
* @deprecated since Expresso 5.1
- * Use getMetaData().getFields() instead
+ * Use getMetaData().getFields() instead
*/
public String[] getFields()
throws DBException {
@@ -3693,8 +3658,6 @@
* author Yves Henri Amaizo <amy_amaizo at compuserve.com>
*
* @return int number of retrieve fields.
- *
- * @throws DBException
*/
public synchronized int getFieldsToRetrieveCount()
throws DBException {
@@ -3710,7 +3673,7 @@
* Return the number of records found in the last search operation. See also
* count() and find().
*
- * @return The count of records found
+ * @return The count of records found
*/
public long getFoundCount() {
if (foundKeys == null) {
@@ -3756,9 +3719,9 @@
* exception to be thrown if indexList is null. Call hasIndex() first
* before calling getIndexArray
* To be soon deprecated
- * @throws DBException
+ *
* @return an object containing all the DBOBjects
- * Use getMetaData().getIndexArray() instead
+ * Use getMetaData().getIndexArray() instead
*/
public synchronized Object[] getIndexArray()
throws DBException {
@@ -3769,7 +3732,7 @@
* Get a string consisting of the values of each key field for this object
* appended together with a | between them.
*
- * @return Value of all keys appended with a | between
+ * @return Value of all keys appended with a | between
*/
public String getKey() {
try {
@@ -3784,9 +3747,8 @@
/**
* Get a list of all of the names of the key fields in this object
*
+ * @return A Vector of all of the names of the key fields
* @deprecated Use getKeyFieldArray instead
- * @return A Vector of all of the names of the key fields
- * @throws DBException
*/
public Enumeration getKeyFieldList()
throws DBException {
@@ -3799,10 +3761,9 @@
/**
* Get a list of all of the names of the key fields in this object
*
- * @return An ArrayList of all of the names of the key fields
- * @throws DBException
+ * @return An ArrayList of all of the names of the key fields
* @deprecated since Expresso 5.1
- * Use getMetaData().getKeyFieldListArray() instead
+ * Use getMetaData().getKeyFieldListArray() instead
*/
public ArrayList getKeyFieldListArray()
throws DBException {
@@ -3813,8 +3774,8 @@
* Get a list of all of the fields in this object This iterator is not thread
* safe.
*
- * @return An iterator of the fieldNamesInOrder array list
- * @throws DBException If the list cannot be retrieved
+ * @return An iterator of the fieldNamesInOrder array list
+ * @throws DBException If the list cannot be retrieved
*/
public Iterator getKeyFieldListIterator()
throws DBException {
@@ -3824,9 +3785,9 @@
/**
* Return the length of a field
*
- * @param fieldName The name of the field
- * @return String: The length of the field
- * @throws DBException If there is no such field in this object
+ * @param fieldName The name of the field
+ * @return String: The length of the field
+ * @throws DBException If there is no such field in this object
*/
public String getLength(String fieldName)
throws DBException {
@@ -3838,9 +3799,9 @@
/**
* Get the length of this field as an integer
+ *
* @param fieldName to check
* @return length of field
- * @throws DBException
*/
public int getLengthInt(String fieldName)
throws DBException {
@@ -3849,8 +3810,9 @@
/**
* programmatically gets the limitation optimisation insertion position
- *
+ * <p/>
* author Peter Pilgrim, Thu Jun 21 10:30:59 BST 2001
+ *
* @return the limitation position code.
* @deprecated Use the connection pool version instead
*/
@@ -3864,11 +3826,11 @@
/**
* programmatically gets the limitation syntax string
- *
+ * <p/>
* author Peter Pilgrim, Thu Jun 21 10:30:59 BST 2001
- * @deprecated use the pool limitation syntax instead
- * @return the Limitation Syntax String
*
+ * @return the Limitation Syntax String
+ * @deprecated use the pool limitation syntax instead
*/
public synchronized String getLimitationSyntax() {
try {
@@ -3899,6 +3861,7 @@
/**
* Returns the local connection currently associated with this DBObject...
* may be null if no local connection has ever been set.
+ *
* @return com.jcorporate.expresso.core.db.DBConnection or null
*/
public DBConnection getLocalConnection() {
@@ -3908,15 +3871,14 @@
/**
* Get the Maximum value in the table of a particular field
- *
+ * <p/>
* Contributed by Madan Mohanrao Kulkarni [kulsmadya at rediffmail.com]
*
- * @param fieldName the Fieldname to get the max value for.
+ * @param fieldName the Fieldname to get the max value for.
* @param whereClause Use a custom whereclause?
- * @throws DBException
* @return a String containing the maximum value for this field name
- *
- * Modify by Yves Henri AMAIZO <amy_amaizo at compuserve.com>
+ * <p/>
+ * Modify by Yves Henri AMAIZO <amy_amaizo at compuserve.com>
* @since $DatabaseSchema $Date$
*/
public String getMax(String fieldName, boolean whereClause)
@@ -3932,12 +3894,12 @@
myConnection = getConnectionPool().getConnection(myClassName);
}
if (!whereClause) {
- myConnection.execute("SELECT MAX(" + fieldName + ") FROM " +
- getJDBCMetaData().getTargetSQLTable(this.getDataContext()));
+ myConnection.execute("SELECT MAX(" + fieldName + ") FROM " +
+ getJDBCMetaData().getTargetSQLTable(this.getDataContext()));
} else {
FastStringBuffer sqlCommand = new FastStringBuffer(60);
- sqlCommand.append("SELECT MAX(" + fieldName + ") FROM " +
- getJDBCMetaData().getTargetSQLTable(this.getDataContext()) + " ");
+ sqlCommand.append("SELECT MAX(" + fieldName + ") FROM " +
+ getJDBCMetaData().getTargetSQLTable(this.getDataContext()) + " ");
if (customWhereClause != null) {
sqlCommand.append(customWhereClause);
@@ -3969,11 +3931,10 @@
/**
* Get the Maximum value in the table of a particular field
- *
+ * <p/>
* Contributed by Madan Mohanrao Kulkarni [kulsmadya at rediffmail.com]
*
* @param fieldName The fieldName to check against
- * @throws DBException
* @return The maximum value for this field in the table.
*/
public String getMax(String fieldName)
@@ -3987,7 +3948,7 @@
* "max records" value has been specified, this method provides access to it.
*
* @return The maximum number of records that should be retrieved, or zero
- * if no max has been set
+ * if no max has been set
*/
public int getMaxRecords() {
return maxRecords;
@@ -3998,8 +3959,8 @@
* Get a string consisting of the values of each key field for this object
* appended together with a | between them.
*
- * @return Value of all keys appended with a | between
- * @throws DBException If the key list cannot be built.
+ * @return Value of all keys appended with a | between
+ * @throws DBException If the key list cannot be built.
*/
public String getMyKeys()
throws DBException {
@@ -4030,8 +3991,8 @@
* Return the vector of updates (see the inner class) that specify what changes
* were just made to this object.
*
- * @deprecated - Use getMyUpdatesArray() instead
* @return Vector containing logged updates
+ * @deprecated - Use getMyUpdatesArray() instead
*/
protected Vector getMyUpdates() {
if (myUpdates == null) {
@@ -4044,6 +4005,7 @@
/**
* Return the array of updates (see the inner class) that specify what changes
* were just made to this object.
+ *
* @return Logged Updates in an Object Array
*/
protected Object[] getMyUpdatesArray() {
@@ -4057,11 +4019,10 @@
/**
* Get the name of this object
*
- * @return String The database object name, or the table name if none
- * has been assigned
- * @throws DBException
+ * @return String The database object name, or the table name if none
+ * has been assigned
* @deprecated since Expresso 5.1
- * Use getMetaData().getName() instead
+ * Use getMetaData().getName() instead
*/
public String getName()
throws DBException {
@@ -4073,12 +4034,11 @@
* Gets the number of records that be skipped. The offset records.
* A DB Object can be told to skip a certain number of
* records, before reading records from the <code>ResultSet</code>.
- *
+ * <p/>
* author Peter Pilgrim, Thu Jun 21 10:30:59 BST 2001
*
* @return The maximum number of records that should be
- * skipped over before reading the data records.
- *
+ * skipped over before reading the data records.
* @see #setOffsetRecord(int)
*/
public int getOffsetRecord() {
@@ -4088,6 +4048,7 @@
/**
* Return the name of the db/context originally requested. getDBName will return the name of the db/context
* that we've been "mapped" to if such mapping occurs.
+ *
* @return the original dbname before the otherdb lookup occurs
* @deprecated Use getMappedDataContext instead
*/
@@ -4099,7 +4060,6 @@
* Get the precision of thie field, if one was specified
*
* @param fieldName The fieldname to get the precision for
- * @throws DBException
* @return length of precision as integer
*/
public int getPrecision(String fieldName)
@@ -4113,8 +4073,8 @@
/**
* Return the set of records found by the last searchAndRetrieve
*
+ * @return Vector of DB Objects retrieved by the last searchAndRetrieve
* @deprecated Use getRecordSetArrayList() instead
- * @return Vector of DB Objects retrieved by the last searchAndRetrieve
*/
public Vector getRecordSet() {
if (recordSet == null) {
@@ -4127,7 +4087,7 @@
/**
* Return the set of records found by the last searchAndRetrieve
*
- * @return Object of DB Objects retrieved by the last searchAndRetrieve
+ * @return Object of DB Objects retrieved by the last searchAndRetrieve
* @deprecated This function is unhealthy for memory.
*/
public synchronized ArrayList getRecordSetArrayList() {
@@ -4139,12 +4099,9 @@
} /* getRecordSetArrayList */
/**
- *
- *
* @return Returns the schema name
- * @throws DBException
* @deprecated since Expresso 5.1
- * Use getMetaData().getSchema() instead
+ * Use getMetaData().getSchema() instead
*/
public String getSchema()
throws DBException {
@@ -4157,13 +4114,12 @@
* the database. It may do additional processing such as encryption depending
* on the field attributes.
*
- * @todo This is not completely implemented yet, and this responsibility for
- * formating a field should probably be
- * put into DBField for better object orientation.
- * @throws DBException
- * @return the value to write to the data source.
* @param theField A DBField object
- */
+ * @return the value to write to the data source.
+ * @todo This is not completely implemented yet, and this responsibility for
+ * formating a field should probably be
+ * put into DBField for better object orientation.
+ */
public String getSerializedForm(DBField theField)
throws DBException {
@@ -4176,9 +4132,8 @@
* that a database object could update or affect other tables as well.
*
* @return String: Table name of the target table of this database object
- * @throws DBException
* @deprecated Since Expresso 5.0 Use getTargetTable instead [Will be
- * removed in Expresso 5.2]
+ * removed in Expresso 5.2]
*/
public String getTableName()
throws DBException {
@@ -4191,7 +4146,6 @@
* that a database object could update or affect other tables as well.
*
* @return String: Table name of the target table of this database object
- * @throws DBException
* @deprecated since Expresso 5.1; Use getJDBCMetaData().getTargetSQLTable() instead
*/
public String getTargetTable()
@@ -4202,21 +4156,20 @@
/**
* This will return a new object of the type of the subclass.
- *
+ * <p/>
* OVERRIDE this method with implentation like
* <p>return new MyObject()</p>
* if you want greatest efficiency. For example: A DBObject called "Customer"
* should return a new "Customer" object.
- *
+ * <p/>
* the implementation in DBObject uses getClass().newInstance(), which seems to be about
* 50% slower than "new MyObject()" calls on JDK 1.4
- *
+ * <p/>
* Note that this method should never be called directly. It should only
* be called by newInstance()
*
+ * @return DBObject A newly allocated object of the subclass's class
* @see #getThisDBObj
- * @return DBObject A newly allocated object of the subclass's class
- * @throws DBException
*/
protected DBObject getThisDBObj()
throws DBException {
@@ -4241,13 +4194,12 @@
/**
* get a new instance of this object, with some basic attributes copied,
* like the local connection of the transaction
- *
+ * <p/>
* Generally speaking, DO NOT OVERRIDE THIS METHOD. Instead, to improve efficiency,
* most subclasses will override the method getThisDBObj()
*
+ * @return DBObject A newly allocated object of the subclass's class
* @see #getThisDBObj
- * @return DBObject A newly allocated object of the subclass's class
- * @throws DBException
*/
public DBObject newInstance()
throws DBException {
@@ -4259,6 +4211,7 @@
/**
* called by newInstance(), this method should make sure that the newly created
* object is properly initialized
+ *
* @param returnObj the object to set the attributes to.
* @throws DBException upon error
*/
@@ -4273,9 +4226,10 @@
/**
* Constructor method that takes a DataTransferObject and builds a full fledged
* DBObject out of it.
+ *
* @param dto The DataTransferObject
* @return a constructed DBObject that still needs DataContext and record
- * ownership to be set.
+ * ownership to be set.
* @throws DBException upon error
*/
public static synchronized DBObject getThisDBbj(DataTransferObject dto) throws DBException {
@@ -4297,8 +4251,8 @@
/**
* Gets the data transfer object usually for serialization purposes
+ *
* @return The built DataTransferObject
- * @throws DBException
*/
public synchronized DataTransferObject getDataTransferObject() throws DBException {
@@ -4317,8 +4271,8 @@
/**
* fill fields with values found in dto; REPLACES any data field already present.
+ *
* @param dto The filled out data transfer object
- * @throws DBException
*/
public synchronized void setDataTransferObject(DataTransferObject dto) throws DBException {
//
@@ -4355,10 +4309,11 @@
/**
* ????
+ *
* @return Iterator of Transitions
* @throws DBException upon error
* @deprecated since Expresso 5.1
- * Use getMetaData().getTransitionsIterator() instead
+ * Use getMetaData().getTransitionsIterator() instead
*/
public Iterator getTransitionsIterator()
throws DBException {
@@ -4369,11 +4324,11 @@
/**
* Return the type of a field - this method returns the internal Expresso type
*
- * @param fieldName The name of the field
- * @return String: The type of the field
- * @throws DBException If there is no such field in this object
+ * @param fieldName The name of the field
+ * @return String: The type of the field
+ * @throws DBException If there is no such field in this object
* @deprecated since Expresso 5.1
- * Use getFieldMetaData(String).getTypeString() instead
+ * Use getFieldMetaData(String).getTypeString() instead
*/
public String getType(String fieldName)
throws DBException {
@@ -4388,8 +4343,8 @@
* for a multi-valued field.
* (Contributed by Adam Rossi)
*
- * @return java.lang.String The description of this multi-valued field
* @param fieldName java.lang.String
+ * @return java.lang.String The description of this multi-valued field
* @throws DBException If there is no such field, or the values cannot be retrieved.
*/
public String getValidValueDescrip(String fieldName)
@@ -4423,6 +4378,7 @@
/**
* Retrieve a list of valid value object for this particular dbobject
+ *
* @param fieldName the name of the field to get the valid values list for
* @return java.util.List of ValidValue objects
* @throws DBException upon error
@@ -4441,7 +4397,6 @@
*
* @param fieldName The name of the fields for which a value set is requested
* @return A Vector of ValidValue objects
- * @throws DBException
*/
public synchronized Vector getValidValues(String fieldName)
throws DBException {
@@ -4493,8 +4448,7 @@
//Do nothing, the method just doesn't exist.
} catch (SecurityException se) {
- throw new DBException(
- "Security Exception trying to call" +
+ throw new DBException("Security Exception trying to call" +
" setDBName in loading lookup object", se);
} catch (java.lang.reflect.InvocationTargetException ive) {
ive.printStackTrace();
@@ -4546,9 +4500,8 @@
* a cache name the same as the db objects class name with ".validValues" appended
* TODO: This should be converted to array List versions
*
- * @see #getValidValues
- * @throws DBException
* @return java.util.Vector of valid values
+ * @see #getValidValues
*/
public Vector getValues()
throws DBException {
@@ -4560,21 +4513,21 @@
* Basic version of getValidValues that stores/retrieves the valid
* values in a Cache. This method does <em>not</em> support
* internationalisation (i18n).
- *
- * <p>
+ * <p/>
+ * <p/>
* Valid values are store inside cache with a key name that equals
* <code>myClassName+".validValues"</code>
* The method creates <code>ValidValue</code> object instances and
* stores them in the cache.
* </p>
*
- * @return java.util.Vector
- * @param valueField java.lang.String
+ * @param valueField java.lang.String
* @param descripField java.lang.String
+ * @return java.util.Vector
* @throws DBException if a database error occurs
- *
- * #see #getValuesDefault(String valueField, String descripField, String whereClause)
- * #see #getISOValuesDefault(String valueField, String descripField)
+ * <p/>
+ * #see #getValuesDefault(String valueField, String descripField, String whereClause)
+ * #see #getISOValuesDefault(String valueField, String descripField)
*/
protected Vector getValuesDefault(String valueField, String descripField)
throws DBException {
@@ -4585,23 +4538,23 @@
* Basic filtered version of getValidValues that stores/retrieves the valid
* values in a Cache. This method does <em>not</em> support
* internationalisation (i18n).
- *
- * <p>
+ * <p/>
+ * <p/>
* Valid values are store inside cache with a key name that equals
* <code>myClassName+".validValues"</code>
* The method creates <code>ValidValue</code> object instances and
* stores them in the cache.
* </p>
*
- * @return java.util.Vector
- * @param valueField java.lang.String
+ * @param valueField java.lang.String
* @param descripField java.lang.String
- * @param whereClause the where clause that will be pass
- * to setCustomWhereClause.
+ * @param whereClause the where clause that will be pass
+ * to setCustomWhereClause.
+ * @return java.util.Vector
* @throws DBException if a database error occurs
- *
- * #see #setCustomWhereClause(String newCustomWhere)
- * #see #getISOValuesDefault(String valueField, String descripField)
+ * <p/>
+ * #see #setCustomWhereClause(String newCustomWhere)
+ * #see #getISOValuesDefault(String valueField, String descripField)
*/
protected Vector getValuesDefault(String valueField, String descripField,
String whereClause)
@@ -4614,26 +4567,26 @@
* in a Cache. This method retrieves the valid values in the order
* specified by the sortKeyString, and filters them with the given where
* clause. Note, it does <em>not</em> support internationalisation (i18n).
- *
- * <p>
+ * <p/>
+ * <p/>
* Valid values are store inside cache with a key name that equals
* <code>myClassName+".validValues"</code>
* The method creates <code>ValidValue</code> object instances and
* stores them in the cache.
* </p>
*
- * @return java.util.Vector
- * @param valueField java.lang.String
- * @param descripField java.lang.String
- * @param whereClause the where clause that will be pass
- * to setCustomWhereClause.
+ * @param valueField java.lang.String
+ * @param descripField java.lang.String
+ * @param whereClause the where clause that will be pass
+ * to setCustomWhereClause.
* @param sortKeyString the pipe delimited string of field names with the
- * optional 'ASC or DESC' keyword afterwords; pass in null to indicate no sorting
+ * optional 'ASC or DESC' keyword afterwords; pass in null to indicate no sorting
+ * @return java.util.Vector
* @throws DBException if a database error occurs
- *
- * #see #setCustomWhereClause(String newCustomWhere)
- * #see #setSortKey(String sortKeyString)
- * #see #getISOValuesDefault(String valueField, String descripField)
+ * <p/>
+ * #see #setCustomWhereClause(String newCustomWhere)
+ * #see #setSortKey(String sortKeyString)
+ * #see #getISOValuesDefault(String valueField, String descripField)
*/
protected Vector getValuesDefault(String valueField, String descripField,
String whereClause, String sortKeyString)
@@ -4683,7 +4636,7 @@
myValues = new Vector();
thisObj.setDataContext(getDataContext());
- if ( sortKeyString == null ) {
+ if (sortKeyString == null) {
// no sort
} else {
String sortField = descripField;
@@ -4709,9 +4662,8 @@
for (Iterator oset = thisObj.searchAndRetrieveList().iterator();
oset.hasNext();) {
oneObj = (DBObject) oset.next();
- myValues.addElement(
- new ValidValue(oneObj.getField(valueField),
- oneObj.getField(descripField)));
+ myValues.addElement(new ValidValue(oneObj.getField(valueField),
+ oneObj.getField(descripField)));
}
//
@@ -4750,9 +4702,9 @@
* Basic version of getValidValues with supports
* <em>internationalisation</code> (i18n) that stores/retrieves
* the valid values in a locale dependent Caches
- *
- * <p>
- *
+ * <p/>
+ * <p/>
+ * <p/>
* Valid values are store inside cache with a key name that equals
* <code>myClassName+"."+oneLocale.getString()+".validValues"</code>.
* For example the key cache could be:
@@ -4761,18 +4713,18 @@
* "com.acme.test.Fruits.de_de.validValues"
* "com.acme.test.Fruits.es_es.validValues"
* </pre>
- *
+ * <p/>
* The method creates <code>ISOValidValue</code> object instances and
* stores them in the cache.
- *
+ * <p/>
* </p>
*
- * @return java.util.Vector
- * @param valueField java.lang.String
+ * @param valueField java.lang.String
* @param descripField java.lang.String
+ * @return java.util.Vector
* @throws DBException if a database error occurs
- *
- * #see #getValuesDefault(String valueField, String descripField)
+ * <p/>
+ * #see #getValuesDefault(String valueField, String descripField)
*/
protected Vector getISOValuesDefault(String valueField, String descripField)
throws DBException {
@@ -4783,9 +4735,9 @@
* Basic filtered version of getValidValues with supports
* <em>internationalisation</code> (i18n) that stores/retrieves
* the valid values in a locale dependent Caches
- *
- * <p>
- *
+ * <p/>
+ * <p/>
+ * <p/>
* Valid values are store inside cache with a key name that equals
* <code>myClassName+"."+oneLocale.getString()+".validValues"</code>.
* For example the key cache could be:
@@ -4794,20 +4746,20 @@
* "com.acme.test.Fruits.de_de.validValues"
* "com.acme.test.Fruits.es_es.validValues"
* </pre>
- *
+ * <p/>
* The method creates <code>ISOValidValue</code> object instances and
* stores them in the cache.
- *
+ * <p/>
* </p>
*
- * @return java.util.Vector
- * @param valueField java.lang.String
+ * @param valueField java.lang.String
* @param descripField java.lang.String
- * @param whereClause the where clause that will be pass
- * to setCustomWhereClause.
+ * @param whereClause the where clause that will be pass
+ * to setCustomWhereClause.
+ * @return java.util.Vector
* @throws DBException if a database error occurs
- *
- * #see #getValuesDefault(String valueField, String descripField, String whereClause)
+ * <p/>
+ * #see #getValuesDefault(String valueField, String descripField, String whereClause)
*/
protected Vector getISOValuesDefault(String valueField, String descripField,
String whereClause)
@@ -4821,9 +4773,9 @@
* values in a locale dependent Caches. This method retrieves the valid
* values in the order specified by the sortKeyString, and filters them
* with the given where clause.
- *
- * <p>
- *
+ * <p/>
+ * <p/>
+ * <p/>
* Valid values are store inside cache with a key name that equals
* <code>myClassName+"."+oneLocale.getString()+".validValues"</code>.
* For example the key cache could be:
@@ -4832,22 +4784,22 @@
* "com.acme.test.Fruits.de_de.validValues"
* "com.acme.test.Fruits.es_es.validValues"
* </pre>
- *
+ * <p/>
* The method creates <code>ISOValidValue</code> object instances and
* stores them in the cache.
- *
+ * <p/>
* </p>
*
- * @return java.util.Vector
- * @param valueField java.lang.String
- * @param descripField java.lang.String
- * @param whereClause the where clause that will be pass
- * to setCustomWhereClause.
+ * @param valueField java.lang.String
+ * @param descripField java.lang.String
+ * @param whereClause the where clause that will be pass
+ * to setCustomWhereClause.
* @param sortKeyString the pipe delimited string of field names with the
- * optional 'ASC or DESC' keyword afterwords
+ * optional 'ASC or DESC' keyword afterwords
+ * @return java.util.Vector
* @throws DBException if a database error occurs
- *
- * #see #getValuesDefault(String valueField, String descripField, String whereClause, String sortKeyString)
+ * <p/>
+ * #see #getValuesDefault(String valueField, String descripField, String whereClause, String sortKeyString)
*/
protected Vector getISOValuesDefault(String valueField, String descripField,
String whereClause, String sortKeyString)
@@ -4866,7 +4818,7 @@
Locale oneLocale = Locale.getDefault();
- String cacheName = myClassName + "." + oneLocale.toString() + ".valueField:" + valueField + "|descrip:" + descripField + "|where:" + whereClause + "|sort:" + sortKeyString;
+ String cacheName = myClassName + "." + oneLocale.toString() + ".valueField:" + valueField + "|descrip:" + descripField + "|where:" + whereClause + "|sort:" + sortKeyString;
CacheManager.getInstance();
CacheSystem cs = CacheManager.getCacheSystem(getDataContext());
@@ -4919,10 +4871,9 @@
for (Iterator oset = thisObj.searchAndRetrieveList(sortField).iterator();
oset.hasNext();) {
oneObj = (DBObject) oset.next();
- myValues.addElement(
- new ISOValidValue(oneSchema, oneLocale, prefix,
- oneObj.getField(valueField),
- oneObj.getField(descripField)));
+ myValues.addElement(new ISOValidValue(oneSchema, oneLocale, prefix,
+ oneObj.getField(valueField),
+ oneObj.getField(descripField)));
}
//
@@ -4961,10 +4912,10 @@
* This method will return a boolean true if the field is defined in the DBOBject,
* false otherwise.
* Creation date: (8/8/00 11:04:32 AM)
- * @return boolean
+ *
* @param fieldName java.lang.String
+ * @return boolean
* @deprecated Use isField(String) instead
- * @throws DBException
*/
public boolean hasField(String fieldName)
throws DBException {
@@ -4974,10 +4925,10 @@
/**
* Returns true if an Index exists for this array.
- * @throws DBException
+ *
* @return true if this has an index
* @deprecated since Expresso 5.1
- * Use getMetaData().hasIndex() instead
+ * Use getMetaData().hasIndex() instead
*/
public boolean hasIndex()
throws DBException {
@@ -4987,8 +4938,7 @@
/**
* See if we have a value for each of the key fields
*
- * @return True if all key fields have a value, false if not
- * @throws DBException
+ * @return True if all key fields have a value, false if not
*/
public boolean haveAllKeys()
throws DBException {
@@ -5014,9 +4964,10 @@
* can simultaneously create the first instance of different classes,
* and so a simple object-level synchronization alone will not suffice here,
* though it is useful to block out calls from the same class.
- *
+ * <p/>
* author Adam Rossi, PlatinumSolutions
* author Larry Hamel, CodeGuild.com
+ *
* @throws DBException The exception description.
*/
protected synchronized void initialize() throws DBException {
@@ -5089,10 +5040,11 @@
/**
* Return true if the given type is a date/time type of field
- * @deprecated use DBField.isDateType()
- * deprecated May 2002; remove anytime after 1/2003
+ *
* @param theType The type to check
* @return true if the data type is a date type
+ * @deprecated use DBField.isDateType()
+ * deprecated May 2002; remove anytime after 1/2003
*/
public static boolean isDateType(String theType) {
if (theType.equalsIgnoreCase("date") ||
@@ -5109,15 +5061,13 @@
* This method iterates through all the <code>DBFields</code> belonging
* <code>DBObject</code> returns <code>true</code> if any of them are
* set a <b>distinct</b>.
- *
+ * <p/>
* author Peter Pilgrim <peter.pilgrim at db.com>
*
+ * @return true if this is a distinct field
* @see #isFieldDistinct(String)
* @see #getDistinctFields()
* @see #getDistinctFieldCount()
- *
- * @return true if this is a distinct field
- * @throws DBException
*/
public synchronized boolean isDistinct()
throws DBException {
@@ -5139,15 +5089,15 @@
} /* isDistinct() */
/**
- * Tells whether a particular field is null or not. <b><i>Note:</i></b>
- * To maintain backwards compatibility, if you have a virtual field then
- * isFieldNull will always return false. You should override this method
- * for virtual fields if you want isNull support.
- *
- * @param fieldName The name of the field to check for isFieldNull()
- * @throws DBException if the field doesn't exist for the particular
- * DBObject.
+ * Tells whether a particular field is null or not. <b><i>Note:</i></b>
+ * To maintain backwards compatibility, if you have a virtual field then
+ * isFieldNull will always return false. You should override this method
+ * for virtual fields if you want isNull support.
+ *
+ * @param fieldName The name of the field to check for isFieldNull()
* @return true if the field is null
+ * @throws DBException if the field doesn't exist for the particular
+ * DBObject.
*/
public boolean isFieldNull(String fieldName) throws DBException {
DataFieldMetaData oneField = getFieldMetaData(fieldName);
@@ -5175,9 +5125,9 @@
* Return true if every field in this object is empty or null. Tests only
* "real" fields, not virtual ones
*
- * @return boolean: True if the record is "empty" (all fields blank),
- * False if not.
- * @throws DBException If the list of fields cannot be traversed
+ * @return boolean: True if the record is "empty" (all fields blank),
+ * False if not.
+ * @throws DBException If the list of fields cannot be traversed
*/
public synchronized boolean isEmpty()
throws DBException {
@@ -5203,10 +5153,11 @@
* Check if a certain name is a field (of any kind) in this DBOBject
* since SQL is case insensitive, ignore case of field name for match,
* this method takes longer, so use isField if the field name is known precisely
- * @return internal format for field name if matched, or null if no match
+ *
* @param fieldName is this a field name
+ * @return internal format for field name if matched, or null if no match
* @deprecated Since Expresso 5.1
- * Use getMetaData().isFieldIgnoreCase() instead
+ * Use getMetaData().isFieldIgnoreCase() instead
*/
public String isFieldIgnoreCase(String fieldName) {
return getDef().isFieldIgnoreCase(fieldName);
@@ -5214,10 +5165,11 @@
/**
* Check if a certain name is a field (of any kind) in this DBOBject
- * @return true if the field is a valid field name
+ *
* @param fieldName The field name to check
+ * @return true if the field is a valid field name
* @deprecated Since Expresso 5.1
- * Use getMetaData().isField() instead
+ * Use getMetaData().isField() instead
*/
public boolean isField(String fieldName) {
return getDef().isField(fieldName);
@@ -5229,11 +5181,9 @@
*
* @param fieldName the name of the field
* @return boolean value true if the field is set distinct.
- *
- * @throws DBException If the operation could not be completed
- *
- * author Peter Pilgrim <peter.pilgrim at db.com>
- *
+ * @throws DBException If the operation could not be completed
+ * <p/>
+ * author Peter Pilgrim <peter.pilgrim at db.com>
* @see #getDistinctFields()
* @see #getDistinctFieldCount()
* @see #setFieldDistinct
@@ -5261,13 +5211,11 @@
* This method iterates through all the <code>DBFields</code> belonging
* <code>DBObject</code> returns <code>true</code> if any of them are
* between the <b>retrieve</b> fields.
- *
+ * <p/>
* author Yves Henri Amaizo <amy_amaizo at compuserve.com>
*
- * @see #isFieldToRetrieve(String)
- *
* @return true if there are specific fields to retrieve
- * @throws DBException
+ * @see #isFieldToRetrieve(String)
*/
public synchronized boolean isFieldsToRetrieve()
throws DBException {
@@ -5287,11 +5235,9 @@
*
* @param fieldName the name of the field
* @return boolean value true if the field is set distinct.
- *
- * @throws DBException If the operation could not be completed
- *
- * author Yves Henri Amaizo <amy_amaizo at compuserve.com>
- *
+ * @throws DBException If the operation could not be completed
+ * <p/>
+ * author Yves Henri Amaizo <amy_amaizo at compuserve.com>
* @see #setFieldsToRetrieve( String )
*/
public boolean isFieldToRetrieve(String fieldName)
@@ -5308,9 +5254,9 @@
* Method called to determine if a particular field is multi-valued,
* that is does it have a set of specific values and descriptions
*
- * @param fieldName Name of the field
- *