flex.data.assemblers
Interface Assembler

All Known Implementing Classes:

AbstractAssembler, HibernateAssembler, SQLAssembler

public interface Assembler

One option for implementing a Data Management Services Assembler is to write a Java class which implements this interface. If you define a Data Management Services destination which refers to a class which implements this interface you do not have to use the XML method tags such as sync-method, get-method to define your destination. Instead of directly implementing this interface, it is recommended that you extend the AbstractAssembler class. There is some chance this interface could be extended in future versions of the product but every effort will be made to ensure extensions of AbstractAssembler continue to work without code change.

See Also:

AbstractAssembler, DataServiceTransaction

Field Summary

static int	APPEND_TO_FILL Constant used as the return value from the refreshFill method.
static int	DO_NOT_EXECUTE_FILL Constant used as the return value from the refreshFill method.
static int	EXECUTE_FILL Constant used as the return value from the refreshFill method.
static int	REMOVE_FROM_FILL Constant used as the return value from the refreshFill method.

Method Summary

void	addItemToFill(List fillParameters, int position, Map identity) Called when a client adds an item to a filled collection.
boolean	autoRefreshFill(List fillParameters) This method can be used to help control how fill methods are refreshed by Data Management Services.
int	count(List countParameters) Retrieve the number of items for a given query with the supplied parameters.
void	createItem(Object item) Creates the item.
void	deleteItem(Object previousVersion) This is called when the client application removes an item managed by the destination corresponding to this assembler.
Collection	fill(List fillParameters) This method is called by the Data Management Service for any fill methods called by the client which are not configured in the configuration file explicitly using the fill-method tag.
Collection	fill(List fillParameters, int startIndex, int numberOfRows) This method is called by the Data Management Service for any paged-fill methods.
Object	getItem(Map identity) Retrieves an item with the specified Map of ids.
List	getItems(List identityList) Given a list of identity Maps, returns the list of items.
int	refreshFill(List fillParameters, Object item, boolean isCreate) If your fill methods are auto-refreshed, this method is called for each item that changes (either created or updated as indicated by the isCreate parameter).
void	removeItemFromFill(List fillParameters, int position, Map identity) Called when a client removes an item from a filled collection.
void	updateItem(Object newVersion, Object previousVersion, List changes) Updates the item.
boolean	useFillPage(List fillParameters) This method can be used to control whether a paged-fill method for a given set of parameters is used.

Field Detail

DO_NOT_EXECUTE_FILL

static final int DO_NOT_EXECUTE_FILL

Constant used as the return value from the refreshFill method. DO_NOT_EXECUTE_FILL tells Data Management Services not to execute the fill method for this newly updated or created item.

See Also:

Constant Field Values

EXECUTE_FILL

static final int EXECUTE_FILL

Constant used as the return value from the refreshFill method. EXECUTE_FILL tells Data Management Services to reexecute the fill method for this newly updated or created item.

See Also:

Constant Field Values

APPEND_TO_FILL

static final int APPEND_TO_FILL

Constant used as the return value from the refreshFill method. APPEND_TO_FILL tells Data Management Services to add this item onto the set of items in this filled collection if it is not already in the collection.

See Also:

Constant Field Values

REMOVE_FROM_FILL

static final int REMOVE_FROM_FILL

Constant used as the return value from the refreshFill method. REMOVE_FROM_FILL tells Data Management Services to remove this item from the set of items in this filled collection if it is in the collection.

See Also:

Constant Field Values

Method Detail

getItem

Object getItem(Map identity)

Retrieves an item with the specified Map of ids. Ids are stored with the key as the property name of the id property, the value as the value of the identity property.

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.

getItems

List getItems(List identityList)

Given a list of identity Maps, returns the list of items. The list should contain null entries for any ids which do not map to a valid item. This is an optimization for the case where the getItem method needs to be called repeatedly to retrieve a list of items.

Parameters:

identityList - a list of java.util.Map objects specifying the list of items.

Returns:

the list of items corresponding to the list of identities specified. If an item is not found, a null value should be placed into the list to indicate that.

createItem

void createItem(Object item)

Creates the item. Often, you fill in the identity properties unless those values were supplied by the client. If any errors occur for this operation, you can throw an exception of your choice to indicate that fact. The message of the exception is delivered to the client.

The Java class of the item supplied depends on the ActionScript class used by your client application. ActionScript to Java rules are by default used to convert the client object into a Java object. This will produce a java.util.Map for the item parameter if the client object is dynamic object or if that object does not have a RemoteClass alias mapping it to a Java class. If your assembler expects instances of a single specific Java class, you can use the item-class tag in your destination's configuration to specify a single class of which all java.util.Map instances are converted into before being passed to the assembler.

Parameters:

item - the initial instance of the item to create.

updateItem

void updateItem(Object newVersion,
                Object previousVersion,
                List changes)

Updates the item. The newVersion is always going to be present and contains the new version of the item. The previousVersion contains any state required for maintaining the integrity of this instance. Currently, it is always fully populated. However, in the future, Adobe anticipates this method to selectively include only the properties of the item required to maintain an item's integrity during an update. It might be null to disable optimistic concurrency detection.

The changes array provides the list of properties changed. You should interpret a null value as "any properties may have changed". If you have a property which has its own properties, only the top level property name will be included.

If the previousVersion conflicts with the current database copy of the item, you can throw a flex.data.DataSyncException to indicate this fact. In this case, you should provide the current version of the item in the database as the serverVersion parameter. This allows the client to resolve the conflict and resubmit a non-conflicting change or revert to the server's version. Your method can also throw any runtime exception to indicate that a general fault has occurred while processing this update.

