InversionOfControl/Castle.MicroKernel/Handlers/IHandler.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.MicroKernel
  16 {
  17         using System;
  18
  19         using Castle.Core;
  20
  21         /// <summary>
  22         /// Possible states for a IHandler instance
  23         /// </summary>
  24         public enum HandlerState
  25         {
  26                 /// <summary>
  27                 /// The component can be requested
  28                 /// </summary>
  29                 Valid,
  30                 /// <summary>
  31                 /// The component can not be requested
  32                 /// as it still depending on a external
  33                 /// dependency not yet available
  34                 /// </summary>
  35                 WaitingDependency
  36         }
  37
  38         /// <summary>
  39         ///
  40         /// </summary>
  41         /// <param name="source"></param>
  42         /// <param name="args"></param>
  43         public delegate void HandlerStateDelegate(object source, EventArgs args);
  44
  45         /// <summary>
  46         /// Contract for the IHandler, which manages an
  47         /// component state and coordinates its creation
  48         /// and destruction (dispatching to activators, lifestyle managers)
  49         /// </summary>
  50         public interface IHandler : ISubDependencyResolver
  51         {
  52                 /// <summary>
  53                 /// Initializes the handler with a reference to the
  54                 /// kernel.
  55                 /// </summary>
  56                 /// <param name="kernel"></param>
  57                 void Init(IKernel kernel);
  58
  59                 /// <summary>
  60                 /// Implementors should return a valid instance
  61                 /// for the component the handler is responsible.
  62                 /// It should throw an exception in the case the component
  63                 /// can't be created for some reason
  64                 /// </summary>
  65                 /// <returns></returns>
  66                 object Resolve(CreationContext context);
  67
  68                 /// <summary>
  69                 /// Implementors should dispose the component instance
  70                 /// </summary>
  71                 /// <param name="instance"></param>
  72                 void Release(object instance);
  73
  74                 /// <summary>
  75                 /// Gets the state of the handler
  76                 /// </summary>
  77                 HandlerState CurrentState { get; }
  78
  79                 /// <summary>
  80                 /// Gets the model of the component being
  81                 /// managed by this handler.
  82                 /// </summary>
  83                 ComponentModel ComponentModel { get; }
  84
  85                 /// <summary>
  86                 /// TODO: Document this
  87                 /// </summary>
  88                 event HandlerStateDelegate OnHandlerStateChanged;
  89
  90                 /// <summary>
  91                 /// Dictionary of String/object used to
  92                 /// associate data with a component dependency.
  93                 /// For example, if you component SmtpServer depends on
  94                 /// host and port, you can add those to this
  95                 /// dictionary and the handler will be able to use them.
  96                 /// </summary>
  97                 /// <remarks>
  98                 /// TODO: Document this
  99                 /// </remarks>
 100                 void AddCustomDependencyValue(string key, object value);
 101
 102                 /// <summary>
 103                 /// TODO: Document this
 104                 /// </summary>
 105                 /// <param name="key"></param>
 106                 void RemoveCustomDependencyValue(string key);
 107
 108                 /// <summary>
 109                 /// TODO: Document this
 110                 /// </summary>
 111                 /// <param name="key"></param>
 112                 /// <returns></returns>
 113                 bool HasCustomParameter(string key);
 114         }
 115 }