| Package | flex.data.assemblers |
| Class | public class AbstractAssembler |
| Inheritance | AbstractAssembler  Object |
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 reexecute 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
| Method | Defined By | ||
|---|---|---|---|
| AbstractAssembler | |||
void addItemToFill(List fillParameters, int position, Map identity) Called when a client adds an item to a filled collection. | AbstractAssembler | ||
boolean autoRefreshFill(List fillParameters) This method can be used to help control how fill methods are refreshed by Data Management Services. | AbstractAssembler | ||
int count(List countParameters) Retrieve the number of items for a given query with the supplied parameters. | AbstractAssembler | ||
void createItem(Object item) Creates the item. | AbstractAssembler | ||
void deleteItem(Object previousVersion) This is called when the client application removes an item managed by the destination corresponding to this assembler. | AbstractAssembler | ||
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. | AbstractAssembler | ||
Collection fill(List fillParameters, int startIndex, int numberOfRows) This method is called by the Data Management Service for any paged-fill methods. | AbstractAssembler | ||
Object getItem(Map identity) Retrieves an item with the specified Map of ids. | AbstractAssembler | ||
Object getItem(Map identity, PropertySpecifier ps) Retrieves a specific subset of properties for the item identified. | AbstractAssembler | ||
List getItems(List identityList) Given a list of identity Maps, returns the list of items. | AbstractAssembler | ||
Collection getPagedCollectionProperty(Map parentIdentity, String propName, int startIndex, int num, PropertySpecifier spec) When you set paged-collection=true on a multi-valued association property, this method is used to retrieve the property's value. | AbstractAssembler | ||
int getPagedCollectionSize(Map parentIdentity, String propName) When you set paged-collection=true on multi-valued association property, this method is used to determine the size of the returned collection. | AbstractAssembler | ||
void initialize(String id, ConfigMap properties) | AbstractAssembler | ||
boolean isStarted() Returns whether the assembler is started or not. | AbstractAssembler | ||
int refreshFill(List fillParameters, Object item, boolean isCreate, Object prevItem, List changes) 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). | AbstractAssembler | ||
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). | AbstractAssembler | ||
String refreshFillStatusToName(int status) [static] Returns the string name of the status codes for the refreshFill method. | AbstractAssembler | ||
void removeItemFromFill(List fillParameters, int position, Map identity) Called when a client removes an item from a filled collection. | AbstractAssembler | ||
void start() The default implementation simply sets started property to true. | AbstractAssembler | ||
void stop() The default implementation simply sets started property to false. | AbstractAssembler | ||
void updateCollectionProperty(Map identity, String propName, UpdateCollectionChanges changes) When the client is using pagedUpdates for updating a collection property, when those changes are committed to the server, this method is used by the assembler to update the collection property. | AbstractAssembler | ||
void updateItem(Object newVersion, Object previousVersion, List changes) Updates the item. | AbstractAssembler | ||
boolean useFillPage(List fillParameters) This method can be used to control whether a paged-fill method for a given set of parameters is used. | AbstractAssembler | ||
| AbstractAssembler | () |
public AbstractAssembler()| 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.
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 |
| 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.
Note, if you define your fill method using the fill-method tag (rather than using the default fill method in the Assembler class) auto-refresh is determined by the auto-refresh tag not this method.
This implementation returns true - auto-refresh is on all for all fills.
Parameters
fillParameters — Client-side parameters to a fill method that created a managed collection still managed by one or more clients. |
| true if the fill identified by the fill parameters should be auto-refreshed or false if auto-refresh is off for this fill. |
| 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 or the useFillPage method returns true for the corresponding set of parameters.
This default implementation throws an error indicating that a count method for the supplied parameters is not defined.
When paged Filling is used and this method returns an accurate count the client will be able to adjust its UI components accordingly. For example the scroll bar on a DataGrid will be sized with respect to total collection size. However, if the count query is expensive, dynamic sizing may be enabled by defining this method to return -1. In this case the client's notion of the size will be incremented with each page request causing UI components such as the DataGrid to adjust with each page request.
Parameters
countParameters — a list of parameters to the count method provided by the client invocation. |
| the number of items in the collection specified by the countParameters. |
| 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.
Parameters
item — the initial instance of the item to create. |
| 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.
If your object model uses properties which are load-on-demand or using page-size on the association tag, these properties are not included in the version of the item supplied as the previous version.
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.
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. |
| 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.
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 records retrieved by this method |
| 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. |
| 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.
Parameters
identity — a java.util.Map which contains key/value pairs for each identity property. |
| the item corresponding to this identity property or null if there is no item for this identity. |
| getItem | () |
public Object getItem(Map identity, PropertySpecifier ps)Retrieves a specific subset of properties for the item identified. The PropertySpecifier argument provides an interface to determine which properties should be retrieved. The rest of the properties are not used in the returned instance and so do not need to be populated. This implementation just uses the regular getItem method. You only need to override this method if there are optimizations you can perform when a subset of the properties of the item are needed.
Parameters
identity | |
ps |
| 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.
Parameters
identityList — a list of java.util.Map objects specifying the list of items. |
| 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. |
| getPagedCollectionProperty | () |
public Collection getPagedCollectionProperty(Map parentIdentity, String propName, int startIndex, int num, PropertySpecifier spec)When you set paged-collection=true on a multi-valued association property, this method is used to retrieve the property's value. When paged-collection=false, getItem is called with the parent item and the property is retrieved from the returned item. With this method you can retrieve only the selected subset of requested items. You also can use the dynamic sizing feature in case the size of the collection is too large to efficiently compute.
This default implementation just returns null which means that getItem method will be used to retrieve the entire property value.
Parameters
parentIdentity — a Map containing the identity properties of the parent item. | |
propName — the name of the collection property. This property will have page-size set on the association to a non-zero value. | |
startIndex — the starting index of the items requested on the client | |
num — the number of items to return | |
spec — the PropertySpecifier indicating which properties of the requested items that should be fetched. |
| the numItems in the requested page or null if the entire collection should be fetched using getItem. |
| getPagedCollectionSize | () |
public int getPagedCollectionSize(Map parentIdentity, String propName)When you set paged-collection=true on multi-valued association property, this method is used to determine the size of the returned collection. If this method returns -1, the collection's size is determined using a dynamic sizing approach. The client sees the collection's size as one more than the last page requested. When that item is fetched another page is requested. When the assembler returns fewer items from the getPagedCollectionProperty method, the size of the collection is known.
Parameters
parentIdentity — a Map containing the identity properties of the parent item. | |
propName — the name of the collection property. This property will have page-size set on the association to a non-zero value. |
| the size of the collection |
| initialize | () |
| isStarted | () |
public boolean isStarted()Returns whether the assembler is started or not.
Returnstrue if the assembler is started; otherwise false. |
| refreshFill | () |
public int refreshFill(List fillParameters, Object item, boolean isCreate, Object prevItem, List changes)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.
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. | |
prevItem — if isCreate is false, this contains the previous item. Otherwise, it is null. | |
changes — if isCreate is false (we are processing an update, this contains the list of properties which were updated or null if all properties might have been updated. |
| 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. |
| 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.
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. |
| 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.
Parameters
status |
| 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.
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 |
| start | () |
public void start()The default implementation simply sets started property to true. Subclasses should call super.start().
| stop | () |
public void stop()The default implementation simply sets started property to false. Subclasses should call super.stop().
| updateCollectionProperty | () |
public void updateCollectionProperty(Map identity, String propName, UpdateCollectionChanges changes)When the client is using pagedUpdates for updating a collection property, when those changes are committed to the server, this method is used by the assembler to update the collection property. The UpdateCollectionChanges method contains the identities of the objects to insert and remove from the collection along with positions in the collection for these operations (used for ordered collections).
The default implementation here retrieves the parent item and from that the collection property. It then applies these changes to that collection property. For lists, it will add or remove the items at the given locations. For other collections it will append new items to the end of the collection and remove items that are to be removed.
Parameters
identity | |
propName | |
changes |
| 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.
If your object model uses properties which are load-on-demand or using page-size on the association tag, these properties are only included in the previous and new versions of the item if they are in the changes list. Otherwise, you can assume those properties have not changed.
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. |
| 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.
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. |
Send me an e-mail when comments are added to this page | Comment Report
Current page: http://livedocs.adobe.com/livecycle/8.2/programLC/programmer/javadoc/flex/data/assemblers/AbstractAssembler.html