flex.data.assemblers
Class HibernateAssembler

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

All Implemented Interfaces:

Assembler, FlexConfigurable, flex.data.adapters.JavaAdapterConstants

public class HibernateAssembler

extends AbstractAssembler

implements FlexConfigurable, 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

protected flex.data.DataDestination	dataDestination
protected String	destinationId
protected flex.data.assemblers.HibernateManager	hibernateManager
protected static Map	hibernateManagers
protected flex.data.assemblers.HibernateType	hibernateType
static String	LOG_CATEGORY

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.
protected org.hibernate.cfg.Configuration	createHibernateConfiguration(String hibernateConfigFile) This method returns the hibernate configuration for the given configuration file name.
void	createItem(Object item) Actually performs the createItem operation.
void	deleteItem(Object clientVersion) Deletes the hibernate item.
protected void	fetchObjectProperties(Object inst) Responsible for ensuring that all data that is needed by the serialization process has been fetched.
Collection	fill(List fillArgs) Implements the fill method for the hibernate assembler.
Object	getItem(Map identity) Returns the item for the specified identity.
protected void	handleHibernateException(RuntimeException ite, String type) This method is called when an exception occurs when processing a hibernate operation.
void	initialize(String id, ConfigMap properties) This initialize method is called once for each destination.
int	refreshFill(List fillParameters, Object item, boolean isCreate) The hibernate assembler refreshes all outstanding fills whenever any item is created or modified.
void	updateItem(Object newItem, Object prevItem, List changes) This method is called to update an item in hibernate.

Methods inherited from class flex.data.assemblers.AbstractAssembler

addItemToFill, getItems, removeItemFromFill

Methods inherited from class java.lang.Object

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

Field Detail

LOG_CATEGORY

public static final String LOG_CATEGORY

See Also:

Constant Field Values

hibernateManagers

protected static Map hibernateManagers

hibernateManager

protected flex.data.assemblers.HibernateManager hibernateManager

hibernateType

protected flex.data.assemblers.HibernateType hibernateType

destinationId

protected String destinationId

dataDestination

protected flex.data.DataDestination dataDestination

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.

createHibernateConfiguration

protected org.hibernate.cfg.Configuration createHibernateConfiguration(String hibernateConfigFile)

This method returns the hibernate configuration for the given configuration file name.

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)

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.

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.

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.

handleHibernateException

protected void handleHibernateException(RuntimeException ite,
                                        String type)

This method is called when an exception occurs when processing a hibernate operation. It does debug logging so we can capture details of the error before throwing the error to the caller.

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 FDS conflict detection. 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

fetchObjectProperties

protected void fetchObjectProperties(Object inst)

Responsible for ensuring that all data that is needed by the serialization process has been fetched. Hibernate has its own lazy flag which is the default for many properties. It will not fetch properties of an item until they are accessed. This must be done while the transaction is open. But we do not want to leave the transaction open while serializing state to the client as that can cause a bottleneck so this method fetches all of the state that will be required during the serialization process.

The basic rule used here is to do a deep traversal of the property value unless the property is marked as a lazy Data Management Services association. In that case, Data Management Services will only look at the id of the associated object so that is all we need to provide.

One awkward thing about this process is that event a lazy Data Management Services destination fetches the ids of the referenced objects in a collection property. Thus even if the collection is lazy, we need to at least traverse the collection enough to be sure the ids of the referenced items are available.

Also note that we need to be aware the object graphs can contain cycles so stop the traversal if we hit an object we have already visited.