flex.data.assemblers
Class HibernateAssembler

java.lang.Object
  flex.data.assemblers.AbstractAssembler
      flex.data.assemblers.HibernateAssembler

All Implemented Interfaces:

flex.data.adapters.JavaAdapterConstants, Assembler, FlexComponent, FlexConfigurable

public class HibernateAssembler
extends AbstractAssembler
implements flex.data.adapters.JavaAdapterConstants

An assembler that provides support for hibernate entities as flex destinations in Flex Data Management Services. You can use this class out of the box, or you can extend it get complete control over how your persistence functionality is exposed to clients. You can also add your own fill and count methods to a subclass and refer to them from the configuration file.

Field Summary

static String

LOG_CATEGORY Log category for HibernateAssembler.

Fields inherited from interface flex.data.adapters.JavaAdapterConstants

AUTO_REFRESH_ELEMENT, CONFLICT_MODE_DEFAULT, CONFLICT_MODE_DELETE_ATTR, CONFLICT_MODE_UPDATE_ATTR, COUNT_ELEMENT, FILL_CONTAINS_METHOD_ELEMENT, FILL_ELEMENT, GET_ELEMENT, METHOD_NAME_ELEMENT, ORDERED_ELEMENT, PARAM_TYPES_ELEMENT, SECURITY_CONSTRAINT_ELEMENT, SECURITY_REF_ATTR, SECURITY_RUN_AS_ELEMENT, SYNC_ELEMENT

Fields inherited from interface flex.data.assemblers.Assembler

APPEND_TO_FILL, DO_NOT_EXECUTE_FILL, EXECUTE_FILL, REMOVE_FROM_FILL

Constructor Summary

HibernateAssembler()
The Assembler class is constructed by Data Management Services so you do not need to construct this yourself.

Method Summary

boolean	autoRefreshFill(List fillParameters) The Hibernate assembler always refreshes fill methods automatically so this method returns true for all fills.
int	count(List countParams) Implements the count queries for the hibernate assembler.
void	createItem(Object item) Actually performs the createItem operation.
void	deleteItem(Object clientVersion) Deletes the hibernate item.
Collection	fill(List fillArgs, int startIndex, int numItems) Implements the fill method for the hibernate assembler.
String	getDeleteConflictMode() Returns the delete-conflict-mode of the HibernateAssembler.
String	getHibernateConfigFile() Returns the hibernate-config-file of the HibernateAssembler.
String	getHibernateEntity() Returns hibernate-entity of the HibernateAssembler.
Object	getItem(Map identity) Returns the item for the specified identity.
boolean	getPageQueriesFromDatabase() Set this to true if you want to page queries for this destination directly from the database.
String	getUpdateConflictMode() Returns the update-conflict-mode/code> of the HibernateAssembler.
void	initialize(String id, ConfigMap properties) This initialize method is called once for each destination.
boolean	isAllowHQLQueries() Returns if hql queries are allowed or not.
boolean	isUseQueryCache() Returns if hibernate's query cache is enabled.
int	refreshFill(List fillParameters, Object item, boolean isCreate) The hibernate assembler refreshes all outstanding fills whenever any item is created or modified.
void	setAllowHQLQueries(boolean allowHQLQueries) Sets if hql queries are allowed or not.
void	setDeleteConflictMode(String deleteConflictMode) Sets the delete-conflict-mode of the HibernateAssembler.
void	setHibernateConfigFile(String hibernateConfigFile) Sets the hibernate-config-file of the HibernateAssembler.
void	setHibernateEntity(String hibernateEntity) Sets hibernate-entity of the HibernateAssembler.
void	setPageQueriesFromDatabase(boolean pfdb)
void	setUpdateConflictMode(String updateConflictMode) Sets the update-conflict-mode of the HibernateAssembler.
void	setUseQueryCache(boolean useQueryCache) Sets whether hibernate's query cache is enabled.
void	start() The default implementation simply sets started property to true.
void	stop() The default implementation simply sets started property to false.
void	updateItem(Object newItem, Object prevItem, List changes) This method is called to update an item in hibernate.
boolean	useFillPage(List fillParameters) This method returns true for any queries which implement the page-by-page method for filling collections.

