The repository pattern

The repository pattern is a method to introduce a shearing layer between your business objects and the data access/persistence technology you are using and this especially useful in unit testing as the alternative (mocking an entire data access library) can be quite heart breaking.

The first thing we need to do in order to create a repository is to make sure our entities can be uniquely identified and that we know how so to do. For anyone from a database background this is like setting up the unique key field(s) on the database table. I use a generic interface to do this in a highly flexible manner :-

vb.net Code:

''' <summary>
''' Interface defining any item we can store in a repository and can identify by 
''' an unique key
''' </summary>
''' <remarks>
''' This interface is typed so we can make type-safe code for retrieving the entity
''' (don't pass in an integer if the entity is keyed by string etc.)
''' </remarks>
Public Interface IKeyedEntity(Of TKeyType)
 
    ''' <summary>
    ''' Get the key to find the entity by
    ''' </summary>
    Property Key As TKeyType
 
End Interface

What this interface means is that for any class that implements it, an instance of that class can be meaningfully uniquely identified and the class will tell me how so to do.

For example if my Client class is uniquely identified by an integer we can declare it thus:-

vb.net Code:

''' <summary>
''' Record for storing a client record in the common database
''' </summary>
''' <remarks></remarks>
Public NotInheritable Class ClientRecord
    Implements IKeyedEntity(Of Integer)
 
 
    ''' <summary>
    ''' The unique number by which we know this client
    ''' </summary>
    ''' <remarks>
    ''' Every client has an unique id but this is not needed publically
    ''' </remarks>
    Public Property ClientUniqueKey As Integer Implements IKeyedEntity(Of Integer).Key
 
    ' Other non-key properties can go here
    ''' <summary>
    ''' The short code for the client
    ''' </summary>
    ''' <remarks>
    ''' e.g. MCL for Merrion Computing Ltd etc.
    ''' </remarks>
    Public Property Code As String
End Class

Now we'd need to define a set of standard operations to do with these objects and their backing storage. I split this into two parts - how I read from the data store and how I update the data store as this allows me to put together read-only data models quickly...

vb.net Code:

''' <summary>
''' Interface to support reading entities from the backing store
''' </summary>
''' <typeparam name="TEntity">
''' The key-identified type of entity we are reading
''' </typeparam>
''' <typeparam name="TKey">
''' The type of the key
''' </typeparam>
''' <remarks>
''' In this architecture there is a seperate read and write interface but often this 
''' pattern has just the one interface for both functions
''' </remarks>
Public Interface IRepositoryRead(Of TKey, TEntity As IKeyedEntity(Of TKey))
 
    ''' <summary>
    ''' Does a record exist in the repository identified by this key
    ''' </summary>
    ''' <param name="key">
    ''' The unique identifier of the entity we are looking for
    ''' </param>
    Function Exists(ByVal key As TKey) As Boolean
 
    ''' <summary>
    ''' Get the entity uniquely identified by the given key
    ''' </summary>
    ''' <param name="key">
    ''' The unique identifier to use to get the entity
    ''' </param>
    Function GetByKey(ByVal key As TKey) As TEntity
 
    ''' <summary>
    ''' Get a set of entities from the repository that match the where clause
    ''' </summary>
    ''' <param name="clause">
    ''' A function to apply to filter the results from the repository
    ''' </param>
    Function GetWhere(ByVal clause As Func(Of TEntity, Boolean)) As IReadOnlyDictionary(Of TKey, TEntity)
 
    ''' <summary>
    ''' Get all of this type of thing from the repository
    ''' </summary>
    Function GetAll() As IReadOnlyDictionary(Of Tkey, TEntity)
 
End Interface

..and on the write side....

vb.net Code:

''' <summary>
''' Interface to support writing (and deletes) to a typed repository
''' </summary>
''' <typeparam name="TEntity">
''' The type of entity in the repository
''' </typeparam>
''' <typeparam name="TKey">
''' The type of the key to uniquely identify the entity
''' </typeparam>
''' <remarks>
''' In this architecture there is a seperate read and write interface but often this 
''' pattern has just the one interface for both functions
''' </remarks>
Public Interface IRepositoryWrite(Of TKey, TEntity As IKeyedEntity(Of TKey))
 
    ''' <summary>
    ''' Delete the entity uniquely identified by this key
    ''' </summary>
    ''' <param name="key">
    ''' The unique identifier of the record to delete
    ''' </param>
    Sub Delete(ByVal key As TKey)
 
    ''' <summary>
    ''' Add or update the entity 
    ''' </summary>
    ''' <param name="entity">
    ''' The record to add or update on the repository
    ''' </param>
    ''' <param name="key" >
    ''' The key that uniquely identifies the record to add or update
    ''' </param>
    Sub AddOrUpdate(ByVal entity As TEntity, ByVal key As TKey)
 
    ''' <summary>
    ''' Adds an entity that we know to be new and returns its assigned key
    ''' </summary>
    ''' <param name="entity">
    ''' The entity we are adding to the repository
    ''' </param>
    ''' <returns>
    ''' The unique identifier for the entity
    ''' </returns>
    ''' <remarks>
    ''' This is useful if the unique identifier is not an intrinsic property of
    ''' the entity - for example if it is a memory address or a GUID
    ''' </remarks>
    Function AddNew(ByVal entity As TEntity) As TKey
 
