1 #Region "Microsoft.VisualBasic::bb2dc61814a9ef8c6094f2a3d1b9516a, Microsoft.VisualBasic.Core\ComponentModel\DataSource\Repository\Repository.vb"
2
3     ' Author:
4     
5     '       asuka (amethyst.asuka@gcmodeller.org)
6     '       xie (genetics@smrucc.org)
7     '       xieguigang (xie.guigang@live.com)
8     
9     ' Copyright (c) 2018 GPL3 Licensed
10     
11     
12     ' GNU GENERAL PUBLIC LICENSE (GPL3)
13     
14     
15     ' This program is free software: you can redistribute it and/or modify
16     ' it under the terms of the GNU General Public License as published by
17     ' the Free Software Foundation, either version 3 of the License, or
18     ' (at your option) any later version.
19     
20     ' This program is distributed in the hope that it will be useful,
21     ' but WITHOUT ANY WARRANTY; without even the implied warranty of
22     ' MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
23     ' GNU General Public License for more details.
24     
25     ' You should have received a copy of the GNU General Public License
26     ' along with this program. If not, see <http://www.gnu.org/licenses/>.
27
28
29
30     ' /********************************************************************************/
31
32     ' Summaries:
33
34     '     Interface IKeyedEntity
35     
36     '         Properties: Key
37     
38     '     Class ClientRecord
39     
40     '         Properties: ClientUniqueKey, Code
41     
42     '     Interface IRepositoryRead
43     
44     '         Function: Exists, GetAll, GetByKey, GetWhere
45     
46     '     Interface IRepositoryWrite
47     
48     '         Function: AddNew
49     
50     '         Sub: AddOrUpdate, Delete
51     
52     '     Interface IRepository
53     
54     
55     
56     '     Interface IClientRepository
57     
58     
59     
60     '     Class RepositoryReadException
61     
62     '         Properties: Fatal
63     
64     '         Constructor: (+2 OverloadsSub New
65     
66     
67     ' /********************************************************************************/
68
69 #End Region
70
71 Namespace ComponentModel.DataSourceModel.Repository
72
73     ' http://www.codeproject.com/Reference/731015/The-repository-pattern-in-VB-Net
74
75     ' The repository pattern (in VB.Net)
76
77     ' Background
78     ' The repository pattern Is a method To introduce a shearing layer between your business objects And
79     ' the data access/persistence technology you are Using And this especially useful In unit testing As
80     ' the alternative(mocking an entire data access library) can be quite heart breaking.
81
82     ' Motivation
83     ' The repository pattern introduces the following advantages over the traditional three-tier architecture over an ORM:
84
85     ' 1. The classes persisted by an ORM (Entity framework Or the Like) need To have a good deal Of information about how they are stored.
86     '    This Is Not ideal because When you make a change To the underlying storage you would need To change the business objects As well.
87     ' 2. Not all persistence Is in the form of a relational database - the repository can be backed by a blended storage made of files,
88     '    database tables And NoSQL records As well.
89     ' 3. Some fields exist only In order To allow navigation To a record Or To identify child records - these fields should Not
90     '    be passed up into the business layer If they have no business meaning.
91
92     ''' <summary>
93     ''' Interface defining any item we can store in a repository and can identify by
94     ''' an unique key
95     ''' </summary>
96     ''' <remarks>
97     ''' This interface is typed so we can make type-safe code for retrieving the entity
98     ''' (don't pass in an integer if the entity is keyed by string etc.)
99     ''' </remarks>
100     Public Interface IKeyedEntity(Of TKeyType)
101
102         ''' <summary>
103         ''' Get the key to find the entity by
104         ''' </summary>
105         Property Key As TKeyType
106
107     End Interface
108
109     ''' <summary>
110     ''' Record for storing a client record in the common database
111     ''' </summary>
112     Public NotInheritable Class ClientRecord
113         Implements IKeyedEntity(Of Integer)
114
115         ''' <summary>
116         ''' The unique number by which we know this client
117         ''' </summary>
118         ''' <remarks>
119         ''' Every client has an unique id but this is not needed publically
120         ''' </remarks>
121         Public Property ClientUniqueKey As Integer Implements IKeyedEntity(Of Integer).Key
122
123         ' Other non-key properties can go here
124         ''' <summary>
125         ''' The short code for the client
126         ''' </summary>
127         ''' <remarks>
128         ''' e.g. MCL for Merrion Computing Ltd etc.
129         ''' </remarks>
130         Public Property Code As String
131     End Class
132
133     ''' <summary>
134     ''' Interface to support reading entities from the backing store
135     ''' </summary>
136     ''' <typeparam name="TEntity">
137     ''' The key-identified type of entity we are reading
138     ''' </typeparam>
139     ''' <typeparam name="TKey">
140     ''' The type of the key
141     ''' </typeparam>
142     ''' <remarks>
143     ''' In this architecture there is a seperate read and write interface but often this
144     ''' pattern has just the one interface for both functions
145     ''' </remarks>
146     Public Interface IRepositoryRead(Of TKey, TEntity As IKeyedEntity(Of TKey))
147
148         ''' <summary>
149         ''' Does a record exist in the repository identified by this key
150         ''' </summary>
151         ''' <param name="key">
152         ''' The unique identifier of the entity we are looking for
153         ''' </param>
154         Function Exists(key As TKey) As Boolean
155
156         ''' <summary>
157         ''' Get the entity uniquely identified by the given key
158         ''' </summary>
159         ''' <param name="key">
160         ''' The unique identifier to use to get the entity
161         ''' </param>
162         Function GetByKey(key As TKey) As TEntity
163
164         ''' <summary>
165         ''' Get a set of entities from the repository that match the where clause
166         ''' </summary>
167         ''' <param name="clause">
168         ''' A function to apply to filter the results from the repository
169         ''' </param>
170         Function GetWhere(clause As Func(Of TEntity, Boolean)) As IReadOnlyDictionary(Of TKey, TEntity)
171
172         ''' <summary>
173         ''' Get all of this type of thing from the repository
174         ''' </summary>
175         ''' <remarks>
176         ''' returns an IQueryable so this request can be filtered further
177         ''' </remarks>
178         Function GetAll() As IReadOnlyDictionary(Of TKey, TEntity)
179
180     End Interface
181
182     ''' <summary>
183     ''' Interface to support writing (and deletes) to a typed repository
184     ''' </summary>
185     ''' <typeparam name="TEntity">
186     ''' The type of entity in the repository
187     ''' </typeparam>
188     ''' <typeparam name="TKey">
189     ''' The type of the key to uniquely identify the entity
190     ''' </typeparam>
191     ''' <remarks>
192     ''' In this architecture there is a seperate read and write interface but often this
193     ''' pattern has just the one interface for both functions
194     ''' </remarks>
195     Public Interface IRepositoryWrite(Of TKey, TEntity As IKeyedEntity(Of TKey))
196
197         ''' <summary>
198         ''' Delete the entity uniquely identified by this key
199         ''' </summary>
200         ''' <param name="key">
201         ''' The unique identifier of the record to delete
202         ''' </param>
203         Sub Delete(key As TKey)
204
205         ''' <summary>
206         ''' Add or update the entity
207         ''' </summary>
208         ''' <param name="entity">
209         ''' The record to add or update on the repository
210         ''' </param>
211         ''' <param name="key" >
212         ''' The key that uniquely identifies the record to add or update
213         ''' </param>
214         Sub AddOrUpdate(entity As TEntity, key As TKey)
215
216         ''' <summary>
217         ''' Adds an entity that we know to be new and returns its assigned key
218         ''' </summary>
219         ''' <param name="entity">
220         ''' The entity we are adding to the repository
221         ''' </param>
222         ''' <returns>
223         ''' The unique identifier for the entity
224         ''' </returns>
225         ''' <remarks>
226         ''' This is useful if the unique identifier is not an intrinsic property of
227         ''' the entity - for example if it is a memory address or a GUID
228         ''' </remarks>
229         Function AddNew(entity As TEntity) As TKey
230
231     End Interface
232
233     ''' <summary>
234     ''' Read/write repository of typed entites
235     ''' </summary>
236     ''' <typeparam name="TKey">
237     ''' The type by which the entity is uniquely identified
238     ''' </typeparam>
239     ''' <typeparam name="TEntity">
240     ''' The type of entity in the repository
241     ''' </typeparam>
242     Public Interface IRepository(Of TKey, TEntity As IKeyedEntity(Of TKey))
243         Inherits IRepositoryRead(Of TKey, TEntity)
244         Inherits IRepositoryWrite(Of TKey, TEntity)
245
246     End Interface
247
248     Public Interface IClientRepository
249         Inherits IRepository(Of Integer, ClientRecord)
250
251     End Interface
252
253     ''' <summary>
254     ''' An exception that occured when reading from the repository backing store
255     ''' </summary>
256     ''' <remarks>
257     ''' The inner exception is from whatever
258     ''' </remarks>
259     Public Class RepositoryReadException
260         Inherits Exception
261
262         Public ReadOnly Property Fatal As Boolean
263
264         Public Sub New(message As String, innerExcption As Exception, fatalInit As Boolean)
265             MyBase.New(message, innerExcption)
266             Fatal = fatalInit
267         End Sub
268
269         Public Sub New(message As String, fatalInit As Boolean)
270             MyBase.New(message)
271             Fatal = fatalInit
272         End Sub
273     End Class
274 End Namespace