There are two types of managed collections of objects: fills and managed associations. A fill is usually a query defined by a set of parameters called fill parameters, which should always identify a globally consistent set of values. Although one of the fill parameters can be a query string such as an HQL query for Hibernate, security can be compromised if you expose the ability for ad hoc queries to be formed from untrusted client code. A managed association is a relationship between two destination that you declare in a destination definition in the data-management-config.xml file; for more information, see Hierarchical data.

When you set the autoSyncEnabled property of the client-side DataService component to true before executing the fill, the results are synchronized with changes detected by other clients. In this case, the parameters of the fill method should identify a globally consistent set of values. In other words, if from some other session another client sends the same fill parameters, they get the same results.

Typically, fill parameters are primitive values such as ints or strings that are used in queries. You can use complex objects, but in that case, the properties must serialize to the server and back again, and the values of the properties must be identical after they return. They should follow the value object pattern and override the equals() method. A copy of the fill parameters is sent to the server as part of the query and returned along with any message returned from the server that updates that collection, so avoid large object graphs as part of your fill parameters and ensure that they serialize to the server and back again.

Maintaining object identities

Each object managed by the Data Management Service must have one or more properties that uniquely identify the object value. These property values can be assigned on the server or on the client.

When the server assigns identities, the identity properties usually include the values of the primary key of the object. If you use identity properties that are not primitive types such as ints or Strings, make sure that your client-side and server-side identity properties serialize to each other as with other managed properties. In other words, they should follow the value object pattern. Identity properties that are not primitive types also must override the java.lang.Object.equals() and java.lang.Object.hashcode() methods. A FaultEvent is thrown when you specify a name that does not exist on the object in the property attribute of the identity element in a destination definition on the server.

When identities are assigned on the client, if you are using any syncing features, the identities must be unique across all clients. To avoid one client seeing the data of another client, you can include a value that is not known to other clients using the mx.utils.UIDUtils.createUID() method, or your session ID, or some other unique identifier you get from the server.

For more information, see Uniquely identifying data items.

About the DataStore object

The Data Management Service keeps outgoing and incoming data changes in a client-side object called DataStore. There are two modes for choosing the default DataStore instance: shared or not shared. If you use a shared DataStore instance, all DataService components that use the same channel set also use the same DataStore instance. A shared DataStore instance is used in the following situations:

1. The DataService component uses runtime configuration; it does not compile in the destination information using the -services compiler option.
2. The DataService component has one or more association element (for example, a one-to-many element).
3. The destination that a DataService component uses is referred to by an association element in another destination.

You can have independent DataStore instances if the data is totally independent. If you have an independent DataService component, the default depends on whether you specify your configuration in configuration files and compile the configuration in the SWF file. If you do compile in the configuration, you get an independent data store. If you do not, it isn't possible to discover whether you are using associations early enough in the initialization process, so a shared DataStore object is created.

If you want to change the default, you can create your own DataStore object and manually assign it to the dataStore property of one or more DataService instances. Do this when you first initialize your DataService component before you have called any other DataService methods, such as fill() or getItem().

When you call a DataService component commit() method, it commits all of the changes for the DataStore object, which include the changes for all DataService components that share that DataStore object. Similarly, when you change one DataService component autoCommit property, the value changes for all DataServices components that share the same DataStore object.

The DataStore.CommitQueueMode property controls how commits are queued to the server. By default, the client sends commit requests one at a time. In other words, the client waits for the result or failure of the first commit before sending the next one. If a batch fails, all messages are put back into the uncommitted queue so there is no possibility of receiving a batch with potentially stale changes. This is a conservative policy from a performance perspective. Many servers have conflict detection that would detect errors on those subsequent batches anyway, and can introduce unnecessary performance delays in certain data streaming applications.

You can also choose the auto mode. This mode checks for simple dependencies between any outstanding batches and the next batch to commit. If there are none, it sends the new batch. If there has been an update or delete request that depends on an outstanding create request, it holds the update or delete request until the create is completed. This imposes some overhead on each commit to check for dependencies. You can also set the value to NOWAIT. In this mode, the Data Management Service just commits the batches without checking dependencies. This is the fastest mode. However, there can be issues if the server does not properly handle update requests that depend on create requests without identity properties defined.