Role Playing with Adaptation - kaisu1986/ATF GitHub Wiki

Adaptation is one of the most useful techniques in all of ATF and it abounds there.

In particular, DOM adapters employ adaptation to allow a single DomNode to take on many roles. This is what a DOM adapter does: a DomNode can be adapted to any DOM adapter defined for the DomNode's type. The DOM adapter class provides the methods and properties useful to handle the object in that role. It is especially useful to define DOM adapters on the type of the root DomNode so it can be adapted to many different types.

The main adaptation methods provided in the Adapters class are:

• As<T>(): adapt an object to the given type, returning null if no adapter found.
• Cast<T>(): adapt an object to the given type, raising an exception if no adapter found.
• Is<T>(): test if an adapter is available for an object for the given type.

To use a DOM adapter in an editor or any other ATF application, do the following:

• Define DOM adapters for types, usually in the type schema loader. For details on doing this, see Defining DOM Adapters for Types.
• Design DOM adapter classes for the types, deriving from DomNodeAdapter. These can be very basic, simply containing a few properties, or quite comprehensive. For a description of various things DOM adapters can do, see:
  • DOM Adapters Adapt: general capabilities of DOM adapters.
  • Wrapping Attributes and Elements in Properties: access attributes through C# properties.
  • DOM Adapters Listen: listen for events on DomNodes.
  • DOM Adapters Validate: validate the data in a DomNode.

If you look for all the occurrences of the adaptation methods in the ATF Simple DOM Editor Sample, you find that all of them are used with DOM adapters! Consider the IDocumentClient.Show() method in the Editor class:

public void Show(IDocument document)
{
    EventSequenceContext context = Adapters.As<EventSequenceContext>(document);
    m_controlHostService.Show(context.ListView);
}

The document parameter implements IDocument. In Simple DOM Editor, the IDocument implementer is EventSequenceDocument:

public class EventSequenceDocument : DomDocument, ISearchableContext

As noted in IDocument Interface Implementation, DomDocument implements IDocument. Because the EventSequenceDocument class derives from DomDocument, the IDocument document parameter refers to an EventSequenceDocument instance.

Show() is attempting to adapt this IDocument to the EventSequenceContext DOM adapter. Here is a partial list of DOM adapters defined for types in Simple DOM Editor (see Define DOM Extensions for the entire list):

Schema.eventSequenceType.Type.Define(new ExtensionInfo<EventSequenceDocument>());
Schema.eventSequenceType.Type.Define(new ExtensionInfo<EventSequenceContext>());

Other uses of As<T>(), Cast<T>(), and Is<T>() in Simple DOM Editor employ similar adaptations. These adaptations make it easier to access all the different kind of objects you need to implement an editor.

In summary, DOM adapters make it easier to implement the interfaces you need in an editor.