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