Methods inherited from class flex.data.assemblers.AbstractAssembler

addItemToFill, fill, getItems, isStarted, refreshFillStatusToName, removeItemFromFill

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LOG_CATEGORY

public static final String LOG_CATEGORY

Log category for HibernateAssembler.

See Also:

Constant Field Values

Constructor Detail

HibernateAssembler

public HibernateAssembler()

The Assembler class is constructed by Data Management Services so you do not need to construct this yourself.

Method Detail

initialize

public void initialize(String id,
                       ConfigMap properties)

This initialize method is called once for each destination. You can override this method if you want to add additional configuration properties. The ConfigMap class contains the properties inside of the properties tag for a given destination. The id parameter is the name of the destination.

The hibernate assembler uses two utility classes. The HibernateManager is a class which is created for each hibernate configuration file you specify. It manages the Data Management Services state for a group of related hibernate entitites. The HibernateType class is created for each assembler instance.

Specified by:

initialize in interface FlexConfigurable

Overrides:

initialize in class AbstractAssembler

Parameters:

id - the destination name for this assembler.

properties - the properties used to configure this destination underneath the properties tag.

start

public void start()

Description copied from class: AbstractAssembler

The default implementation simply sets started property to true. Subclasses should call super.start().

Specified by:

start in interface FlexComponent

Overrides:

start in class AbstractAssembler

stop

public void stop()

Description copied from class: AbstractAssembler

The default implementation simply sets started property to false. Subclasses should call super.stop().

Specified by:

stop in interface FlexComponent

Overrides:

stop in class AbstractAssembler

isAllowHQLQueries

public boolean isAllowHQLQueries()

Returns if hql queries are allowed or not.

Returns:

true if hql queries are allowed, false otherwise.

setAllowHQLQueries

public void setAllowHQLQueries(boolean allowHQLQueries)

Sets if hql queries are allowed or not. If true, allows clients to directly execute hql statements. This is useful for prototyping but is not recommended for production deployment due to the potential for untrusted code to execute queries it chooses in your deployment.

Parameters:

allowHQLQueries -

getPageQueriesFromDatabase

public boolean getPageQueriesFromDatabase()

Set this to true if you want to page queries for this destination directly from the database. The default behavior is to load all items with the query and then to page them from this list to the client only. If your queries have lots of items in them, it may make sense to only fetch the page the client wants and to go back to the database each time the client wants a new page.

If the client is paging to the database, there are two ways the size of the collection can be determined. The count method is called with the same set of fill parameters used by the fill method for this collection. If count returns -1 (the default), the array collection on the client will be dynamically sized. In this mode, the query fetches one more than the number of items requested by the page. If the query hits the end of the list, the collection size is known and set on the page response. If the query returns the one plus the page size items we requested, the collection size is set to include that extra item we fetched in the last page fetched. This extra item is not returned to the client however. When the client requests the page containing the one missing item, the next page is fetched which again requests one more than the page size.

If you want your client to know the correct size of the collection on the first page request, you need to provide a count method which takes the same set of fill parameters as the fill method that returns an accurate count. (For dynamically sized queries, the count method returns -1). for each query you define for a given "name", provide a "name.count" query which returns the number of items in the query. For HQL queries specified on the client, if the query starts with "from" we turn that query into a count query automatically by prepending the "select count(*)" string onto the query.

setPageQueriesFromDatabase

public void setPageQueriesFromDatabase(boolean pfdb)

getDeleteConflictMode

public String getDeleteConflictMode()

Returns the delete-conflict-mode of the HibernateAssembler. If the Hibernate entity class is configured to use Hibernate's automatic version or timestamp based concurrent conflict detection, that will override the configured conflict detection mode.

Returns:

delete-conflict-mode

setDeleteConflictMode

