org.mentabean

Interface BeanSession

All Known Implementing Classes:

AnsiSQLBeanSession, FirebirdBeanSession, H2BeanSession, MySQLBeanSession, OracleBeanSession, PostgreSQLBeanSession

public interface BeanSession

Describe a simple ORM interface that can perform CRUD for Beans according to properties defined programmatically on BeanManager. It can also load lists and unique beans based on properties set on a given bean. It also supports dynamic update, in other words, it will only update fields from a bean loaded from the database that were actually modified during the session. The behavior can be turned off when necessary ,in other words, when you want to blindly update all properties from a bean in the database regarding of whether they were modified or not.

Author:

Sergio Oliveira Jr.

Field Summary

Fields

Modifier and Type	Field and Description
static int	INSERT
static int	UPDATE

Method Summary

Methods

Modifier and Type	Method and Description
void	addTrigger(TriggerListener trigger) Add a TriggerListener in this session.
QueryBuilder	buildQuery() Builds a new QueryBuilder so it's possible to create fluent custom SQL queries
String	buildSelect(Class<? extends Object> beanClass)
String	buildSelect(Class<? extends Object> beanClass, Object... properties)
String	buildSelect(Class<? extends Object> beanClass, String tableName)
String	buildSelect(Class<? extends Object> beanClass, String tableName, Object... properties)
String	buildSelectMinus(Class<? extends Object> beanClass, Object... minus)
String	buildSelectMinus(Class<? extends Object> beanClass, String tableName, Object... minus)
String	buildTableName(Class<? extends Object> clazz) Returns the table name configured for the given class
<E> E	compareDifferences(E bean, E another, List<String> nullProps) Compare differences between two beans holding the properties of first bean passed and adding null properties in nullProps list.
int	countList(Object bean) Count the number of beans that would be returned by a loadList method.
<E> E	createBasicInstance(E bean) Creates an single instance only with primary keys according the given object
void	createTable(Class<? extends Object> beanKlass)
<E> TableAlias<E>	createTableAlias(Class<? extends E> beanClass) Return a table alias for this bean class
<E> TableAlias<E>	createTableAlias(Class<? extends E> beanClass, String prefix) Return a table alias for this bean class with a prefix.
void	createTables()
boolean	delete(Object bean) Delete the bean from the database.
int	deleteAll(Object bean) Delete all data based on the properties present in the bean passed The PK doesn't need to be set
void	dropTable(Class<? extends Object> beanKlass)
BeanConfig	getConfigFor(Class<?> clazz) Returns the BeanConfig object from the given bean class
Connection	getConnection() Get the database connection being used by this bean session.
void	insert(Object bean) Insert the bean in the database.
boolean	load(Object bean) Load the bean from the database, injecting all its properties through reflection.
boolean	load(Object bean, Object... properties)
<E> List<E>	loadList(E bean) Load a list of beans based on the properties present in the bean passed.
<E> List<E>	loadList(E bean, Limit limit) Same as loadList(bean) except that you can limit the number of beans returned in the list.
<E> List<E>	loadList(E bean, Limit limit, Object... properties)
<E> List<E>	loadList(E bean, Object... properties)
<E> List<E>	loadList(E bean, OrderBy orderBy) Same as loadList(bean) except that you can order the list returned by passing an SQL orderBy clause.
<E> List<E>	loadList(E bean, OrderBy orderBy, Limit limit) Same as loadList(bean) except that you can limit the number of beans returned in the list as well as sort them by passing a orderBy SQL clause.
<E> List<E>	loadList(E bean, OrderBy orderBy, Limit limit, Object... properties)
<E> List<E>	loadList(E bean, OrderBy orderBy, Object... properties)
<E> List<E>	loadListMinus(E bean, Limit limit, Object... minus)
<E> List<E>	loadListMinus(E bean, Object... minus)
<E> List<E>	loadListMinus(E bean, OrderBy orderBy, Limit limit, Object... minus)
<E> List<E>	loadListMinus(E bean, OrderBy orderBy, Object... minus)
boolean	loadMinus(Object bean, Object... minus)
<E> E	loadUnique(E bean) Same as loadList(bean) but it attempts to load a single bean only.
<E> E	loadUnique(E bean, Object... properties)
<E> E	loadUniqueMinus(E bean, Object... minus)
void	populateBean(ResultSet rset, Object bean)
void	populateBean(ResultSet rset, Object bean, Object... properties)
void	populateBean(ResultSet rset, Object bean, String tableName)
void	populateBean(ResultSet rset, Object bean, String tableName, Object... properties)
void	populateBeanMinus(ResultSet rset, Object bean, Object... minus)
void	populateBeanMinus(ResultSet rset, Object bean, String tableName, Object... minus)
String	propertyToColumn(Class<? extends Object> clazz, Object property)
String	propertyToColumn(Class<? extends Object> clazz, Object property, String alias)
void	removeTrigger(TriggerListener trigger) Removes the TriggerListener from session
int	save(Object bean, Object... forceNull) Tries to update or insert a bean using the update method.
int	saveAll(Object bean) Tries to update or insert a bean object into database.
int	update(Object bean, Object... forceNull) Update the bean in the database.
int	updateAll(Object bean) Same as update(bean) but here you can turn off the default dynamic update behavior and force all bean properties to be updated regardless whether they have been modified or not.
<E> int	updateDiff(E newBean, E oldBean) Updates an object using only the differences between newBean and oldBean instances.

