Object-relational Map

Summary

• Purpose
• Scenario
• Structure & UML
• Example
• Applicability
• Strategies / Variants
• Benefits
• Liabilities
• Related Patterns

Purpose

Decouples active domain objects from the underlying data model and data access details. An Object-Relational Map object is responsible for mapping relational data to object-oriented concepts, allowing it to be changed independently of the application and its domain objects.

Scenario

The following figure illustrates how an Object-Relational Map decouples active domain objects from the underlying data and data model:

A sophisticated Object-Relational Map system would map database details using metadata. This versatile approach allows metadata to be changed without recompiling or updating the application. It is common to store mapping metadata in database tables and to define administration tools to allow users to view and update mapping details without having to understand the underlying metadata structure.

The most fundamental issue that an Object-Relational Map deals with is how to map relation database concepts to object-oriented concepts. Domain object mapping is responsible for translating a row from a given table to an object that exposes that row's columns as properties. This situation is shown below:

The following table shows a common strategy using C# and ADO.NET

In practice, things are not that simple. For example, an Object-Relational Map often hides relational data that an application might not need such as timestamp columns and other columns used purely to define table relationships. An Object-Relational Map may convert data in both directions (for example, BLOBs in Oracle) and calculate attributes on behalf of the application.

For example, the steps for generating an invoice within an order-processing application would be:

• Application requests an order and the Object-Relational Map returns an Order object.
• The application uses the Order object returned by the Object-Relational Map to get each order's order item. Order items should be implemented as properties on the Order object.
• The application uses the Order object properties (such as cost for each order item) to calculate the total value of the invoice.

Note that the application operates exclusively using domain objects and makes no explicit reference to the data model or to the underlying data accessors.

Implementing Object-Relational Map classes is usually a non-trivial undertaking. Writing an efficient, versatile and metadata-driven Object-Relational Map can be a difficult task. However, there are many commercial products that can be employed directly within your application.

Structure & UML

The above figure represents the static structure of one variety of an Object-Relational Map class. The IPersistenceManager interface defines database operations in terms of  generic domain object - it defines operations for reading/writing/deleting domain objects. This interface does not expose any database details as these are taken care of by the data accessor. A ConcretePersistenceManager implements IPersistenceManager for a specific domain object. A ConcretePersistenceManager reads/writes/deletes domain objects using the help of both MapMetadata class to describe domain object mapping to relational database table and IDataAccessor to access the database. A ConcretePersistenceManager therefore encapsulates data access and data model details as well as domain object mapping.

The sequence of operations begins when an application invokes the read operation on a ConcretePersistenceManager:

The ConcretePersistenceManager finds the relevant metadata that describes the mapping details, obtains relational data from the database and then creates a new domain object and initializes using the relational data and metadata.

Example

This example illustrates the order processing application described in the Scenario section. The active domain object in this example is OrderItem which represents a single item in any given order. The persistence manager is responsible for mapping the contents of OrderItem objects to the [OrderItems] table. At runtime, the persistence manager instantiates an OrderItem object for each row in the [OrderItems] table.  Each property in OrderItem corresponds to a column from [OrderItems] table. In the OrderItem class definition below, note that it is defined using pure object-oriented domain concepts and that there is no reference to the underlying data table: 

public class OrderItem
{
    /* Data members */
    private string m_strProductName;
    private long m_lOrderID;
    private long m_lProductID;
    private long m_lQuantity;
    private float m_fPrice;

    /* Constructor */
    public OrderItem( string name, long oid, long pid, long qty, float prc)
    {
        // Initialize member variables
    }

    /* Properties. Used mostly by persistence manager to set with database values */
    public string ProductName
    {
        get { return m_strProductName; }
        set { m_strProductName = (string)value; }
    }

    public long OrderID
    {
        get { return m_lOrderID ; }
        set { m_lOrderID = (long)value; }
    }

    public long ProductID { get { ... } set { ... } }
    public long Quantity { get { ... } set { ... } }
    public float Price { get { ... } set { ... } }

    /* Other public functions exposed by this domain object */
    ...
}

The Order class serves a similar purpose to OrderItem in that it represents the domain concept of a customer's order using object-oriented semantics. Again, the persistence manage is responsible for mapping the contents of Order objects to the [Orders] table:

public class Order
{
    /* Data members */
    private DateTime    m_dtOrderTime
    private long        m_lOrderID;
    private float       m_fTotal;
    private ArrayList   m_alOrderItems;         // Every Order object references a collection of OrderItems

