| java.lang.Object com.jcorporate.expresso.core.dataobjects.BaseDataObject com.jcorporate.expresso.core.dataobjects.jdbc.JDBCDataObject com.jcorporate.expresso.core.dbobj.DBObject
All known Subclasses: com.jcorporate.expresso.core.dbobj.tests.Test2, com.jcorporate.expresso.services.dbobj.RowGroupPerms, com.jcorporate.expresso.core.dbobj.tests.Test1, com.jcorporate.expresso.services.dbobj.RowPermissions, com.jcorporate.expresso.core.dbobj.SecuredDBObject, com.jcorporate.expresso.services.dbobj.ChangeLog,
Inner Class :public class FieldError | |
Inner Class :public class FieldUpdate | |
Constructor Summary | |
public | DBObject() Default Constructor. | public | DBObject(DBConnection newConnection) 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. | public | DBObject(DBConnection newConnection, String setupTablesContext) 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. | public | DBObject(RequestContext request) For using DBObjects within Controllers. | public | DBObject(String newdbKey) |
Method Summary | |
public void | add() Add a new record to the target table.
Assumes that the fields of this object are populated with data for the new
record. | protected synchronized void | addDetail(String objName, String keyFieldsLocal, String keyFieldsForeign) Specify a new "detail" db object, and the fields in this object
they specify the fields in the related object
Parameters: objName - The class name of the related object. | protected synchronized void | addField(String fieldName, String fieldType, int fieldSize, int fieldPrecision, boolean allowNull, String fieldDescription) Add a field with more details: This version allows the user to specify a
precision, for fields that use both a size and precision. | protected synchronized void | addField(String fieldName, String fieldType, int fieldSize, boolean allowNull, String fieldDescription) Add a field with more details: This version of addfield supplies
the allowNull flags and a description of the field to be used
when reporting errors to the user. | protected void | addFieldError(String fieldName, String errorMessage) Use this in your derived checkField() class to add error messages to
be associated with various fields. | public void | addFoundKeys(String fieldName) This is used internally by JDBC Exceutor's and JDBC Query when dealing
with queries to the underlying datasource. | public synchronized void | addIfNeeded() Determine if a record with this key exists already - if
not, add a new record. | protected void | addIndex(String indexName, String fieldNames, boolean isUnique) Add an index to the table. | protected synchronized void | addKey(String keyFieldName) Add a new field to the list of fields that are part of this
object's key. | public synchronized void | addOrUpdate() Determine if a record with these fields exists already - if so, update. | public void | addSortKey(String fieldString, boolean ascending) | protected void | addTransition(Transition t) | protected synchronized void | addVirtualField(String fieldName, String fieldType, int fieldSize, int fieldPrecision, boolean allowNull, String fieldDescription) Add a field with more details: This version allows the user to specify a
precision, for fields that use both a size and precision. | protected synchronized void | addVirtualField(String fieldName, String fieldType, int fieldSize, int fieldPrecision, boolean allowNull, String descripKey, String fieldDescription) Add a field with more details: This version allows the user to specify a
precision, for fields that use both a size and precision. | protected synchronized void | addVirtualField(String fieldName, String fieldType, int fieldSize, String fieldDescription) Add a new virtual field to the definition of this object. | protected synchronized void | addVirtualField(String fieldName, String fieldType, int fieldSize, String descripKey, String fieldDescription) Add a new virtual field to the definition of this object. | public double | average(String fieldName) Find the average of the values in the specified field of records
selected by the DBObject selection criteria. | public synchronized void | basicAdd()
A "simplified"e; version of add that can be used to do a basic
INSERT statement into this table. | public void | cacheIsChangedComparison() reset 'original' value and isChanged flags on all fields, establishing a baseline for comparison. | protected synchronized void | checkAllReferredToBy() Extended by subclasses to make calls to ReferredToBy as needed. | protected synchronized void | checkAllRefs() Extended by subclasses to make calls to checkRef as needed. | public synchronized void | checkAllRefsPublic() | public boolean | checkAllowed(String function) No security is applied at the DBObject level, only at the level
of SecuredDBObjects. | protected void | checkDeleteDetailPerm(DBObject obj) | public synchronized void | checkField(String fieldName, String fieldValue) Check that a given value is valid for a given field.
This method is overriden by specific DBObjects to do their own field-level
validations - they should also call super in order to do the
standard stuff. | protected synchronized void | checkRef(String foreignKeyNames, DBObject refObject, String errorMessage) | protected synchronized void | checkRef(String foreignKeyNames, DBObject refObject, String errorMessage, boolean allowBlank) Verify referential integrity from the given list of fields to the
key fields in the given DB Object. | public synchronized void | clear() | public synchronized void | clearDistinctFields() | protected void | clearError(String fieldName) Used to clear field error flags. | public synchronized void | clearFieldsToRetrieve() | public void | clearSortKeys() | protected synchronized boolean | containsWildCards(String fieldValue) See if this field value contains wild cards (e.g. | protected void | copyAttributes(DBObject returnObj) | public synchronized int | count() Just like find, but only retrieves the count, not the records themselves. | public void | delete() Delete this record from the target table. | public synchronized void | delete(boolean deleteDetails) Delete this record, optionally deleting any associated detail
records. | public synchronized void | deleteAll() Delete all of the records specified by the current search criteria. | public synchronized void | deleteAll(boolean oneByOne) Delete all of the records specified by the current search criteria. | protected void | deleteDetails(DBConnection detailConnection) If this DB object has associated detail objects,
locate the appropriate related detail records and
delete them as well. | protected String | denotesRange(String fieldValue) Does a given field value denote a range?
Parameters: fieldValue - The field value to check against. | public boolean | equals(Object parm1) Equals implementation. | public boolean | find() A lot like retrieve, but works with any fields, not just the key field. | public String | forKey() | public String | formatDateTime(String fieldName) Given the value of a date/time or date/time field, return the value formatted
as appropriate for the current DBMS. | public Object | get(String fieldName) | public Map | getAllAttributes() Returns a Read Only Map containing all the current attributes set
for this particular data object instance. | public Object | getAttribute(String attribName) Return an "attribute". | public Iterator | getAttributesIterator(String fieldName) | protected String | getBooleanFieldValue(boolean fieldValue) Internal refactoring for getting what a boolean field should be set to. | public int | getCacheSize() | public static synchronized HashMap | getCacheStatsMap() | protected CacheUtils | getCacheUtil() 'Pseudo' factory method to retrieve the caching utility class instance. | public synchronized boolean | getCheckZeroUpdate() Gets the check zero update flags for this DBObject. | public String | getCustomWhereClause() Allows us to query the custom where clause (if any). | public synchronized String | getDBName() Return the name of the context/database connection that this DB object is using. | public String | getDataContext() | public DataField | getDataField(String fieldName) Same as getField, but works with the DataObject interface for now. | public synchronized DataTransferObject | getDataTransferObject() | public Enumeration | getDetails() Get a list of all db objects that are specified as being "details"
to this db object. | public synchronized int | getDistinctFieldCount() This convenience method counts
DBFields belonging to this
DBObject that are set to distinct. | public String[] | getDistinctFields() | public synchronized String | getField(String fieldName) | public BigDecimal | getFieldBigDecimal(String fieldName) Get the BigDecimal value of a field in this object. | public boolean | getFieldBoolean(String fieldName) | public byte | getFieldByte(String fieldName) Get the primitive byte value of a field in this object. | public byte[] | getFieldByteArray(String fieldName) Get the primitive byteArray value of a field in this object. | protected String | getFieldData(String fieldName) | public java.util.Date | getFieldDate(String fieldName) | public String | getFieldDecimalFormatted(String fieldName, String formatPattern) Return the value of a field as a Date object
Parameters: fieldName - The field to be retrieved Parameters: formatPattern - A formatting pattern according to java.text.DecimalFormat.Leave null for the default format for this locale.Symbol Meaning0 a digit# a digit, zero shows as absent. | public double | getFieldDouble(String fieldName) Get the primitive double value of a field in this object. | public String | getFieldErrorMessage(String fieldName) Retrieve the error message associated with this field.
Parameters: fieldName - the fieldName to get the associated error message A string containing the field error message or NULL if there isno error for this field. | public float | getFieldFloat(String fieldName) Get the primitive float value of a field in this object. | public int | getFieldInt(String fieldName) Get the primitive integer value of a field in this object. | public long | getFieldLong(String fieldName) Get the prmitive long value of a field in this object. | public DataFieldMetaData | getFieldMetaData(String fieldName) Returns the metadata for the specified field. | public short | getFieldShort(String fieldName) Get the primitive integer value of a field in this object. | public synchronized int | getFieldsToRetrieveCount() This convenience method counts
DBFields belonging to this
DBObject that are set to retrieve. | public Class | getFilterClass() the INSTANCE value of filter class that will be used for all string filtering for THIS INSTANCE.
defaults to null, which means that there is no instance filter, so static filter will be used.
If this instance returns null, static value in
DBField.getFilterClass() filter class will be used. | public long | getFoundCount() Return the number of records found in the last search operation. | public Object[] | getFoundKeysArray() | protected Vector | getISOValuesDefault(String valueField, String descripField) Basic version of getValidValues with supports
internationalisation (i18n) that stores/retrieves
the valid values in a locale dependent Caches
Valid values are store inside cache with a key name that equals
myClassName+"."+oneLocale.getString()+".validValues" . | protected Vector | getISOValuesDefault(String valueField, String descripField, String whereClause) Basic filtered version of getValidValues with supports
internationalisation (i18n) that stores/retrieves
the valid values in a locale dependent Caches
Valid values are store inside cache with a key name that equals
myClassName+"."+oneLocale.getString()+".validValues" .
For example the key cache could be:
"com.acme.test.Fruits.en_gb.validValues"
"com.acme.test.Fruits.de_de.validValues"
"com.acme.test.Fruits.es_es.validValues"
The method creates ISOValidValue object instances and
stores them in the cache.
Parameters: valueField - java.lang.String Parameters: descripField - java.lang.String Parameters: whereClause - the where clause that will be passto setCustomWhereClause. | protected Vector | getISOValuesDefault(String valueField, String descripField, String whereClause, String sortKeyString) Basic version of getValidValues with supports
internationalisation (i18n) that stores/retrieves the valid
values in a locale dependent Caches. | public synchronized Object[] | getIndexArray() Get an array of DBIndex objects for purpose of
creating them through the schema. | public String | getKey() Get a string consisting of the values of each key field for this object
appended together with a | between them. | public Iterator | getKeyFieldListIterator() Get a list of all of the fields in this object This iterator is not thread
safe. | public String | getLength(String fieldName) | public int | getLengthInt(String fieldName) | public DBConnection | getLocalConnection() Returns the local connection currently associated with this DBObject... | public Locale | getLocale() | public Logger | getLogger() | public String | getLookupObject(String fieldName) Get a field's lookup object - this is the name of another database
object that can be used to look up valid values for this object. | public String | getMax(String fieldName, boolean whereClause) | public String | getMax(String fieldName) | public int | getMaxRecords() A DB Object can be told to only retrieve a certain number of records. | public String | getMyKeys() Get a string consisting of the values of each key field for this object
appended together with a | between them. | protected Object[] | getMyUpdatesArray() Return the array of updates (see the inner class) that specify what changes
were just made to this object. | public int | getOffsetRecord() Gets the number of records that be skipped. | protected PatternMatcher | getPatternMatcher() Retrieve a thread local instance of the Perl5 pattern matcher. | public int | getPrecision(String fieldName) | public String | getSerializedForm(DBField theField) This function is called whenever the DBField is about to be written to
the database. | public synchronized String | getStringFilter(String fieldName) get the current filter for a particular field. | protected DBObject | getThisDBObj() This will return a new object of the type of the subclass.
OVERRIDE this method with implentation like
return new MyObject()
if you want greatest efficiency. | public static synchronized DBObject | getThisDBbj(DataTransferObject dto) Constructor method that takes a DataTransferObject and builds a full fledged
DBObject out of it. | public String | getValidValueDescrip(String fieldName) This is a convenience method which will return a ValidValue description
for a multi-valued field. | public synchronized Vector | getValidValues(String fieldName) New method to replace getValues with a structure of valid values
and descriptions. | public java.util.List | getValidValuesList(String fieldName) | public Vector | getValues() Method to return a Vector of ValidValue
Template method--not implemented in this superclass.
This method may be implemented by objects that want to provide a
list of valid values for other DB objects. | protected Vector | getValuesDefault(String valueField, String descripField) Basic version of getValidValues that stores/retrieves the valid
values in a Cache. | protected Vector | getValuesDefault(String valueField, String descripField, String whereClause) Basic filtered version of getValidValues that stores/retrieves the valid
values in a Cache. | protected Vector | getValuesDefault(String valueField, String descripField, String whereClause, String sortKeyString) Basic version of getValidValues that stores/retrieves the valid values
in a Cache. | public boolean | hasError(String fieldName) Use this to check if a field is in error.
Parameters: fieldName - Check if there's an error set for this field. | public boolean | hasErrors() Use this to check if any fields are in error. | public boolean | haveAllKeys() | protected synchronized void | initialize() Sets up metadata for the dbobject via call to setupFields().
it is important within this method to provide STATIC synchronization
to enable static (meta)data members to be setup by the first
instantiation of a given class. | public boolean | isCached() | public boolean | isChanged() summarize DataField.isChanged() for all fields. | public synchronized boolean | isDistinct() This method iterates through all the DBFields belonging
DBObject returns true if any of them are
set a distinct. | public synchronized boolean | isEmpty() Return true if every field in this object is empty or null. | public boolean | isFieldDistinct(String fieldName) Convenience method to check if a field is distinct or not
within this database object. | public boolean | isFieldNull(String fieldName) Tells whether a particular field is null or not. | public boolean | isFieldToRetrieve(String fieldName) Convenience method to check if a field is field to be retrieve or not
within this database object. | public synchronized boolean | isFieldsToRetrieve() This method iterates through all the DBFields belonging
DBObject returns true if any of them are
between the retrieve fields. | public synchronized boolean | isMultiValued(String fieldName) | public boolean | isReadOnly(String fieldName) | public boolean | isSecret(String fieldName) Is a given field 'secret' - these fields are not shown
when a list is produced by the generic database maintenance servlet (DBMaint). | public boolean | isVirtual(String fieldName) Is a given field virtual? A virtual field is not stored in the target table
for this object - it may be computed, or stored in another table. | public synchronized int | loadFromConnection(DBConnection connection) Hand a dbobject a connection that contains fields corresponding to
what the dbobject expects, and it'll set itself.
Does not increment the result set in the DBConnection.
Parameters: connection - The connection that currently has a dbobject ready tobe read in it's result set. | protected void | logChange(DBField oneField, String fieldValue) | public double | max(String fieldName) Find the maximum of the values in the specified field of records
se;lected by the DBObject selection criteria. | public double | min(String fieldName) Find the minimum of the values in the specified field of records
selected by the DBObject selection criteria. | public DBObject | newInstance() get a new instance of this object, with some basic attributes copied,
like the local connection of the transaction
Generally speaking, DO NOT OVERRIDE THIS METHOD. | protected String | noNewLine(String fieldValue) | protected String | noQuotes(String oldString) | protected synchronized void | notifyListeners(String eventCode) Used by internal caching to ensure that caches are cleared when an update is
made. | public synchronized void | populateDefaultValues() populateDefaultValues is called by the schema object to allow a table to
populate itself with any desired values. | protected synchronized void | referredToBy(DBObject refObject, String foreignKeyNames, String errorMessage) | public void | removeAttribute(String attributeName) Removes an attribute from this particular database object. | public synchronized void | removeFromCache(DBObject theDBObj) Remove a specific object from that object's cache. | public void | retrieve() | public boolean | retrieveFromCache() Retrieve this object from cache, if possible. | public void | saveBinaryField(String fieldName, byte[] incomingData) | public synchronized void | search() Find a set of keys of all of the objects that match the current
search critieria in the fields. | public synchronized void | search(String sortKeyString) Second form of search: takes a list of sort keys & calls regular search. | public synchronized ArrayList | searchAndRetrieveList() Find a set of records of all of the objects that match the current
search critieria in the fields
and retrieve the list of all records that match this criteria
NOTE: Criteria in 'text' type colums is ignored (SQL Server limitation)
SIDE-EFFECT: custom 'where' clause is set to null. | public synchronized ArrayList | searchAndRetrieveList(String sortKeyString) | public void | set(String fieldName, Object o) | public synchronized void | setAttribute(String attribName, Object attribValue) Set an attribute. | public synchronized void | setCacheSize() Read the configuration table to determine the max size
of the cache for this db object. | public synchronized void | setCharset(String newCharSet) Set a characterset for a particular field.
for more information on Filters and implementing Filters for your own
characterset.
Sets the characterset expected for a this DB object. | public synchronized void | setCheckZeroUpdate(boolean newFlag) Turn on or off the facility to verify that when an update is made that at
least one record got updated. | public synchronized void | setConnection(DBConnection newConnection) Set a specific DB connection for use with this db object. | public synchronized void | setConnection(DBConnection newConnection, String setupTablesContext)
Set a specific DB connection for use with this db object. | public synchronized void | setCustomWhereClause(String newCustomWhere) Specify a custom "where" clause for the SQL used to retrieve records for this
object. | public synchronized void | setCustomWhereClause(String newCustomWhere, boolean append) Allows us to specify a custom WHERE clause and have it appended to the
one built from the field values in the object
Parameters: newCustomWhere - java.lang.String string with clause. | public void | setDataContext(String newContext) Sets the data context that this object is residing in. | public void | setDataField(String fieldName, DataField o) Same as setField, but works with the DataObject Interface
Parameters: fieldName - the name of the field to set. Parameters: o - the object to set the field to... | public synchronized void | setDataTransferObject(DataTransferObject dto) fill fields with values found in dto; REPLACES any data field already present. | protected synchronized void | setDefaultValue(String fieldName, String fieldValue) Define a "default" value for a field - to be used for the field
when the user does not specify a value. | public synchronized void | setDescription(String newDescription) | public synchronized void | setField(String fieldName, byte fieldValue) Byte primitive integer Typesafe version of setField. | public synchronized void | setField(String fieldName, byte[] fieldValue) Byte primitive integer Typesafe version of setField. | public synchronized void | setField(String fieldName, short fieldValue) Short primitive integer Typesafe version of setField. | public synchronized void | setField(String fieldName, int fieldValue) Integer primitive Typesafe version of setField. | public synchronized void | setField(String fieldName, long fieldValue) Long primitive Typesafe version of setField . | public synchronized void | setField(String fieldName, double fieldValue) Double primitive Typesafe version of setField . | public synchronized void | setField(String fieldName, BigDecimal fieldValue) BigDecimal object Typesafe version of setField . | public synchronized void | setField(String fieldName, boolean fieldValue) | public synchronized void | setField(String fieldName, String fieldValue) Set the given field to a given value. | public void | setField(String fieldName, java.util.Date fieldValue) Date object Typesafe version of setField . | protected synchronized void | setFieldData(String fieldName, String fieldValue) Helper function that doesn't fire all the processing... | protected synchronized void | setFieldData(String fieldName, byte[] fieldValue) Helper function that doesn't fire all the processing... | public void | setFieldDistinct(String fieldName, boolean flag) Convenience method to set a field to be distinct or not
within this database object. | public void | setFieldsToRetrieve(String fieldNames) Convenience method to set the fields to be retrieved
within this database object.
NOTE AS OF EXPRESSO 5.0 setFieldsToRetrieve() could cause you
some problems if you're attempting to retrieve long objects since
everything will be converted to a STRING. | public Class | setFilterClass(Class filter) set the filter class that will be used for all string filtering
for this object instance ONLY. | public Filter | setFilterClass(Filter filter) set the filter class that will be used for all string filtering
for this object instance ONLY. | public synchronized void | setKeys(String keyValues) | public void | setLocale(Locale newLocale) | public synchronized void | setLookupField(String fieldName, String lookupFieldName) Sets the lookup field name. | public synchronized void | setLookupObject(String fieldName, String objectName) Set a field's lookup object - this is the name of another database
object that can be used to look up valid values for this object. | protected synchronized void | setMask(String fieldName, String newMask) Set a "mask", or regular expresso to be matched, for the named field.
This regular expression is then checked whenever the field is validated
Note: Masks are used to validate a field's data type to prevent sql injections. | public synchronized void | setMaxRecords(int newMax) Specify a maximum number of records to be retrieved in any subsequent
searchAndRetrieve() call. | protected synchronized void | setMultiValued(String fieldName) Set this field to be multi-valued - e.g. | protected synchronized void | setName(String theName) | public synchronized void | setOffsetRecord(int newOffset) Specifies the number of records that should be skipped over
before any data from the ResultSet
is retrieved in any subsequent
searchAndRetrieve() call. | public synchronized void | setReadOnly(String fieldName) Set a field as read-only - these fields are not offered for update
when a form is produced by the generic database maintenance servlet
(DBMaint). | public synchronized void | setSchema(Schema schema) Specify which schema this DB object belongs to. | public synchronized void | setSecret(String fieldName) Set a field as 'secret' - these fields are not shown
when a list is produced by the generic database maintenance servlet. | protected void | setSortKey(String sortKeyString) Parses the sort key string into useful values. | public synchronized String | setStringFilter(String fieldName, String filterMethod) Set a filter for a particular field, permanently for all instances of this class.
for a means to set a filter on just a single instance, see setFilterClass
Parameters: fieldName - The name of the field to set a particular filter for. Parameters: filterMethod - The name of the filter method to use when calling a filter.Can be one of three values: See com.jcorporate.expresso.core.security.filters.FilterManager.filterString formore information on this parameter. | public void | setStringFiltersOnAll(String filter) | public synchronized void | setTargetDbSchema(String theDbSchema) Set the target table for this DBObject. | public synchronized void | setTargetTable(String theTable) Set the target table for this DBObject. | protected void | setupFields() Method to set up the fields for this database object. | protected synchronized double | sqlAggrFunction(String func, String fieldName) This allows the invocation of the SQL AVG, MIN, MAX and SUM
aggregate functions on one of the DB's columns (the DBObject
fieldname is supplied). | public double | sum(String fieldName) Find the sum of the values in the specified field of records
selected by the DBObject selection criteria. | public String | toDebugString() Generate a debuggable string for suitable printing out in an
interactive Java IDE. | public void | update() Update the database with the new info. | public void | update(boolean updateChangedFieldsOnly) Update the database with the new info. | public synchronized void | updateAll() Update all of the records specified by the current search criteria. | public void | updateAll(boolean oneByOne) Update the database with the new info. | public void | verify() Verify that this object is working correctly
by selecting all records, running a validation on each of them. |
ATTRIBUTE_ERROR | final public static String ATTRIBUTE_ERROR(Code) | | Attribute String for if there's an error with the field.
|
ATTRIBUTE_ERROR_MESSAGE | final public static String ATTRIBUTE_ERROR_MESSAGE(Code) | | Attribute String for what message to display if there's an error
with thie field.
|
ATTRIBUTE_PAGE_LIMIT | final public static String ATTRIBUTE_PAGE_LIMIT(Code) | | Attribute for what is the limit to retrieve from searchAndRetrieve operations
|
EMAIL_MASK | final public static String EMAIL_MASK(Code) | | Email Regular Expression Constant.
|
EVENT_ADD | final public static String EVENT_ADD(Code) | | Event 'Add' code
|
EVENT_DELETE | final public static String EVENT_DELETE(Code) | | Event 'Delete' Code
|
EVENT_UPDATE | final public static String EVENT_UPDATE(Code) | | Event 'Update' Code
|
FLOAT_MASK | final public static String FLOAT_MASK(Code) | | Floating point regular expression syntax for easy reference.
|
INT_MASK | final public static String INT_MASK(Code) | | Integer Regular Expression for easy reference
|
IS_CHECK_RELATIONAL_INTEGRITY | final public static String IS_CHECK_RELATIONAL_INTEGRITY(Code) | | |
UPDATE_CHANGED_ONLY | final public static String UPDATE_CHANGED_ONLY(Code) | | setup code for update() policy:
for efficiency, developers who are confident that their code does not have any
'blind updates' can set the Setup value UPDATE_CHANGED_ONLY to true
(a blind update is where the object is not retieved before values in it are reset)
|
anyFieldsToRetrieveMulti | boolean anyFieldsToRetrieveMulti(Code) | | Very Similar to "anyFieldsToRetrieve" already present on the DBObject.
author ABHI
|
DBObject | public DBObject() throws DBException(Code) | | 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 - upon error. |
DBObject | public DBObject(DBConnection newConnection) throws DBException(Code) | | 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,
there is no way to use commit() and rollback() in the event of failure, as a
different DBConnection might be used for each phase of the transaction.
Critial sections should therefore explicity request a DBConnection from the
connection pool and pass it to each of the DB objects in that section.
Parameters: newConnection - The DBConnection to utilize throws: DBException - upon error. |
DBObject | public DBObject(DBConnection newConnection, String setupTablesContext) throws DBException(Code) | | 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,
there is no way to use commit() and rollback() in the event of failure, as a
different DBConnection might be used for each phase of the transaction.
Critial sections should therefore explicity request a DBConnection from the
connection pool and pass it to each of the DB objects in that section.
This constructor is neceesary to work with otherDBMap and transaction
capabilities
Parameters: newConnection - The DBConnection to utilize Parameters: setupTablesContext - The data context that contains the setup (andsecurity) tables for this object throws: DBException - upon error. since: Expresso 5.0.1 |
DBObject | public DBObject(RequestContext request) throws DBException(Code) | | For using DBObjects within Controllers. Initializes based upon
the current locale and the requested db context. There is no
current user login id set in this method. If you need the user id
then use you should use the subclass SecuredDBObject
type instead.
Parameters: request - - The controller request handed to you by the framework. throws: DBException - if there's an error constructing the SecuredDBObject |
DBObject | public DBObject(String newdbKey) throws DBException(Code) | | Initialize this DBObject and set the db/context to the specified key
Parameters: newdbKey - The database Context name throws: DBException - upon error. |
add | public void add() throws DBException(Code) | | Add a new record to the target table.
Assumes that the fields of this object are populated with data for the new
record. All key fields at least must be supplied with values, and all fields
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 therecord has a duplicate key |
addDetail | protected synchronized void addDetail(String objName, String keyFieldsLocal, String keyFieldsForeign) throws DBException(Code) | | Specify a new "detail" db object, and the fields in this object
they specify the fields in the related object
Parameters: objName - The class name of the related object. There is assumed to bea one to one or one to many relationship from this object to the specified object Parameters: keyFieldsLocal - A pipe-delimited list of field names in this object Parameters: keyFieldsForeign - A pipe-delimieted list of field names in the other object throws: DBException - upon error. |
addField | protected synchronized void addField(String fieldName, String fieldType, int fieldSize, int fieldPrecision, boolean allowNull, String fieldDescription) throws DBException(Code) | | Add a field with more details: This version allows the user to specify a
precision, for fields that use both a size and precision.
Parameters: fieldName - Name of the field Parameters: fieldType - Type of the field - this is the internal Expresso type,mapping in DBField to a specific database data type. Parameters: fieldSize - Size of the field Parameters: fieldPrecision - The precision of the field Parameters: allowNull - Does this field allow nulls? Parameters: fieldDescription - A longer description of this field(user-understandable hopefully!) throws: DBException - upon error. |
addField | protected synchronized void addField(String fieldName, String fieldType, int fieldSize, boolean allowNull, String fieldDescription) throws DBException(Code) | | Add a field with more details: This version of addfield supplies
the allowNull flags and a description of the field to be used
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.
Parameters: fieldName - Name of the field Parameters: fieldType - Type of the field - this is the "internal" Expresso type,and is mapped to a specific type for the database depending on themappings in the properties file (if any). The DBField object containsthe default mappings. Parameters: fieldSize - Size of this field, if specified for this type of field. Forfields that do not use a size (such as "date"), specify 0 for the size. Parameters: allowNull - Does this field allow nulls? Parameters: fieldDescription - A longer description of this field(user-understandable hopefully!) throws: DBException - upon error. |
addFieldError | protected void addFieldError(String fieldName, String errorMessage)(Code) | | Use this in your derived checkField() class to add error messages to
be associated with various fields.
Parameters: fieldName - The field name to add the error to Parameters: errorMessage - The custom error message to associate when there'sa problem with this field |
addFoundKeys | public void addFoundKeys(String fieldName)(Code) | | 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.
Parameters: fieldName - the name of the fieldname found. |
addIfNeeded | public synchronized void addIfNeeded() throws DBException(Code) | | 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 - upon error. |
addIndex | protected void addIndex(String indexName, String fieldNames, boolean isUnique) throws IllegalArgumentException, DBException(Code) | | Add an index to the table.
Parameters: indexName - the name to give the index in the table; MUST CONTAIN NO SPACES--use underscores instead Parameters: fieldNames - A comma delimited list of all fields in the index. Parameters: isUnique - - True if this field is a unique index. throws: IllegalArgumentException - of fieldName is null or doesn't existor if indexName is null throws: DBException - upon error. |
addKey | protected synchronized void addKey(String keyFieldName) throws DBException(Code) | | Add a new field to the list of fields that are part of this
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.
Parameters: keyFieldName - The name of the field to add as part of the key throws: DBException - if the field name is not valid or the fieldallows nulls |
addOrUpdate | public synchronized void addOrUpdate() throws DBException(Code) | | Determine if a record with these fields exists already - if so, update. If
not, add a new record.
throws: DBException - upon error. |
addSortKey | public void addSortKey(String fieldString, boolean ascending)(Code) | | Add a field to be sorted in a search
Parameters: fieldString - the name of the field to sort on Parameters: ascending - true if using ascending sort order, false if descendingsort order. throws: IllegalArgumentException - if the fieldString does not exist |
addVirtualField | protected synchronized void addVirtualField(String fieldName, String fieldType, int fieldSize, int fieldPrecision, boolean allowNull, String fieldDescription) throws DBException(Code) | | Add a field with more details: This version allows the user to specify a
precision, for fields that use both a size and precision.
Parameters: fieldName - Name of the field Parameters: fieldType - Type of the field - this is the internal Expresso type,mapping in DBField to a specific database data type. Parameters: fieldSize - Size of the field Parameters: fieldPrecision - The precision of the field Parameters: allowNull - Does this field allow nulls? Parameters: fieldDescription - A longer description of this field(user-understandable hopefully!) throws: DBException - upon error. |
addVirtualField | protected synchronized void addVirtualField(String fieldName, String fieldType, int fieldSize, int fieldPrecision, boolean allowNull, String descripKey, String fieldDescription) throws DBException(Code) | | Add a field with more details: This version allows the user to specify a
precision, for fields that use both a size and precision.
Parameters: fieldName - Name of the field Parameters: fieldType - Type of the field - this is the internal Expresso type,mapping in DBField to a specific database data type. Parameters: fieldSize - Size of the field Parameters: fieldPrecision - The precision of the field Parameters: allowNull - Does this field allow nulls? Parameters: descripKey - The key in the local language file for thedescription of this field Parameters: fieldDescription - A longer description of this field(user-understandable hopefully!) throws: DBException - upon error. |
addVirtualField | protected synchronized void addVirtualField(String fieldName, String fieldType, int fieldSize, String fieldDescription) throws DBException(Code) | | Add a new virtual field to the definition of this object.
A virtual field is just like a regular one, except it's
not stored in the target table
A normal call to getField or setField on a virtual field will throw
an exception - getField and setField should be extended to handle the virtual
fields for a particular object correctly.
Parameters: fieldName - Name of the field Parameters: fieldType - Database type of the field Parameters: fieldSize - Size of the field in characters Parameters: fieldDescription - A longer description of this field(user-understandable hopefully!) throws: DBException - upon error. |
addVirtualField | protected synchronized void addVirtualField(String fieldName, String fieldType, int fieldSize, String descripKey, String fieldDescription) throws DBException(Code) | | Add a new virtual field to the definition of this object.
A virtual field is just like a regular one, except it's
not stored in the target table
A normal call to getField or setField on a virtual field will throw
an exception - getField and setField should be extended to handle the virtual
fields for a particular object correctly.
Parameters: fieldName - Name of the field Parameters: fieldType - Database type of the field Parameters: fieldSize - Size of the field in characters Parameters: descripKey - Key into the local langauge file for thedescription of this field Parameters: fieldDescription - A longer description of this field(user-understandable hopefully!) throws: DBException - upon error. |
average | public double average(String fieldName) throws DBException(Code) | | Find the average of the values in the specified field of records
selected by the DBObject selection criteria.
Parameters: fieldName - String DBObject fieldName to average double Average of the records matching the criteria throws: DBException - If the search could not be completed |
basicAdd | public synchronized void basicAdd() throws DBException(Code) | |
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
must be temporarily bypassed.
NOTE BLOB Objects are not added with this function!
NOTE this function does NOT handle auto-increment fields!
throws: DBException - If the record cannot be added - this includes if therecord has a duplicate key Modify by Yves Henri AMAIZO |
cacheIsChangedComparison | public void cacheIsChangedComparison() throws DBException(Code) | | reset 'original' value and isChanged flags on all fields, establishing a baseline for comparison.
call when add(), retrieve, or update() has occurred, and currentValue of data fields should be
considered 'original value' for purposes of determining 'isChanged'
throws: DBException - upon error. |
checkAllReferredToBy | protected synchronized void checkAllReferredToBy() throws DBException(Code) | | Extended by subclasses to make calls to ReferredToBy as needed. This method
implements the basic referential integrity of an object by specifying all of
the object that refer to this object as a foreign key. This method is called
when a delete is about to occurr to verify that removing the current object
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 |
checkAllRefs | protected synchronized void checkAllRefs() throws DBException(Code) | | Extended by subclasses to make calls to checkRef as needed. Thie method
implements (along with checkAllReferredToBy()) basic referential integrity
for this object. Whenever an update or add is about to be made, this method is
called to see if the changed record is referring to invalid foreign keys - e.g.
lookup tables that do not have an appropriate related record. If so, an
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 invalidforeign key reference. |
checkAllRefsPublic | public synchronized void checkAllRefsPublic() throws DBException(Code) | | Public interface to checkAllRefs()
throws: DBException - upon error. |
checkAllowed | public boolean checkAllowed(String function) throws DBException(Code) | | No security is applied at the DBObject level, only at the level
of SecuredDBObjects. The method is still here, however, so that
it can be called by the cascading delete and any other methods
as required
Parameters: function - The appropriate function code. This is mainly usedin objects derived from SecuredDBObject true if this function is alloed throws: DBException - upon error. |
checkDeleteDetailPerm | protected void checkDeleteDetailPerm(DBObject obj) throws DBException(Code) | | extracted for subclasses checking
Parameters: obj - the dbobject to check it's permission throws: DBException - upon error |
checkField | public synchronized void checkField(String fieldName, String fieldValue) throws DBException(Code) | | Check that a given value is valid for a given field.
This method is overriden by specific DBObjects to do their own field-level
validations - they should also call super in order to do the
standard stuff. Every field is automatically checked by this method before the
database is updated.
Parameters: fieldName - Name of the field to verify Parameters: fieldValue - Value of the field to be evaluated throws: DBException - If the value is not valid |
checkRef | protected synchronized void checkRef(String foreignKeyNames, DBObject refObject, String errorMessage) throws DBException(Code) | | 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
Parameters: foreignKeyNames - names of the foreign key fields Parameters: refObject - The foreign DBObject to check against Parameters: errorMessage - The custom error message to display if check fails throws: DBException - if check fails |
checkRef | protected synchronized void checkRef(String foreignKeyNames, DBObject refObject, String errorMessage, boolean allowBlank) throws DBException(Code) | | Verify referential integrity from the given list of fields to the
key fields in the given DB Object. Calls to this method are made in the
checkAllRefs method only. checkAllRefs is automatically called before any
database updates are made to validate the referential integrity of the update.
Use of this method (and the checkAllRefs method) allow the referential
constraints to be "declared", then automatically maintained for a dbobject.
Parameters: foreignKeyNames - A semicolon-sperated list of foreignkey fields from this object Parameters: refObject - Another DBObject that we are to refer to Parameters: errorMessage - Error string to throw if the check fails Parameters: allowBlank - true if blank fields are allowed throws: DBException - If the referential integrity is not correct |
clear | public synchronized void clear() throws DBException(Code) | | Set all fields to empty value & clear the last result set & clear sort keys and customWhereClause
throws: DBException - If the fields cannot be cleared |
clearError | protected void clearError(String fieldName)(Code) | | Used to clear field error flags.
Parameters: fieldName - the name of the field to clear the error flag |
clearFieldsToRetrieve | public synchronized void clearFieldsToRetrieve() throws DBException(Code) | | This convenience method clears all the fileds to be retrieved
DBFields belonging to this
DBObject
author Yves Henri Amaizo
throws: DBException - upon error. See Also: DBObject.isFieldsToRetrieve() |
containsWildCards | protected synchronized boolean containsWildCards(String fieldValue) throws DBException(Code) | | See if this field value contains wild cards (e.g. pattern matching
criteria for the database). The wild cards can be configured via the
properties file.
Parameters: fieldValue - The field value to check for wild cards True if the string does contain wild cards, False if it does not throws: DBException - upon error. |
copyAttributes | protected void copyAttributes(DBObject returnObj) throws DBException(Code) | | called by newInstance(), this method should make sure that the newly created
object is properly initialized
Parameters: returnObj - the object to set the attributes to. throws: DBException - upon error |
count | public synchronized int count() throws DBException(Code) | | Just like find, but only retrieves the count, not the records themselves.
integer Count of the records matching the criteria throws: DBException - If the search could not be completed |
delete | public void delete() throws DBException(Code) | | Delete this record from the target table. The current field values for the key
of this object tell us which record to delete. This default version
of delete also deletes associated detail records (e.g. performs a
"cascading delete" of details.
throws: DBException - If the delete fails or if the referential integritywould be violated by the delete See Also: DBObject.deleteAll See Also: to delete objects identified by non-key fields |
delete | public synchronized void delete(boolean deleteDetails) throws DBException(Code) | | Delete this record, optionally deleting any associated detail
records.
Parameters: deleteDetails - Delete associated detail records if true throws: DBException - Modify by Yves Henri AMAIZO See Also: DBObject.deleteAll See Also: to delete objects identified by non-key fields |
deleteAll | public synchronized void deleteAll() throws DBException(Code) | | 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 |
deleteAll | public synchronized void deleteAll(boolean oneByOne) throws DBException(Code) | | 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
Parameters: oneByOne - set 'true' usually, to make sure that all 'detail' records are also deleted. Set to false if you are sure that the table has no detail records (i.e., it supplies no foreign keys--has no dependent records) throws: DBException - upon error |
deleteDetails | protected void deleteDetails(DBConnection detailConnection) throws DBException(Code) | | 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.
Parameters: detailConnection - the DBConnection to use while retrieving details throws: DBException - upon error. |
denotesRange | protected String denotesRange(String fieldValue)(Code) | | Does a given field value denote a range?
Parameters: fieldValue - The field value to check against. The "range" string if the value starts with a range indicator, null if not |
equals | public boolean equals(Object parm1)(Code) | | Equals implementation. this == parm1 If and only if:
1 - The two classes are of the same classname
2 - All the data fields in the two classes are the same
3 - The data contexts are the same
Parameters: parm1 - The object to compare to true if the two objects being compared are equal |
find | public boolean find() throws DBException(Code) | | A lot like retrieve, but works with any fields, not just the key field. Does not
throw an exception if the record is not found, just returns false.
Finds only first record matching the criteria. The current fields in this object
are populated with the data in the record found after the call to find() if the
find is successful.
boolean If the search resulted in a record throws: DBException - If the search could not be completedModify by Yves Henri AMAIZO |
forKey | public String forKey()(Code) | | 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
String: A formatted string showing the key of this record |
formatDateTime | public String formatDateTime(String fieldName) throws DBException(Code) | | Given the value of a date/time or date/time field, return the value formatted
as appropriate for the current DBMS. Can be configured using property
file values.
Parameters: fieldName - java.lang.String The value for the date/time field. java.lang.String The formatted date time, ready for use in the DBMS throws: DBException - upon error. |
get | public Object get(String fieldName) throws DataException(Code) | | Directly gets the DataField Data without having to deal with the DataField
itself
Parameters: fieldName - the name of the field to get Object or null. throws: DataException - upon error. |
getAllAttributes | public Map getAllAttributes()(Code) | | Returns a Read Only Map containing all the current attributes set
for this particular data object instance.
Read Only java.util.Map |
getAttribute | public Object getAttribute(String attribName)(Code) | | Return an "attribute". Attributes are temporary (e.g. not stored in the DBMS)
values associated with this particular DB object instance.
Parameters: attribName - The attribute name to check the object associated with this attribute |
getAttributesIterator | public Iterator getAttributesIterator(String fieldName) throws DBException(Code) | | Get an iterator for all of the attributes specified for a field
Parameters: fieldName - The field name to get the attirbutes for the Iterator for all attributes associated with this field throws: DBException - upon error. |
getBooleanFieldValue | protected String getBooleanFieldValue(boolean fieldValue) throws DBException(Code) | | Internal refactoring for getting what a boolean field should be set to.
Parameters: fieldValue - The target value the string value throws: DBException - upon error. |
getCacheSize | public int getCacheSize()(Code) | | Gets the set size of the cache for this DBOBject
The number of cache objects available for this object. |
getCacheStatsMap | public static synchronized HashMap getCacheStatsMap()(Code) | | a HashMap of all cache stats |
getCacheUtil | protected CacheUtils getCacheUtil()(Code) | | 'Pseudo' factory method to retrieve the caching utility class instance.
CacheUtils instance |
getCustomWhereClause | public String getCustomWhereClause()(Code) | | Allows us to query the custom where clause (if any). ' WHERE ' has been prepended to the clause.
You may want to remove this prepended info for reuse, e.g. getCustomWhereClause().substring(WHERE_KEYWORD.length())
java.lang.String or null if no custom where clause has been set. |
getDBName | public synchronized String getDBName()(Code) | | Return the name of the context/database connection that this DB object is using.
If none is set, then we are using the "default" database/context.
a String containing the name of the DBName to use. |
getDataContext | public String getDataContext()(Code) | | Returns the name of the currently set DataContext
java.lang.String |
getDataField | public DataField getDataField(String fieldName) throws DBException(Code) | | Same as getField, but works with the DataObject interface for now. Will
eventually return something other than Strings. For example, dates, times,
etc
Parameters: fieldName - name of the field to get the object for. DataField or null if the field doesn't exist yet. throws: DBException - upon error. |
getDataTransferObject | public synchronized DataTransferObject getDataTransferObject() throws DBException(Code) | | Gets the data transfer object usually for serialization purposes
The built DataTransferObject throws: DBException - upon error. |
getDetails | public Enumeration getDetails() throws DBException(Code) | | 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
java.util.Enumeration containing all detail objects throws: DBException - upon error. |
getDistinctFieldCount | public synchronized int getDistinctFieldCount() throws DBException(Code) | | This convenience method counts
DBFields belonging to this
DBObject that are set to distinct.
int number of distinct fields.author Peter Pilgrim throws: DBException - upon error. |
getDistinctFields | public String[] getDistinctFields() throws DBException(Code) | | This convenience method iterates through all the
fields belonging to this DBObject
returns an array of field names ( String )
that are set to distinct.
If there are are no distinct fields then the method
returns a null reference.
String array of distinct field names in this object.author Peter Pilgrim throws: DBException - upon error. See Also: DBObject.getDistinctFieldCount() See Also: DBObject.isDistinct() |
getField | public synchronized String getField(String fieldName) throws DBException(Code) | | Get the string value of a field in this object as a string
Parameters: fieldName - Name of the field to fetch 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 |
getFieldBigDecimal | public BigDecimal getFieldBigDecimal(String fieldName) throws DBException(Code) | | Get the BigDecimal value of a field in this object.
We use the locale specified
in the properties file directly to determine how to parse the field
NB: Corresponds to java.sql.Type.DECIMAL or java.sql.Type.NUMERIC
Parameters: fieldName - Name of the field to be retrieved BigDecimal The value of the field as a BigDecimal object throws: DBException - If there is no such field or it's valuecannot be converted to a BigDecimalauthor Peter Pilgrim See Also: "'JDBC API Tutorial and Reference', Second Edition, pg 944, by Catell, Hamilton et al; published by Addison Wesley" See Also: DBObject.setField(String,BigDecimal) |
getFieldBoolean | public boolean getFieldBoolean(String fieldName) throws DBException(Code) | | Boolean typesafe getField
Parameters: fieldName - to retrieve boolean true false throws: DBException - upon error. |
getFieldByte | public byte getFieldByte(String fieldName) throws DBException(Code) | | Get the primitive byte value of a field in this object.
A convenience method for getField
Parameters: fieldName - Name of a field in this object int The value of the field as a int throws: DBException - if there is no such field or it's value cannot beconverted to a byte integer. See Also: DBObject.setField(String,byte) |
getFieldByteArray | public byte[] getFieldByteArray(String fieldName) throws DBException(Code) | | Get the primitive byteArray value of a field in this object.
A convenience method for getField
Parameters: fieldName - Name of a field in this object int The value of the field as a byte{] throws: DBException - if there is no such field or it's value cannot beget to a byte array. See Also: DBObject.setField(String,byte[]) |
getFieldData | protected String getFieldData(String fieldName)(Code) | | Internal mechanism for getting the raw field data
Parameters: fieldName - the name of the field to retrieve the data for java.lang.String or null if the fieldData doesn't exist in the map |
getFieldDate | public java.util.Date getFieldDate(String fieldName) throws DBException(Code) | | Return the value of a field as a Date object
Parameters: fieldName - The field to be retrieved The Date object equivilant to this field's value throws: DBException - If the field does not exist or it's valueis not a date or cannot be converted to a date |
getFieldDecimalFormatted | public String getFieldDecimalFormatted(String fieldName, String formatPattern) throws DBException(Code) | | Return the value of a field as a Date object
Parameters: fieldName - The field to be retrieved Parameters: formatPattern - A formatting pattern according to java.text.DecimalFormat.Leave null for the default format for this locale.Symbol Meaning0 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; ifdoubled, replaced by international currency symbol.If present in a pattern, the monetary decimal separatoris 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. The Date object equivilant to this field's value throws: DBException - If the field does not exist or it's valueis not a date or cannot be converted to a date See Also: java.text.DecimalFormat |
getFieldDouble | public double getFieldDouble(String fieldName) throws DBException(Code) | | Get the primitive double value of a field in this object. we use the locale specified
in the properties file directly to determine how to parse the field
Parameters: fieldName - Name of the field to be retrieved float The value of the field as a float throws: DBException - If there is no such field or it's valuecannot be converted to a float See Also: DBObject.setField(String,double) |
getFieldErrorMessage | public String getFieldErrorMessage(String fieldName)(Code) | | Retrieve the error message associated with this field.
Parameters: fieldName - the fieldName to get the associated error message A string containing the field error message or NULL if there isno error for this field. or POSSIBLY if no error message has been setfor this field. |
getFieldFloat | public float getFieldFloat(String fieldName) throws DBException(Code) | | Get the primitive float value of a field in this object. we use the locale specified
in the properties file directly to determine how to parse the field
Parameters: fieldName - Name of the field to be retrieved float The value of the field as a float throws: DBException - If there is no such field or it's valuecannot be converted to a float See Also: DBObject.setField(String,double) |
getFieldInt | public int getFieldInt(String fieldName) throws DBException(Code) | | Get the primitive integer value of a field in this object.
A convenience method for getField
Parameters: fieldName - Name of a field in this object 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 beconverted to an integer. See Also: DBObject.setField(String,int) See Also: DBObject.isFieldNull(java.lang.String) See Also: in order to know if 0 is 'real' or because of an underlying null |
getFieldLong | public long getFieldLong(String fieldName) throws DBException(Code) | | Get the prmitive long value of a field in this object.
A convenience method for getField
Parameters: fieldName - Name of a field in this object long The value of the field as a long throws: DBException - if there is no such field or it's value cannot beconverted to a long integer. See Also: DBObject.setField(String,long) |
getFieldMetaData | public DataFieldMetaData getFieldMetaData(String fieldName)(Code) | | Returns the metadata for the specified field.
Parameters: fieldName - The name of the field to get The DBField for this fieldName |
getFieldShort | public short getFieldShort(String fieldName) throws DBException(Code) | | Get the primitive integer value of a field in this object.
A convenience method for getField
Parameters: fieldName - Name of a field in this object int The value of the field as a int throws: DBException - if there is no such field or it's value cannot beconverted to a short integer. See Also: DBObject.setField(String,short) |
getFieldsToRetrieveCount | public synchronized int getFieldsToRetrieveCount() throws DBException(Code) | | This convenience method counts
DBFields belonging to this
DBObject that are set to retrieve.
int number of retrieve fields. throws: DBException - upon error. |
getFilterClass | public Class getFilterClass()(Code) | | the INSTANCE value of filter class that will be used for all string filtering for THIS INSTANCE.
defaults to null, which means that there is no instance filter, so static filter will be used.
If this instance returns null, static value in
DBField.getFilterClass() filter class will be used. This method only
returns the local data member, not the static value from DBField
the current filter (a subclass of Filter), or null to indicate default (HTML) filter See Also: DBField.getFilterClass See Also: com.jcorporate.expresso.core.security.filters.HtmlFilter |
getFoundCount | public long getFoundCount()(Code) | | Return the number of records found in the last search operation. See also
count() and find().
The count of records found |
getFoundKeysArray | public Object[] getFoundKeysArray()(Code) | | Return the Array of keys (in the form field/field/field) that
was found in the last search() call
An array containing keys as strings |
getISOValuesDefault | protected Vector getISOValuesDefault(String valueField, String descripField) throws DBException(Code) | | Basic version of getValidValues with supports
internationalisation (i18n) that stores/retrieves
the valid values in a locale dependent Caches
Valid values are store inside cache with a key name that equals
myClassName+"."+oneLocale.getString()+".validValues" .
For example the key cache could be:
"com.acme.test.Fruits.en_gb.validValues"
"com.acme.test.Fruits.de_de.validValues"
"com.acme.test.Fruits.es_es.validValues"
The method creates ISOValidValue object instances and
stores them in the cache.
Parameters: valueField - java.lang.String Parameters: descripField - java.lang.String java.util.Vector throws: DBException - if a database error occurs#see #getValuesDefault(String valueField, String descripField) |
getISOValuesDefault | protected Vector getISOValuesDefault(String valueField, String descripField, String whereClause) throws DBException(Code) | | Basic filtered version of getValidValues with supports
internationalisation (i18n) that stores/retrieves
the valid values in a locale dependent Caches
Valid values are store inside cache with a key name that equals
myClassName+"."+oneLocale.getString()+".validValues" .
For example the key cache could be:
"com.acme.test.Fruits.en_gb.validValues"
"com.acme.test.Fruits.de_de.validValues"
"com.acme.test.Fruits.es_es.validValues"
The method creates ISOValidValue object instances and
stores them in the cache.
Parameters: valueField - java.lang.String Parameters: descripField - java.lang.String Parameters: whereClause - the where clause that will be passto setCustomWhereClause. java.util.Vector throws: DBException - if a database error occurs#see #getValuesDefault(String valueField, String descripField, String whereClause) |
getISOValuesDefault | protected Vector getISOValuesDefault(String valueField, String descripField, String whereClause, String sortKeyString) throws DBException(Code) | | Basic version of getValidValues with supports
internationalisation (i18n) that stores/retrieves the valid
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.
Valid values are store inside cache with a key name that equals
myClassName+"."+oneLocale.getString()+".validValues" .
For example the key cache could be:
"com.acme.test.Fruits.en_gb.validValues"
"com.acme.test.Fruits.de_de.validValues"
"com.acme.test.Fruits.es_es.validValues"
The method creates ISOValidValue object instances and
stores them in the cache.
Parameters: valueField - java.lang.String Parameters: descripField - java.lang.String Parameters: whereClause - the where clause that will be passto setCustomWhereClause. Parameters: sortKeyString - the pipe delimited string of field names with theoptional 'ASC or DESC' keyword afterwords java.util.Vector throws: DBException - if a database error occurs#see #getValuesDefault(String valueField, String descripField, String whereClause, String sortKeyString) |
getIndexArray | public synchronized Object[] getIndexArray() throws DBException(Code) | | Get an array of DBIndex objects for purpose of
creating them through the schema. Return type
should actually be DBIndex. Please Note This may cause an
exception to be thrown if indexList is null. Call hasIndex() first
before calling getIndexArray
To be soon deprecated
an object containing all the DBOBjects throws: DBException - upon error. |
getKey | public String getKey()(Code) | | Get a string consisting of the values of each key field for this object
appended together with a | between them.
Value of all keys appended with a | between |
getKeyFieldListIterator | public Iterator getKeyFieldListIterator() throws DBException(Code) | | Get a list of all of the fields in this object This iterator is not thread
safe.
An iterator of the fieldNamesInOrder array list throws: DBException - If the list cannot be retrieved |
getLength | public String getLength(String fieldName) throws DBException(Code) | | Return the length of a field
Parameters: fieldName - The name of the field String: The length of the field throws: DBException - If there is no such field in this object |
getLengthInt | public int getLengthInt(String fieldName) throws DBException(Code) | | Get the length of this field as an integer
Parameters: fieldName - to check length of field throws: DBException - upon error. |
getLocalConnection | public DBConnection getLocalConnection()(Code) | | Returns the local connection currently associated with this DBObject...
may be null if no local connection has ever been set.
com.jcorporate.expresso.core.db.DBConnection or null |
getLocale | public Locale getLocale()(Code) | | Get the current locale for this dbobject
The currently set locale or null if there is no locale set. since: Expresso 5.0.1 |
getLogger | public Logger getLogger()(Code) | | convenience for getting logger for current (sub) class
Category for logging |
getLookupObject | public String getLookupObject(String fieldName) throws DBException(Code) | | Get a field's lookup object - this is the name of another database
object that can be used to look up valid values for this object. The lookup
object for a field is set in the db objects setupFields method, and is used
by the DBMaint servlet to provide automatic lookup links for fields.
Parameters: fieldName - The fieldname to look up A String containing the classname of the lookup dbobject throws: DBException - If the specified field does not exist. |
getMax | public String getMax(String fieldName, boolean whereClause) throws DBException(Code) | | Get the Maximum value in the table of a particular field
Contributed by Madan Mohanrao Kulkarni [kulsmadya@rediffmail.com]
Parameters: fieldName - the Fieldname to get the max value for. Parameters: whereClause - Use a custom whereclause? a String containing the maximum value for this field nameModify by Yves Henri AMAIZO throws: DBException - upon error. |
getMax | public String getMax(String fieldName) throws DBException(Code) | | Get the Maximum value in the table of a particular field
Contributed by Madan Mohanrao Kulkarni [kulsmadya@rediffmail.com]
Parameters: fieldName - The fieldName to check against The maximum value for this field in the table. throws: DBException - upon error. |
getMaxRecords | public int getMaxRecords()(Code) | | A DB Object can be told to only retrieve a certain number of records. If a
"max records" value has been specified, this method provides access to it.
The maximum number of records that should be retrieved, or zeroif no max has been set |
getMyKeys | public String getMyKeys() throws DBException(Code) | | Get a string consisting of the values of each key field for this object
appended together with a | between them.
Value of all keys appended with a | between throws: DBException - If the key list cannot be built. |
getMyUpdatesArray | protected Object[] getMyUpdatesArray()(Code) | | Return the array of updates (see the inner class) that specify what changes
were just made to this object.
Logged Updates in an Object Array |
getOffsetRecord | public int getOffsetRecord()(Code) | | 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 ResultSet .
author Peter Pilgrim, Thu Jun 21 10:30:59 BST 2001
The maximum number of records that should beskipped over before reading the data records. See Also: DBObject.setOffsetRecord(int) |
getPatternMatcher | protected PatternMatcher getPatternMatcher()(Code) | | Retrieve a thread local instance of the Perl5 pattern matcher. Allows
for optimization of # of instances of pattern matcher vs synchronization.
PatternMatcher |
getPrecision | public int getPrecision(String fieldName) throws DBException(Code) | | Get the precision of thie field, if one was specified
Parameters: fieldName - The fieldname to get the precision for length of precision as integer throws: DBException - upon error. |
getSerializedForm | public String getSerializedForm(DBField theField) throws DBException(Code) | | This function is called whenever the DBField is about to be written to
the database. It may do additional processing such as encryption depending
on the field attributes.
Parameters: theField - A DBField object the value to write to the data source. throws: DBException - upon error. |
getThisDBObj | protected DBObject getThisDBObj() throws DBException(Code) | | This will return a new object of the type of the subclass.
OVERRIDE this method with implentation like
return new MyObject()
if you want greatest efficiency. For example: A DBObject called "Customer"
should return a new "Customer" object.
the implementation in DBObject uses getClass().newInstance(), which seems to be about
50% slower than "new MyObject()" calls on JDK 1.4
Note that this method should never be called directly. It should only
be called by newInstance()
DBObject A newly allocated object of the subclass's class throws: DBException - upon error. See Also: DBObject.getThisDBObj |
getThisDBbj | public static synchronized DBObject getThisDBbj(DataTransferObject dto) throws DBException(Code) | | Constructor method that takes a DataTransferObject and builds a full fledged
DBObject out of it.
Parameters: dto - The DataTransferObject a constructed DBObject that still needs DataContext and recordownership to be set. throws: DBException - upon error |
getValidValueDescrip | public String getValidValueDescrip(String fieldName) throws DBException(Code) | | This is a convenience method which will return a ValidValue description
for a multi-valued field.
(Contributed by Adam Rossi)
Parameters: fieldName - java.lang.String java.lang.String The description of this multi-valued field throws: DBException - If there is no such field, or the values cannot be retrieved. |
getValidValues | public synchronized Vector getValidValues(String fieldName) throws DBException(Code) | | New method to replace getValues with a structure of valid values
and descriptions. Database objects should extend this method to
return Vectors of ValidValue objects for multi-valued fields. A
specific object can return it's own list of ValidValues, or it
can call this super method to use the lookup object to get the
list of valid values instead.
Parameters: fieldName - The name of the fields for which a value set is requested A Vector of ValidValue objects throws: DBException - upon error. |
getValidValuesList | public java.util.List getValidValuesList(String fieldName) throws DBException(Code) | | Retrieve a list of valid value object for this particular dbobject
Parameters: fieldName - the name of the field to get the valid values list for java.util.List of ValidValue objects throws: DBException - upon error |
getValues | public Vector getValues() throws DBException(Code) | | Method to return a Vector of ValidValue
Template method--not implemented in this superclass.
This method may be implemented by objects that want to provide a
list of valid values for other DB objects. It is strongly recommended
that the valid value list be cached (via the CacheManager) for performance.
The naming convention used in Expresso is to store the ValidValue list with
a cache name the same as the db objects class name with ".validValues" appended
TODO: This should be converted to array List versions
java.util.Vector of valid values throws: DBException - upon error. See Also: DBObject.getValidValues |
getValuesDefault | protected Vector getValuesDefault(String valueField, String descripField) throws DBException(Code) | | Basic version of getValidValues that stores/retrieves the valid
values in a Cache. This method does not support
internationalisation (i18n).
Valid values are store inside cache with a key name that equals
myClassName+".validValues"
The method creates ValidValue object instances and
stores them in the cache.
Parameters: valueField - java.lang.String Parameters: descripField - java.lang.String java.util.Vector throws: DBException - if a database error occurs#see #getValuesDefault(String valueField, String descripField, String whereClause)#see #getISOValuesDefault(String valueField, String descripField) |
getValuesDefault | protected Vector getValuesDefault(String valueField, String descripField, String whereClause) throws DBException(Code) | | Basic filtered version of getValidValues that stores/retrieves the valid
values in a Cache. This method does not support
internationalisation (i18n).
Valid values are store inside cache with a key name that equals
myClassName+".validValues"
The method creates ValidValue object instances and
stores them in the cache.
Parameters: valueField - java.lang.String Parameters: descripField - java.lang.String Parameters: whereClause - the where clause that will be passto setCustomWhereClause. java.util.Vector throws: DBException - if a database error occurs#see #setCustomWhereClause(String newCustomWhere)#see #getISOValuesDefault(String valueField, String descripField) |
getValuesDefault | protected Vector getValuesDefault(String valueField, String descripField, String whereClause, String sortKeyString) throws DBException(Code) | | Basic version of getValidValues that stores/retrieves the valid values
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 not support internationalisation (i18n).
Valid values are store inside cache with a key name that equals
myClassName+".validValues"
The method creates ValidValue object instances and
stores them in the cache.
Parameters: valueField - java.lang.String Parameters: descripField - java.lang.String Parameters: whereClause - the where clause that will be passto setCustomWhereClause. Parameters: sortKeyString - the pipe delimited string of field names with theoptional 'ASC or DESC' keyword afterwords; pass in null to indicate no sorting java.util.Vector throws: DBException - if a database error occurs#see #setCustomWhereClause(String newCustomWhere)#see #setSortKey(String sortKeyString)#see #getISOValuesDefault(String valueField, String descripField) |
hasError | public boolean hasError(String fieldName)(Code) | | Use this to check if a field is in error.
Parameters: fieldName - Check if there's an error set for this field. true if an error is set for this field. |
hasErrors | public boolean hasErrors()(Code) | | Use this to check if any fields are in error.
true if an error is set. |
haveAllKeys | public boolean haveAllKeys() throws DBException(Code) | | See if we have a value for each of the key fields
True if all key fields have a value, false if not throws: DBException - upon error. |
initialize | protected synchronized void initialize() throws DBException(Code) | | Sets up metadata for the dbobject via call to setupFields().
it is important within this method to provide STATIC synchronization
to enable static (meta)data members to be setup by the first
instantiation of a given class. Two threads
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.
author Adam Rossi, PlatinumSolutions
author Larry Hamel, CodeGuild.com
throws: DBException - The exception description. |
isCached | public boolean isCached()(Code) | | Is this object using internal caching?
If the cache value is set to other than zero, it is using caching
True if internal caching is enabled, else false |
isChanged | public boolean isChanged() throws DBException(Code) | | summarize DataField.isChanged() for all fields.
isChanged() per field means that setField() has been called twice for that field,
once presumably by retrieval from DB, once to change a value (with
new value != former value)
true if any field has been changed--i.e., setField() for that field has been called twice, once presumably by retrieval from DB, once to change a value throws: DBException - upon error. See Also: DataField.isChanged |
isEmpty | public synchronized boolean isEmpty() throws DBException(Code) | | Return true if every field in this object is empty or null. Tests only
"real" fields, not virtual ones
boolean: True if the record is "empty" (all fields blank),False if not. throws: DBException - If the list of fields cannot be traversed |
isFieldNull | public boolean isFieldNull(String fieldName) throws DBException(Code) | | Tells whether a particular field is null or not. Note:
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.
Parameters: fieldName - The name of the field to check for isFieldNull() true if the field is null throws: DBException - if the field doesn't exist for the particularDBObject. |
isFieldToRetrieve | public boolean isFieldToRetrieve(String fieldName) throws DBException(Code) | | Convenience method to check if a field is field to be retrieve or not
within this database object.
Parameters: fieldName - the name of the field boolean value true if the field is set distinct. throws: DBException - If the operation could not be completedauthor Yves Henri Amaizo See Also: DBObject.setFieldsToRetrieve(String) |
isFieldsToRetrieve | public synchronized boolean isFieldsToRetrieve() throws DBException(Code) | | This method iterates through all the DBFields belonging
DBObject returns true if any of them are
between the retrieve fields.
author Yves Henri Amaizo
true if there are specific fields to retrieve throws: DBException - upon error. See Also: DBObject.isFieldToRetrieve(String) |
isMultiValued | public synchronized boolean isMultiValued(String fieldName) throws DBException(Code) | | Method called to determine if a particular field is multi-valued,
that is does it have a set of specific values and descriptions
Parameters: fieldName - Name of the field boolean True if the field is multi-valued, false if not throws: DBException - If there is no such field |
isReadOnly | public boolean isReadOnly(String fieldName) throws DBException(Code) | | Is a given field readOnly - these fields are not offered for entry
when a form is produced by the generic database maintenance servlet
Parameters: fieldName - The field name to check True of the field is "read only", false if it is not throws: DBException - Ff there is no such field |
isSecret | public boolean isSecret(String fieldName) throws DBException(Code) | | Is a given field 'secret' - these fields are not shown
when a list is produced by the generic database maintenance servlet (DBMaint).
This means that only users with update permission to the record can see the
value of the specified field.
Parameters: fieldName - The name of the field to check True if the field is 'secret', false if it is not throws: DBException - If there is no such field. See Also: DBObject.setSecret(String) |
isVirtual | public boolean isVirtual(String fieldName) throws DBException(Code) | | Is a given field virtual? A virtual field is not stored in the target table
for this object - it may be computed, or stored in another table.
Parameters: fieldName - The name of the field to check True of the field is virtual, false if it is not throws: DBException - If there is no such field See Also: DBObject.addVirtualField(String,String,int,String) |
loadFromConnection | public synchronized int loadFromConnection(DBConnection connection) throws DBException(Code) | | Hand a dbobject a connection that contains fields corresponding to
what the dbobject expects, and it'll set itself.
Does not increment the result set in the DBConnection.
Parameters: connection - The connection that currently has a dbobject ready tobe read in it's result set. The number of fields read. Depending on the SQL you sent to the connectionthe DBObject might not have all fields in existence. throws: DBException - upon error. |
logChange | protected void logChange(DBField oneField, String fieldValue)(Code) | | Helper Function:
If Change Logging is enabled, then this logs what has changed
Parameters: oneField - The field to set the data to. Parameters: fieldValue - The value to set the field to. |
max | public double max(String fieldName) throws DBException(Code) | | Find the maximum of the values in the specified field of records
se;lected by the DBObject selection criteria.
Parameters: fieldName - String DBObject fieldName to average double Maximum of the records matching the criteria throws: DBException - If the search could not be completed |
min | public double min(String fieldName) throws DBException(Code) | | Find the minimum of the values in the specified field of records
selected by the DBObject selection criteria.
Parameters: fieldName - String DBObject fieldName to average double Minimum of the records matching the criteria throws: DBException - If the search could not be completed |
newInstance | public DBObject newInstance() throws DBException(Code) | | get a new instance of this object, with some basic attributes copied,
like the local connection of the transaction
Generally speaking, DO NOT OVERRIDE THIS METHOD. Instead, to improve efficiency,
most subclasses will override the method getThisDBObj()
DBObject A newly allocated object of the subclass's class throws: DBException - upon error. See Also: DBObject.getThisDBObj |
noNewLine | protected String noNewLine(String fieldValue)(Code) | | Strip out the newlines out of a string
Parameters: fieldValue - the Value to strip of newlines the data with newlines stripped |
noQuotes | protected String noQuotes(String oldString)(Code) | | Utility method to return a string with all single quotes replaced with a pair of
single quotes, and all double quotes also replaced with a pair of single quotes
Parameters: oldString - The original string The string modified as above |
notifyListeners | protected synchronized void notifyListeners(String eventCode) throws DBException(Code) | | Used by internal caching to ensure that caches are cleared when an update is
made. Notifies all of the objects registered to receive "update events" on
this object of the fact that an update has occurred. The "listener" then
clears or updates it's cache as appropriate.
Parameters: eventCode - The "code" for the event that has just occurred throws: DBException - If an error occurrs trying to send all of the event notices |
populateDefaultValues | public synchronized void populateDefaultValues() throws DBException(Code) | | populateDefaultValues is called by the schema object to allow a table to
populate itself with any desired values.
The base class implementation does nothing. Override this method in derived
classes to achieve your custom behavior.
The calling routine, DBTool.populateTables(), will set dbName on each
object, so you can get it from getDataContext(), and you can assume that the
user for the population action is Admin.
throws: DBException - Upon add error, never if it isn't overridden. |
referredToBy | protected synchronized void referredToBy(DBObject refObject, String foreignKeyNames, String errorMessage) throws DBException(Code) | | The reverse of the checkRef method - if this object is referred to
by some other object, and we are changing our own key (only allowed
by deleting)
then check the other table to make sure our key is not being used by it!
This method should by called by subclass delete() methods
(which then call super.delete() to handle
the actual deletion)
Parameters: refObject - An instance of the DBObject that refers to us Parameters: foreignKeyNames - A semicolon-delimited list of foreignkey names from the other object Parameters: errorMessage - The error message to throw if the key is in use throws: DBException - If it is not possible to register thegiven referential constraint |
removeAttribute | public void removeAttribute(String attributeName)(Code) | | Removes an attribute from this particular database object.
Parameters: attributeName - The name of the attribute to remove. |
removeFromCache | public synchronized void removeFromCache(DBObject theDBObj) throws DBException(Code) | | Remove a specific object from that object's cache. It will then be re-read
when a new object is requested by a client program
Creation date: (4/18/00 1:49:46 PM)
Parameters: theDBObj - com.jcorporate.expresso.core.dbobj.DBObject The object tobe removed throws: DBException - upon error. |
retrieveFromCache | public boolean retrieveFromCache() throws DBException(Code) | | Retrieve this object from cache, if possible.
true if the cache supplied this item, falseotherwise throws: DBException - upon error. |
saveBinaryField | public void saveBinaryField(String fieldName, byte[] incomingData) throws DBException(Code) | | Sets a byte array to the underlying data as a blob
Parameters: fieldName - The name of the field to save. Parameters: incomingData - the stream to write to the database table. throws: DBException - upon error |
search | public synchronized void search() throws DBException(Code) | | Find a set of keys of all of the objects that match the current
search critieria in the fields. Search assumes that the fields are
populated with search criteria instead of data
NOTE: Criteria in 'text' type colums is ignored. After the search, the
foundKeys vector is populated with the keys of the records found by the search.
throws: DBException - if unable to retreive records due to a database problemModify by Yves Henri AMAIZO |
search | public synchronized void search(String sortKeyString) throws DBException(Code) | | Second form of search: takes a list of sort keys & calls regular search.
The records retrieved are in the specified order
Parameters: sortKeyString - A string containing field names,seperated by pipes, that indicate in what order the objectsare retrieved throws: DBException - upon error. |
searchAndRetrieveList | public synchronized ArrayList searchAndRetrieveList() throws DBException(Code) | | Find a set of records of all of the objects that match the current
search critieria in the fields
and retrieve the list of all records that match this criteria
NOTE: Criteria in 'text' type colums is ignored (SQL Server limitation)
SIDE-EFFECT: custom 'where' clause is set to null.
Vector A vector of new database objects containing the resultsof the search throws: DBException - If the search could not be completed |
searchAndRetrieveList | public synchronized ArrayList searchAndRetrieveList(String sortKeyString) throws DBException(Code) | | Search and retrieve in a particular order
Parameters: sortKeyString - A pipe-delimited list of key fields to sortthe returned set by Vector A vector of new database objects retrieved by the search throws: DBException - If the search could not be completed |
set | public void set(String fieldName, Object o) throws DataException(Code) | | sets the field value by using 'instanceof' operator; convenient for template methods, but less efficient
than calling setField()
Parameters: fieldName - the name of the field to set Parameters: o - the object value to set it to. throws: DataException - upon error. See Also: DBObject.setField |
setAttribute | public synchronized void setAttribute(String attribName, Object attribValue)(Code) | | Set an attribute. Attributes are temporary (e.g. not stored in the DBMS) values
associated with this particular DB object instance.
Parameters: attribName - The name of the attribute being defined Parameters: attribValue - The object to store under this attribute name |
setCacheSize | public synchronized void setCacheSize()(Code) | | Read the configuration table to determine the max size
of the cache for this db object. The way we go about it is like so:
- Check if setCacheSize(int) has been set before. If so, return that
- Check if a specific entry exists for this object in the ControllerDefaults
table if so return that
- Try to read the default entries in the table. If it doesn't exist you're
going to see a log warning. Return that value
- And finally if that all fails, set the default cache size to zero
|
setCheckZeroUpdate | public synchronized void setCheckZeroUpdate(boolean newFlag) throws DBException(Code) | | Turn on or off the facility to verify that when an update is made that at
least one record got updated. If this flag is on, and no records get updated,
the update() method throws an Exception. Note that for some databases, if the
existing record is not changed (e.g. it was already identical to what
was being updated) this counts "no update" (notably, mySQL does this).
Parameters: newFlag - True to turn on checking, false to turn it off throws: DBException - upon error. |
setConnection | public synchronized void setConnection(DBConnection newConnection) throws DBException(Code) | | Set a specific DB connection for use with this db object. If you do not set
a connection, the db object will request it's own connection from the
appropriate connection pool & release it again after every operation (e.g.
add, update, etc). It is important to use your own explicit connection when
dealing with a database transactional environment (e.g. commit(), rollback()).
Parameters: newConnection - The new DBConnection object to be used by this DB Object throws: DBException - upon error. |
setConnection | public synchronized void setConnection(DBConnection newConnection, String setupTablesContext) throws DBException(Code) | |
Set a specific DB connection for use with this db object. If you do not set
a connection, the db object will request it's own connection from the
appropriate connection pool & release it again after every operation (e.g.
add, update, etc). It is important to use your own explicit connection when
dealing with a database transactional environment (e.g. commit(), rollback()).
The difference between this and setConnection(DBConnection) is that this
is used for using otherDB capabilities within a transaction. So you use
a dbconnection from your other pool, but the setup tables are in a different
context
Parameters: newConnection - The new DBConnection object to be used by this DB Object Parameters: setupTablesContext - the data context that is used for the expresso setup tables. throws: DBException - upon error. See Also: DBObject.setConnection(DBConnection) |
setCustomWhereClause | public synchronized void setCustomWhereClause(String newCustomWhere)(Code) | | Specify a custom "where" clause for the SQL used to retrieve records for this
object. The where clause 'reset' after each call to searchAndRetrieve() or
other retrieval methods, so it must be set just before the call to retrieve
the records is made. If no custom where clause is specified by this method, the
where clause is built from the field values in the object.
Parameters: newCustomWhere - java.lang.String string with clause. Do NOT add 'WHERE' keyword--this is prepended by system, so that multiple calls to append can be made |
setCustomWhereClause | public synchronized void setCustomWhereClause(String newCustomWhere, boolean append)(Code) | | Allows us to specify a custom WHERE clause and have it appended to the
one built from the field values in the object
Parameters: newCustomWhere - java.lang.String string with clause. Do NOT add 'WHERE' keyword--this is prepended by system, so that multiple calls to append can be made Parameters: append - if true, custom WHERE clause is appended |
setDataContext | public void setDataContext(String newContext)(Code) | | Sets the data context that this object is residing in. This is identical
to the pre-Expresso 5.0 setDBName()
Parameters: newContext - the new name of the data context. throws: IllegalArgumentException - if the DataContext does not exist |
setDataField | public void setDataField(String fieldName, DataField o) throws DataException(Code) | | Same as setField, but works with the DataObject Interface
Parameters: fieldName - the name of the field to set. Parameters: o - the object to set the field to... currently should bejava.lang.Strings only. throws: DataException - upon error. since: Expresso 5.0 |
setDataTransferObject | public synchronized void setDataTransferObject(DataTransferObject dto) throws DBException(Code) | | fill fields with values found in dto; REPLACES any data field already present.
Parameters: dto - The filled out data transfer object throws: DBException - upon error. |
setDefaultValue | protected synchronized void setDefaultValue(String fieldName, String fieldValue) throws DBException(Code) | | Define a "default" value for a field - to be used for the field
when the user does not specify a value.
Parameters: fieldName - the field to set Parameters: fieldValue - the default value to set throws: DBException - upon error. |
setDescription | public synchronized void setDescription(String newDescription) throws DBException(Code) | | Set the description of this object
Parameters: newDescription - A description of this database object throws: DBException - upon error. |
setField | public synchronized void setField(String fieldName, byte fieldValue) throws DBException(Code) | | Byte primitive integer Typesafe version of setField.
Convenience method to set the field values.
Parameters: fieldName - The name to set Parameters: fieldValue - the byte integer field value to set throws: DBException - upon error. |
setField | public synchronized void setField(String fieldName, byte[] fieldValue) throws DBException(Code) | | Byte primitive integer Typesafe version of setField.
Convenience method to set the field values.
Parameters: fieldName - The name to set Parameters: fieldValue - the byte integer field value to set throws: DBException - upon error. |
setField | public synchronized void setField(String fieldName, short fieldValue) throws DBException(Code) | | Short primitive integer Typesafe version of setField.
Convenience method to set the field values.
Parameters: fieldName - The name to set Parameters: fieldValue - the short integer field value to set throws: DBException - upon error. |
setField | public synchronized void setField(String fieldName, int fieldValue) throws DBException(Code) | | Integer primitive Typesafe version of setField.
Convenience method to set the field value.
Parameters: fieldName - The name to set Parameters: fieldValue - the integer field value to set throws: DBException - upon invalid parameters. |
setField | public synchronized void setField(String fieldName, long fieldValue) throws DBException(Code) | | Long primitive Typesafe version of setField .
Convenience method to set the field value.
Parameters: fieldName - The name to set Parameters: fieldValue - the long integer field value to set throws: DBException - upon invalid parameters. |
setField | public synchronized void setField(String fieldName, double fieldValue) throws DBException(Code) | | Double primitive Typesafe version of setField .
Convenience method to set the field values.
Parameters: fieldName - The name to set Parameters: fieldValue - the double field value to set throws: DBException - upon invalid values. |
setField | public synchronized void setField(String fieldName, BigDecimal fieldValue) throws DBException(Code) | | BigDecimal object Typesafe version of setField .
Convenience method to set the field values.
Parameters: fieldName - The name to set Parameters: fieldValue - the big decimal value to set throws: DBException - upon error. |
setField | public synchronized void setField(String fieldName, boolean fieldValue) throws DBException(Code) | | Boolean typesafe version of setField
Parameters: fieldName - The field name to set Parameters: fieldValue - the new boolean Field Value to set throws: DBException - upon error. |
setField | public synchronized void setField(String fieldName, String fieldValue) throws DBException(Code) | | Set the given field to a given value. Call checkField
before setting the value to verify that it is allowed for this field
The subclass must override checkField as required
Parameters: fieldName - The name of the field Parameters: fieldValue - The value to set the field throws: DBException - If the given field does not exist in this object orthe value supplied is not allowed for this field |
setField | public void setField(String fieldName, java.util.Date fieldValue) throws DBException(Code) | | Date object Typesafe version of setField .
Convenience method to set the field values.
Parameters: fieldName - The name to set Parameters: fieldValue - the Java date value to set throws: DBException - upon error. |
setFieldData | protected synchronized void setFieldData(String fieldName, String fieldValue)(Code) | | Helper function that doesn't fire all the processing... just set's the
field data in raw form and forgets it.
Parameters: fieldName - The name of the field to set Parameters: fieldValue - the value to set it to. |
setFieldData | protected synchronized void setFieldData(String fieldName, byte[] fieldValue)(Code) | | Helper function that doesn't fire all the processing... just set's the
field data in raw form and forgets it.
Parameters: fieldName - The name of the field to set Parameters: fieldValue - the value to set it to. |
setFieldDistinct | public void setFieldDistinct(String fieldName, boolean flag) throws DBException(Code) | | Convenience method to set a field to be distinct or not
within this database object.
Parameters: fieldName - the name of the field Parameters: flag - boolean value true if the field is set distinct. throws: DBException - If the operation could not be completedauthor Peter Pilgrim See Also: DBObject.isFieldDistinct See Also: DBObject.isDistinct() |
setFieldsToRetrieve | public void setFieldsToRetrieve(String fieldNames) throws DBException(Code) | | Convenience method to set the fields to be retrieved
within this database object.
NOTE AS OF EXPRESSO 5.0 setFieldsToRetrieve() could cause you
some problems if you're attempting to retrieve long objects since
everything will be converted to a STRING. Please use caution :).
Parameters: fieldNames - contain the name of the fields separate by "|" throws: DBException - If the operation could not be completedauthor Yves Henri Amaizo See Also: DBObject.isFieldsToRetrieve() |
setFilterClass | public Filter setFilterClass(Filter filter)(Code) | | set the filter class that will be used for all string filtering
for this object instance ONLY.
Parameters: filter - which is subclass of Filter; we will persist only the class name, NOT the instance passed in old filter that was just replaced; can be null See Also: DBObject.setStringFilter(java.lang.String,java.lang.String) See Also: for a means to set "permanenent" filters in metadata for all objects of this class See Also: DBField.setFilterClass |
setKeys | public synchronized void setKeys(String keyValues) throws DBException(Code) | | Set the values for each of the key fields of this object from
a /-delimited string
Parameters: keyValues - The string containing one value for each keyfield in the object throws: DBException - If the key fields cannot be set |
setLocale | public void setLocale(Locale newLocale)(Code) | | Sets the locale to be used with this DBObject
Parameters: newLocale - The new Locale to use with this object since: Expresso 5.0.1 |
setLookupField | public synchronized void setLookupField(String fieldName, String lookupFieldName)(Code) | | Sets the lookup field name. This field allows automatic lookups to
be performed by matching the field name given with the primary key of the
lookup object. Note to use this feature, the lookup object can only
have one and only one primary key field at this time.
Parameters: fieldName - the name to set the lookup field value for. Parameters: lookupFieldName - the field name in the lookup object to map. |
setLookupObject | public synchronized void setLookupObject(String fieldName, String objectName) throws DBException(Code) | | Set a field's lookup object - this is the name of another database
object that can be used to look up valid values for this object. This value
is used by the DBMaint servlet to provide automatic lookup ability for
related fields. Side-effect: adds a listener for this object to cache manager
in order to maintain caches for valid values
Parameters: fieldName - The field name that this lookup is associated with Parameters: objectName - The db object used to look up valid values for this field. throws: DBException - upon error. |
setMask | protected synchronized void setMask(String fieldName, String newMask) throws DBException(Code) | | Set a "mask", or regular expresso to be matched, for the named field.
This regular expression is then checked whenever the field is validated
Note: Masks are used to validate a field's data type to prevent sql injections. So, when
setting your own mask, make sure it excludes thwarts sql injections.
Parameters: fieldName - The field name to set Parameters: newMask - the regular expression to apply to this field throws: DBException - upon error. |
setMaxRecords | public synchronized void setMaxRecords(int newMax) throws DBException(Code) | | Specify a maximum number of records to be retrieved in any subsequent
searchAndRetrieve() call. Records will be retrieved (in the specified
sort order) until the specified maximum is reached, then the remainder
of the result set is discarded. Specifying zero indicates that all
records are to be retrieved.
Parameters: newMax - The maximum number of records to retrieve. throws: DBException - If the max number is less than 0 |
setMultiValued | protected synchronized void setMultiValued(String fieldName) throws DBException(Code) | | Set this field to be multi-valued - e.g. there is a specific list of
values that are valid for this field. There should be code in the
getValidValues method that returns the valid values for the specified
multi-valued field.
Parameters: fieldName - The name of the field to specify as multi-valued throws: DBException - If the field name given is not valid, or is a virtual field |
setName | protected synchronized void setName(String theName) throws DBException(Code) | | Set the name of this object - this name is used to identify the db object
with a more human-readable description
Parameters: theName - New name for this object throws: DBException - upon error. |
setOffsetRecord | public synchronized void setOffsetRecord(int newOffset) throws DBException(Code) | | Specifies the number of records that should be skipped over
before any data from the ResultSet
is retrieved in any subsequent
searchAndRetrieve() call. Records will be skipped over (in the specified
sort order) until the record counts is equal to or greater
than the offset record. Specifying zero indicates that no
records should be skipped over and the
ResultSet immediately from the start.
Parameters: newOffset - The maximum number of records to retrieve. throws: DBException - If the max number is less than 0author Peter Pilgrim |
setReadOnly | public synchronized void setReadOnly(String fieldName) throws DBException(Code) | | Set a field as read-only - these fields are not offered for update
when a form is produced by the generic database maintenance servlet
(DBMaint). It does not otherwise affect the use of the field.
Typical uses are for serial-numbered fields and timestamps
Parameters: fieldName - The name of the field to be reserved as normally read-only. throws: DBException - If there is no such field. |
setSchema | public synchronized void setSchema(Schema schema) throws DBException(Code) | | Specify which schema this DB object belongs to. This is
necessary when using the local-langauge strings in the
DB object for field names, descriptions, etc. The schema
will be assumed to be Expresso's schema if not otherwise
set.
From expresso 5.3, this method is called in ConfigManager at startup. You probably do
not need to call it. (Previously, developers had to call it within each DBObject's setup().)
Parameters: schema - The schema to set throws: DBException - upon error. |
setSecret | public synchronized void setSecret(String fieldName) throws DBException(Code) | | Set a field as 'secret' - these fields are not shown
when a list is produced by the generic database maintenance servlet. In
this way, only users with update permission to the object can view the
values of "secret" fields.
Parameters: fieldName - The name of the field to set as 'secret' throws: DBException - I fthe field does not exist |
setSortKey | protected void setSortKey(String sortKeyString)(Code) | | Parses the sort key string into useful values. This version forces full
parsing of the input values to prevent SQL injection attacks.
Parameters: sortKeyString - the pipe delimited string of field names with the optional 'ASC or DESC' keyword afterwords; null indicates no sorting |
setStringFiltersOnAll | public void setStringFiltersOnAll(String filter) throws DBException(Code) | | set string filters to the given filter on ALL fields that are quoted text fields
Parameters: filter - filter to set throws: DBException - upon error |
setTargetDbSchema | public synchronized void setTargetDbSchema(String theDbSchema) throws DBException(Code) | | Set the target table for this DBObject. Note that an object
can span tables by the use of virtual fields, but that this table
is the default table for the object.
Parameters: theDbSchema - Table for this object throws: DBException - upon error. |
setTargetTable | public synchronized void setTargetTable(String theTable) throws DBException(Code) | | Set the target table for this DBObject. Note that an object
can span tables by the use of virtual fields, but that this table
is the default table for the object.
Parameters: theTable - Table for this object throws: DBException - upon error. |
setupFields | protected void setupFields() throws DBException(Code) | | Method to set up the fields for this database object. This method should
be defined in the implementing object and should make calls to addField,
addKey, setMultiValued, etc. as required to define the content of
the DBObject. Each setupFields method should call "super.setupFields()"
so that field definitions can be "inheritcable"
throws: DBException - If there is an error setting up the fieldsas requested. For example, if a field allowing null is requestedas part of the key |
sqlAggrFunction | protected synchronized double sqlAggrFunction(String func, String fieldName) throws DBException(Code) | | This allows the invocation of the SQL AVG, MIN, MAX and SUM
aggregate functions on one of the DB's columns (the DBObject
fieldname is supplied).
This function is not meant to be used directly, but is here
as the common/shared code used by the following methods in DBObject:
avg(String), min(String), max(String), sum(String).
Parameters: func - String The SQL aggregate function - must be one of AVG, MIN, MAX, SUM Parameters: fieldName - String The DBObject fieldName to use for the aggregate function double The result of the SQL function invocation throws: DBException - If the function could not be completedModify by Yves Henri AMAIZO |
sum | public double sum(String fieldName) throws DBException(Code) | | Find the sum of the values in the specified field of records
selected by the DBObject selection criteria.
Parameters: fieldName - String DBObject fieldName to average double Sum of the records matching the criteria throws: DBException - If the search could not be completed |
toDebugString | public String toDebugString()(Code) | | Generate a debuggable string for suitable printing out in an
interactive Java IDE. Write the string in PERL hash structure
style. Primary key field are denoted with (*) asterisks.
com.bar.foo.AcmePayroll@1234BABE{
id* => 7, fullname => Peter Pilgrim,
city => country => England }
This is a method is not the standard
toString() because some times a data object used
professionally can have dozens of data fields. We also dont
want to overwhelm you with useless information!
java.lang.String |
update | public void update() throws DBException(Code) | | Update the database with the new info. Update affects only one record,
and uses the current field values to write to the DBMS.
by default, updates all fields each time.
for efficiency, developers who are confident that their code does not have any
'blind updates' can set the Setup value UPDATE_CHANGED_ONLY to true
(a blind update is where the object is not retieved before values in it are reset)
throws: DBException - if the update to the database fails due toa database error See Also: DBObject.update(boolean) |
update | public void update(boolean updateChangedFieldsOnly) throws DBException(Code) | | Update the database with the new info. Update affects only one record,
and uses the current field values to write to the DBMS.
if param updateChangedFieldsOnly is true, only changed fields are updated.
this assumes that the entire object has been retrieved from DB prior
to resetting any field.
Parameters: updateChangedFieldsOnly - if true only modified fields (isChanged = true)will be included in the update throws: DBException - if the update to the database fails due toa database error |
updateAll | public synchronized void updateAll() throws DBException(Code) | | Update 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 |
updateAll | public void updateAll(boolean oneByOne) throws DBException(Code) | | Update the database with the new info. Update affects all records,
and uses the current field values to write to the DBMS.
Parameters: oneByOne - if true the records will be modifed one by one andwill be included in the cache throws: DBException - if the update to the database fails due toa database error |
verify | public void verify() throws DBException(Code) | | Verify that this object is working correctly
by selecting all records, running a validation on each of them. The
validation consists of verifying the referential integrity against all
objects defined as being referred to by this object in the checkAllRefs method
throws: DBException - If the validation fails |
|
|