End Interface

Of course you most often want both read and write sides in one class so I have a combining interface for that:-

vb.net Code:

''' <summary>
''' Read/write repository of typed entites
''' </summary>
''' <typeparam name="TKey">
''' The type by which the entity is uniquely identified
''' </typeparam>
''' <typeparam name="TEntity">
''' The type of entity in the repository
''' </typeparam>
''' <remarks></remarks>
Public Interface IRepository(Of TKey, TEntity As IKeyedEntity(Of TKey))
    Inherits IRepositoryRead(Of TKey, TEntity)
    Inherits IRepositoryWrite(Of TKey, TEntity)
 
End Interface

Worked example - a memory backed repository...

To show this in action a very simple memory-backed repository could look like this:-

vb.net Code:

Namespace MemoryBacked
 
    Public Class ClientRepository
        Implements IClientRepository
 
        ' Backing store for this data
        Private m_data As New Dictionary(Of Integer, ClientRecord)
 
        Public Function Exists(key As Integer) As Boolean Implements IRepositoryRead(Of Integer, ClientRecord).Exists
            Return m_data.ContainsKey(key)
        End Function
 
        Public Function GetAll() As IReadOnlyDictionary(Of Integer, ClientRecord) Implements IRepositoryRead(Of Integer, ClientRecord).GetAll
            Return m_data.Values()
        End Function
 
        Public Function GetByKey(key As Integer) As ClientRecord Implements IRepositoryRead(Of Integer, ClientRecord).GetByKey
            If (m_data.ContainsKey(key)) Then
                Return m_data(key)
            Else
                Return Nothing
            End If
        End Function
 
        Public Function GetWhere(clause As Func(Of ClientRecord, Boolean)) As IReadOnlyDictionary(Of Integer, ClientRecord) Implements IRepositoryRead(Of Integer, ClientRecord).GetWhere
            Return m_data.Values.Where(clause)
        End Function
 
        Public Function AddNew(entity As ClientRecord) As Integer Implements IRepositoryWrite(Of Integer, ClientRecord).AddNew
 
            If (entity.ClientUniqueKey = 0) Then
                entity.ClientUniqueKey = m_data.Count
            End If
 
            If Not (m_data.ContainsKey(entity.ClientUniqueKey)) Then
                m_data.Add(entity.ClientUniqueKey, entity)
            End If
 
            Return entity.ClientUniqueKey
        End Function
 
        Public Sub AddOrUpdate(entity As ClientRecord, key As Integer) Implements IRepositoryWrite(Of Integer, ClientRecord).AddOrUpdate
            If Not (m_data.ContainsKey(entity.ClientUniqueKey)) Then
                m_data.Add(entity.ClientUniqueKey, entity)
            Else
                m_data(entity.ClientUniqueKey) = entity
            End If
        End Sub
 
        Public Sub Delete(key As Integer) Implements IRepositoryWrite(Of Integer, ClientRecord).Delete
            If (m_data.ContainsKey(key)) Then
                m_data.Remove(key)
            End If
        End Sub
    End Class
 
End Namespace

(It's not thread safe or overly good but sufficient for unit test purposes)

Now you write your business layer against the repository classes and leave the data access completely alone to be independently implemented.

To further the shearing layer separation, I also recommend creating specific repository exceptions that your business layer can trap rather than it having to understand the underlying storage technology. These can wrap the inner exception so the developer can always get the required error information:-

vb.net Code:

''' <summary>
''' An exception that occured when reading from the repository backing store
''' </summary>
''' <remarks>
''' The inner exception is from whatever 
''' </remarks>
Public Class RepositoryReadException
    Inherits Exception
 
    ReadOnly m_fatal As Boolean
 
    Public ReadOnly Property Fatal As Boolean
        Get
            Return m_fatal
        End Get
    End Property
 
    Public Sub New(ByVal message As String, ByVal innerExcption As Exception, ByVal fatalInit As Boolean)
        MyBase.New(message, innerExcption)
        m_fatal = fatalInit
    End Sub
 
 
    Public Sub New(ByVal message As String, ByVal fatalInit As Boolean)
        MyBase.New(message)
        m_fatal = fatalInit
    End Sub
End Class

Nice article. I love this kind of layered design. Been a while since I used anything this clean in my own projects rhough. Time constraints and sometimes laziness usually lead to poorly thought out designs which results in some clumsy coupling of layers.

BTW, I'm speaking about layered designs in general, not just business/data layer designs like those found in POS apps.

I feel that things are becoming easier for layered/architecture systems because things like NuGet are bringing more of them into "common" usage. Also MVC and MVVM.

These code examples come from my own home code, not work - but when I have them working I intend turn them into a project template and that makes it easier to do the right thing than the wrong thing....