    /* Constructor */
    public Order( DateTime odt, long oid, float totl, ArrayList items)
    {
        // Initialize member variables
    }

    /* Properties. Used mostly by persistence manager to set with database values */
    public DateTime  OrderTime
    {
        get { return m_dtOrderTime; }
        set { m_dtOrderTime = (DateTime)value; }
    }

    public ArrayList OrderItems
    {
        get { return m_alOrderItems; }
        set { m_alOrderItems = (ArrayList)value; }
    }

    public long  OrderID   { get { ... } set { ... } }
    public float Total     { get { ... } set { ... } }

    /* Other public functions exposed by this domain object */
    ...
}

Note how the Order object references a collection of OrderItems. This models the ONE-TO-MANY aggregation relationship between [Orders] and [OrderItems] tables.

Object-Relational Map objects do not define any mapping details. Instead the developer defines these mapping details using metadata, most commonly in XML. This XML can then either be stored in configuration files, or much-preferably in databases. Complex applications may require some custom-made GUI tools to graphically creates these mappings while less-complex applications may require you to code the XML by hand. A possible XML file for mapping [OrderItems] table to the [Order] domain object is shown below:

<Root>
    <!-- Data store definition --> 
    <DataStore>
        <Database server="..." database="..." uid="..." pwd="..." ></Database>
    </DataStore>

    <!-- Mapping definitions - object property to table field -->
    <MappingObjects>

        <!-- mappings for the OrderItem class -->
        <MappingObject class ="OderItem" table="OrderItems">
            <Property name="ProductName" column="product_name" type="string"></Property>
            <Property name="OrderID" column="order_is" type="long"></Property>
            <Property name="ProductID" column="product_id" type="long" primarykey="true"></Property>
            <Property name="Quantity" column="quantity" type="long"></Property>
            <Property name="Price" column="price" type="float"></Property>
        </MappingObject>

        <!-- mappings for the Order class -->
        <MappingObject class="Order" table="Orders">
            <Property name="OrderTime" column="order_timestamp" type="DateTime"></Property>
            ...
        </MappingObject>

    </MappingObjects>
</Root>

In general, it is easy to write a tool (perhaps a Visual Studio.NET add-in) that can read this XML mapping file and automatically generate code that was previously shown for OrderItem and Order. This tool (or add-in) can actually generate appropriate code and then add it as a new project file. Users will only need to create XML mappings and the tool takes care of generating code.

The next code block shows how all these pieces fit together. The application initializes a persistence manager to read the XML file, connect to the database using the <Database> element to get data, and finally initialize the appropriate mapping objects as indicated by the <MappingObject> elements.

// Create and initialize a persistence manager
PersistenceManager pm = PersistenceManagerFactory.GetPersistenceManager();
pm.Load( strMetadataFilePath );

// Create a new order object with a list of Order items
ArrayList alOrderItems = new ArrayList();
alOrderItems.Add( new OrderItem( ... ) );
alOrderItems.Add( new OrderItem( ... ) );
alOrderItems.Add( new OrderItem( ... ) );
Order order = new Order( ..., alOrderItems)

// Persist the order object to the database
pm.PersisteObject( order );

Applicability

Use this pattern when:

• You want to hide the physical data model and data access complexity from application logic and domain objects.
• You want to encapsulate domain-object mapping within a single component so that you can adapt to data model changes without changing the application code or domain object definitions.
• You want the versatility to map domain objects to multiple data models without changing application code or domain object definitions. This allows you to integrate your application with multiple data models regardless of how they are defined.

Strategies / Variants

Consider these strategies when designing Object-Relational Map classes

Unmapped attributes

In general, domain objects that participate in Object-Relational Map (like OrderItem and Order in the example above) often correspond to a row in a database table or join. However, not all of an object domain's properties are stored in a database. In some cases, they are computed or aggregated from different fields. These attributes are called unmapped attributes because they do not correspond to a single piece of relational data. Unmapped attributes do not typically present and issues as they can be derived from properties (attributed) already obtained by the domain object.

Object Identity

For a persistence manage to properly map domain objects to their corresponding rows in a table, you must define the notion of identity on both sided of the relationship. If a table defines a primary key, then it already defines a unique identity for its rows. Similarly, if a domain object defines one or more properties that map to the table's primary key, then the domain object has an identity. Two possible reasons for defining object identity are:

