ActiveRecord/Castle.ActiveRecord/Framework/Scopes/ISessionScope.cs

   1 // Copyright 2004-2008 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
  19         using NHibernate;
  20
  21         /// <summary>
  22         /// Define session scope types
  23         /// </summary>
  24         public enum SessionScopeType
  25         {
  26                 /// <summary>
  27                 /// Undefined type of session scope.
  28                 /// This value probably should never exist
  29                 /// </summary>
  30                 Undefined,
  31                 /// <summary>
  32                 /// Simple - non transactional session scope
  33                 /// </summary>
  34                 Simple,
  35                 /// <summary>
  36                 /// Transactional session scope
  37                 /// </summary>
  38                 Transactional,
  39                 /// <summary>
  40                 /// Custom implementation of session scope.
  41                 /// </summary>
  42                 Custom
  43         }
  44
  45         /// <summary>
  46         /// Contract for implementation of scopes.
  47         /// </summary>
  48         /// <remarks>
  49         /// A scope can implement a logic that affects
  50         /// AR for the scope lifetime. Session cache and
  51         /// transaction are the best examples, but you
  52         /// can create new scopes adding new semantics.
  53         /// <para>
  54         /// The methods on this interface are mostly invoked
  55         /// by the <see cref="Castle.ActiveRecord.Framework.ISessionFactoryHolder"/>
  56         /// implementation
  57         /// </para>
  58         /// </remarks>
  59         public interface ISessionScope : IDisposable
  60         {
  61                 /// <summary>
  62                 /// Returns the <see cref="FlushAction"/> defined
  63                 /// for this scope
  64                 /// </summary>
  65                 FlushAction FlushAction { get; }
  66
  67                 /// <summary>
  68                 /// Returns the <see cref="SessionScopeType"/> defined
  69                 /// for this scope
  70                 /// </summary>
  71                 SessionScopeType ScopeType { get; }
  72
  73                 /// <summary>
  74                 /// Flushes the sessions that this scope
  75                 /// is maintaining
  76                 /// </summary>
  77                 void Flush();
  78
  79                 /// <summary>
  80                 /// Evicts the specified instance from the session cache.
  81                 /// </summary>
  82                 /// <param name="instance">The instance.</param>
  83                 void Evict(object instance);
  84
  85                 /// <summary>
  86                 /// This method is invoked when no session was available
  87                 /// at and the <see cref="Castle.ActiveRecord.Framework.ISessionFactoryHolder"/>
  88                 /// just created one. So it registers the session created
  89                 /// within this scope using a key. The scope implementation
  90                 /// shouldn't make any assumption on what the key
  91                 /// actually is as we reserve the right to change it
  92                 /// <seealso cref="IsKeyKnown"/>
  93                 /// </summary>
  94                 /// <param name="key">an object instance</param>
  95                 /// <param name="session">An instance of <c>ISession</c></param>
  96                 void RegisterSession(object key, ISession session);
  97
  98                 /// <summary>
  99                 /// This method is invoked when the
 100                 /// <see cref="Castle.ActiveRecord.Framework.ISessionFactoryHolder"/>
 101                 /// instance needs a session instance. Instead of creating one it interrogates
 102                 /// the active scope for one. The scope implementation must check if it
 103                 /// has a session registered for the given key.
 104                 /// <seealso cref="RegisterSession"/>
 105                 /// </summary>
 106                 /// <param name="key">an object instance</param>
 107                 /// <returns><c>true</c> if the key exists within this scope instance</returns>
 108                 bool IsKeyKnown(object key);
 109
 110                 /// <summary>
 111                 /// This method should return the session instance associated with the key.
 112                 /// </summary>
 113                 /// <param name="key">an object instance</param>
 114                 /// <returns>the session instance or null if none was found</returns>
 115                 ISession GetSession(object key);
 116
 117                 /// <summary>
 118                 /// Implementors should return true if they
 119                 /// want that their scope implementation
 120                 /// be in charge of creating the session
 121                 /// </summary>
 122                 bool WantsToCreateTheSession { get; }
 123
 124                 /// <summary>
 125                 /// If the <see cref="WantsToCreateTheSession"/> returned
 126                 /// <c>true</c> then this method is invoked to allow
 127                 /// the scope to create a properly configured session
 128                 /// </summary>
 129                 /// <param name="sessionFactory">From where to open the session</param>
 130                 /// <param name="interceptor">the NHibernate interceptor</param>
 131                 /// <returns>the newly created session</returns>
 132                 ISession OpenSession(ISessionFactory sessionFactory, IInterceptor interceptor);
 133
 134                 /// <summary>
 135                 /// This method will be called if a session action fails.
 136                 /// The scope may then decide to use an different approach to flush/dispose it.
 137                 /// </summary>
 138                 /// <param name="session">The session that failed</param>
 139                 void FailSession(ISession session);
 140         }
 141 }