ActiveRecord/Castle.ActiveRecord/Framework/ActiveRecordBase.Generic.cs

   1 // Copyright 2004-2007 Castle Project - http://www.castleproject.org/
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at
   6 //
   7 //     http://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14
  15 namespace Castle.ActiveRecord
  16 {
  17         using System;
  18         using System.Collections;
  19         using Castle.ActiveRecord.Framework;
  20         using NHibernate;
  21         using NHibernate.Expression;
  22
  23         /// <summary>
  24         /// Base class for all ActiveRecord Generic classes.
  25         /// Implements all the functionality to simplify the code on the subclasses.
  26         /// </summary>
  27         [Serializable]
  28         public abstract class ActiveRecordBase<T> : ActiveRecordBase
  29         {
  30                 #region protected internal static
  31
  32                 #region Create/Update/Save/Delete/Refresh
  33
  34                 #region Create
  35
  36                 /// <summary>
  37                 /// Creates (Saves) a new instance to the database.
  38                 /// </summary>
  39                 /// <param name="instance">The ActiveRecord instance to be created on the database</param>
  40                 protected internal static void Create(T instance)
  41                 {
  42                         ActiveRecordBase.Create(instance);
  43                 }
  44
  45                 #endregion
  46
  47                 #region Delete
  48
  49                 /// <summary>
  50                 /// Deletes the instance from the database.
  51                 /// </summary>
  52                 /// <param name="instance">The ActiveRecord instance to be deleted</param>
  53                 protected internal static void Delete(T instance)
  54                 {
  55                         ActiveRecordBase.Delete(instance);
  56                 }
  57
  58                 #endregion
  59
  60                 #region DeleteAll
  61
  62                 /// <summary>
  63                 /// Deletes all rows for the specified ActiveRecord type
  64                 /// </summary>
  65                 /// <remarks>
  66                 /// This method is usually useful for test cases.
  67                 /// </remarks>
  68                 public static void DeleteAll()
  69                 {
  70                         DeleteAll(typeof(T));
  71                 }
  72
  73                 /// <summary>
  74                 /// Deletes all rows for the specified ActiveRecord type that matches
  75                 /// the supplied HQL condition
  76                 /// </summary>
  77                 /// <remarks>
  78                 /// This method is usually useful for test cases.
  79                 /// </remarks>
  80                 /// <param name="where">HQL condition to select the rows to be deleted</param>
  81                 public static void DeleteAll(String where)
  82                 {
  83                         DeleteAll(typeof(T), where);
  84                 }
  85
  86                 /// <summary>
  87                 /// Deletes all <typeparamref name="T"/> objects, based on the primary keys
  88                 /// supplied on <paramref name="pkValues" />.
  89                 /// </summary>
  90                 /// <returns>The number of objects deleted</returns>
  91                 public static int DeleteAll(IEnumerable pkValues)
  92                 {
  93                         return DeleteAll(typeof(T), pkValues);
  94                 }
  95
  96                 #endregion
  97
  98                 #region Refresh
  99
 100                 /// <summary>
 101                 /// Refresh the instance from the database.
 102                 /// </summary>
 103                 /// <param name="instance">The ActiveRecord instance to be reloaded</param>
 104                 protected internal static void Refresh(T instance)
 105                 {
 106                         ActiveRecordBase.Refresh(instance);
 107                 }
 108
 109                 #endregion
 110
 111                 #region Update
 112
 113                 /// <summary>
 114                 /// Persists the modification on the instance
 115                 /// state to the database.
 116                 /// </summary>
 117                 /// <param name="instance">The ActiveRecord instance to be updated on the database</param>
 118                 protected internal static void Update(T instance)
 119                 {
 120                         ActiveRecordBase.Update(instance);
 121                 }
 122
 123                 #endregion
 124
 125                 #region Save
 126
 127                 /// <summary>
 128                 /// Saves the instance to the database. If the primary key is unitialized
 129                 /// it creates the instance on the database. Otherwise it updates it.
 130                 /// <para>
 131                 /// If the primary key is assigned, then you must invoke <see cref="Create"/>
 132                 /// or <see cref="Update"/> instead.
 133                 /// </para>
 134                 /// </summary>
 135                 /// <param name="instance">The ActiveRecord instance to be saved</param>
 136                 protected internal static void Save(T instance)
 137                 {
 138                         ActiveRecordBase.Save(instance);
 139                 }
 140
 141         /// <summary>
 142         /// Saves a copy of the instance to the database. If the primary key is unitialized
 143         /// it creates the instance on the database. Otherwise it updates it.
 144         /// <para>
 145         /// If the primary key is assigned, then you must invoke <see cref="Create"/>
 146         /// or <see cref="Update"/> instead.
 147         /// </para>
 148         /// </summary>
 149         /// <param name="instance">The transient instance to be saved</param>
 150         /// <returns>The saved ActiveRecord instance.</returns>
 151         protected internal static T SaveCopy(T instance)
 152         {
 153             return (T) ActiveRecordBase.SaveCopy(instance);
 154         }
 155
 156                 #endregion
 157
 158                 #endregion
 159
 160                 #region Execute
 161
 162                 /// <summary>
 163                 /// Invokes the specified delegate passing a valid
 164                 /// NHibernate session. Used for custom NHibernate queries.
 165                 /// </summary>
 166                 /// <param name="call">The delegate instance</param>
 167                 /// <param name="instance">The ActiveRecord instance</param>
 168                 /// <returns>Whatever is returned by the delegate invocation</returns>
 169                 protected static object Execute(NHibernateDelegate call, object instance)
 170                 {
 171                         return Execute(typeof(T), call, instance);
 172                 }
 173
 174                 /// <summary>
 175                 /// Executes the query and return a strongly typed result
 176                 /// </summary>
 177                 /// <param name="query">The query.</param>
 178                 /// <returns>The query result.</returns>
 179                 protected internal static R ExecuteQuery2<R>(IActiveRecordQuery<R> query)
 180                 {
 181                         return (R) ExecuteQuery(query);
 182                 }
 183
 184                 #endregion
 185
 186                 #region Count
 187
 188                 /// <summary>
 189                 /// Returns the number of records of <typeparamref name="T"/> in the database
 190                 /// </summary>
 191                 /// <example>
 192                 /// <code escaped="true">
 193                 /// [ActiveRecord]
 194                 /// public class User : ActiveRecordBase&lt;User&gt;
 195                 /// {
 196                 ///   ...
 197                 ///
 198                 ///   public static int CountAllUsers()
 199                 ///   {
 200                 ///     return Count(); // Equivalent to: Count(typeof(User));
 201                 ///   }
 202                 /// }
 203                 /// </code>
 204                 /// </example>
 205                 /// <returns>The count query result</returns>
 206                 protected internal static int Count()
 207                 {
 208                         return Count(typeof(T));
 209                 }
 210
 211                 /// <summary>
 212                 /// Returns the number of records of <typeparamref name="T"/> in the database
 213                 /// </summary>
 214                 /// <example>
 215                 /// <code escaped="true">
 216                 /// [ActiveRecord]
 217                 /// public class User : ActiveRecordBase&lt;User&gt;
 218                 /// {
 219                 ///   ...
 220                 ///
 221                 ///   public static int CountAllUsersLocked()
 222                 ///   {
 223                 ///     return Count("IsLocked = ?", true); // Equivalent to: Count(typeof(User), "IsLocked = ?", true);
 224                 ///   }
 225                 /// }
 226                 /// </code>
 227                 /// </example>
 228                 /// <param name="filter">A sql where string i.e. Person=? and DOB &gt; ?</param>
 229                 /// <param name="args">Positional parameters for the filter string</param>
 230                 /// <returns>The count result</returns>
 231                 protected internal static int Count(String filter, params object[] args)
 232                 {
 233                         return Count(typeof(T), filter, args);
 234                 }
 235
 236                 /// <summary>
 237                 /// Check if any instance matching the criteria exists in the database.
 238                 /// </summary>
 239                 /// <param name="criteria">The criteria expression</param>
 240                 /// <returns>The count result</returns>
 241                 protected internal static int Count(params ICriterion[] criteria)
 242                 {
 243                         return Count(typeof(T), criteria);
 244                 }
 245
 246                 /// <summary>
 247                 /// Returns the number of records of the specified
 248                 /// type in the database
 249                 /// </summary>
 250                 /// <param name="detachedCriteria">The criteria expression</param>
 251                 /// <returns>The count result</returns>
 252                 protected internal static int Count(DetachedCriteria detachedCriteria)
 253                 {
 254                         return Count(typeof(T), detachedCriteria);
 255                 }
 256
 257                 #endregion
 258
 259                 #region Exists
 260
 261                 /// <summary>
 262                 /// Check if there is any records in the db for <typeparamref name="T"/>
 263                 /// </summary>
 264                 /// <returns><c>true</c> if there's at least one row</returns>
 265                 public static bool Exists()
 266                 {
 267                         return ActiveRecordBase.Exists(typeof(T));
 268                 }
 269
 270                 /// <summary>
 271                 /// Check if there is any records in the db for <typeparamref name="T"/>
 272                 /// </summary>
 273                 /// <param name="filter">A sql where string i.e. Person=? and DOB &gt; ?</param>
 274                 /// <param name="args">Positional parameters for the filter string</param>
 275                 /// <returns><c>true</c> if there's at least one row</returns>
 276                 public static bool Exists(String filter, params object[] args)
 277                 {
 278                         return Exists(typeof(T), filter, args);
 279                 }
 280
 281                 /// <summary>
 282                 /// Check if the <paramref name="id"/> exists in the database.
 283                 /// </summary>
 284                 /// <typeparam name="PkType">The <c>System.Type</c> of the PrimaryKey</typeparam>
 285                 /// <param name="id">The id to check on</param>
 286                 /// <returns><c>true</c> if the ID exists; otherwise <c>false</c>.</returns>
 287                 public static bool Exists<PkType>(PkType id)
 288                 {
 289                         return Exists(typeof(T), id);
 290                 }
 291
 292                 /// <summary>
 293                 /// Check if any instance matching the criteria exists in the database.
 294                 /// </summary>
 295                 /// <param name="criteria">The criteria expression</param>
 296                 /// <returns><c>true</c> if an instance is found; otherwise <c>false</c>.</returns>
 297                 public static bool Exists(params ICriterion[] criteria)
 298                 {
 299                         return Exists(typeof(T), criteria);
 300                 }
 301
 302                 /// <summary>
 303                 /// Check if any instance matching the criteria exists in the database.
 304                 /// </summary>
 305                 /// <param name="detachedCriteria">The criteria expression</param>
 306                 /// <returns><c>true</c> if an instance is found; otherwise <c>false</c>.</returns>
 307                 public static bool Exists(DetachedCriteria detachedCriteria)
 308                 {
 309                         return Exists(typeof(T), detachedCriteria);
 310                 }
 311
 312                 #endregion
 313
 314                 #region FindAll
 315
 316                 /// <summary>
 317                 /// Returns all the instances that match the detached criteria.
 318                 /// </summary>
 319                 /// <param name="criteria">Detached criteria</param>
 320                 /// <param name="orders">Optional ordering</param>
 321                 /// <returns>All entities that match the criteria</returns>
 322                 public static T[] FindAll(DetachedCriteria criteria, params Order[] orders)
 323                 {
 324                         return (T[]) FindAll(typeof(T), criteria, orders);
 325                 }
 326
 327                 /// <summary>
 328                 /// Returns all instances found for <typeparamref name="T"/>
 329                 /// </summary>
 330                 /// <returns>An <see cref="Array"/> of <typeparamref name="T"/></returns>
 331                 public static T[] FindAll()
 332                 {
 333                         return (T[]) FindAll(typeof(T));
 334                 }
 335
 336                 /// <summary>
 337                 /// Returns all instances found for the specified type
 338                 /// using sort orders and criteria.
 339                 /// </summary>
 340                 /// <param name="order">An <see cref="Order"/> object.</param>
 341                 /// <param name="criteria">The criteria expression</param>
 342                 /// <returns>The <see cref="Array"/> of results.</returns>
 343                 public static T[] FindAll(Order order, params ICriterion[] criteria)
 344                 {
 345                         return (T[]) FindAll(typeof(T), new Order[] {order}, criteria);
 346                 }
 347
 348                 /// <summary>
 349                 /// Returns all instances found for <typeparamref name="T"/>
 350                 /// using sort orders and criteria.
 351                 /// </summary>
 352                 /// <param name="orders"></param>
 353                 /// <param name="criteria"></param>
 354                 /// <returns>An <see cref="Array"/> of <typeparamref name="T"/></returns>
 355                 public static T[] FindAll(Order[] orders, params ICriterion[] criteria)
 356                 {
 357                         return (T[]) FindAll(typeof(T), orders, criteria);
 358                 }
 359
 360                 /// <summary>
 361                 /// Returns all instances found for <typeparamref name="T"/>
 362                 /// using criteria.
 363                 /// </summary>
 364                 /// <param name="criteria"></param>
 365                 /// <returns>An <see cref="Array"/> of <typeparamref name="T"/></returns>
 366                 public static T[] FindAll(params ICriterion[] criteria)
 367                 {
 368                         return (T[]) FindAll(typeof(T), criteria);
 369                 }
 370
 371                 #endregion
 372
 373                 #region FindAllByProperty
 374
 375                 /// <summary>
 376                 /// Finds records based on a property value
 377                 /// </summary>
 378                 /// <param name="property">A property name (not a column name)</param>
 379                 /// <param name="value">The value to be equals to</param>
 380                 /// <returns>An <see cref="Array"/> of <typeparamref name="T"/></returns>
 381                 public static T[] FindAllByProperty(String property, object value)
 382                 {
 383                         return (T[]) FindAllByProperty(typeof(T), property, value);
 384                 }
 385
 386                 /// <summary>
 387                 /// Finds records based on a property value
 388                 /// </summary>
 389                 /// <param name="orderByColumn">The column name to be ordered ASC</param>
 390                 /// <param name="property">A property name (not a column name)</param>
 391                 /// <param name="value">The value to be equals to</param>
 392                 /// <returns>An <see cref="Array"/> of <typeparamref name="T"/></returns>
 393                 public static T[] FindAllByProperty(String orderByColumn, String property, object value)
 394                 {
 395                         return (T[]) FindAllByProperty(typeof(T), orderByColumn, property, value);
 396                 }
 397
 398                 #endregion
 399
 400                 #region FindByPrimaryKey/Find/TryFind
 401
 402                 /// <summary>
 403                 /// Finds an object instance by an unique ID
 404                 /// </summary>
 405                 /// <param name="id">ID value</param>
 406                 /// <exception cref="ObjectNotFoundException">if the row is not found</exception>
 407                 /// <returns>T</returns>
 408                 public static T Find(object id)
 409                 {
 410                         return (T) FindByPrimaryKey(typeof(T), id, true);
 411                 }
 412
 413                 /// <summary>
 414                 /// Finds an object instance by an unique ID.
 415                 /// If the row is not found this method will not throw an exception.
 416                 /// </summary>
 417                 /// <param name="id">ID value</param>
 418                 /// <returns>A <typeparamref name="T"/></returns>
 419                 public static T TryFind(object id)
 420                 {
 421                         return (T) FindByPrimaryKey(typeof(T), id, false);
 422                 }
 423
 424                 /// <summary>
 425                 /// Finds an object instance by an unique ID for <typeparamref name="T"/>
 426                 /// </summary>
 427                 /// <param name="id">ID value</param>
 428                 /// <returns>A <typeparamref name="T"/></returns>
 429                 protected internal static T FindByPrimaryKey(object id)
 430                 {
 431                         return (T) FindByPrimaryKey(typeof(T), id);
 432                 }
 433
 434                 /// <summary>
 435                 /// Finds an object instance by a unique ID for <typeparamref name="T"/>
 436                 /// </summary>
 437                 /// <param name="id">ID value</param>
 438                 /// <param name="throwOnNotFound"><c>true</c> if you want to catch an exception
 439                 /// if the object is not found</param>
 440                 /// <returns>A <typeparamref name="T"/></returns>
 441                 /// <exception cref="ObjectNotFoundException">if <c>throwOnNotFound</c> is set to
 442                 /// <c>true</c> and the row is not found</exception>
 443                 protected internal static T FindByPrimaryKey(object id, bool throwOnNotFound)
 444                 {
 445                         return (T) FindByPrimaryKey(typeof(T), id, throwOnNotFound);
 446                 }
 447
 448                 #endregion
 449
 450                 #region FindFirst
 451
 452                 /// <summary>
 453                 /// Searches and returns the first row for <typeparamref name="T"/>.
 454                 /// </summary>
 455                 /// <param name="criteria">Detached criteria.</param>
 456                 /// <param name="orders">The sort order - used to determine which record is the first one.</param>
 457                 /// <returns>A <c>targetType</c> instance or <c>null</c>.</returns>
 458                 public static T FindFirst(DetachedCriteria criteria, params Order[] orders)
 459                 {
 460                         return (T) FindFirst(typeof(T), criteria, orders);
 461                 }
 462
 463                 /// <summary>
 464                 /// Searches and returns the first row for <typeparamref name="T"/>
 465                 /// </summary>
 466                 /// <param name="order">The sort order - used to determine which record is the first one</param>
 467                 /// <param name="criteria">The criteria expression</param>
 468                 /// <returns>A <c>targetType</c> instance or <c>null</c></returns>
 469                 public static T FindFirst(Order order, params ICriterion[] criteria)
 470                 {
 471                         return (T) FindFirst(typeof(T), new Order[] {order}, criteria);
 472                 }
 473
 474                 /// <summary>
 475                 /// Searches and returns the first row for <typeparamref name="T"/>
 476                 /// </summary>
 477                 /// <param name="orders">The sort order - used to determine which record is the first one</param>
 478                 /// <param name="criteria">The criteria expression</param>
 479                 /// <returns>A <c>targetType</c> instance or <c>null</c></returns>
 480                 public static T FindFirst(Order[] orders, params ICriterion[] criteria)
 481                 {
 482                         return (T) FindFirst(typeof(T), orders, criteria);
 483                 }
 484
 485                 /// <summary>
 486                 /// Searches and returns the first row for <typeparamref name="T"/>
 487                 /// </summary>
 488                 /// <param name="criteria">The criteria expression</param>
 489                 /// <returns>A <c>targetType</c> instance or <c>null</c></returns>
 490                 public static T FindFirst(params ICriterion[] criteria)
 491                 {
 492                         return (T) FindFirst(typeof(T), criteria);
 493                 }
 494
 495                 #endregion
 496
 497                 #region FindOne
 498
 499                 /// <summary>
 500                 /// Searches and returns a row. If more than one is found,
 501                 /// throws <see cref="ActiveRecordException"/>
 502                 /// </summary>
 503                 /// <param name="criteria">The criteria expression</param>
 504                 /// <returns>A <c>targetType</c> instance or <c>null</c></returns>
 505                 public static T FindOne(params ICriterion[] criteria)
 506                 {
 507                         return (T) FindOne(typeof(T), criteria);
 508                 }
 509
 510                 /// <summary>
 511                 /// Searches and returns a row. If more than one is found,
 512                 /// throws <see cref="ActiveRecordException"/>
 513                 /// </summary>
 514                 /// <param name="criteria">The criteria</param>
 515                 /// <returns>A <c>targetType</c> instance or <c>null</c></returns>
 516                 public static T FindOne(DetachedCriteria criteria)
 517                 {
 518                         return (T) FindOne(typeof(T), criteria);
 519                 }
 520
 521                 #endregion
 522
 523                 #region SlicedFindAll
 524
 525                 /// <summary>
 526                 /// Returns a portion of the query results (sliced)
 527                 /// </summary>
 528                 /// <param name="firstResult">The number of the first row to retrieve.</param>
 529                 /// <param name="maxResults">The maximum number of results retrieved.</param>
 530                 /// <param name="orders">An <see cref="Array"/> of <see cref="Order"/> objects.</param>
 531                 /// <param name="criteria">The criteria expression</param>
 532                 /// <returns>The sliced query results.</returns>
 533                 public static T[] SlicedFindAll(int firstResult, int maxResults, Order[] orders,
 534                                                 params ICriterion[] criteria)
 535                 {
 536                         return (T[]) SlicedFindAll(typeof(T), firstResult, maxResults, orders, criteria);
 537                 }
 538
 539                 /// <summary>
 540                 /// Returns a portion of the query results (sliced)
 541                 /// </summary>
 542                 /// <param name="firstResult">The number of the first row to retrieve.</param>
 543                 /// <param name="maxResults">The maximum number of results retrieved.</param>
 544                 /// <param name="criteria">The criteria expression</param>
 545                 /// <returns>The sliced query results.</returns>
 546                 public static T[] SlicedFindAll(int firstResult, int maxResults,
 547                                                 params ICriterion[] criteria)
 548                 {
 549                         return (T[]) SlicedFindAll(typeof(T), firstResult, maxResults, criteria);
 550                 }
 551
 552                 /// <summary>
 553                 /// Returns a portion of the query results (sliced)
 554                 /// </summary>
 555                 /// <param name="firstResult">The number of the first row to retrieve.</param>
 556                 /// <param name="maxResults">The maximum number of results retrieved.</param>
 557                 /// <param name="orders">An <see cref="Array"/> of <see cref="Order"/> objects.</param>
 558                 /// <param name="criteria">The criteria expression</param>
 559                 /// <returns>The sliced query results.</returns>
 560                 public static T[] SlicedFindAll(int firstResult, int maxResults, DetachedCriteria criteria, params Order[] orders)
 561                 {
 562                         return (T[]) SlicedFindAll(typeof(T), firstResult, maxResults, orders, criteria);
 563                 }
 564
 565                 #endregion
 566
 567                 #endregion
 568         }
 569 }