org.javalite.activejdbc
Class Model

java.lang.Object
  org.javalite.activejdbc.Model

All Implemented Interfaces:

Externalizable, Serializable

public abstract class Model
extends Object
implements Externalizable

This class is a super class of all "models" and provides most functionality necessary for implementation of Active Record pattern.

Author:

Igor Polevoy, Eric Nielsen

See Also:

Serialized Form

Constructor Summary

protected

Model()

Method Summary

void	add(Model child) Adds a new child dependency.
static void	addCallbacks(CallbackListener... listeners) Deprecated. use callbackWith(CallbackListener...) instead
void	addError(String key, String value) Adds a new error to the collection of errors.
static ValidationBuilder	addValidator(Validator validator) Adds a validator to the model.
void	addValidator(Validator validator, String errorKey) Binds a validator to an attribute if validation fails.
protected void	afterCreate()
protected void	afterDelete()
protected void	afterLoad()
protected void	afterSave()
protected void	afterUpdate()
protected void	afterValidation()
static List<Association>	associations() Returns all associations of this model.
static Set<String>	attributeNames() Returns names of all attributes from this model.
static List<String>	attributes() Deprecated. use attributeNames() instead
void	beforeClosingBrace(boolean pretty, String indent, StringWriter writer) Deprecated. use beforeClosingBrace(StringBuilder, boolean, String, String...) instead
void	beforeClosingBrace(StringBuilder sb, boolean pretty, String indent, String... attributeNames) Override in subclasses in order to inject custom content into Json just before the closing brace.
void	beforeClosingTag(int spaces, StringWriter writer, String... attributeNames) Deprecated. use beforeClosingTag(StringBuilder, boolean, String, String...) instead
void	beforeClosingTag(StringBuilder sb, boolean pretty, String indent, String... attributeNames) Override in a subclass to inject custom content onto XML just before the closing tag.
protected void	beforeCreate()
protected void	beforeDelete()
protected void	beforeSave()
protected void	beforeUpdate()
protected void	beforeValidation()
static boolean	belongsTo(Class<? extends Model> targetClass)
protected static void	blankToNull(String... attributeNames) Registers BlankToNullConverter for specified attributes.
static void	callbackWith(CallbackListener... listeners)
protected static ValidationBuilder	convertDate(String attributeName, String format) Deprecated. use {@link #dateFormat(String, String...) instead
protected static ValidationBuilder	convertTimestamp(String attributeName, String format) Deprecated. use {@link #timestampFormat(String, String...) instead
protected static ValidationBuilder	convertWith(Converter converter) Deprecated. use convertWith(org.javalite.activejdbc.conversion.Converter, String...) instead
protected static void	convertWith(Converter converter, String... attributeNames) Registers a custom converter for the specified attributes.
void	copyFrom(Model other) Copies all attribute values (except for ID, created_at and updated_at) from other instance to this one.
void	copyTo(Model other) Copies all attribute values (except for ID, created_at and updated_at) from this instance to the other.
static Long	count() Returns total count of records in table.
static Long	count(String query, Object... params) Returns count of records in table under a condition.
static <T extends Model> T	create(Object... namesAndValues) This is a convenience method to create a model instance already initialized with values.
static <T extends Model> T	createIt(Object... namesAndValues) This is a convenience method to create(Object...).
protected static void	dateFormat(DateFormat format, String... attributeNames) Registers date format for specified attributes.
protected static void	dateFormat(String pattern, String... attributeNames) Registers date format for specified attributes.
void	defrost() Synonym for thaw().
boolean	delete() Deletes a single table record represented by this instance.
void	delete(boolean cascade) Convenience method, will call delete() or deleteCascade().
static int	delete(String query, Object... params) Deletes some records from associated table.
static int	deleteAll() Deletes all records from associated table.
void	deleteCascade() Deletes this record from associated table, as well as children.
void	deleteCascadeExcept(Association... excludedAssociations) This method does everything deleteCascade() does, but in addition allows to exclude some associations from this action.
void	deleteCascadeShallow() Deletes this record from associated table, as well as its immediate children.
protected Set<String>	dirtyAttributeNames()
Errors	errors() Provides an instance of Errors object, filled with error messages after validation.
Errors	errors(Locale locale) Provides an instance of localized Errors object, filled with error messages after validation.
boolean	exists() Returns true if record corresponding to the id of this instance exists in the DB.
static boolean	exists(Object id) Returns true if record corresponding to the id passed exists in the DB.
static void	find(String query, ModelListener listener) Deprecated. use findWith(ModelListener, String, Object...).
static <T extends Model> LazyList<T>	find(String subquery, Object... params) Synonym of where(String, Object...)
static <T extends Model> LazyList<T>	findAll() This method returns all records from this table.
static <T extends Model> T	findByCompositeKeys(Object... values) Composite PK values in exactly the same order as specified in CompositePK.
static <T extends Model> T	findById(Object id)
static <T extends Model> LazyList<T>	findBySQL(String fullQuery, Object... params) Free form query finder.
static <T extends Model> T	findFirst(String subQuery, Object... params) Synonym of first(String, Object...).
static void	findWith(ModelListener listener, String query, Object... params) This method is for processing really large result sets.
static <T extends Model> T	first(String subQuery, Object... params) Returns a first result for this condition.
<T extends Model> T	fromMap(Map input) Overrides attribute values from input map.
void	fromXml(String xml) Parses XML into a model.
boolean	frozen() Synonym for isFrozen().
<C extends Model> LazyList<C>	get(Class<C> clazz, String query, Object... params) Provides a list of child models in one to many, many to many and polymorphic associations, but in addition also allows to filter this list by criteria.
Object	get(String attributeName) Returns a value for attribute.
<C extends Model> LazyList<C>	getAll(Class<C> clazz) This methods supports one to many, many to many relationships as well as polymorphic associations.
protected Map<String,Object>	getAttributes()
BigDecimal	getBigDecimal(String attributeName) Gets attribute value as java.math.BigDecimal.
Boolean	getBoolean(String attributeName) Gets attribute value as Boolean.
byte[]	getBytes(String attributeName) Gets a value as bytes.
String[]	getCompositeKeys() Provides a list of composite keys as specified in CompositePK.
Date	getDate(String attributeName) Gets attribute value as java.sql.Date.
Double	getDouble(String attributeName) Gets attribute value as Double.
Float	getFloat(String attributeName) Gets attribute value as Float.
Object	getId() Value of ID.
String	getIdName() Name of ID column.
Integer	getInteger(String attributeName) Gets attribute value as Integer.
Long	getLong(String attributeName) Gets attribute value as Long.
Long	getLongId() Convenience method: converts ID value to Long and returns it.
static MetaModel	getMetaModel()
protected MetaModel	getMetaModelLocal() This method should be called from all instance methods for performance.
Short	getShort(String attributeName) Gets attribute value as Short.
String	getString(String attributeName) Gets attribute value as String.
static String	getTableName() Returns name of corresponding table.
Time	getTime(String attributeName) Gets attribute value as java.sql.Time.
Timestamp	getTimestamp(String attributeName) Gets attribute value as java.sql.Timestamp.
static List<Validator>	getValidators(Class<? extends Model> clazz)
boolean	hasErrors()
protected void	hydrate(Map<String,Object> attributesMap, boolean fireAfterLoad) Hydrates a this instance of model from a map.
boolean	insert() This method will save a model as new.
boolean	isFrozen() Will return true if this instance is frozen, false otherwise.
boolean	isModified() Will return true if any attribute of this instance was changed after latest load/save.
boolean	isNew() returns true if this is a new instance, not saved yet to DB, false otherwise.
boolean	isValid() This method performs validations and then returns true if no errors were generated, otherwise returns false.
void	manageTime(boolean manage) Turns off automatic management of time-related attributes created_at and updated_at.
boolean	modified() Synonym for isModified().
<P extends Model> P	parent(Class<P> parentClass) Returns parent of this model, assuming that this table represents a child.
<P extends Model> P	parent(Class<P> parentClass, boolean cache)
static void	purgeCache() Use to force-purge cache associated with this table.
void	readExternal(ObjectInput in)
void	refresh() Re-reads all attribute values from DB.
int	remove(Model child) Removes associated child from this instance.
static void	removeValidator(Validator validator)
void	reset() Resets all data in this model, including the ID.
boolean	save() This method will save data from this instance to a corresponding table in the DB.
boolean	saveIt() This method will not exit silently like save(), it instead will throw ValidationException if validations did not pass.
<T extends Model> T	set(Object... namesAndValues) This is a convenience method to set multiple values to a model.
void	set(String[] attributeNames, Object[] values) Sets values for this model instance.
<T extends Model> T	set(String attributeName, Object value) Sets a value of an attribute.
<T extends Model> T	setBigDecimal(String attributeName, Object value) Sets attribute value as java.math.BigDecimal.
<T extends Model> T	setBoolean(String attributeName, Object value) Sets attribute value as Boolean.
protected void	setCachedParent(Model parent)
protected void	setChildren(Class childClass, List<Model> children)
<T extends Model> T	setDate(String attributeName, Object value) Sets attribute value as java.sql.Date.
<T extends Model> T	setDouble(String attributeName, Object value) Sets attribute value as Double.
<T extends Model> T	setFloat(String attributeName, Object value) Sets attribute value as Float.
<T extends Model> T	setId(Object id) Convenience method, sets ID value on this model, equivalent to set(getIdName(), id).
<T extends Model> T	setInteger(String attributeName, Object value) Sets attribute value as Integer.
<T extends Model> T	setLong(String attributeName, Object value) Sets attribute value as Long.
protected void	setMetamodelLocal(MetaModel metamodelLocal)
void	setParent(Model parent) Sets a parent on this instance.
void	setParents(Model... parents) Sets multiple parents on this instance.
<T extends Model> T	setShort(String attributeName, Object value) Sets attribute value as Short.
<T extends Model> T	setString(String attributeName, Object value) Sets attribute value as String.
<T extends Model> T	setTime(String attributeName, Object value) Sets attribute value as java.sql.Time.
<T extends Model> T	setTimestamp(String attributeName, Object value) Sets attribute value as java.sql.Timestamp.
void	setTS(String name, Date date) Deprecated. use setTimestamp(String, Object) instead.
void	thaw() Unfreezes this model.
protected static void	timestampFormat(DateFormat format, String... attributeNames) Registers date format for specified attributes.
protected static void	timestampFormat(String pattern, String... attributeNames) Registers date format for specified attributes.
String	toInsert() Generates INSERT SQL based on this model.
String	toInsert(Dialect dialect) Generates INSERT SQL based on this model with the provided dialect.
String	toInsert(Formatter... formatters) Deprecated. Use toInsert(Dialect) instead.
String	toInsert(String leftStringQuote, String rightStringQuote) Deprecated. Use toInsert(Dialect) instead.
String	toJson(boolean pretty, String... attributeNames) Generates a JSON document from content of this model.
protected void	toJsonP(StringBuilder sb, boolean pretty, String indent, String... attributeNames)
Map<String,Object>	toMap() Returns all values of the model with all attribute names converted to lower case, regardless how these names came from DB.
String	toString()
String	toUpdate() Generates UPDATE SQL based on this model.
String	toUpdate(Dialect dialect) Generates UPDATE SQL based on this model with the provided dialect.
String	toXml(boolean pretty, boolean declaration, String... attributeNames) Generates a XML document from content of this model.
String	toXml(int spaces, boolean declaration, String... attributeNames) Deprecated. use toXml(boolean, boolean, String...) instead
protected void	toXmlP(StringBuilder sb, boolean pretty, String indent, String... attributeNames)
static int	update(String updates, String conditions, Object... params) Updates records associated with this model.
static int	updateAll(String updates, Object... params) Updates all records associated with this model.
void	validate() Executes all validators attached to this model.
protected static ValidationBuilder	validateEmailOf(String attributeName) Validates email format.
protected static NumericValidationBuilder	validateNumericalityOf(String... attributeNames)
protected static ValidationBuilder	validatePresenceOf(String... attributeNames) The validation will not pass if the value is either an empty string "", or null.
protected static ValidationBuilder	validateRange(String attributeName, Number min, Number max) Validates range.
protected static ValidationBuilder	validateRegexpOf(String attributeName, String pattern) Validates an attribite format with a ree hand regular expression.
protected static ValidationBuilder	validateWith(Validator validator) Add a custom validator to the model.
static <T extends Model> LazyList<T>	where(String subquery, Object... params) Finder method for DB queries based on table represented by this model.
void	writeExternal(ObjectOutput out)
protected static void	zeroToNull(String... attributeNames) Registers ZeroToNullConverter for specified attributes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Model

protected Model()

Method Detail

getMetaModel

public static MetaModel getMetaModel()

getAttributes

protected Map<String,Object> getAttributes()

dirtyAttributeNames

protected Set<String> dirtyAttributeNames()

fromMap

public <T extends Model> T fromMap(Map input)

Overrides attribute values from input map. The input map may have attributes whose name do not match the attribute names (columns) of this model. Such attributes will be ignored. Those values whose names are not present in the argument map, will stay untouched. The input map may have only partial list of attributes.

Parameters:

input - map with attributes to overwrite this models'. Keys are names of attributes of this model, values are new values for it.

hydrate

protected void hydrate(Map<String,Object> attributesMap,
                       boolean fireAfterLoad)

Hydrates a this instance of model from a map. Only picks values from a map that match this instance's attribute names, while ignoring the others.

Parameters:

attributesMap - map containing values for this instance.

setId

public <T extends Model> T setId(Object id)

Convenience method, sets ID value on this model, equivalent to set(getIdName(), id).

Parameters:

id - value of ID

Returns:

reference to self for chaining.

setDate

public <T extends Model> T setDate(String attributeName,
                                   Object value)

Sets attribute value as java.sql.Date. If there is a Converter registered for the attribute that converts from Class S to Class java.sql.Date, given the value is an instance of S, then it will be used, otherwise performs a conversion using Convert.toSqlDate(Object).

Parameters:

attributeName - name of attribute.

value - value to convert.

Returns:

reference to this model.

getDate

public Date getDate(String attributeName)

Gets attribute value as java.sql.Date. If there is a Converter registered for the attribute that converts from Class S to Class java.sql.Date, given the attribute value is an instance of S, then it will be used, otherwise performs a conversion using Convert.toSqlDate(Object).

Parameters:

attributeName - name of attribute to convert

Returns:

value converted to java.sql.Date

setTS

@Deprecated
public void setTS(String name,
                             Date date)

Deprecated. use setTimestamp(String, Object) instead.

Performs a primitive conversion of java.util.Date to java.sql.Timestamp based on the time value.

Parameters:

name - name of field.

date - date value.

set

public void set(String[] attributeNames,
                Object[] values)

Sets values for this model instance. The sequence of values must correspond to sequence of names.

Parameters:

attributeNames - names of attributes.

values - values for this instance.

set

public <T extends Model> T set(String attributeName,
                               Object value)

Sets a value of an attribute. If there is a Converter registered for the attribute that converts from Class S to Class java.lang.Object, given the value is an instance of S, then it will be used and the converted value will be set.

Parameters:

attributeName - name of attribute to set. Names not related to this model will be rejected (those not matching table columns).

value - value of attribute. Feel free to set any type, as long as it can be accepted by your driver.

Returns:

reference to self, so you can string these methods one after another.

isModified

public boolean isModified()

Will return true if any attribute of this instance was changed after latest load/save. (Instance state differs from state in DB)

Returns:

true if this instance was modified.

isFrozen

public boolean isFrozen()

Will return true if this instance is frozen, false otherwise. A frozen instance cannot use used, as it has no relation to a record in table.

Returns:

true if this instance is frozen, false otherwise.

modified

public boolean modified()

Synonym for isModified().

Returns:

true if this instance was modified.

attributes

@Deprecated
public static List<String> attributes()

Deprecated. use attributeNames() instead

Returns names of all attributes from this model.

Returns:

names of all attributes from this model.

attributeNames

public static Set<String> attributeNames()

Returns names of all attributes from this model.

Returns:

names of all attributes from this model.

associations

public static List<Association> associations()

Returns all associations of this model.

Returns:

all associations of this model.

isNew

public boolean isNew()

returns true if this is a new instance, not saved yet to DB, false otherwise.

Returns:

true if this is a new instance, not saved yet to DB, false otherwise

frozen

public boolean frozen()

Synonym for isFrozen(). if(m.frozen()) seems to read better than classical Java convention.

Returns:

true if this instance is frozen, false otherwise.

delete

public boolean delete()

Deletes a single table record represented by this instance. This method assumes that a corresponding table has only one record whose PK is the ID of this instance. After deletion, this instance becomes frozen() and cannot be used anymore until thaw() is called.

Returns:

true if a record was deleted, false if not.

delete

public void delete(boolean cascade)

Convenience method, will call delete() or deleteCascade().

Parameters:

cascade - true to call deleteCascade(), false to call delete().

deleteCascade

public void deleteCascade()

Deletes this record from associated table, as well as children. Deletes current model and all of its child and many to many associations. This is not a high performance method, as it will load every row into a model instance before deleting, effectively calling (N + 1) per table queries to the DB, one to select all the associated records (per table), and one delete statement per record. Use it for small data sets.

In cases of simple one to many and polymorphic associations, things are as expected, a parent is deleted an all children are deleted as well, but in more complicated cases, this method will walk entire three of associated tables, sometimes coming back to the same one where it all started. It will follow associations of children and their associations too; consider this a true cascade delete with all implications (circular dependencies, referential integrity constraints, potential performance bottlenecks, etc.)

Imagine a situation where you have DOCTORS and PATIENTS in many to many relationship (with DOCTORS_PATIENTS table as a join table), and in addition PATIENTS and PRESCRIPTIONS in one to many relationship, where a patient might have many prescriptions:

     DOCTORS
        +----+------------+-----------+-----------------+
        | id | first_name | last_name | discipline      |
        +----+------------+-----------+-----------------+
        |  1 | John       | Kentor    | otolaryngology  |
        |  2 | Hellen     | Hunt      | dentistry       |
        |  3 | John       | Druker    | oncology        |
        +----+------------+-----------+-----------------+

     PATIENTS
        +----+------------+-----------+
        | id | first_name | last_name |
        +----+------------+-----------+
        |  1 | Jim        | Cary      |
        |  2 | John       | Carpenter |
        |  3 | John       | Doe       |
        +----+------------+-----------+

     DOCTORS_PATIENTS
        +----+-----------+------------+
        | id | doctor_id | patient_id |
        +----+-----------+------------+
        |  1 |         1 |          2 |
        |  2 |         1 |          1 |
        |  3 |         2 |          1 |
        |  4 |         3 |          3 |
        +----+-----------+------------+

     PRESCRIPTIONS
        +----+------------------------+------------+
        | id | name                   | patient_id |
        +----+------------------------+------------+
        |  1 | Viagra                 |          1 |
        |  2 | Prozac                 |          1 |
        |  3 | Valium                 |          2 |
        |  4 | Marijuana (medicinal)  |          2 |
        |  5 | CML treatment          |          3 |
        +----+------------------------+------------+
 

Lets start with a simple example, Doctor John Druker. This doctor has one patient John Doe, and the patient has one prescription. So, when an instance of this doctor model is issued statement:

     drDruker.deleteCascade();
 

, the result is as expected: the DOCTORS:ID=3 is deleted, DOCTORS_PATIENTS:ID=4 is deleted, PATIENTS:ID=3 is deleted and PRESCRIPTIONS:ID=5 is deleted.

However, when doctor Kentor(#1) is deleted, the following records are also deleted:

• DOCTORS_PATIENTS:ID=1, 2 - these are links to patients
• PATIENTS:ID=1,2 these are patients themselves
• PRESCRIPTIONS:ID=1,2,3,4 - these are prescriptions of patients 1 and 2

But, in addition, since this is a many to many relationship, deleting patients 1 and 2 results in also deleting doctor Hellen Hunt(#2), since she is a doctor of patient Jim Cary(#1), deleting all corresponding join links from table DOCTORS_PATIENTS. So, deleting doctor Kentor, deleted most all records from related tables, leaving only these records in place:

• DOCTORS:ID=3
• DOCTORS_PATIENTS:ID=4
• PATIENTS:ID=3
• PRESCRIPTIONS:ID=5

Had doctor Hellen Hunt(#2) had more patients, it would delete them too, and so on. This goes a long way to say that it could be easy to be tangled up in web of associations, so be careful out there.

After deletion, this instance becomes frozen() and cannot be used anymore until thaw() is called.

deleteCascadeExcept

public void deleteCascadeExcept(Association... excludedAssociations)

This method does everything deleteCascade() does, but in addition allows to exclude some associations from this action. This is necessary because deleteCascade() method can be far too eager to delete records in a database, and this is a good way to tell the model to exclude some associations from deletes.

Example:

Patient.findById(3).deleteCascadeExcept(Patient.getMetaModel().getAssociationForTarget("prescriptions"));

Parameters:

excludedAssociations - associations

See Also:

#deleteCascade()} - see for more information.

deleteCascadeShallow

public void deleteCascadeShallow()

Deletes this record from associated table, as well as its immediate children. This is a high performance method because it does not walk through a chain of child dependencies like deleteCascade() does, but rather issues one DELETE statement per child dependency table. Also, its semantics are a bit different between than deleteCascade(). It only deletes current record and immediate children, but not their children (no grand kinds are dead as a result :)).

One to many and polymorphic associations

The current record is deleted, as well as immediate children.

Many to many associations

The current record is deleted, as well as links in a join table. Nothing else is deleted.

After deletion, this instance becomes frozen() and cannot be used anymore until thaw() is called.

delete

public static int delete(String query,
                         Object... params)

Deletes some records from associated table. This method does not follow any associations. If this model has one to many associations, you might end up with either orphan records in child tables, or run into integrity constraint violations. However, this method if very efficient as it deletes all records in one shot, without pre-loading them. This method also has a side-effect: it will not mark loaded instances corresponding to deleted records as "frozen". This means that such an instance would allow calling save() and saveIt() methods resulting DB errors, as you would be attempting to update phantom records.

Parameters:

query - narrows which records to delete. Example:

"last_name like '%sen%'"

.

params - (optional) - list of parameters if a query is parametrized.

Returns:

number of deleted records.

exists

public static boolean exists(Object id)

Returns true if record corresponding to the id passed exists in the DB.

Parameters:

id - id in question.

Returns:

true if corresponding record exists in DB, false if it does not.

exists

public boolean exists()

Returns true if record corresponding to the id of this instance exists in the DB.

Returns:

true if corresponding record exists in DB, false if it does not.

deleteAll

public static int deleteAll()

Deletes all records from associated table. This methods does not take associations into account.

Returns:

number of records deleted.

update

public static int update(String updates,
                         String conditions,
                         Object... params)

Updates records associated with this model. This example :

  Employee.update("bonus = ?", "years_at_company > ?", "5", "10");
 

Parameters:

updates - - what needs to be updated.

conditions - specifies which records to update. If this argument is null, all records in table will be updated. In such cases, use a more explicit updateAll(String, Object...) method.

params - list of parameters for both updates and conditions. Applied in the same order as in the arguments, updates first, then conditions.

Returns:

number of updated records.

updateAll

public static int updateAll(String updates,
                            Object... params)

Updates all records associated with this model. This example :

  Employee.updateAll("bonus = ?", "10");
 

In this example, all employees get a bonus of 10%.

Parameters:

updates - - what needs to be updated.

params - list of parameters for both updates and conditions. Applied in the same order as in the arguments, updates first, then conditions.

Returns:

number of updated records.

toMap

public Map<String,Object> toMap()

Returns all values of the model with all attribute names converted to lower case, regardless how these names came from DB. This method is a convenience method for displaying values on web pages.

If LazyList.include(Class[]) method was used, and this model belongs to a parent (as in many to one relationship), then the parent will be eagerly loaded and also converted to a map. Parents' maps are keyed in the returned map by underscored name of a parent model class name.

For example, if this model were Address and a parent is User (and user has many addresses), then the resulting map would have all the attributes of the current table and another map representing a parent user with a key "user" in current map.

Returns:

all values of the model with all attribute names converted to lower case.

toString

public String toString()

Overrides:

toString in class Object

fromXml

public void fromXml(String xml)

Parses XML into a model. It expects the same structure of XML as the method toXml(int, boolean, String...). It ignores children and dependencies (for now) if any. This method will parse the model attributes from the XML document, and will then call fromMap(java.util.Map) method. It does not save data into a database, just sets the attributes.

Parameters:

xml - xml to read model attributes from.

toXml

public String toXml(boolean pretty,
                    boolean declaration,
                    String... attributeNames)

Generates a XML document from content of this model.

Parameters:

pretty - pretty format (human readable), or one line text.

declaration - true to include XML declaration at the top

attributeNames - list of attributes to include. No arguments == include all attributes.

Returns:

generated XML.

toXmlP

protected void toXmlP(StringBuilder sb,
                      boolean pretty,
                      String indent,
                      String... attributeNames)

toXml

@Deprecated
public String toXml(int spaces,
                               boolean declaration,
                               String... attributeNames)

Deprecated. use toXml(boolean, boolean, String...) instead

Generates a XML document from content of this model.

Parameters:

spaces - by how many spaces to indent.

declaration - true to include XML declaration at the top

attributeNames - list of attributes to include. No arguments == include all attributes.

Returns:

generated XML.

beforeClosingTag

public void beforeClosingTag(StringBuilder sb,
                             boolean pretty,
                             String indent,
                             String... attributeNames)

Override in a subclass to inject custom content onto XML just before the closing tag.

To keep the formatting, it is recommended to implement this method as the example below.

 if (pretty) { sb.append(ident); }
 sb.append("<test>...</test>");
 if (pretty) { sb.append('\n'); }
 

Parameters:

sb - to write content to.

pretty - pretty format (human readable), or one line text.

indent - indent at current level

attributeNames - list of attributes to include

beforeClosingTag

@Deprecated
public void beforeClosingTag(int spaces,
                                        StringWriter writer,
                                        String... attributeNames)

Deprecated. use beforeClosingTag(StringBuilder, boolean, String, String...) instead

Override in a subclass to inject custom content onto XML just before the closing tag.

Parameters:

spaces - number of spaces of indent

writer - to write content to.

attributeNames - list of attributes to include

toJson

public String toJson(boolean pretty,
                     String... attributeNames)

Generates a JSON document from content of this model.

Parameters:

pretty - pretty format (human readable), or one line text.

attributeNames - list of attributes to include. No arguments == include all attributes.

Returns:

generated JSON.

toJsonP

protected void toJsonP(StringBuilder sb,
                       boolean pretty,
                       String indent,
                       String... attributeNames)

beforeClosingBrace

public void beforeClosingBrace(StringBuilder sb,
                               boolean pretty,
                               String indent,
                               String... attributeNames)

Override in subclasses in order to inject custom content into Json just before the closing brace.

To keep the formatting, it is recommended to implement this method as the example below.

 sb.append(',');
 if (pretty) { sb.append('\n').append(indent); }
 sb.append("\"test\":\"...\"");
 

Parameters:

sb - to write custom content to

pretty - pretty format (human readable), or one line text.

indent - indent at current level

attributeNames - list of attributes to include

beforeClosingBrace

@Deprecated
public void beforeClosingBrace(boolean pretty,
                                          String indent,
                                          StringWriter writer)

Deprecated. use beforeClosingBrace(StringBuilder, boolean, String, String...) instead

Override in subclasses in order to inject custom content into Json just before the closing brace.

Parameters:

pretty - pretty format (human readable), or one line text.

indent - indent at current level

writer - writer to write custom content to

parent

public <P extends Model> P parent(Class<P> parentClass)

Returns parent of this model, assuming that this table represents a child. This method may return null in cases when you have orphan record and referential integrity is not enforced in DBMS with a foreign key constraint.

Parameters:

parentClass - class of a parent model.

Returns:

instance of a parent of this instance in the "belongs to" relationship.

parent

public <P extends Model> P parent(Class<P> parentClass,
                                  boolean cache)

setCachedParent

protected void setCachedParent(Model parent)

setParents

public void setParents(Model... parents)

Sets multiple parents on this instance. Basically this sets a correct value of a foreign keys in a parent/child relationship. This only works for one to many and polymorphic associations.

Parameters:

parents - - collection of potential parents of this instance. Its ID values must not be null.

setParent

public void setParent(Model parent)

Sets a parent on this instance. Basically this sets a correct value of a foreign key in a parent/child relationship. This only works for one to many and polymorphic associations. The act of setting a parent does not result in saving to a database.

Parameters:

parent - potential parent of this instance. Its ID value must not be null.

copyTo

public void copyTo(Model other)

Copies all attribute values (except for ID, created_at and updated_at) from this instance to the other.

Parameters:

other - target model.

copyFrom

public void copyFrom(Model other)

Copies all attribute values (except for ID, created_at and updated_at) from other instance to this one.

Parameters:

other - source model.

getMetaModelLocal

protected MetaModel getMetaModelLocal()

This method should be called from all instance methods for performance.

Returns:

setMetamodelLocal

protected void setMetamodelLocal(MetaModel metamodelLocal)

refresh

public void refresh()

Re-reads all attribute values from DB.

get

public Object get(String attributeName)

Returns a value for attribute. If there is a Converter registered for the attribute that converts from Class S to Class java.lang.Object, given the attribute value is an instance of S, then it will be used.

Infer relationship from name of argument

Besides returning direct attributes of this model, this method is also aware of relationships and can return collections based on naming conventions. For example, if a model User has a one to many relationship with a model Address, then the following code will work:

 Address address = ...;
 User user = (User)address.get("user");
 

Conversely, this will also work:

 List<Address> addresses = (List<Address>)user.get("addresses");
 

The same would also work for many to many relationships:

 List<Doctor> doctors = (List<Doctor>)patient.get("doctors");
 ...
 List<Patient> patients = (List<Patient>)doctor.get("patients");
 

This methods will try to infer a name if a table by using Inflector to try to convert it to singular and them plural form, an attempting to see if this model has an appropriate relationship with another model, if one is found. This method of finding of relationships is best used in templating technologies, such as JSPs. For standard cases, please use parent(Class), and getAll(Class).

Suppressing inference for performance

In some cases, the inference of relationships might take a toll on performance, and if a project is not using the getter method for inference, than it is wise to turn it off with a system property activejdbc.get.inference:

         -Dactivejdbc.get.inference = false
     

If inference is turned off, only a value of the attribute is returned.

Parameters:

attributeName - name of attribute of name or related object.

Returns:

value for attribute.

getString

public String getString(String attributeName)

Gets attribute value as String. If there is a Converter registered for the attribute that converts from Class S to Class java.lang.String, given the attribute value is an instance of S, then it will be used, otherwise performs a conversion using Convert.toString(Object).

Parameters:

attributeName - name of attribute to convert

Returns:

value converted to String

getBytes

public byte[] getBytes(String attributeName)

Gets a value as bytes. If the column is Blob, bytes are read directly, if not, then the value is converted to String first, then string bytes are returned. Be careful out there, this will read entire Blob onto memory.

Parameters:

attributeName - name of attribute

Returns:

value as bytes.

getBigDecimal

public BigDecimal getBigDecimal(String attributeName)

Gets attribute value as java.math.BigDecimal. If there is a Converter registered for the attribute that converts from Class S to Class java.math.BigDecimal, given the attribute value is an instance of S, then it will be used, otherwise performs a conversion using Convert.toBigDecimal(Object).

Parameters:

attributeName - name of attribute to convert

Returns:

value converted to java.math.BigDecimal

getInteger

public Integer getInteger(String attributeName)

Gets attribute value as Integer. If there is a Converter registered for the attribute that converts from Class S to Class java.lang.Integer, given the attribute value is an instance of S, then it will be used, otherwise performs a conversion using Convert.toInteger(Object).

Parameters:

attributeName - name of attribute to convert

Returns:

value converted to Integer

getLong

public Long getLong(String attributeName)

Gets attribute value as Long. If there is a Converter registered for the attribute that converts from Class S to Class java.lang.Long, given the attribute value is an instance of S, then it will be used, otherwise performs a conversion using Convert.toLong(Object).

Parameters:

attributeName - name of attribute to convert

Returns:

value converted to Long

getShort

public Short getShort(String attributeName)

Gets attribute value as Short. If there is a Converter registered for the attribute that converts from Class S to Class java.lang.Short, given the attribute value is an instance of S, then it will be used, otherwise performs a conversion using Convert.toShort(Object).

Parameters:

attributeName - name of attribute to convert

Returns:

value converted to Short

getFloat

public Float getFloat(String attributeName)

Gets attribute value as Float. If there is a Converter registered for the attribute that converts from Class S to Class java.lang.Float, given the attribute value is an instance of S, then it will be used, otherwise performs a conversion using Convert.toFloat(Object).

Parameters:

attributeName - name of attribute to convert

Returns:

value converted to Float

getTime

public Time getTime(String attributeName)

Gets attribute value as java.sql.Time. If there is a Converter registered for the attribute that converts from Class S to Class java.sql.Time, given the attribute value is an instance of S, then it will be used, otherwise performs a conversion using Convert.toTime(Object).

Parameters:

attributeName - name of attribute to convert

Returns:

instance of Timestamp

getTimestamp

public Timestamp getTimestamp(String attributeName)

Gets attribute value as java.sql.Timestamp. If there is a Converter registered for the attribute that converts from Class S to Class java.sql.Timestamp, given the attribute value is an instance of S, then it will be used, otherwise performs a conversion using Convert.toTimestamp(Object).

Parameters:

attributeName - name of attribute to convert

Returns:

instance of Timestamp

getDouble

public Double getDouble(String attributeName)

Gets attribute value as Double. If there is a Converter registered for the attribute that converts from Class S to Class java.lang.Double, given the attribute value is an instance of S, then it will be used, otherwise performs a conversion using Convert.toDouble(Object).

Parameters:

attributeName - name of attribute to convert

Returns:

value converted to Double

getBoolean

public Boolean getBoolean(String attributeName)

Gets attribute value as Boolean. If there is a Converter registered for the attribute that converts from Class S to Class java.lang.Boolean, given the attribute value is an instance of S, then it will be used, otherwise performs a conversion using Convert.toBoolean(Object).

Parameters:

attributeName - name of attribute to convert

Returns:

value converted to Boolean

setString

public <T extends Model> T setString(String attributeName,
                                     Object value)

Sets attribute value as String. If there is a Converter registered for the attribute that converts from Class S to Class java.lang.String, given the value is an instance of S, then it will be used, otherwise performs a conversion using Convert.toString(Object).

Parameters:

attributeName - name of attribute.

value - value

Returns:

reference to this model.

setBigDecimal

public <T extends Model> T setBigDecimal(String attributeName,
                                         Object value)

Sets attribute value as java.math.BigDecimal. If there is a Converter registered for the attribute that converts from Class S to Class java.math.BigDecimal, given the value is an instance of S, then it will be used, otherwise performs a conversion using Convert.toBigDecimal(Object).

Parameters:

attributeName - name of attribute.

value - value

Returns:

reference to this model.

setShort

public <T extends Model> T setShort(String attributeName,
                                    Object value)

Sets attribute value as Short. If there is a Converter registered for the attribute that converts from Class S to Class java.lang.Short, given the value is an instance of S, then it will be used, otherwise performs a conversion using Convert.toShort(Object).

Parameters:

attributeName - name of attribute.

value - value

Returns:

reference to this model.

setInteger

public <T extends Model> T setInteger(String attributeName,
                                      Object value)

Sets attribute value as Integer. If there is a Converter registered for the attribute that converts from Class S to Class java.lang.Integer, given the value is an instance of S, then it will be used, otherwise performs a conversion using Convert.toInteger(Object).

Parameters:

attributeName - name of attribute.

value - value

Returns:

reference to this model.

setLong

public <T extends Model> T setLong(String attributeName,
                                   Object value)

Sets attribute value as Long. If there is a Converter registered for the attribute that converts from Class S to Class java.lang.Long, given the value is an instance of S, then it will be used, otherwise performs a conversion using Convert.toLong(Object).

Parameters:

attributeName - name of attribute.

value - value

Returns:

reference to this model.

setFloat

public <T extends Model> T setFloat(String attributeName,
                                    Object value)

Sets attribute value as Float. If there is a Converter registered for the attribute that converts from Class S to Class java.lang.Float, given the value is an instance of S, then it will be used, otherwise performs a conversion using Convert.toFloat(Object).

Parameters:

attributeName - name of attribute.

value - value to convert.

Returns:

reference to this model.

setTime

public <T extends Model> T setTime(String attributeName,
                                   Object value)

Sets attribute value as java.sql.Time. If there is a Converter registered for the attribute that converts from Class S to Class java.sql.Time, given the value is an instance of S, then it will be used, otherwise performs a conversion using Convert.toTime(Object).

Parameters:

attributeName - name of attribute.

value - value

Returns:

reference to this model.

setTimestamp

public <T extends Model> T setTimestamp(String attributeName,
                                        Object value)

Sets attribute value as java.sql.Timestamp. If there is a Converter registered for the attribute that converts from Class S to Class java.sql.Timestamp, given the value is an instance of S, then it will be used, otherwise performs a conversion using Convert.toTimestamp(Object).

Parameters:

attributeName - name of attribute.

value - value

Returns:

reference to this model.

setDouble

public <T extends Model> T setDouble(String attributeName,
                                     Object value)

Sets attribute value as Double. If there is a Converter registered for the attribute that converts from Class S to Class java.lang.Double, given the value is an instance of S, then it will be used, otherwise performs a conversion using Convert.toDouble(Object).

Parameters:

attributeName - name of attribute.

value - value to convert.

Returns:

reference to this model.

setBoolean

public <T extends Model> T setBoolean(String attributeName,
                                      Object value)

Sets attribute value as Boolean. If there is a Converter registered for the attribute that converts from Class S to Class java.lang.Boolean, given the value is an instance of S, then it will be used, otherwise performs a conversion using Convert.toBoolean(Object).

Parameters:

attributeName - name of attribute.

value - value

Returns:

reference to this model.

getAll

public <C extends Model> LazyList<C> getAll(Class<C> clazz)

This methods supports one to many, many to many relationships as well as polymorphic associations.

In case of one to many, the clazz must be a class of a child model, and it will return a collection of all children.

In case of many to many, the clazz must be a class of a another related model, and it will return a collection of all related models.

In case of polymorphic, the clazz must be a class of a polymorphically related model, and it will return a collection of all related models.

Parameters:

clazz - class of a child model for one to many, or class of another model, in case of many to many or class of child in case of polymorphic

Returns:

list of children in case of one to many, or list of other models, in case many to many.

get

public <C extends Model> LazyList<C> get(Class<C> clazz,
                                         String query,
                                         Object... params)

Provides a list of child models in one to many, many to many and polymorphic associations, but in addition also allows to filter this list by criteria.

1. For one to many, the criteria is against the child table.

2. For polymorphic association, the criteria is against the child table.

3. For many to many, the criteria is against the join table. For example, if you have table PROJECTS, ASSIGNMENTS and PROGRAMMERS, where a project has many programmers and a programmer has many projects, and ASSIGNMENTS is a join table, you can write code like this, assuming that the ASSIGNMENTS table has a column duration_weeks:

 List threeWeekProjects = programmer.get(Project.class, "duration_weeks = ?", 3);
 

where this list will contain all projects to which this programmer is assigned for 3 weeks.

Parameters:

clazz - related type

query - sub-query for join table.

params - parameters for a sub-query

Returns:

list of relations in many to many

validateNumericalityOf

protected static NumericValidationBuilder validateNumericalityOf(String... attributeNames)

addValidator

public static ValidationBuilder addValidator(Validator validator)

Adds a validator to the model.

Parameters:

validator - new validator.

addError

public void addError(String key,
                     String value)

Adds a new error to the collection of errors. This is a convenience method to be used from custom validators.

Parameters:

key - - key wy which this error can be retrieved from a collection of errors: errors().

value - - this is a key of the message in the resource bundle.

See Also:

Messages}.

removeValidator

public static void removeValidator(Validator validator)

getValidators

public static List<Validator> getValidators(Class<? extends Model> clazz)

validateRegexpOf

protected static ValidationBuilder validateRegexpOf(String attributeName,
                                                    String pattern)

Validates an attribite format with a ree hand regular expression.

Parameters:

attributeName - attribute to validate.

pattern - regexp pattern which must match the value.

Returns:

validateEmailOf

protected static ValidationBuilder validateEmailOf(String attributeName)

Validates email format.

Parameters:

attributeName - name of attribute that holds email value.

Returns:

validateRange

protected static ValidationBuilder validateRange(String attributeName,
                                                 Number min,
                                                 Number max)

Validates range. Accepted types are all java.lang.Number subclasses: Byte, Short, Integer, Long, Float, Double BigDecimal.

Parameters:

attributeName - attribute to validate - should be within range.

min - min value of range.

max - max value of range.

Returns:

validatePresenceOf

protected static ValidationBuilder validatePresenceOf(String... attributeNames)

The validation will not pass if the value is either an empty string "", or null.

Parameters:

attributeNames - list of attributes to validate.

Returns:

validateWith

protected static ValidationBuilder validateWith(Validator validator)

Add a custom validator to the model.

Parameters:

validator - custom validator.

convertWith

@Deprecated
protected static ValidationBuilder convertWith(Converter converter)

Deprecated. use convertWith(org.javalite.activejdbc.conversion.Converter, String...) instead

Adds a custom converter to the model.

Parameters:

converter - custom converter

convertWith

protected static void convertWith(Converter converter,
                                  String... attributeNames)

Registers a custom converter for the specified attributes.

Parameters:

converter - custom converter

attributeNames - attribute names

convertDate

@Deprecated
protected static ValidationBuilder convertDate(String attributeName,
                                                          String format)

Deprecated. use {@link #dateFormat(String, String...) instead

Converts a named attribute to java.sql.Date if possible. Acts as a validator if cannot make a conversion.

Parameters:

attributeName - name of attribute to convert to java.sql.Date.

format - format for conversion. Refer to SimpleDateFormat

Returns:

message passing for custom validation message.

convertTimestamp

@Deprecated
protected static ValidationBuilder convertTimestamp(String attributeName,
                                                               String format)

Deprecated. use {@link #timestampFormat(String, String...) instead

Converts a named attribute to java.sql.Timestamp if possible. Acts as a validator if cannot make a conversion.

Parameters:

attributeName - name of attribute to convert to java.sql.Timestamp.

format - format for conversion. Refer to SimpleDateFormat

Returns:

message passing for custom validation message.

dateFormat

protected static void dateFormat(String pattern,
                                 String... attributeNames)

Registers date format for specified attributes. This format will be used to convert between Date -> String -> java.sql.Date when using the appropriate getters and setters.

For example:

 public class Person extends Model {
     static {
         dateFormat("MM/dd/yyyy", "dob");
     }
 }

 Person p = new Person();
 // will convert String -> java.sql.Date
 p.setDate("dob", "02/29/2000");
 // will convert Date -> String, if dob value in model is of type Date
 String str = p.getString("dob");

 // will convert Date -> String
 p.setString("dob", new Date());
 // will convert String -> java.sql.Date, if dob value in model is of type String
 Date date = p.getDate("dob");
 

Parameters:

pattern - pattern to use for conversion

attributeNames - attribute names

dateFormat

protected static void dateFormat(DateFormat format,
                                 String... attributeNames)

Registers date format for specified attributes. This format will be used to convert between Date -> String -> java.sql.Date when using the appropriate getters and setters.

See example in dateFormat(String, String...).

Parameters:

format - format to use for conversion

attributeNames - attribute names

timestampFormat

protected static void timestampFormat(String pattern,
                                      String... attributeNames)

Registers date format for specified attributes. This format will be used to convert between Date -> String -> java.sql.Timestamp when using the appropriate getters and setters.

For example:

 public class Person extends Model {
     static {
         timestampFormat("MM/dd/yyyy hh:mm a", "birth_datetime");
     }
 }

 Person p = new Person();
 // will convert String -> java.sql.Timestamp
 p.setTimestamp("birth_datetime", "02/29/2000 12:07 PM");
 // will convert Date -> String, if dob value in model is of type Date or java.sql.Timestamp
 String str = p.getString("birth_datetime");

 // will convert Date -> String
 p.setString("birth_datetime", new Date());
 // will convert String -> java.sql.Timestamp, if dob value in model is of type String
 Timestamp ts = p.getTimestamp("birth_datetime");
 

Parameters:

pattern - pattern to use for conversion

attributeNames - attribute names

timestampFormat

protected static void timestampFormat(DateFormat format,
                                      String... attributeNames)

Registers date format for specified attributes. This format will be used to convert between Date -> String -> java.sql.Timestamp when using the appropriate getters and setters.

See example in timestampFormat(String, String...).

Parameters:

format - format to use for conversion

attributeNames - attribute names

blankToNull

protected static void blankToNull(String... attributeNames)

Registers BlankToNullConverter for specified attributes. This will convert instances of String that are empty or contain only whitespaces to null.

Parameters:

attributeNames - attribute names

zeroToNull

protected static void zeroToNull(String... attributeNames)

Registers ZeroToNullConverter for specified attributes. This will convert instances of Number that are zero to null.

Parameters:

attributeNames - attribute names

belongsTo

public static boolean belongsTo(Class<? extends Model> targetClass)

addCallbacks

@Deprecated
public static void addCallbacks(CallbackListener... listeners)

Deprecated. use callbackWith(CallbackListener...) instead

callbackWith

public static void callbackWith(CallbackListener... listeners)

isValid

public boolean isValid()

This method performs validations and then returns true if no errors were generated, otherwise returns false.

Returns:

true if no errors were generated, otherwise returns false.

validate

public void validate()

Executes all validators attached to this model.

hasErrors

public boolean hasErrors()

addValidator

public void addValidator(Validator validator,
                         String errorKey)

Binds a validator to an attribute if validation fails.

Parameters:

errorKey - key of error in errors map. Usually this is a name of attribute, but not limited to that, can be anything.

validator - -validator that failed validation.

errors

public Errors errors()

Provides an instance of Errors object, filled with error messages after validation.

Returns:

an instance of Errors object, filled with error messages after validation.

errors

public Errors errors(Locale locale)

Provides an instance of localized Errors object, filled with error messages after validation.

Parameters:

locale - locale.

Returns:

an instance of localized Errors object, filled with error messages after validation.

create

public static <T extends Model> T create(Object... namesAndValues)

This is a convenience method to create a model instance already initialized with values. Example:

 Person p = Person.create("name", "Sam", "last_name", "Margulis", "dob", "2001-01-07");
 

The first (index 0) and every other element in the array is an attribute name, while the second (index 1) and every other is a corresponding value. This allows for better readability of code. If you just read this aloud, it will become clear.

Parameters:

namesAndValues - names and values. elements at indexes 0, 2, 4, 8... are attribute names, and elements at indexes 1, 3, 5... are values. Element at index 1 is a value for attribute at index 0 and so on.

Returns:

newly instantiated model.

set

public <T extends Model> T set(Object... namesAndValues)

This is a convenience method to set multiple values to a model. Example:

 Person p = ...
 Person p = p.set("name", "Sam", "last_name", "Margulis", "dob", "2001-01-07");
 

The first (index 0) and every other element in the array is an attribute name, while the second (index 1) and every other is a corresponding value. This allows for better readability of code. If you just read this aloud, it will become clear.

Parameters:

namesAndValues - names and values. elements at indexes 0, 2, 4, 8... are attribute names, and elements at indexes 1, 3, 5... are values. Element at index 1 is a value for attribute at index 0 and so on.

Returns:

newly instantiated model.

createIt

public static <T extends Model> T createIt(Object... namesAndValues)

This is a convenience method to create(Object...). It will create a new model and will save it to DB. It has the same semantics as saveIt().

Parameters:

namesAndValues - names and values. elements at indexes 0, 2, 4, 8... are attribute names, and elements at indexes 1, 3, 5... are values. Element at index 1 is a value for attribute at index 0 and so on.

Returns:

newly instantiated model which also has been saved to DB.

findById

public static <T extends Model> T findById(Object id)

findByCompositeKeys

public static <T extends Model> T findByCompositeKeys(Object... values)

Composite PK values in exactly the same order as specified in CompositePK.

Parameters:

values - Composite PK values in exactly the same order as specified in CompositePK.

Returns:

instance of a found model, or null if nothing found.

See Also:

CompositePK

where

public static <T extends Model> LazyList<T> where(String subquery,
                                                  Object... params)

Finder method for DB queries based on table represented by this model. Usually the SQL starts with: "select * from table_name where " + subquery where table_name is a table represented by this model. Code example:

 List teenagers = Person.where("age > ? and age < ?", 12, 20);
 // iterate...

 //same can be achieved (since parameters are optional):
 List teenagers = Person.where("age > 12 and age < 20");
 //iterate
 

Limit, offset and order by can be chained like this:

 List teenagers = Person.where("age > ? and age < ?", 12, 20).offset(101).limit(20).orderBy(age);
 //iterate
 

This is a great way to build paged applications.

Parameters:

subquery - this is a set of conditions that normally follow the "where" clause. Example: "department = ? and dob > ?". If this value is "*" and no parameters provided, then findAll() is executed.

params - list of parameters corresponding to the place holders in the subquery.

Returns:

instance of LazyList containing results.

find

public static <T extends Model> LazyList<T> find(String subquery,
                                                 Object... params)

Synonym of where(String, Object...)

Parameters:

subquery - this is a set of conditions that normally follow the "where" clause. Example: "department = ? and dob > ?". If this value is "*" and no parameters provided, then findAll() is executed.

params - list of parameters corresponding to the place holders in the subquery.

Returns:

instance of LazyList containing results.

findFirst

public static <T extends Model> T findFirst(String subQuery,
                                            Object... params)

Synonym of first(String, Object...).

Parameters:

subQuery - selection criteria, example:

 Person johnTheTeenager = Person.findFirst("name = ? and age > 13 and age < 19 order by age", "John")
 

Sometimes a query might be just a clause like this:

 Person oldest = Person.findFirst("order by age desc")
 

params - list of parameters if question marks are used as placeholders

Returns:

a first result for this condition. May return null if nothing found.

first

public static <T extends Model> T first(String subQuery,
                                        Object... params)

Returns a first result for this condition. May return null if nothing found. If last result is needed, then order by some field and call this nethod: Synonym of findFirst(String, Object...).

 //first:
 Person youngestTeenager= Person.first("age > 12 and age < 20 order by age");

 //last:
 Person oldestTeenager= Person.first("age > 12 and age < 20 order by age desc");
 

Parameters:

subQuery - selection criteria, example:

 Person johnTheTeenager = Person.first("name = ? and age < 13 order by age", "John")
 

Sometimes a query might be just a clause like this:

 Person p = Person.first("order by age desc")
 

params - list of parameters if question marks are used as placeholders

Returns:

a first result for this condition. May return null if nothing found.

find

@Deprecated
public static void find(String query,
                                   ModelListener listener)

Deprecated. use findWith(ModelListener, String, Object...).

This method is for processing really large result sets. Results found by this method are never cached.

Parameters:

query - query text.

listener - this is a call back implementation which will receive instances of models found.

findWith

public static void findWith(ModelListener listener,
                            String query,
                            Object... params)

This method is for processing really large result sets. Results found by this method are never cached.

Parameters:

listener - this is a call back implementation which will receive instances of models found.

query - sub-query (content after "WHERE" clause)

params - optional parameters for a query.

findBySQL

public static <T extends Model> LazyList<T> findBySQL(String fullQuery,
                                                      Object... params)

Free form query finder. Example:

 List rules = Rule.findBySQL("select rule.*, goal_identifier from rule, goal where goal.goal_id = rule.goal_id order by goal_identifier asc, rule_type desc");
 

Ensure that the query returns all columns associated with this model, so that the resulting models could hydrate itself properly. Returned columns that are not part of this model will be ignored, but can be used for caluses like above.

Type Parameters:

T - - class that extends Model.

Parameters:

fullQuery - free-form SQL.

params - parameters if query is parametrized.

Returns:

list of models representing result set.

findAll

public static <T extends Model> LazyList<T> findAll()

This method returns all records from this table. If you need to get a subset, look for variations of "find()".

Returns:

result list

add

public void add(Model child)

Adds a new child dependency. This method works for all three association types:

• One to many - argument model should be a child in the relationship. This method will immediately set it's ID as a foreign key on the child and will then save the child.
• Many to many - argument model should be the other model in the relationship. This method will check if the added child already has an ID. If the child does have an ID, then the method will create a link in the join table. If the child does not have an ID, then this method saves the child first, then creates a record in the join table linking this model instance and the child instance.
• Polymorphic - argument model should be a polymorphic child of this model. This method will set the parent_id and parent_type as appropriate and then will then save the child.

This method will throw a NotAssociatedException in case a model that has no relationship is passed.

Parameters:

child - instance of a model that has a relationship to the current model. Either one to many or many to many relationships are accepted.

remove

public int remove(Model child)

Removes associated child from this instance. The child model should be either in belongs to association (including polymorphic) to this model or many to many association.

One to many and polymorphic associations

This method will simply call child.delete() method. This will render the child object frozen.

Many to many associations

This method will remove an associated record from the join table, and will do nothing to the child model or record.

This method will throw a NotAssociatedException in case a model that has no relationship is passed.

Parameters:

child - model representing a "child" as in one to many or many to many association with this model.

Returns:

number of records affected

saveIt

public boolean saveIt()

This method will not exit silently like save(), it instead will throw ValidationException if validations did not pass.

Returns:

true if the model was saved, false if you set an ID value for the model, but such ID does not exist in DB.

reset

public void reset()

Resets all data in this model, including the ID. After this method, this instance is equivalent to an empty, just created instance.

thaw

public void thaw()

Unfreezes this model. After this method it is possible again to call save() and saveIt() methods. This method will erase the value of ID on this instance, while preserving all other attributes' values. If a record was deleted, it is frozen and cannot be saved. After it is thawed, it can be saved again, but it will generate a new insert statement and create a new record in the table with all the same attribute values.

Synonym for defrost().

defrost

public void defrost()

Synonym for thaw().

save

public boolean save()

This method will save data from this instance to a corresponding table in the DB. It will generate insert SQL if the model is new, or update if the model exists in the DB. This method will execute all associated validations and if those validations generate errors, these errors are attached to this instance. Errors are available by {#link #errors() } method. The save() method is mostly for web applications, where code like this is written:

 if(person.save())
      //show page success
 else{
      request.setAttribute("errors", person.errors());
      //show errors page, or same page so that user can correct errors.
   }
 

In other words, this method will not throw validation exceptions. However, if there is a problem in the DB, then there can be a runtime exception thrown.

Returns:

true if a model was saved and false if values did not pass validations and the record was not saved. False will also be returned if you set an ID value for the model, but such ID does not exist in DB.

count

public static Long count()

Returns total count of records in table.

Returns:

total count of records in table.

count

public static Long count(String query,
                         Object... params)

Returns count of records in table under a condition.

Parameters:

query - query to select records to count.

params - parameters (if any) for the query.

Returns:

count of records in table under a condition.

insert

public boolean insert()

This method will save a model as new. In other words, it will not try to guess if this is a new record or a one that exists in the table. It does not have "belt and suspenders", it will simply generate and execute insert statement, assuming that developer knows what he/she is doing.

Returns:

true if model was saved, false if not

getTableName

public static String getTableName()

Returns name of corresponding table.

Returns:

name of corresponding table.

getId

public Object getId()

Value of ID.

Returns:

of ID.

getIdName

public String getIdName()

Name of ID column.

Returns:

Name of ID column.

getCompositeKeys

public String[] getCompositeKeys()

Provides a list of composite keys as specified in CompositePK.

Returns:

a list of composite keys as specified in CompositePK.

setChildren

protected void setChildren(Class childClass,
                           List<Model> children)

manageTime

public void manageTime(boolean manage)

Turns off automatic management of time-related attributes created_at and updated_at. If management of time attributes is turned off,

Parameters:

manage - if true, the attributes are managed by the model. If false, they are managed by developer.

toInsert

public String toInsert()

Generates INSERT SQL based on this model. Uses the dialect associated with this model database to format the value literals. Example:

 String sql = user.toInsert();
 //yields this output:
 //INSERT INTO users (id, email, first_name, last_name) VALUES (1, 'mmonroe@yahoo.com', 'Marilyn', 'Monroe')
 

Returns:

INSERT SQL based on this model.

toInsert

public String toInsert(Dialect dialect)

Generates INSERT SQL based on this model with the provided dialect. Example:

 String sql = user.toInsert(new MySQLDialect());
 //yields this output:
 //INSERT INTO users (id, email, first_name, last_name) VALUES (1, 'mmonroe@yahoo.com', 'Marilyn', 'Monroe')
 

Parameters:

dialect - dialect to be used to generate the SQL

Returns:

INSERT SQL based on this model.

toUpdate

public String toUpdate()

Generates UPDATE SQL based on this model. Uses the dialect associated with this model database to format the value literals. Example:

 String sql = user.toUpdate();
 //yields this output:
 //UPDATE users SET email = 'mmonroe@yahoo.com', first_name = 'Marilyn', last_name = 'Monroe' WHERE id = 1
 

Returns:

UPDATE SQL based on this model.

toUpdate

public String toUpdate(Dialect dialect)

Generates UPDATE SQL based on this model with the provided dialect. Example:

 String sql = user.toUpdate(new MySQLDialect());
 //yields this output:
 //UPDATE users SET email = 'mmonroe@yahoo.com', first_name = 'Marilyn', last_name = 'Monroe' WHERE id = 1
 

Parameters:

dialect - dialect to be used to generate the SQL

Returns:

UPDATE SQL based on this model.

toInsert

@Deprecated
public String toInsert(String leftStringQuote,
                                  String rightStringQuote)

Deprecated. Use toInsert(Dialect) instead.

Generates INSERT SQL based on this model. For instance, for Oracle, the left quote is: "q'{" and the right quote is: "}'". The output will also use single quotes for java.sql.Timestamp and java.sql.Date types. Example:

 String insert = u.toInsert("q'{", "}'");
 //yields this output
 //INSERT INTO users (id, first_name, email, last_name) VALUES (1, q'{Marilyn}', q'{mmonroe@yahoo.com}', q'{Monroe}');
 

Parameters:

leftStringQuote - - left quote for a string value, this can be different for different databases.

rightStringQuote - - left quote for a string value, this can be different for different databases.

Returns:

SQL INSERT string;

toInsert

@Deprecated
public String toInsert(Formatter... formatters)

Deprecated. Use toInsert(Dialect) instead.

Parameters:

formatters -

Returns:

purgeCache

public static void purgeCache()

Use to force-purge cache associated with this table. If this table is not cached, this method has no side effect.

getLongId

public Long getLongId()

Convenience method: converts ID value to Long and returns it.

Returns:

value of attribute corresponding to getIdName(), converted to Long.

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException

Specified by:

writeExternal in interface Externalizable

Throws:

IOException

readExternal

public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException

Specified by:

readExternal in interface Externalizable

Throws:

IOException

ClassNotFoundException

beforeSave

protected void beforeSave()

afterLoad

protected void afterLoad()

afterSave

protected void afterSave()

beforeCreate

protected void beforeCreate()

afterCreate

protected void afterCreate()

beforeUpdate

protected void beforeUpdate()

afterUpdate

protected void afterUpdate()

beforeDelete

protected void beforeDelete()

afterDelete

protected void afterDelete()

beforeValidation

protected void beforeValidation()

afterValidation

protected void afterValidation()