You use fill methods to implement queries that return a collection of items for a particular destination. When a client executes a fill method with its DataService.autoSyncEnabled property set to true, it listens for changes to the results of this query so that it can update the list displayed on the client. By default, the Data Management Service implements this functionality by using an technique called auto-refresh, which usually ensures that the client results are in sync with the database. With auto-refresh, whenever either the client or the server push API creates or updates an item, the Data Management Service re-executes any fill() methods currently managed on active clients. The Data Management Service compares the identity properties of the returned items to its cached results. If any have been added or removed, the Data Management Service builds an update collection message that it sends to the clients that have that fill method cached. For simple applications, auto-refresh could be all you require; however, when the number of fill methods with unique parameters managed by clients grows large, the auto-refresh technique can result in the execution of many unnecessary queries.

You can keep fill methods from being executed unnecessarily in several ways. You can disable auto-refresh, and use the refreshFill() method of the flex.data.DataServiceTransaction class (the server push API) to explicitly invalidate a fill or set of fill methods. You explicitly invalidate a fill or set of fill methods by specifying a pattern that matches the parameters of the fill methods you want to refresh. Alternatively, you can leave auto-refresh enabled, and set it so that it only re-executes a fill method when a specified item changes the fill results. Another option is to disable auto-refresh and call the addItemToFill() or removeItemFromFill() methods to make explicit changes to an individual filled collection.

When you leave auto-refresh enabled, you supply a method that is called for each item that is created or updated for each unique set of fill parameters currently managed on active clients. This method returns a value that indicates how the fill should be treated for that change. How this method works depends on whether your assembler implements the Assembler interface or uses XML-based fill-method and sync-method elements in a destination.

Detecting changes with the Assembler interface approach

When you implement the Assembler interface, a refreshFill() method is called for each active fill managed on the client. The refreshFill() method is given the list of fill parameters and the changed items and returns one of three codes that indicate whether the fill should be re-executed, the item is appended to the fill, or the fill should be left unchanged for this operation.

Detecting changes with the fill-method approach

When you use the fill-method approach, you define a fill-contains-method element that points to a method in your Assembler class. That method takes the changed or created item and the List of fill parameters and returns true or false depending on whether the item is in that fill result. If the fill is not ordered and the method returns true, the item is added to the end of the list of managed items for that fill. If the fill is ordered and you return true, the fill method is re-executed to get the proper ordering of the list. If the method returns false, the fill method is left as is for that update.

The following example shows fill-method elements with fill-contains-method elements for unordered and ordered fills:

<fill-method>
    <name>loadUnorderedPatternGroups</name>
    <params>java.lang.String,java.lang.Boolean</params>
    <ordered>false</ordered>
    <fill-contains-method>
        <name>unorderedPatternContains</name>
    </fill-contains-method>
</fill-method>
<fill-method>
    <name>loadOrderedPatternGroups</name>
    <params>java.lang.Boolean,java.lang.String</params>
    <ordered>true</ordered>
    <fill-contains-method>
        <name>orderedPatternContains</name>
    </fill-contains-method>
</fill-method>

The following example shows the unorderedPatternContains() and orderedPatternContains() methods in the corresponding assembler:

...
    public boolean unorderedPatternContains(Object[] params, Object group) {
        AssocGroup g = (AssocGroup)group;
        if (g.getName().indexOf((String)params[0]) != -1)
        return true;
        return false;
}

    public boolean orderedPatternContains(Object[] params, Object group) {
        AssocGroup g = (AssocGroup)group;
        if (g.getName().indexOf((String)params[1]) != -1)
        return true;
        return false;
}