A hierarchical collection is hierarchical data that includes at least one complex object whose properties are not simple primitive values. For example, consider a collection that contains a Person object that has an Address property, which itself has street, city, and state properties.

There are three techniques for managing hierarchical data with the Data Management Service:

Hierarchical values approach 

A single Data Management Service destination manages an entire tree of data. In this approach, you treat the complex property as a value object.

Managed associations approach 

You define a parent destination that has declared associations to child destinations, which manage the values of the properties of the child objects. In this approach, the complex property references other entities.

Query approach 

You implement a relationship between two objects using queries where one of the parameters of a fill method defined in an assembler is the property defined as the identity property of the related object.

You can use one of these approaches, or you can combine approaches on a property-by-property basis.

In the hierarchical values approach and the managed associations approach, the parent destination returns the same graph of objects from its fill invocation. However, in the hierarchical values approach, the adapter of the parent object is responsible for saving the state of the entire complex property. The parent is also responsible for updating the entire graph in response to a sync invocation; on any change, it receives the complete new graph for the object and updates that graph with any changes.

For the managed associations approach, the parent destination manages the identity properties of the referenced child objects and the relationship between the parent and child objects. The child assembler owns the state of the child objects. A side benefit of using the managed association approach is that you can use destinations independently of each other in one application, while using them together in another application.

In the managed associations approach, the configuration for the parent destination contains an additional element that defines an association for the child object that has its own destination. This association tag refers to the separate destination that is responsible for managing the state of the child object.

When you use the hierarchical values approach or the managed association approach, you either mark each class in the top-level object graph of managed classes with the [Managed] metadata tag or explicitly implement the mx.data.IManaged interface. This ensures that the managed objects support the proper change events and that getter methods for one-to-one association properties that are lazily loaded can throw ItemPendingErrors. For more information about lazy loading and ItemPendingErrors, see The managed association approach.

The following example shows the code for an ActionScript class that uses the [Managed] metadata tag. This Employee class is used in an ArrayCollection of Employees, which is used as a property of a Company class.

package samples.crm
{
    [Managed]
    [RemoteClass(alias="samples.crm.Employee")]
    public class Employee {
        public var employeeId:int;
        public var firstName:String = "";
        public var lastName:String = "";
        public var title:String = "";
        public var phone:String = "";
        public var email:String = "";
    }
}

The following example shows a class that implements the mx.data.IManaged interface instead of using the [Managed] metadata tag. When you implement mx.data.IManaged, you must support the mx.core.IUID interface, which requires a uid property. You also must include the referenceIds and destination variables declared under the last comment block in this class.

import mx.core.mx_internal;
import mx.data.Managed;
import mx.data.IManaged;
import mx.utils.UIDUtil;

    [RemoteClass(alias="foo.bar.Customer")]
    public class Customer implements IManaged {
        public function Customer() {
        super();
    }

    [Bindable(event="propertyChange")]
    public function get firstName():String {
        _firstName = Managed.getProperty(this, "firstName", _firstName);
        return _firstName;
    }

    public function set firstName(value:String):void {
        var oldValue:String = this._firstName;
        _firstName = value;
        Managed.setProperty(this, "firstName", oldValue, _firstName);
    }
// all implementors of IManaged must support IUID which requires a uid
// property
    [Bindable(event="propertyChange")] 
    public function get uid():String {
        // If the uid hasn't been assigned a value, just create a new one.
        if (_uid == null) {
            _uid = UIDUtil.createUID();
        }
        return _uid;
    }

    public function set uid(value:String):void {
        _uid = value;
    }
// These are special requirements of any object that wants to be
// "managed" by a DataService.
// The referencedIds is a list of object IDs that belong to properties that
// are lazily loaded.
// The destination is used to look up metadata information about the
// associations this object has been configured with in the
// flex-dataservices.xml file located at the remote destination.

    mx_internal var referencedIds:Object = {};
    mx_internal var destination:String;

    private var _firstName:String;
    private var _uid:String;
}