Field Detail

UPDATE

static final int UPDATE

See Also:

Constant Field Values

INSERT

static final int INSERT

See Also:

Constant Field Values

Method Detail

getConnection

Connection getConnection()

Get the database connection being used by this bean session.

Returns:

the database connection

load

boolean load(Object bean)

Load the bean from the database, injecting all its properties through reflection. Note that the bean passed MUST have its primary key set otherwise there is no way we can load it from the database.

Parameters:

bean - The bean we want to load from the DB.

Returns:

true if the bean was found in the database, false otherwise

load

boolean load(Object bean,
           Object... properties)

loadMinus

boolean loadMinus(Object bean,
                Object... minus)

update

int update(Object bean,
         Object... forceNull)

Update the bean in the database. Only the bean fields that have been modified (dirty) will be updated. It will return 1 if an update did happen or 0 if the bean could not be found in the database or if there was nothing modified in bean. The bean MUST have its primary key set, otherwise it is impossible to update the bean in the database, and an exception will be thrown.

Parameters:

bean - The bean to be updated

forceNull - Database columns that will be forced to null if the bean property is not set

Returns:

1 if update was successful, 0 if the update did not happen or was not necessary

updateAll

int updateAll(Object bean)

Same as update(bean) but here you can turn off the default dynamic update behavior and force all bean properties to be updated regardless whether they have been modified or not.

Parameters:

bean -

Returns:

the number of rows that were updated

Throws:

Exception

updateDiff

<E> int updateDiff(E newBean,
                 E oldBean)

Updates an object using only the differences between newBean and oldBean instances. This method is useful in distributed environments like RMI or web services because these approaches should serialize objects to send/receive informations from client to server and vice versa

Parameters:

newBean -

oldBean -

Returns:

1 if update was successful, 0 if the update did not happen or was not necessary (when bean instances have no differences)

insert

void insert(Object bean)

Insert the bean in the database. Depending on the type of PK, the generation of the PK can and should be taken care by the DB itself. The generated PK should be inserted in the bean by reflection, before the method returns. The default, database-independent implementation of this method, insert all fields in the database not worrying about PK generation strategies.

Parameters:

bean - The bean to insert

save

int save(Object bean,
       Object... forceNull)

Tries to update or insert a bean using the update method.

Parameters:

bean - The bean to update or insert

forceNull - Database columns that will be forced to null (or zero) if the bean property is not set

Returns:

A value 0 (zero) if operation executed an update and 1 (one) if insert method was executed

See Also:

saveAll(Object), update(Object, Object...)

saveAll

int saveAll(Object bean)

Tries to update or insert a bean object into database. The update uses the updateAll method.

Parameters:

bean - The bean to update or insert

Returns:

A value 0 (zero) if operation executed an update and 1 (one) if insert method was executed

See Also:

updateAll(Object)

delete

boolean delete(Object bean)

Delete the bean from the database. The PK of the bean MUST be set. The bean can only be deleted by its PK.

Parameters:

bean -

Returns:

true if it was deleted or false if it did not exist

Throws:

Exception

deleteAll

int deleteAll(Object bean)

Delete all data based on the properties present in the bean passed The PK doesn't need to be set

Parameters:

bean -

Returns:

The total of tuples removed from database

countList

int countList(Object bean)

Count the number of beans that would be returned by a loadList method.

Parameters:

bean - The bean holding the properties used by the list query.

Returns:

the number of beans found in the database

loadList

<E> List<E> loadList(E bean)

Load a list of beans based on the properties present in the bean passed. For example, if you want to load all users with lastName equal to 'saoj' you would instantiate a bean and set its lastName property to 'saoj' before passing it as an argument to this method.

Type Parameters:

E -

Parameters:

bean - The bean holding the properties used by the list query.

Returns:

A list of beans the match the properties in the given bean. Or an empty list if nothing was found.

loadList

<E> List<E> loadList(E bean,
                   Object... properties)

loadListMinus

<E> List<E> loadListMinus(E bean,
                        Object... minus)

loadList

<E> List<E> loadList(E bean,
                   OrderBy orderBy)

Same as loadList(bean) except that you can order the list returned by passing an SQL orderBy clause.

Type Parameters:

E -

Parameters:

bean - The bean holding the properties used by the list query.

orderBy - The orderBy SQL clause.

Returns:

A list of beans the match the properties in the given bean. Or an empty list if nothing was found.

loadList

<E> List<E> loadList(E bean,
                   OrderBy orderBy,
                   Object... properties)

loadListMinus

<E> List<E> loadListMinus(E bean,
                        OrderBy orderBy,
                        Object... minus)

loadList

<E> List<E> loadList(E bean,
                   Limit limit)

Same as loadList(bean) except that you can limit the number of beans returned in the list.

