Upcasting

• Sep 15, 2020
• 5 minutes to read

When using persistent class hierarchies, you often have to combine base and derived classes in a single query. However, this is challenging since the derived classes obviously have an extended set of properties. The article below shows how to reference these properties using the Upcasting feature.

Suppose we have the following persistent class hierarchy. The CustomerBase class is the base class that implements properties that are common to all customers. The CustomerRegistered and CustomerTrialed classes extend the base functionality by implementing customer specific properties. This hierarchy is displayed in the image below.

The code below describes the persistent class hierarchy:

Persistent Class Hierarchy

C#

using DevExpress.Xpo;

public class CustomerBase : XPObject {
    string fCustomerName;
    private string fEmail;
    public CustomerBase(Session session) : base(session) { }

    public string CustomerName {
        get { return fCustomerName; }
        set { SetPropertyValue(nameof(CustomerName), ref fCustomerName, value); }
    }
    public string Email {
        get { return fEmail; }
        set { SetPropertyValue(nameof(Email), ref fEmail, value); }
    }
}

public class CustomerRegistered : CustomerBase {
    string fOwnedProducts;
    public CustomerRegistered(Session session) : base(session) { }

    public string OwnedProducts {
        get { return fOwnedProducts; }
        set { SetPropertyValue(nameof(OwnedProducts), ref fOwnedProducts, value); }
    }
}

public class CustomerTrialed : CustomerBase {
    string fTrialedProducts;
    public CustomerTrialed(Session session) : base(session) { }

    public string TrialedProducts {
        get { return fTrialedProducts; }
        set { SetPropertyValue(nameof(TrialedProducts), ref fTrialedProducts, value); }
    }
}

VB.NET

Imports DevExpress.Xpo

Public Class CustomerBase
    Inherits XPObject
    Private fCustomerName As String
    Private fEmail As String
    Public Sub New(ByVal session As Session)
        MyBase.New(session)
    End Sub

    Public Property CustomerName() As String
        Get
            Return fCustomerName
        End Get
        Set(ByVal value As String)
            SetPropertyValue(NameOf(CustomerName), fCustomerName, value)
        End Set
    End Property
    Public Property Email() As String
        Get
            Return fEmail
        End Get
        Set(ByVal value As String)
            SetPropertyValue(NameOf(Email), fEmail, value)
        End Set
    End Property
End Class

Public Class CustomerRegistered
    Inherits CustomerBase
    Private fOwnedProducts As String
    Public Sub New(ByVal session As Session)
        MyBase.New(session)
    End Sub

    Public Property OwnedProducts() As String
        Get
            Return fOwnedProducts
        End Get
        Set(ByVal value As String)
            SetPropertyValue(NameOf(OwnedProducts), fOwnedProducts, value)
        End Set
    End Property
End Class

Public Class CustomerTrialed
    Inherits CustomerBase
    Private fTrialedProducts As String
    Public Sub New(ByVal session As Session)
        MyBase.New(session)
    End Sub

    Public Property TrialedProducts() As String
        Get
            Return fTrialedProducts
        End Get
        Set(ByVal value As String)
            SetPropertyValue(NameOf(TrialedProducts), fTrialedProducts, value)
        End Set
    End Property
End Class

Now, you may wish to create a collection of all customers, including those of the derived type, and access all their properties. This can be accomplished by creating a collection of the base class type, as shown below.

C#

XPCollection<CustomerBase> allCustomers = new XPCollection<CustomerBase>(session1);

VB.NET

Dim allCustomers As New XPCollection(Of CustomerBase)(session1)

Since the type of this collection is CustomerBase, you can only access properties of this type. You are not able to access, for instance, the OwnedProducts property even if the collection contains CustomerRegistered objects. This is because the OwnedProducts property is not known to the base class type.

To overcome the limitation, use the Upcasting feature. All you have to do is modify the collection’s XPBaseCollection.DisplayableProperties property to something like this: “Oid;CustomerName;<CustomerRegistered>OwnedProducts”. Here, the “Oid;CustomerName” is a part of the property value - you get it by default for the CustomerBase class. The <CustomerRegistered>OwnedProducts references the property of a type that differs from the base class type. The required type is enclosed in angle brackets.

The same syntax can also be used when building criteria. For instance, to retrieve all the customers who have bought or evaluated XtraGrid, use the following code.

C#

XPCollection<CustomerBase> gridCustomers = new XPCollection<CustomerBase>(session1, 
CriteriaOperator.Parse(
"<CustomerRegistered>OwnedProducts = 'XtraGrid' or <CustomerTrialed>TrialedProducts = 'XtraGrid'"
 ));

VB.NET

Dim gridCustomers As New XPCollection(Of CustomerBase)(session1, _
CriteriaOperator.Parse( _
"<CustomerRegistered>OwnedProducts = 'XtraGrid' or <CustomerTrialed>TrialedProducts = 'XtraGrid'" _
))

Use the following syntax to upcast reference type properties.

C#

public class Invoice : XPObject {
    CustomerBase fCustomer;
    public Invoice(Session session) : base(session) { }

    // This is a reference type property. It can reference any CustomerBase descendant.
    public CustomerBase Customer {
        get { return fCustomer; }
        set { SetPropertyValue(nameof(Customer), ref fCustomer, value); }
    }
}

// Uses upcasting to access CustomerRegistered properties.
XPCollection<Invoice> invoices = new XPCollection<Invoice>(session1,
  CriteriaOperator.Parse("Customer.<CustomerRegistered>OwnedProducts = 'XtraGrid'"));

VB.NET

Public Class Invoice
    Inherits XPObject
    Private fCustomer As CustomerBase
    Public Sub New(ByVal session As Session)
        MyBase.New(session)
    End Sub

    ' This is a reference type property. It can reference any CustomerBase descendant.
    Public Property Customer() As CustomerBase
        Get
            Return fCustomer
        End Get
        Set(ByVal value As CustomerBase)
            SetPropertyValue(NameOf(Customer), fCustomer, value)
        End Set
    End Property
End Class

' Uses upcasting to access CustomerRegistered properties.
Private invoices As New XPCollection(Of Invoice)(session1, _
CriteriaOperator.Parse("Customer.<CustomerRegistered>OwnedProducts = 'XtraGrid'"))

The code above retrieves a collection of invoices for registered customers who have bought XtraGrid.

 

Note

The Upcasting feature requires all the necessary tables to be created in the database. That is the database schema must exactly match the persistent classes used in your application.