XObject

The XObjectBuilder

The XObjectBuilder static class provides methods for creating instances from IXObject interfaces.

T xObject = XObjectBuilder.FromXDoc<T>(XDoc doc);

T xObject = XObjectBuilder.FromXml<T>(string xml);

T xObject = XObjectBuilder.New<T>();

[XObjectRoot("user")]
public interface IUser : IXObject {
  ...
}

Defining XPath's by Naming Convention

By default XObjectBuilder will infer an xpath based on simple naming conventions. The rules used for xpath inference are:

• The Accessor name will be lower-cased (Foo becomes foo)
• CamelHumps insert hyphens in the lower-cased name (i.e. FooBar becomes foo-bar)
• Underscores are replaced with / for Xpath (i.e. Foo_Bar becomes foo/bar)
  • Leading and trailing underscores are ignored
• A lower case accessor is treated as an attribute (i.e. foo becomes @foo)
  • the only lower case considered as attribute is the very last segment of the name

Of course these conventions could be combined so that an accessor named Foo_barBaz becomes foo/@bar-baz.

<user id="...">
    <name>...</name>
</user>

Can be represented by the model

public interface IUser : IXObject {
    int id { get; }
    string Name { get; }
}

Basic Attribute markup

If the naming conventions are not sufficient for XPath inference, or the different naming conventions are desired, the XObjectPath attribute can be used on an accessors to define an exact xpath.

[XObjectPath("name/first)]
public string FirstName { get; set; }

Built-in Accessor Types

XObject's as Accessor Types

In order to represent deeper hierarchies of Xml, an IXObject Accessor can be another IXObject, allowing for the creation of arbitrarily complex object graphs.

For example

<user>
    <name>...</name>
    <email>...</email>
    <home-address>
        <street>...</street>
        <city>...</city>
    </home-address>
    <work-address>
        <street>...</street>
        <city>...</city>
    </work-address>
</user>

could be consumed and represented by the following two interfaces

public interface IUser : IXObject {
    public string Name { get; set; }
    public string Email { get; set; }
    public IAddress HomeAddress { get; set; }
    public IAddress WorkAddress { get; set; }
}

public interface IAddress : IXObject {
    public string Street;
    public string City;
}

Underlying XDoc is only re-written when access to the XDoc is invoked

In the interest of efficiency IXObject does not clone the source XDoc, but assumes that it's the authoritative owner. If an existing XDoc is used to create an IXObject, it's possible to hold on to the original XDoc and continue to modify it, but this will produce unexpected results. XObject uses auto-initialized backing fields to store values set on the instance and the underlying XDoc is only modified is the AsDocument or this[xpath] accessors are invoked.

Holding on to references of Accesor values is not recommended

The behavior is not deterministic. The value may change as other accesses occur, and conversely changes to the references may or may not affect the XObject, since whether it's a lazy reference or a new instance of the value cannot be determined.

XDoc Accessor types may have their root rewritten

An accessor of type XDoc assumes that the doc's root is named the same as the last element part of the Accessor's XPath. Generally, using XDoc, root names are ignored anyhow, so this is not much of an issue. However, the above caveat of lazy writing applies here as well, i.e. if the Accessor is set, that Accessor will continue to reference the set XDoc (and it's incorrect root) until the XDoc is rewritten.

The IXObject interface

The IXObject interface is the base for all XObjects, providing basic access to the underlying XDoc.

public interface IXObject {
    XDoc this[string path] { get; }
    XDoc AsDocument { get; }
}

XObjects neither loose any of the original data, even if not exposed, nor do they fail if the XPath of an Accessor defined on the interface does not exist in the XDoc. XObject is not meant to validate or enforce schema, simply to provide an interface to the data model that is easier to read, type safe and more friendly to C# programming.

XObject Attributes

[XObjectRoot(string rootElement)]

[XObjectPath(string xpath)]

<html>
    <head>
        <title>Foo</title>
    </head>
    ...
</html>

[XObjectPath("head/title")
string Title { get; }

[XObjectTypeConverter(Type converterType)]

public interface IXObjectTypeConverter {
    bool CanConvert(Type t);
    object Convert(XDoc doc);
    bool CanConvertBack { get; }
    void ConvertBack(XDoc doc, object value);
}

public interface IXPathDocBuilder {
    XDoc BuildXDoc(XDoc rootDoc, string xpath, int nodeCount);
    bool CanHandle(string xpath, bool isNodeCollection);
}

Collection Accessors

XObjectBuilder supports four types of collections natively:

• Array
• IEnumerable<T>
• ICollection<T>
• IList<T>

All collections except IEnumerable<T> require a type that has native support for a setter or have an XObjectTypeConverter<T> that provides a ConvertBack delegate. While Array may seem like a read-only collection, it still allows the setting of items in the array.

Advanced Object Graphs

Any IXObject can be a return type of an IXObject Accessor and it will automatically be built from the original XDoc.

<user>
    <name>...</name>
    <groups>
        <group id="...">
            <name>...</name>
            <permissions>
                <permission>read</permission>
                <permission>write</permission>
            </permissions>
        </group>
    <groups>
</user>

The above document could be wrapped by a contract like this:

public interface IUser : IXObject {
    
    string Name { get; }
    IList<IGroup> Groups { get; }
}

public interface IGroup : IXObject {
    
    string Name { get; }
    
    [XObjectPath("permissions[permission='read']")]
    [XObjectTypeConverter(typeof(XObjectNotEmptyConverter))]
    bool CanRead { get; }

    [XObjectPath("permissions[permission='write']")]
    [XObjectTypeConverter(typeof(XObjectNotEmptyConverter))]
    bool CanWrite { get; }
}

Notice that IGroup has no coupling to IUser, but simply assumes that it will be provided an XDoc that is rooted such that i can find the name and permissions elements.

The XObjectBuilder<T> and XObjectBuilderRepository

By default the builder system for IXObject is hidden behind static accessors on XObjectBuilder. However, behind the scenes, a repository of builders is cached, both for efficiency and because the nature of IXObject graphs requires that the same builders are accessible for construction of subsequent objects. The repository system can be manually accessed if more control over the XPathDocBuilders and Converters is needed, or if XObjectBuilder is to be used in an Inversion of Control Container.

T xObject = XObjectBuilder.New<T>();

T xObject = XObjectBuilder.FromXDoc<T>(XDoc doc);

T xObject = XObjectBuilder.FromXml<T>(string xml);

// assuming that the repository is pulled from an IoC container
IXObjectBuilderRespository repository = container.Resolve<IXObjectBuilderRespository>();
XObjectBuilder.SetRepository(repository);

public interface IXObjectBuilderRepository {
    IEnumerable<IXPathDocBuilder> DocBuilders { get;}
    IEnumerable<IXObjectTypeConverter> TypeConverters { get; }
    XObjectBuilder<T> GetBuilder<T>() where T : IXObject;
    object GetBuilder(Type t);
}

void RegisterDocBuilder(IXPathDocBuilder docBuilder);
void RegisterConverter<T>(IXObjectTypeConverter<T> typeConverter);