Type Parameters:

E -

Parameters:

bean - The bean holding the properties used by the list query.

limit - The max number of beans returned in the list.

Returns:

A list of beans the match the properties in the given bean. Or an empty list if nothing was found.

loadList

<E> List<E> loadList(E bean,
                   Limit limit,
                   Object... properties)

loadListMinus

<E> List<E> loadListMinus(E bean,
                        Limit limit,
                        Object... minus)

loadList

<E> List<E> loadList(E bean,
                   OrderBy orderBy,
                   Limit limit)

Same as loadList(bean) except that you can limit the number of beans returned in the list as well as sort them by passing a orderBy SQL clause.

Type Parameters:

E -

Parameters:

bean - The bean holding the properties used by the list query.

orderBy - The orderBy SQL clause.

limit - The max number of beans returned in the list.

Returns:

A list of beans the match the properties in the given bean. Or an empty list if nothing was found.

loadList

<E> List<E> loadList(E bean,
                   OrderBy orderBy,
                   Limit limit,
                   Object... properties)

loadListMinus

<E> List<E> loadListMinus(E bean,
                        OrderBy orderBy,
                        Limit limit,
                        Object... minus)

loadUnique

<E> E loadUnique(E bean)

Same as loadList(bean) but it attempts to load a single bean only. If more than one bean is found it throws an exception. NOTE: The returned bean will be attached by the session so only the modified properties will be updated in case update() is called.

Type Parameters:

E -

Parameters:

bean - The bean holding the properties used by the load query.

Returns:

A unique bean that match the properties in the given bean. Or null if nothing was found.

Throws:

BeanException - if more than one bean is found by the query.

loadUnique

<E> E loadUnique(E bean,
               Object... properties)

loadUniqueMinus

<E> E loadUniqueMinus(E bean,
                    Object... minus)

buildSelect

String buildSelect(Class<? extends Object> beanClass)

buildSelect

String buildSelect(Class<? extends Object> beanClass,
                 Object... properties)

buildSelectMinus

String buildSelectMinus(Class<? extends Object> beanClass,
                      Object... minus)

buildSelect

String buildSelect(Class<? extends Object> beanClass,
                 String tableName)

buildSelect

String buildSelect(Class<? extends Object> beanClass,
                 String tableName,
                 Object... properties)

buildSelectMinus

String buildSelectMinus(Class<? extends Object> beanClass,
                      String tableName,
                      Object... minus)

populateBean

void populateBean(ResultSet rset,
                Object bean)

populateBean

void populateBean(ResultSet rset,
                Object bean,
                Object... properties)

populateBeanMinus

void populateBeanMinus(ResultSet rset,
                     Object bean,
                     Object... minus)

populateBean

void populateBean(ResultSet rset,
                Object bean,
                String tableName)

populateBean

void populateBean(ResultSet rset,
                Object bean,
                String tableName,
                Object... properties)

populateBeanMinus

void populateBeanMinus(ResultSet rset,
                     Object bean,
                     String tableName,
                     Object... minus)

createTable

void createTable(Class<? extends Object> beanKlass)

dropTable

void dropTable(Class<? extends Object> beanKlass)

createTables

void createTables()

propertyToColumn

String propertyToColumn(Class<? extends Object> clazz,
                      Object property,
                      String alias)

propertyToColumn

String propertyToColumn(Class<? extends Object> clazz,
                      Object property)

createBasicInstance

<E> E createBasicInstance(E bean)

Creates an single instance only with primary keys according the given object

Parameters:

bean - - The bean with all primary key set

Returns:

A new instance of the bean

compareDifferences

<E> E compareDifferences(E bean,
                       E another,
                       List<String> nullProps)

Compare differences between two beans holding the properties of first bean passed and adding null properties in nullProps list. This method returns null when beans has no differences

Parameters:

bean -

another -

nullProps - An empty list

Returns:

buildTableName

String buildTableName(Class<? extends Object> clazz)

Returns the table name configured for the given class

Parameters:

clazz - - The bean class

Returns:

Table name

getConfigFor

BeanConfig getConfigFor(Class<?> clazz)

Returns the BeanConfig object from the given bean class

Parameters:

clazz -

Returns:

BeanConfig

buildQuery

QueryBuilder buildQuery()

Builds a new QueryBuilder so it's possible to create fluent custom SQL queries

Returns:

QueryBuilder object

addTrigger

void addTrigger(TriggerListener trigger)

Add a TriggerListener in this session. Remember that it's not added in BeanConfig, only in current session

Parameters:

trigger -

removeTrigger

void removeTrigger(TriggerListener trigger)

Removes the TriggerListener from session

Parameters:

trigger -

createTableAlias

<E> TableAlias<E> createTableAlias(Class<? extends E> beanClass)

Return a table alias for this bean class

Parameters:

beanClass -

Returns:

TableAlias

createTableAlias

<E> TableAlias<E> createTableAlias(Class<? extends E> beanClass,
                                 String prefix)

Return a table alias for this bean class with a prefix.

Parameters:

beanClass -

prefix -

Returns:

TableAlias