public void setDeleteConflictMode(String deleteConflictMode)

Sets the delete-conflict-mode of the HibernateAssembler. Valid values are NONE and OBJECT. If the Hibernate entity class is configured to use Hibernate's automatic version or timestamp based concurrent conflict detection, that will override the configured conflict detection mode.

Parameters:

deleteConflictMode - delete-conflict-mode

getHibernateEntity

public String getHibernateEntity()

Returns hibernate-entity of the HibernateAssembler.

Returns:

hibernate-entity.

setHibernateEntity

public void setHibernateEntity(String hibernateEntity)

Sets hibernate-entity of the HibernateAssembler. Optional. If not present, the adapter will assume that the Hibernate entity has the same name as the destination id. This property cannot be changed after startup.

Parameters:

hibernateEntity -

getHibernateConfigFile

public String getHibernateConfigFile()

Returns the hibernate-config-file of the HibernateAssembler.

Returns:

hibernate-config-file.

setHibernateConfigFile

public void setHibernateConfigFile(String hibernateConfigFile)

Sets the hibernate-config-file of the HibernateAssembler. If no config file is specified, then Hibernate uses its de facto standard hibernate.cfg.xml. This property cannot be changed after startup.

Parameters:

hibernateConfigFile - hibernate-config-file.

getUpdateConflictMode

public String getUpdateConflictMode()

Returns the update-conflict-mode/code> of the HibernateAssembler. If the Hibernate entity class is configured to use Hibernate's automatic version or timestamp based concurrent conflict detection, that will override the configured conflict detection mode.

Returns:

update-conflict-mode/code>

setUpdateConflictMode

public void setUpdateConflictMode(String updateConflictMode)

Sets the update-conflict-mode of the HibernateAssembler. Valid values are NONE, PROPERTY, and OBJECT. If the Hibernate entity class is configured to use Hibernate's automatic version or timestamp based concurrent conflict detection, that will override the configured conflict detection mode.

Parameters:

updateConflictMode - update-conflict-mode

isUseQueryCache

public boolean isUseQueryCache()

Returns if hibernate's query cache is enabled.

Returns:

true if hibernate's query cache is enabled, false otherwise.

setUseQueryCache

public void setUseQueryCache(boolean useQueryCache)

Sets whether hibernate's query cache is enabled.

Parameters:

useQueryCache -

count

public int count(List countParams)

Implements the count queries for the hibernate assembler. This implementation creats SQL queries which return the total number of entities for the type managed by this destination (i.e. it only supports the "all" query). You can override this method if you need to provide the count to your clients for specific custom hibernate queries.

Specified by:

count in interface Assembler

Overrides:

count in class AbstractAssembler

Parameters:

countParams - a list of parameters to the count method provided by the client invocation.

Returns:

the number of items in the collection specified by the countParameters.

getItem

public Object getItem(Map identity)

Returns the item for the specified identity.

Specified by:

getItem in interface Assembler

Overrides:

getItem in class AbstractAssembler

Parameters:

identity - a java.util.Map which contains key/value pairs for each identity property.

Returns:

the item corresponding to this identity property or null if there is no item for this identity.

fill

public Collection fill(List fillArgs,
                       int startIndex,
                       int numItems)

Implements the fill method for the hibernate assembler. This implementation supports named queries that are specified in the hibernate mapping file for this object type. When you use named queries, the first parameter is the name of the query, the second parameter specifies the rest of the parameters required by the hibernate assembler. If the named query uses positional parameters, the second parameter should be an Object[] or java.util.List of those parameters. If the named query uses named parameters, the second parameter should itself be a java.util.Map containing the parameter names mapped to the paramter values.

If the destination configuration sets the allow-hql-queries attribute to true, your client can also pass in arbitrary HQL queries. In this case, the first parameter is the string token: "flex:hql", the second parameter is the HQL string and the third parameter specifies the parameter set for the queries as either an array or a java.util.Map.

You can override this method to add additional queries or augment how hibernate queries are implemented in general.

Specified by:

