InversionOfControl/Castle.MicroKernel/IKernel.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.MicroKernel
  16 {
  17         using System;
  18         using System.Collections;
  19
  20         using Castle.Core;
  21
  22         /// <summary>
  23         /// The <c>IKernel</c> interface exposes all the functionality
  24         /// the MicroKernel implements.
  25         /// </summary>
  26         /// <remarks>
  27         /// It allows you to register components and
  28         /// request them by the key or the service they implemented.
  29         /// It also allow you to register facilities and subsystem, thus
  30         /// augmenting the functionality exposed by the kernel alone to fits
  31         /// your needs.
  32         /// <seealso cref="IFacility"/>
  33         /// <seealso cref="ISubSystem"/>
  34         /// </remarks>
  35         public interface IKernel : IKernelEvents, IDisposable
  36         {
  37                 /// <summary>
  38                 /// Adds a concrete class as a component
  39                 /// </summary>
  40                 /// <param name="key"></param>
  41                 /// <param name="classType"></param>
  42                 void AddComponent(String key, Type classType);
  43
  44                 /// <summary>
  45                 /// Adds a concrete class
  46                 /// as a component with the specified <paramref name="lifestyle"/>.
  47                 /// </summary>
  48                 /// <param name="key">The key with which to index the component.</param>
  49                 /// <param name="classType">The <see cref="Type"/> of the component.</param>
  50                 /// <param name="lifestyle">The specified <see cref="LifestyleType"/> for the component.</param>
  51                 /// <remarks>
  52                 /// If you have indicated a lifestyle for the specified <paramref name="classType"/> using
  53                 /// attributes, this method will not overwrite that lifestyle. To do that, use the
  54                 /// <see cref="AddComponent(string,Type,LifestyleType,bool)"/> method.
  55                 /// </remarks>
  56                 /// <exception cref="ArgumentNullException">
  57                 /// Thrown if <paramref name="key"/>, or <paramref name="classType"/>
  58                 /// are <see langword="null"/>.
  59                 /// </exception>
  60                 /// <exception cref="ArgumentException">
  61                 /// Thrown if <paramref name="lifestyle"/> is <see cref="LifestyleType.Undefined"/>.
  62                 /// </exception>
  63                 void AddComponent(String key, Type classType, LifestyleType lifestyle);
  64
  65                 /// <summary>
  66                 /// Adds a concrete class
  67                 /// as a component with the specified <paramref name="lifestyle"/>.
  68                 /// </summary>
  69                 /// <param name="key">The key with which to index the component.</param>
  70                 /// <param name="classType">The <see cref="Type"/> of the component.</param>
  71                 /// <param name="lifestyle">The specified <see cref="LifestyleType"/> for the component.</param>
  72                 /// <param name="overwriteLifestyle">
  73                 /// If <see langword="true"/>, then ignores all other configurations
  74                 /// for lifestyle and uses the value in the <paramref name="lifestyle"/> parameter.
  75                 /// </param>
  76                 /// <remarks>
  77                 /// If you have indicated a lifestyle for the specified <paramref name="classType"/> using
  78                 /// attributes, this method will not overwrite that lifestyle. To do that, use the
  79                 /// <see cref="AddComponent(string,Type,Type,LifestyleType,bool)"/> method.
  80                 /// </remarks>
  81                 /// <exception cref="ArgumentNullException">
  82                 /// Thrown if <paramref name="key"/> or <paramref name="classType"/>
  83                 /// are <see langword="null"/>.
  84                 /// </exception>
  85                 /// <exception cref="ArgumentException" />
  86                 /// Thrown if <paramref name="lifestyle"/> is <see cref="LifestyleType.Undefined"/>.
  87                 void AddComponent(String key, Type classType, LifestyleType lifestyle, bool overwriteLifestyle);
  88
  89                 /// <summary>
  90                 /// Adds a concrete class and an interface
  91                 /// as a component
  92                 /// </summary>
  93                 /// <param name="key">The key with which to index the component.</param>
  94                 /// <param name="serviceType">The service <see cref="Type"/> that this component implements.</param>
  95                 /// <param name="classType">The <see cref="Type"/> of the component.</param>
  96                 void AddComponent(String key, Type serviceType, Type classType);
  97
  98                 /// <summary>
  99                 /// Adds a concrete class and an interface
 100                 /// as a component with the specified <paramref name="lifestyle"/>.
 101                 /// </summary>
 102                 /// <param name="key">The key with which to index the component.</param>
 103                 /// <param name="serviceType">The service <see cref="Type"/> that this component implements.</param>
 104                 /// <param name="classType">The <see cref="Type"/> of the component.</param>
 105                 /// <param name="lifestyle">The specified <see cref="LifestyleType"/> for the component.</param>
 106                 /// <remarks>
 107                 /// If you have indicated a lifestyle for the specified <paramref name="classType"/> using
 108                 /// attributes, this method will not overwrite that lifestyle. To do that, use the
 109                 /// <see cref="AddComponent(string,Type,Type,LifestyleType,bool)"/> method.
 110                 /// </remarks>
 111                 /// <exception cref="ArgumentNullException">
 112                 /// Thrown if <paramref name="key"/>, <paramref name="serviceType"/>, or <paramref name="classType"/>
 113                 /// are <see langword="null"/>.
 114                 /// </exception>
 115                 /// <exception cref="ArgumentException">
 116                 /// Thrown if <paramref name="lifestyle"/> is <see cref="LifestyleType.Undefined"/>.
 117                 /// </exception>
 118                 void AddComponent(String key, Type serviceType, Type classType, LifestyleType lifestyle);
 119
 120                 /// <summary>
 121                 /// Adds a concrete class and an interface
 122                 /// as a component with the specified <paramref name="lifestyle"/>.
 123                 /// </summary>
 124                 /// <param name="key">The key with which to index the component.</param>
 125                 /// <param name="serviceType">The service <see cref="Type"/> that this component implements.</param>
 126                 /// <param name="classType">The <see cref="Type"/> of the component.</param>
 127                 /// <param name="lifestyle">The specified <see cref="LifestyleType"/> for the component.</param>
 128                 /// <param name="overwriteLifestyle">
 129                 /// If <see langword="true"/>, then ignores all other configurations
 130                 /// for lifestyle and uses the value in the <paramref name="lifestyle"/> parameter.
 131                 /// </param>
 132                 /// <remarks>
 133                 /// If you have indicated a lifestyle for the specified <paramref name="classType"/> using
 134                 /// attributes, this method will not overwrite that lifestyle. To do that, use the
 135                 /// <see cref="AddComponent(string,Type,Type,LifestyleType,bool)"/> method.
 136                 /// </remarks>
 137                 /// <exception cref="ArgumentNullException">
 138                 /// Thrown if <paramref name="key"/>, <paramref name="serviceType"/>, or <paramref name="classType"/>
 139                 /// are <see langword="null"/>.
 140                 /// </exception>
 141                 /// <exception cref="ArgumentException">
 142                 /// Thrown if <paramref name="lifestyle"/> is <see cref="LifestyleType.Undefined"/>.
 143                 /// </exception>
 144                 void AddComponent(string key, Type serviceType, Type classType, LifestyleType lifestyle, bool overwriteLifestyle);
 145
 146                 /// <summary>
 147                 /// Adds a concrete class as a component and specify the extended properties.
 148                 /// Used by facilities, mostly.
 149                 /// </summary>
 150                 /// <param name="key"></param>
 151                 /// <param name="classType"></param>
 152                 /// <param name="extendedProperties"></param>
 153                 void AddComponentWithExtendedProperties(String key, Type classType, IDictionary extendedProperties);
 154
 155                 /// <summary>
 156                 /// Adds a concrete class and an interface
 157                 /// as a component and specify the extended properties.
 158                 /// Used by facilities, mostly.
 159                 /// </summary>
 160                 /// <param name="key"></param>
 161                 /// <param name="serviceType"></param>
 162                 /// <param name="classType"></param>
 163                 /// <param name="extendedProperties"></param>
 164                 void AddComponentWithExtendedProperties(String key, Type serviceType, Type classType, IDictionary extendedProperties);
 165
 166                 /// <summary>
 167                 /// Adds a custom made <see cref="ComponentModel"/>.
 168                 /// Used by facilities.
 169                 /// </summary>
 170                 /// <param name="model"></param>
 171                 void AddCustomComponent(ComponentModel model);
 172
 173                 /// <summary>
 174                 /// Used mostly by facilities. Adds an instance
 175                 /// to be used as a component.
 176                 /// </summary>
 177                 /// <param name="key"></param>
 178                 /// <param name="instance"></param>
 179                 void AddComponentInstance(String key, object instance);
 180
 181                 /// <summary>
 182                 /// Used mostly by facilities. Adds an instance
 183                 /// to be used as a component.
 184                 /// </summary>
 185                 /// <param name="key"></param>
 186                 /// <param name="serviceType"></param>
 187                 /// <param name="instance"></param>
 188                 void AddComponentInstance(String key, Type serviceType, object instance);
 189
 190                 /// <summary>
 191                 /// Returns true if the specified component was
 192                 /// found and could be removed (i.e. no other component depends on it)
 193                 /// </summary>
 194                 /// <param name="key">The component's key</param>
 195                 /// <returns></returns>
 196                 bool RemoveComponent(String key);
 197
 198                 /// <summary>
 199                 /// Returns true if the specified key was registered
 200                 /// </summary>
 201                 /// <param name="key"></param>
 202                 /// <returns></returns>
 203                 bool HasComponent(String key);
 204
 205                 /// <summary>
 206                 /// Returns true if the specified service was registered
 207                 /// </summary>
 208                 /// <param name="service"></param>
 209                 /// <returns></returns>
 210                 bool HasComponent(Type service);
 211
 212                 /// <summary>
 213                 /// Returns the component instance by the key
 214                 /// </summary>
 215                 object this[String key] { get; }
 216
 217                 /// <summary>
 218                 /// Returns the component instance by the service type
 219                 /// </summary>
 220                 object this[Type service] { get; }
 221
 222                 /// <summary>
 223                 /// Returns the component instance by the service type
 224                 /// using dynamic arguments
 225                 /// </summary>
 226                 /// <param name="service"></param>
 227                 /// <param name="arguments"></param>
 228                 /// <returns></returns>
 229                 object Resolve(Type service, IDictionary arguments);
 230
 231                 /// <summary>
 232                 /// Returns the component instance by the component key
 233                 /// using dynamic arguments
 234                 /// </summary>
 235                 /// <param name="key"></param>
 236                 /// <param name="arguments"></param>
 237                 /// <returns></returns>
 238                 object Resolve(String key, IDictionary arguments);
 239
 240                 #if DOTNET2
 241
 242                 /// <summary>
 243                 /// Returns a component instance by the key
 244                 /// </summary>
 245                 /// <param name="key"></param>
 246                 /// <param name="service"></param>
 247                 /// <returns></returns>
 248                 object Resolve(String key, Type service);
 249
 250                 /// <summary>
 251                 /// Returns component instances that implement TService
 252                 /// </summary>
 253                 /// <typeparam name="TService"></typeparam>
 254                 /// <returns></returns>
 255                 TService[] ResolveServices<TService>();
 256
 257                 /// <summary>
 258                 /// Returns a component instance by the key
 259                 /// </summary>
 260                 /// <param name="key"></param>
 261                 /// <param name="service"></param>
 262                 /// <param name="arguments"></param>
 263                 /// <returns></returns>
 264                 object Resolve(String key, Type service, IDictionary arguments);
 265
 266                 #endif
 267
 268                 /// <summary>
 269                 /// Associates objects with a component handler,
 270                 /// allowing it to use the specified dictionary
 271                 /// when resolving dependencies
 272                 /// </summary>
 273                 /// <param name="service"></param>
 274                 /// <param name="dependencies"></param>
 275                 void RegisterCustomDependencies(Type service, IDictionary dependencies);
 276
 277                 /// <summary>
 278                 /// Associates objects with a component handler,
 279                 /// allowing it to use the specified dictionary
 280                 /// when resolving dependencies
 281                 /// </summary>
 282                 /// <param name="key"></param>
 283                 /// <param name="dependencies"></param>
 284                 void RegisterCustomDependencies(String key, IDictionary dependencies);
 285
 286                 /// <summary>
 287                 /// Releases a component instance. This allows
 288                 /// the kernel to execute the proper decomission
 289                 /// lifecycles on the component instance.
 290                 /// </summary>
 291                 /// <param name="instance"></param>
 292                 void ReleaseComponent(object instance);
 293
 294                 /// <summary>
 295                 /// Constructs an implementation of <see cref="IComponentActivator"/>
 296                 /// for the given <see cref="ComponentModel"/>
 297                 /// </summary>
 298                 /// <param name="model"></param>
 299                 /// <returns></returns>
 300                 IComponentActivator CreateComponentActivator(ComponentModel model);
 301
 302                 /// <summary>
 303                 /// Returns the implementation of <see cref="IComponentModelBuilder"/>
 304                 /// </summary>
 305                 IComponentModelBuilder ComponentModelBuilder { get; }
 306
 307                 /// <summary>
 308                 /// Returns the implementation of <see cref="IHandlerFactory"/>
 309                 /// </summary>
 310                 IHandlerFactory HandlerFactory { get; }
 311
 312                 /// <summary>
 313                 /// Gets or sets the implementation of <see cref="IConfigurationStore"/>
 314                 /// </summary>
 315                 IConfigurationStore ConfigurationStore { get; set; }
 316
 317                 /// <summary>
 318                 /// Returns the <see cref="IHandler"/>
 319                 /// for the specified component key.
 320                 /// </summary>
 321                 /// <param name="key"></param>
 322                 /// <returns></returns>
 323                 IHandler GetHandler(String key);
 324
 325                 /// <summary>
 326                 /// Returns the <see cref="IHandler"/>
 327                 /// for the specified service.
 328                 /// </summary>
 329                 /// <param name="service"></param>
 330                 /// <returns></returns>
 331                 IHandler GetHandler(Type service);
 332
 333                 /// <summary>
 334                 /// Return handlers for components that
 335                 /// implements the specified service.
 336                 /// </summary>
 337                 /// <param name="service"></param>
 338                 /// <returns></returns>
 339                 IHandler[] GetHandlers(Type service);
 340
 341                 /// <summary>
 342                 /// Return handlers for components that
 343                 /// implements the specified service.
 344                 /// The check is made using IsAssignableFrom
 345                 /// </summary>
 346                 /// <param name="service"></param>
 347                 /// <returns></returns>
 348                 IHandler[] GetAssignableHandlers(Type service);
 349
 350                 /// <summary>
 351                 /// Gets or sets the implementation for <see cref="IReleasePolicy"/>
 352                 /// </summary>
 353                 IReleasePolicy ReleasePolicy { get; set; }
 354
 355                 /// <summary>
 356                 /// Returns the implementation for <see cref="IDependencyResolver"/>
 357                 /// </summary>
 358                 IDependencyResolver Resolver { get; }
 359
 360                 /// <summary>
 361                 /// Adds a <see cref="IFacility"/> to the kernel.
 362                 /// </summary>
 363                 /// <param name="key"></param>
 364                 /// <param name="facility"></param>
 365                 void AddFacility(String key, IFacility facility);
 366
 367                 /// <summary>
 368                 /// Returns the facilities registered on the kernel.
 369                 /// </summary>
 370                 /// <returns></returns>
 371                 IFacility[] GetFacilities();
 372
 373                 /// <summary>
 374                 /// Adds (or replaces) an <see cref="ISubSystem"/>
 375                 /// </summary>
 376                 /// <param name="key"></param>
 377                 /// <param name="subsystem"></param>
 378                 void AddSubSystem(String key, ISubSystem subsystem);
 379
 380                 /// <summary>
 381                 /// Returns an implementation of <see cref="ISubSystem"/>
 382                 /// for the specified key.
 383                 /// <seealso cref="SubSystemConstants"/>
 384                 /// </summary>
 385                 /// <param name="key"></param>
 386                 /// <returns></returns>
 387                 ISubSystem GetSubSystem(String key);
 388
 389                 /// <summary>
 390                 /// Gets or sets the implementation of <see cref="IProxyFactory"/>
 391                 /// allowing different strategies for proxy creation.
 392                 /// </summary>
 393                 IProxyFactory ProxyFactory { get; set; }
 394
 395                 /// <summary>
 396                 /// Returns the parent kernel
 397                 /// </summary>
 398                 IKernel Parent { get; set; }
 399
 400                 /// <summary>
 401                 /// Support for kernel hierarchy
 402                 /// </summary>
 403                 /// <param name="kernel"></param>
 404                 void AddChildKernel(IKernel kernel);
 405
 406                 /// <summary>
 407                 /// Remove child kernel
 408                 /// </summary>
 409                 /// <param name="kernel"></param>
 410                 void RemoveChildKernel(IKernel kernel);
 411
 412                 /// <summary>
 413                 /// Graph of components and iteractions.
 414                 /// </summary>
 415                 GraphNode[] GraphNodes { get; }
 416         }
 417 }