Key concepts of data management
All objects managed by a particular Data Management Service destination must have one or more identity properties that uniquely identify instances managed by that destination. These identity properties can be initially undefined when you create a new managed object. However, after the server has persisted the object, their values must be fixed for the lifetime of the object. The Data Management Service ensures that each client only works with a single managed version of each instance. After an instance is returned from the Data Management Service, if the client receives a new version of that instance it merges those changes into that instance. With this method, data model mapping remains simple even when a data model grows more complex.
For more information, see Uniquely identifying data items.
The Data Management Service distinguishes between two different types of objects: value objects and entities. The identity of a value object is determined by its values. Entities have one or more properties that, when combined, uniquely determine a fixed identity for the object. For example, a customer record in a database is typically an entity. Example value objects include primitive object types such as int and String, and complex objects such as objects that store the parameters to a query.
The Data Management Service only directly manages entities but also uses value objects as parts of the model. Identity properties must be value objects. Other properties of managed objects are treated as value objects unless a managed association is defined for that property. In that case, the property defines a reference to other managed associations.
The primary way to fetch data from the server in data management is by using a fill method. The fill method is passed an ArrayCollection object to populate and a list of parameters which define the query and returns a collection of objects that the destination manages. The fill method parameters are value objects that form a unique identity for a particular query. A set of fill parameters returns a consistent set of managed entities. The entities act as a key to identify the list of objects. Other clients using the same key get the same set of objects when you use the synchronization features of data management.
There are two ways to implement queries on the server. Using the default approach, you provide a method that takes the set of query parameters and returns the entire array collection. You can also use the paged-fill approach where your method takes additional start and count parameters. Paging works with either approach. In the first case, paging only pages from the client to the server. In the second case, you page directly from the client to the database.
The Data Management Service can manage both strongly typed objects, which have an explicit class, and weak typed or anonymous objects. In ActionScript, a weak typed object is represented as an instance of the Object class. In Java, it is represented by an object that implements the java.util.Map interface. The Data Management Service uses the standard LiveCycle Data Services ES serialization mechanism to convert from ActionScript to Java and that mechanism supports mixing strong and weak data types, and performing customized conversions between these classes in a flexible manner.
The Data Management Service must intercept the get and set property operations for its managed instances. This allows the Data Management Service to track changes made to managed objects from your application and to implement on-demand loading features. If you use a weakly typed object, the object is proxied by a dynamic object wrapper called ManagedObjectProxy, which performs this logic. The existence of this proxy is usually transparent to your application.
When you use a strongly typed class in ActionScript, the easiest way to add managed behavior to your object is to use the [Managed] metadata tag at the class level in your ActionScript class.
Modeling relationships between objects
The Data Management Service supports two basic approaches to modeling relationships in your object model code. You can manipulate identity properties directly in your object model, or you can model those relationships using associations, which are strongly typed references to objects of the associated type. You declare associations in XML elements in a destination definition. You can declare many-to-one, one-to-one, one-to-many, and many-to-many associations between objects.
Using identity properties in your model is a fairly simple approach but involves more code for fetching and managing the relationships. Instead of referring to related objects using the dot notation (a.b[i].c), you execute queries from a method you call explicitly.
There is no correct approach to how you model objects in every situation, and your choice is largely a matter of style. Queries are more flexible in terms of how you can fetch the data; it is easy to add new parameters to the query for sorting or filtering the query.
Associations manage membership of the query automatically. Using queries sometimes requires more work to make sure that membership changes in the query results are properly and efficiently updated on the clients. With queries, you must execute the query explicitly in ActionScript code, but with association properties you can leverage lazy and load-on-demand behavior so that queries are executed automatically as the application tries to fetch the data.
For more information, see Hierarchical data.
Each DataService component on the client manages the data for a particular destination. A destination is typically created for each type of data that you want to manage. For the most programming flexibility when you have inheritance in your data model, define a destination for each class and set the item-class attribute for the destination. One destination can extend another destination to mirror your class hierarchy, making it easier to manage complex object models. If you do not set the item-class attribute for a particular destination, that destination can manage arbitrary types of objects that share the same identity property and associations.
An adapter is responsible for updating the persistent data store in a manner appropriate to the data store type. The Java adapter delegates this responsibility to a class called an assembler class. For more information, see Understanding data management adapters.
Strategies for fetching objects
When you define an explicit association (in a one-to-one, many-to-one, one-to-many, or many-to-many element), you have several options for specifying how the client fetches the associated object. When you use the default mode in which the lazy attribute is set to false and the load-on-demand attribute is set to false, the associated object or objects are fetched when the referencing object is fetched.
If you set the lazy attribute of the association element to true, the identities of the associated object are fetched when the parent object is fetched. If you set the load-on-demand attribute to true, no information for the associated object is fetched when the parent object is fetched. Instead, the property value is fetched the first time the client asks for that value. For a one-to-many, many-to-one, or many-to-many association, you can additionally use the page-size attribute so that when you do fetch the value of the collection, it is retrieved one page at a time.
For more information, see Data paging.
The Data Management Service provides several ways to improve performance with large sets of data by incrementally paging data from the server to the client and from server to the database. For more information, see Data paging.
By default, LiveCycle Data Services ES encapsulates client-committed operations in a single J2EE distributed transaction. All client data changes are handled as a unit. If one value cannot be changed, changes to all other values are rolled back. For more information, see Using transactions.
The Data Management Service provides exceptions that let you handle conflicts between versions of data items on the client and server. For more information, see Handling data synchronization conflicts.