fill in interface Assembler

Overrides:

fill in class AbstractAssembler

Parameters:

fillArgs - the list of fill parameters provided to the DataService.fill method on the client. Note that the first parameter - the ArrayCollection is not included in this list.

startIndex - the index in the fill collection from which this method will start retrieving records. The first record starts at 0, not 1 as is used in JDBC. If startIndex is -1, you should return the entire collection.

numItems - the number of recrods retrieved by this method

Returns:

a collection containing a list of items to be managed by the client. This collection should contain instances which all have valid identity properties and should not contain more than one instance with the same identity.

useFillPage

public boolean useFillPage(List fillParameters)

This method returns true for any queries which implement the page-by-page method for filling collections. Since the default hibernate fill method supports this for all queries, we return true here. If you override the fill method to use some custom logic, and you use the paging feature with that filled collection, and you do not override the fill variant which takes start and numberOfRows, you should override this method for that fill and return false so your fill method is called.

Specified by:

useFillPage in interface Assembler

Overrides:

useFillPage in class AbstractAssembler

Parameters:

fillParameters - the list of fill parameters provided to the DataService.fill method on the client. Note that the first parameter - the ArrayCollection is not included in this list.

autoRefreshFill

public boolean autoRefreshFill(List fillParameters)

The Hibernate assembler always refreshes fill methods automatically so this method returns true for all fills.

Specified by:

autoRefreshFill in interface Assembler

Overrides:

autoRefreshFill in class AbstractAssembler

Parameters:

fillParameters - Client-side parameters to a fill method that created a managed collection still managed by one or more clients.

Returns:

true if the fill identified by the fill parameters should be auto-refreshed or false if auto-refresh is off for this fill.

refreshFill

public int refreshFill(List fillParameters,
                       Object item,
                       boolean isCreate)

The hibernate assembler refreshes all outstanding fills whenever any item is created or modified. This method always returns the EXECUTE_FILL return code.

Specified by:

refreshFill in interface Assembler

Overrides:

refreshFill in class AbstractAssembler

Parameters:

fillParameters - the parameters which identify a fill method that is still actively being managed by one or more clients connected to this server.

item - The item which is being created or updated in a recently committed transactino.

isCreate - true if this item was just created operation, false if it was just updated.

Returns:

DO_NOT_EXECUTE_FILL - do nothing, EXECUTE_FILL - re-run the fill method to get the new list, APPEND_TO_FILL - just add it to the existing list, REMOVE_FROM_FILL - remove it from the sequence.

createItem

public void createItem(Object item)

Actually performs the createItem operation. We simply save this item in the hibernate session.

Specified by:

createItem in interface Assembler

Overrides:

createItem in class AbstractAssembler

Parameters:

item - the initial instance of the item to create.

updateItem

public void updateItem(Object newItem,
                       Object prevItem,
                       List changes)

This method is called to update an item in hibernate. If conflict detection is enabled, we perform conflict detection before performing the update and throw a DataSyncException if a conflict is detected. If the Hibernate entity class is configured to use Hibernate's automatic version or timestamp based concurrent conflict detection, that will override the configured conflict detection mode. For association properties, we pull the id out of the referenced item and look up the corresponding item in the session to be sure we do not try to put more than one instance with the same identity in the same hibernate session (that causes a hibernate runtime error). For collection properties, we also walk through and merge the new value into the old value removing and adding items as needed.

Specified by:

updateItem in interface Assembler

Overrides:

updateItem in class AbstractAssembler

Parameters:

newItem - the new version of the item with which to perform the update

prevItem - the original version of the item before these changes were made (used for conflict detection).

changes - the list of changed property names.

deleteItem

public void deleteItem(Object clientVersion)

Deletes the hibernate item. This method performs conflict detection if it is enabled and then deletes the hibernate entity from the database.

Specified by:

deleteItem in interface Assembler

Overrides:

deleteItem in class AbstractAssembler

Parameters:

clientVersion - the original version of the item on the client which the client intends to remove