Keel 2.1RC2

org.keel.services.persist
Interface Persistent

All Known Implementing Classes:
DefaultPersistent, HibernatePersistent

public interface Persistent

A persistent object. Your application classes should *not* normally directly implement this interface, but should instead request instances from the current PersistentFactory. Only implementation classes for the persistence service implement this interface directly. If you prefer to do "bean-like" objects as your persistent classes, see AbstractPersistent instead.


Field Summary
static int ADD
          Operation codes
static int CURRENT
          Status codes
static int DELETE
           
static int DELETED
           
static int MODIFIED
           
static int NEW
           
static int QUERY
           
static int UPDATE
           
 
Method Summary
 void add()
          Determine if a record with this key exists already - if not, add a new record.
 boolean allowed(int operation)
          Determine if the given operation is allowed for the current user, given one of the operation codes ADD, UPDATE, DELETE or QUERY
 void clear()
          Set all fields to empty value & clear the last result set
 int count()
          Just like find, but only retrieves the count, not the records themselves.
 void delete()
          Delete a record from the target table.
 void delete(boolean deleteDetails)
          Delete this record, optionally deleting any associated detail records.
 void deleteAll()
          Delete all of the records specified by the current search criteria.
 boolean find()
          A lot like retrieve, but works with any fields, not just the key field.
 java.lang.Object getAttribute(java.lang.String attribName)
          Get a general-purpose attribute where the scope is the whole persistent
 java.lang.Object getAttribute(java.lang.String fieldName, java.lang.String attribName)
          Get a general-purpose attribute for a specific field.
 java.util.Map getAttributes()
           
 java.lang.Object getBean()
          Convenience method that returns a JavaBean containing the data from the current persistent.
 java.util.List getDetails(java.lang.String detailName)
          The PersistentMetaData object associated with this Persistent can supply a list of the "detail" names associated with this Persistent.
 java.util.Map getErrors()
          Any database operation might in fact result in more than one error - validations, for example, or referential integrity problems.
 java.lang.Object getField(java.lang.String fieldName)
          Get the value of a field in this object
 boolean getFieldBoolean(java.lang.String fieldName)
          Boolean typesafe getField
 java.sql.Date getFieldDate(java.lang.String fieldName)
          Return the value of a field as a Date object
 int getFieldInt(java.lang.String fieldName)
          Get the integer value of a field in this object
 java.lang.String getFieldString(java.lang.String fieldName)
          Return the value of a field as a Strintg object
 Helper getHelper()
           
 PersistentMetaData getMetaData()
          Return the PersistentMetaData object which describes this Persistent.
 java.lang.String getName()
          Each persistent object has a name, assigned in the configuration file.
 int getStatus()
          Return one of the valid status codes indicating the current state of the Persistent object.
 java.util.Map getValidValues(java.lang.String fieldName)
          Return a Map of valid values and an associated description of each value for this field.
 void lock()
          Get exclusive read-write access to the underlying store for a persistent table
 double max(java.lang.String fieldName)
          Return the maximum value of the specified field
 double min(java.lang.String fieldName)
          Return the minimum value of the specified field
 java.util.List query()
          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)
 java.util.List query(java.lang.String sortKeyString)
          Search and retrieve in a particular order
 void retrieve()
          Get a single record from the database into this Persistent's fields Assumes that the key fields are set to the key of the object to be retrieved
 void setAttribute(java.lang.String attribName, java.lang.Object attribValue)
          Set a general-purpose short-lived attribute for this persistent.
 void setBean(java.lang.Object newBean)
          Set the persistent fields from the fields of a bean.
 void setBypassAuthorizationManager(AuthorizationManager bypassAm)
           
 void setField(java.lang.String fieldName, java.lang.Object fieldValue)
          Set the given field to the specified value.
 void setMaxRecords(int newMax)
          Specify the maximum number of records retrieved by the next query
 void setMetaData(PersistentMetaData newMeta)
          A Persistent is always configured from it's factory, never from the application directly
 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 query() call.
 void setTransaction(Transaction t)
           
 double sum(java.lang.String fieldName)
          Find the sum of the values in the specified field of records selected by the Persistent selection criteria.
 void unlock()
          Release the exclusive read-write access to the underlying store for the persistence table
 void update()
          Update the database with the new info.
 java.util.Map validateAll()
          Apply all field validations to all fields, returning a map where the key is the field name and the value is the error message for that field.
 java.lang.String validateField(java.lang.String fieldName, java.lang.Object fieldValue)
          Apply field validations to a single field, returning a validation message if there is a problem, or null if there's no problem
 

Field Detail

CURRENT

public static final int CURRENT
Status codes

See Also:
Constant Field Values

MODIFIED

public static final int MODIFIED
See Also:
Constant Field Values

DELETED

public static final int DELETED
See Also:
Constant Field Values

NEW

public static final int NEW
See Also:
Constant Field Values

ADD

public static final int ADD
Operation codes

See Also:
Constant Field Values

UPDATE

public static final int UPDATE
See Also:
Constant Field Values

DELETE