• Ability to update individual domain objects
  In the example given above, to account for the case where an application needs to update a single OrderItem, you need to introduce an [OrderItems].[OrderItemID] column as a primary key as well as the corresponding OrderItemID property in the OrderItem class. This enables the persistence manage to manage individual OrderItem domain objects without having to relay on the Order object. 
• Cache domain object
  A persistence manager may cache domain objects that are accessed frequently. This enables faster access to these domain objects. This variety of caching mechanism often use an identity attribute as the cache key since it uniquely identifies a domain object.

Aggregation Relationships

In databases, aggregation involves matching a foreign key in one table to a primary key in another table. Corresponding domain objects model similar relationships, but they translate to object aggregation in which one domain object directly references others (usually through a collection). It is common to describe relationships between tables as one of the following types:

• One-To-One
  Every row in table T1 corresponds to exactly one row in T2. Similarly, every instance of object A corresponds to exactly one instance of object B.
  
• One-To-Many
  Every row in table T1 corresponds to zero or more rows in T2. Similarly, every instance of object A corresponds to a collection of zero or more instances of object B.
  
• Many-To-Many
  Any number of rows in table T1 corresponds any number of  rows in T2. Similarly, every instance of object A corresponds to a collection of instances of object B, and every instance of object B corresponds to a collection of instances of object A. An alternate strategy for many-to-many relationship is to define a third table C that lists related keys from each table.

Regardless of the relationship, it is the responsibility of the persistence manager to resolve and manage object B instances when it deals with object A instances. In the previous example, there is a one-to-many relationship between Order and OrderItems classes. The Order class exposes this relationship through its OrderItems collection property.

The persistence manage can implement the corresponding data access operations using one or more of the following strategies:

• Use single join operations
  This is valid for read operations where the persistence manager issues a single join operation across the related tables. This join operation returns all the data necessary to populate a set of Order objects and their corresponding OrderItems. This approach cannot be used with updates and deletes.
  
• Use multiple query operations
  The persistence manager can issue two queries - one for each table. This works for reads, updates, and deletes.
  
• Use lazy initialization
  This is an alternative approach where the persistence manager does not populate aggregate domain objects until applications reference them. For example, the persistence manager only queries the [Order] table when then application references an unmapped Order object

Inheritance Relationships

It is common for domain objects to relate to each other by inheritance, but relational data does not support a similar concept. For example a Manager class may extend (or specialize) an Employee class by adding attributes that only apply to managers. It is common for a persistence manager to map these domain objects using one of these strategies:

• Concrete table inheritance
  Each type of concrete domain object is mapped to its own table. In this example, there would an [Employee] table that contains data for all employees that are not managers, and a [Manager] table that only contains data for all managers. [Manager] contains all columns in [Employee] as well as Manager-specific columns.
  
• Class table inheritance
  Map each class in the inheritance hierarchy to its own table. In this example, there would an [Employee] table that contains data common to employees and managers, and a [Manager] table that contains data specific to managers only. In this approach, [Manager] supplements [Employee].  
  
• Single table inheritance
  Map all domain objects within the same hierarchy to the same table. In this example, there is a single [Employee] table that contains columns that map to both employees and managers. These kind of tables should always include a column identifying the concrete type for each row. Manager columns should be set to null for rows that correspond to employees and vice versa. 

Single table inheritance makes query, batch update and batch deletes simpler and more efficient to implement since they only involve a single table. The same operations using concrete or class table inheritance require joins or multiple database operations. However, single table inheritance does not make the most efficient use of database storage as it requires the table to define the union of all attributes (columns) within an inheritance hierarchy.

Benefits

• Clean application code
  Application code that works exclusively with domain objects is much easier to understand and maintain that application code that includes data model and data access details.  
  
• Maps to alternate data models
  Metadata can be switched to use different databases without affecting application code. Encapsulating data model details within metadata enables you to make changes such as rearranging tables, moving to different platforms, or even moving to a different kind of data store such as XML without having to recompile application code.

Liabilities

• Dependence on third party commercial products
  If you use Object-Relational Map extensively, you are likely to encounter significant development effort unless you integrate with a commercial Object-Relational Map product.
  
• Limits application control of data
  Application code is limited to operations defined by the IPersistenceManager interface. Because it is the ConcretePersistenceManager that encapsulates data access details, it becomes harder to tune database operations, especially for commercial products

Related Patterns

The following patterns are related to the object-relation map patterns:

• Active Domain Object
  Mapping is implemented within active domain objects rather than in a single separate component. 
•