Your updateItem method can modify changes sent in from the client and add additional properties. To do this you update properties in the newVersion and add additional property names to the changes property.

The Java class of the items supplied depends on the ActionScript class used by your client application. ActionScript to Java rules are by default used to convert the client object into a Java object. This will produce a java.util.Map for the item parameter if the client object is dynamic object or if that object does not have a RemoteClass alias mapping it to a Java class. If your assembler expects instances of a single specific Java class, you can use the item-class tag in your destination's configuration to specify a single class of which all java.util.Map instances are converted into before being passed to the assembler.

Parameters:

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

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

changes - the list of changed property names.

deleteItem

void deleteItem(Object previousVersion)

This is called when the client application removes an item managed by the destination corresponding to this assembler. In this case, your deleteItem method is called with the version of the item intended for removal on the client. This method can do conflict detection to ensure that the item has not been modified since this deletion event was scheduled. In this case, your deleteItem method can throw the flex.data.DataSyncException where it should provide the current version of the item as the serverVersion parameter.

This method can also thrown any runtime exception to indicate a general error to be returned to the client.

Parameters:

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

fill

Collection fill(List fillParameters)

This method is called by the Data Management Service for any fill methods called by the client which are not configured in the configuration file explicitly using the fill-method tag. If you have a matching fill-method definition for a given set of parameters, it is called instead of calling this method.

In general a fill method corresponds to a database query made on the server. The results of a fill method should be based solely on the parameters provided here - do not return different results of a fill for the same parameter set since Data Management Services is designed to try and keep all clients which use the same set of fill parameters viewing the same results.

Depending upon the number and type of fill method you need for this destination, it can be a good practice to use the first parameter as the name of the fill and the rest as the parameters to make it easier to identify the particular fill you are dealing with.

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.

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

boolean useFillPage(List fillParameters)

This method can be used to control whether a paged-fill method for a given set of parameters is used. This method will be called whenever paging is enabled and a client issues either a FILL or a PAGE request. If this method returns true, the paged-fill method will be called. If it returns false, the standard fill method will be called.

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.

fill

Collection fill(List fillParameters,
                int startIndex,
                int numberOfRows)

This method is called by the Data Management Service for any paged-fill methods. A paged-fill method is called to satisfy fill and page requests from the client when paging is enabled for the given destination. This method will be used when a paged-fill method is not configured in the configuration file explicitly using the paged fill-method child tag of the fill-method tag. If you have a matching paged-fill-method definition for a given set of parameters, it is called instead of calling this method.

This method corresponds to a fill method with the same parameter list. Its benefit is improved performance in that it only retrieves a page of records instead of the entire set.

This default implementation calls the correspoding fill method. This will forego any performance gain and return the entire cillection.

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.

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.

numberOfRows - 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.

count

int count(List countParameters)

Retrieve the number of items for a given query with the supplied parameters. This method is only necessary if your client code uses the corresponding count method on the DataService class.

When paging is enabled and this method is defined to return -1 , the client will be sent the number of records for the given query dynamically with each page request. This allows you to avoid an expensive count query for large data sets.

Parameters:

countParameters - 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.

addItemToFill

void addItemToFill(List fillParameters,
                   int position,
                   Map identity)

Called when a client adds an item to a filled collection.

You can use this method to track changes made to a filled collection by client applications. Usually the results of a fill are maintained by a query made on the server and so changes made by the client are temporary or replaced when the server has a chance to update the fill based on reexecuting the query. In some cases though, you may want to turn auto-refresh off for the fill, and track the changes made by the client to the filled collection. You might do this if the list of items returned for a given fill is maintained by an explicit list of object ids.

Warning: if you need clients to maintain a consistent order of items, you may not want to use this technique. If two clients insert different items into the same position at roughly the same time, each will have processed the inserts in different orders and so will have the two items swapped. You can ignore the position and maintain consistent lists where order is not critical or the client sorts the list.

Parameters:

fillParameters - the list of parameters which identify the fill that the client changed.

position - the index where a new item was added

identity - the identity of the item added at the specified position

removeItemFromFill

void removeItemFromFill(List fillParameters,
                        int position,
                        Map identity)

Called when a client removes an item from a filled collection. Like addItemToFill, you can use this method to monitor and record changes made by a client to a given filled collection.

Parameters:

fillParameters - the list of parameters which identify the fill that the client changed.

position - the index where a new item was removed

identity - the identity of the item removed at the specified position

autoRefreshFill

boolean autoRefreshFill(List fillParameters)

This method can be used to help control how fill methods are refreshed by Data Management Services. If this method returns true for a given set of fill parameters, it indicates that this fill method is to be auto-refreshed. In this mode, the Data Management Service calls your refreshFill method for each item of the appropriate type is created or updated. That method can determine whether or not we append this item to the existing list, re-execute the fill method, remove the item from the existing list, or do nothing. If this method always returns false, your refreshFill method is not called. In this case, you either use the DataServiceTransaction.refreshFill method to manually cause the fill to be reexecuted or you can let the clients changes to the fill update the assembler and other clients.

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

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

If your fill methods are auto-refreshed, this method is called for each item that changes (either created or updated as indicated by the isCreate parameter). It can return DO_NOT_EXECUTE_FILL if you want to leave the contents of the fill unchanged, EXECUTE_FILL if you want the data service to call your fill method, or APPEND_TO_FILL if you just want this changed item to be added onto the end of the list returned by the last fill invocation.

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.