flex.data.assemblers
Class AbstractAssembler

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

All Implemented Interfaces:

Assembler, FlexComponent, FlexConfigurable

Direct Known Subclasses:

HibernateAssembler, SQLAssembler

public class AbstractAssembler
extends Object
implements Assembler, FlexComponent

You can implement a Data Management Services Assembler by extending this AbstractAssembler class. When you extend this class, you do not need to specify the methods via the XML tags in the Data Services configuration (if you also specify the XML tags, the methods specified in the XML tags will be used instead of the methods in this interface).

When you extend this abstract class, you then override methods as required to support your clients. If clients use the fill method, you need to provide a matching implementation of the fill method in this interface. You should override the getItem method if clients call getItem, or if you enable paging with cache-items set to false, or if any other associations use this destination for a lazy managed association property. You must provide createItem, updateItem, and deleteItem methods if your clients create any new items, update items of this type or delete items. The default implementation of these methods in this class is to throw an error indicating that the method is not implemented.

This class also has two methods you override if you want to change how the contents of fill methods are updated as new items are created or updated. The default is to rexecute fill methods after each transaction which creates or updates items of the type returned by the fill (auto-refresh=true). You can change this for all fills or for a specific fill by overriding the autoRefreshFill method. It is provided the fill parameters that define that query. You return false if you do not want to reexecute that fill method automatically. If a fill is not refreshed automatically, there are two ways you can still update it. The client can change the filled collection directly and the changes it makes will be propagated to other clients. Alternatively, you can use the DataServiceTransaction.refreshFill method to explicitly cause that fill to be refreshed as needed. Often this call is placed into the createItem or updateItem methods of your assembler.

If auto-refresh is true for a given fill, you can also avoid reexecuting the fill method unless it is absolutely necessary. To do this, you override the refreshFill method on this class. This method is called before we execute the fill when auto-refresh is true for each newly created item or updated item managed by this destination. You are given the new version of the item and your refreshFill method returns one of the constants: EXECUTE_FILL (to cause the fill to be executed), ADD_TO_FILL to add this item to the fill, REMOVE_FROM_FILL to remove it, and DO_NOT_EXECUTE_FILL if this change should not affect the contents of the fill.

Note that assemblers and clients can either use strongly typed objects or weakly typed objects. On the client, weakly typed objects are dynamic objects of type Object. On the server, weakly typed objects are those which implement the java.util.Map interface. You are not required to explicitly define the type or types used by an assembler. By default, the assembler can return whatever types it wants from the fill, and getItem methods. The clients should be coded to expect whatever types these are converted to after they are serialized from Java to ActionScript. Similarly, the assembler by default should be coded to expect whatever types are sent in by the clients. The ActionScript objects there are converted to Java by the serialization process, and these objects are passed directly to the assembler.

If your assembler returns strongly-typed instances and there is no corresponding ActionScript class mapped to that type, with no configuration your assembler will be called with instances of java.util.Map not the class your assembler returned originally. The type info is lost when the object is converted from Java to ActionScript and back again. If your assembler only expects instances of a single class you can use the <item-class> tag as part of your destination configuration to specify this class and Data Management Services will convert the java.util.Map to this class before calling your assembler.

See Also:

DataServiceTransaction

Field Summary

Fields inherited from interface flex.data.assemblers.Assembler

APPEND_TO_FILL, DO_NOT_EXECUTE_FILL, EXECUTE_FILL, REMOVE_FROM_FILL

Constructor Summary

AbstractAssembler()

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.
void	initialize(String id, ConfigMap properties) Initializes the component with configuration information.
boolean	isStarted() Returns whether the assembler is started or not.
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).
static String	refreshFillStatusToName(int status) Returns the string name of the status codes for the refreshFill method.
void	removeItemFromFill(List fillParameters, int position, Map identity) Called when a client removes an item from a filled collection.
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 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.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractAssembler

public AbstractAssembler()

Method Detail

initialize

public void initialize(String id,
                       ConfigMap properties)

Description copied from interface: FlexConfigurable

Initializes the component with configuration information. The id parameter contains an identity you can use in diagnostic messages to determine which component's configuration this is. The configMap parameter contains the properties for configuring your component.

Specified by:

initialize in interface FlexConfigurable

start

public void start()

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

Specified by:

start in interface FlexComponent

stop

public void stop()

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

Specified by:

stop in interface FlexComponent

isStarted

public boolean isStarted()

Returns whether the assembler is started or not.

Specified by:

isStarted in interface FlexComponent

Returns:

true if the assembler is started; otherwise false.

getItem

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

Specified by:

getItem in interface Assembler

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

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

This method is implemented by repeatedly calling getItem so you do not need to override it unless you can provide a more efficient implementation.

Specified by:

getItems in interface Assembler

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

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

Specified by:

createItem in interface Assembler

Parameters:

item - the initial instance of the item to create.

updateItem

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

Specified by:

updateItem in interface 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

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

Specified by:

deleteItem in interface Assembler

Parameters:

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

fill

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

This default implementation simply throws an error indicating that the fill with the supplied parameters is not defined.

Specified by:

fill in interface Assembler

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.

fill

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

Specified by:

fill in interface Assembler

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. If startIndex is -1, you should return the entire collection.

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.

useFillPage

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

Specified by:

useFillPage in interface Assembler

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.

count

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

This default implementation throws an error indicating that a count method for the supplied parameters is not defined.

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

Specified by:

count in interface Assembler

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

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

Specified by:

addItemToFill in interface Assembler

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

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

Specified by:

removeItemFromFill in interface Assembler

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

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

The implementation of this method enables auto-refresh for all fills.

Specified by:

autoRefreshFill in interface Assembler

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)

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.

The implementation of this method reexecutes all fills.

Specified by:

refreshFill in interface Assembler

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.

refreshFillStatusToName

public static String refreshFillStatusToName(int status)

Returns the string name of the status codes for the refreshFill method.