public static final int DELETE
See Also:
Constant Field Values

QUERY

public static final int QUERY
See Also:
Constant Field Values
Method Detail

getStatus

public int getStatus()
Return one of the valid status codes indicating the current state of the Persistent object. The valid codes are CURRENT, MODIFIED, DELETED and NEW TODO: More details


allowed

public boolean allowed(int operation)
                throws PersistenceException
Determine if the given operation is allowed for the current user, given one of the operation codes ADD, UPDATE, DELETE or QUERY

Returns:
True if the operation is permitted, false otherwise
Throws:
PersistenceException

add

public void add()
         throws PersistenceException
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:
PersistenceException

clear

public void clear()
           throws PersistenceException
Set all fields to empty value & clear the last result set

Throws:
PersistenceException - If the fields cannot be cleared

delete

public void delete()
            throws PersistenceException
Delete a 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:
PersistenceException - If the delete fails or if the referential integrity would be violated by the delete

delete

public void delete(boolean deleteDetails)
            throws PersistenceException
Delete this record, optionally deleting any associated detail records. WARNING: Deleting details is *recursive* - e.g. any details of those details will also be deleted. Use with caution on extremely large data sets - might be a better idea to use deleteAll on each appropriate table, which is non-recursive and uses a single SQL statement to delete groups of records.

Parameters:
deleteDetails - Delete associated detail records if true
Throws:
PersistenceException - If the delete fails or if the referential integrity would be violated by the delete

deleteAll

public void deleteAll()
               throws PersistenceException
Delete all of the records specified by the current search criteria. IMPORTANT: deleteAll does *not* check for details, nor does it offer the option of deleting associated detail records. In order to do this, retrieve each record with query and use delete(true), not deleteAll(). deleteAll() is more efficient for deleting a large number of records from a single table.

Throws:
PersistenceException - If the delete fails or if the referential integrity would be violated by the delete

find

public boolean find()
             throws PersistenceException
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 first (or only) record found after the call to find() if the find is successful.

Returns:
boolean If the search resulted in a record
Throws:
PersistenceException - If the search could not be completed

retrieve

public void retrieve()
              throws PersistenceException
Get a single record from the database into this Persistent's fields Assumes that the key fields are set to the key of the object to be retrieved

Throws:
PersistenceException - If the record could not be retrieved, or if the key fields were not set. If you are not sure if the record exists, use find() instead.
See Also:
find()

query

public java.util.List query()
                     throws PersistenceException
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)

Returns:
A List of new database objects containing the results of the search
Throws:
PersistenceException - If the search could not be completed

query

public java.util.List query(java.lang.String sortKeyString)
                     throws PersistenceException
Search and retrieve in a particular order

Parameters:
sortKeyString - A comma-delimited list of key fields to sort the returned set by
Returns:
A List of new database objects retrieved by the search
Throws:
PersistenceException - If the search could not be completed

setField

public void setField(java.lang.String fieldName,
                     java.lang.Object fieldValue)
              throws PersistenceException
Set the given field to the specified value. Note that no validation is done at this point, other than possible type conversion if required. Use validateField or validateAll to apply appropriate validations and record the errors, if any. Note that field names in the Persistent object may or may not be the same as the database field in which the Persistent is stored. This is determined by the configuration file.

Throws:
PersistenceException

getField

public java.lang.Object getField(java.lang.String fieldName)
                          throws PersistenceException
Get the value of a field in this object

Returns:
The value of the given field as a string - if the field is null, an empty string is returned.
Throws:
PersistenceException - If there is no such field or it's value cannot be accessed

getFieldInt

public int getFieldInt(java.lang.String fieldName)
                throws PersistenceException
Get the integer value of a field in this object

Parameters:
fieldName - Name of a field in this object
Returns:
int The value of the field as a float
Throws:
PersistenceException - if there is no such field or it's value cannot be converted to an integer.

getFieldDate

public java.sql.Date getFieldDate(java.lang.String fieldName)
                           throws PersistenceException
Return the value of a field as a Date object

Parameters:
fieldName - The field to be retrieved
Returns:
The java.sql.Date object equivilant to this field's value
Throws:
PersistenceException - If the field does not exist or it's value is not a date or cannot be converted to a date

getFieldBoolean

public boolean getFieldBoolean(java.lang.String fieldName)
                        throws PersistenceException
Boolean typesafe getField

Parameters:
fieldName - The field to be retrieved
Returns:
The boolean equivilant to this field's value
Throws:
PersistenceException - If the field does not exist or it's value is not a date or cannot be converted to a date

getFieldString

public java.lang.String getFieldString(java.lang.String fieldName)
                                throws PersistenceException
Return the value of a field as a Strintg object

Parameters:
fieldName - The field to be retrieved
Returns:
The String object equivilant to this field's value
Throws:
PersistenceException - If the field does not exist or it's value is not a date or cannot be converted to a date

update

public void update()
            throws PersistenceException
Update the database with the new info. Update affects only one record, and uses the current field values to write to the DBMS. Referential integrity is verified before the update is performed.

Throws:
PersistenceException - if the update to the database fails due to a database error

setTransaction

public void setTransaction(Transaction t)
                    throws PersistenceException
Throws:
PersistenceException

getHelper

public Helper getHelper()
                 throws PersistenceException
Throws:
PersistenceException

validateField

public java.lang.String validateField(java.lang.String fieldName,
                                      java.lang.Object fieldValue)
Apply field validations to a single field, returning a validation message if there is a problem, or null if there's no problem


validateAll

public java.util.Map validateAll()
Apply all field validations to all fields, returning a map where the key is the field name and the value is the error message for that field. If a field is not listed, there was no problem with it's validation


setMetaData

public void setMetaData(PersistentMetaData newMeta)
                 throws PersistenceException
A Persistent is always configured from it's factory, never from the application directly

Throws:
PersistenceException

getMetaData

public PersistentMetaData getMetaData()
                               throws PersistenceException
Return the PersistentMetaData object which describes this Persistent. This object contains all information about fieldnames, types, etc.

Throws:
PersistenceException

getName

public java.lang.String getName()
Each persistent object has a name, assigned in the configuration file. This name may or may not bear any relationship to the table name in which the Persistent is stored.


getErrors

public java.util.Map getErrors()
Any database operation might in fact result in more than one error - validations, for example, or referential integrity problems. This method allows the caller to retrieve all of the errors from the most recent operation. For example, if you call "add()" and it throws an exception, there may in fact have been more than one problem preventing the add from happening, e.g. multiple validation errors. An empty map is returned when the last operation was successful.


getValidValues

public java.util.Map getValidValues(java.lang.String fieldName)
                             throws PersistenceException
Return a Map of valid values and an associated description of each value for this field.

Throws:
PersistenceException - If there is no such field

count

public int count()
          throws PersistenceException
Just like find, but only retrieves the count, not the records themselves.

Returns:
integer Count of the records matching the criteria
Throws:
PersistenceException - If the search could not be completed
See Also:
find()

setAttribute

public void setAttribute(java.lang.String attribName,
                         java.lang.Object attribValue)
Set a general-purpose short-lived attribute for this persistent. The attribute is not (necessarily) stored in the database.


getAttribute

public java.lang.Object getAttribute(java.lang.String attribName)
Get a general-purpose attribute where the scope is the whole persistent


getAttributes

public java.util.Map getAttributes()

getAttribute

public java.lang.Object getAttribute(java.lang.String fieldName,
                                     java.lang.String attribName)
                              throws PersistenceException
Get a general-purpose attribute for a specific field.

Throws:
PersistenceException - If there is no such field

setMaxRecords

public void setMaxRecords(int newMax)
Specify the maximum number of records retrieved by the next query


setOffsetRecord

public 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 query() 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.

Throws:
PersistenceException - If the max number is less than 0

lock

public void lock()
          throws PersistenceException
Get exclusive read-write access to the underlying store for a persistent table

Throws:
PersistenceException

unlock

public void unlock()
            throws PersistenceException
Release the exclusive read-write access to the underlying store for the persistence table

Throws:
PersistenceException

max

public double max(java.lang.String fieldName)
           throws PersistenceException
Return the maximum value of the specified field

Throws:
PersistenceException

min

public double min(java.lang.String fieldName)
           throws PersistenceException
Return the minimum value of the specified field

Throws:
PersistenceException

sum

public double sum(java.lang.String fieldName)
           throws PersistenceException
Find the sum of the values in the specified field of records selected by the Persistent selection criteria.

Returns:
double Sum of the records matching the criteria
Throws:
PersistenceException - If the search could not be completed

getDetails

public java.util.List getDetails(java.lang.String detailName)
                          throws PersistenceException
The PersistentMetaData object associated with this Persistent can supply a list of the "detail" names associated with this Persistent. Each of these names refers to another Persistent which has a detail relationship to this Persistent. For each such name, this method can be used to retrieve the set of related Persistents from the detail object.

Parameters:
detailName - The name of the detail relationship, as provided by the meta-data
Returns:
List A list of Persistents related to this one via the specified relationship
Throws:
PersistenceException - If a problem occurs retrieving the details or if there is no such relationship

getBean

public java.lang.Object getBean()
                         throws PersistenceException
Convenience method that returns a JavaBean containing the data from the current persistent. The bean class is specified in configuration, and associated with the persistent name. If there is no classname specified, a DynaBean will be returned instead.

Returns:
An object (a JavaBean) populated with the data from the current persistent
Throws:
PersistenceException - If there is a problem instantiating or populating the bean.

setBean

public void setBean(java.lang.Object newBean)
             throws PersistenceException
Set the persistent fields from the fields of a bean.

Parameters:
newBean - A JavaBean with the data to populate the current persistent from.
Throws:
PersistenceException

setBypassAuthorizationManager

public void setBypassAuthorizationManager(AuthorizationManager bypassAm)
                                   throws PersistenceException
Throws:
PersistenceException

Keel 2.1RC2

Please see keelframework.org for information about new Keel releases.