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         using Castle.MicroKernel.Registration;
  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 : IServiceProviderEx, 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
 148                 /// </summary>
 149                 void AddComponent<T>();
 150
 151                 /// <summary>
 152                 /// Adds a concrete class
 153                 /// as a component with the specified <paramref name="lifestyle"/>.
 154                 /// </summary>
 155                 /// <param name="lifestyle">The specified <see cref="LifestyleType"/> for the component.</param>
 156                 /// <remarks>
 157                 /// If you have indicated a lifestyle for the specified T using
 158                 /// attributes, this method will not overwrite that lifestyle. To do that, use the
 159                 /// <see cref="AddComponent(string,Type,LifestyleType,bool)"/> method.
 160                 /// </remarks>
 161                 /// <exception cref="ArgumentException">
 162                 /// Thrown if <paramref name="lifestyle"/> is <see cref="LifestyleType.Undefined"/>.
 163                 /// </exception>
 164                 void AddComponent<T>(LifestyleType lifestyle);
 165
 166                 /// <summary>
 167                 /// Adds a concrete class
 168                 /// as a component with the specified <paramref name="lifestyle"/>.
 169                 /// </summary>
 170                 /// <param name="lifestyle">The specified <see cref="LifestyleType"/> for the component.</param>
 171                 /// <param name="overwriteLifestyle">
 172                 /// If <see langword="true"/>, then ignores all other configurations
 173                 /// for lifestyle and uses the value in the <paramref name="lifestyle"/> parameter.
 174                 /// </param>
 175                 /// <remarks>
 176                 /// If you have indicated a lifestyle for the specified T using
 177                 /// attributes, this method will not overwrite that lifestyle. To do that, use the
 178                 /// <see cref="AddComponent(string,Type,LifestyleType,bool)"/> method.
 179                 /// </remarks>
 180                 /// <exception cref="ArgumentException" />
 181                 /// Thrown if <paramref name="lifestyle"/> is <see cref="LifestyleType.Undefined"/>.
 182                 void AddComponent<T>(LifestyleType lifestyle, bool overwriteLifestyle);
 183
 184                 /// <summary>
 185                 /// Adds a concrete class and an interface
 186                 /// as a component
 187                 /// </summary>
 188                 /// <param name="serviceType">The service <see cref="Type"/> that this component implements.</param>
 189                 void AddComponent<T>(Type serviceType);
 190
 191                 /// <summary>
 192                 /// Adds a concrete class and an interface
 193                 /// as a component with the specified <paramref name="lifestyle"/>.
 194                 /// </summary>
 195                 /// <param name="serviceType">The service <see cref="Type"/> that this component implements.</param>
 196                 /// <param name="lifestyle">The specified <see cref="LifestyleType"/> for the component.</param>
 197                 /// <remarks>
 198                 /// If you have indicated a lifestyle for the specified T using
 199                 /// attributes, this method will not overwrite that lifestyle. To do that, use the
 200                 /// <see cref="AddComponent(string,Type,Type,LifestyleType,bool)"/> method.
 201                 /// </remarks>
 202                 /// <exception cref="ArgumentNullException">
 203                 /// are <see langword="null"/>.
 204                 /// </exception>
 205                 /// <exception cref="ArgumentException">
 206                 /// Thrown if <paramref name="lifestyle"/> is <see cref="LifestyleType.Undefined"/>.
 207                 /// </exception>
 208                 void AddComponent<T>(Type serviceType, LifestyleType lifestyle);
 209
 210                 /// <summary>
 211                 /// Adds a concrete class and an interface
 212                 /// as a component with the specified <paramref name="lifestyle"/>.
 213                 /// </summary>
 214                 /// <param name="serviceType">The service <see cref="Type"/> that this component implements.</param>
 215                 /// <param name="lifestyle">The specified <see cref="LifestyleType"/> for the component.</param>
 216                 /// <param name="overwriteLifestyle">
 217                 /// If <see langword="true"/>, then ignores all other configurations
 218                 /// for lifestyle and uses the value in the <paramref name="lifestyle"/> parameter.
 219                 /// </param>
 220                 /// <remarks>
 221                 /// attributes, this method will not overwrite that lifestyle. To do that, use the
 222                 /// <see cref="AddComponent(string,Type,Type,LifestyleType,bool)"/> method.
 223                 /// </remarks>
 224                 /// <exception cref="ArgumentNullException">
 225                 /// are <see langword="null"/>.
 226                 /// </exception>
 227                 /// <exception cref="ArgumentException">
 228                 /// Thrown if <paramref name="lifestyle"/> is <see cref="LifestyleType.Undefined"/>.
 229                 /// </exception>
 230                 void AddComponent<T>(Type serviceType, LifestyleType lifestyle, bool overwriteLifestyle);
 231
 232                 /// <summary>
 233                 /// Used mostly by facilities. Adds an instance
 234                 /// to be used as a component.
 235                 /// </summary>
 236                 /// <param name="instance"></param>
 237                 void AddComponentInstance<T>(object instance);
 238
 239                 /// <summary>
 240                 /// Used mostly by facilities. Adds an instance
 241                 /// to be used as a component.
 242                 /// </summary>
 243                 /// <param name="serviceType"></param>
 244                 /// <param name="instance"></param>
 245                 void AddComponentInstance<T>(Type serviceType, object instance);
 246
 247                 /// <summary>
 248                 /// Adds a concrete class as a component and specify the extended properties.
 249                 /// Used by facilities, mostly.
 250                 /// </summary>
 251                 /// <param name="key"></param>
 252                 /// <param name="classType"></param>
 253                 /// <param name="extendedProperties"></param>
 254                 void AddComponentWithExtendedProperties(String key, Type classType, IDictionary extendedProperties);
 255
 256                 /// <summary>
 257                 /// Adds a concrete class and an interface
 258                 /// as a component and specify the extended properties.
 259                 /// Used by facilities, mostly.
 260                 /// </summary>
 261                 /// <param name="key"></param>
 262                 /// <param name="serviceType"></param>
 263                 /// <param name="classType"></param>
 264                 /// <param name="extendedProperties"></param>
 265                 void AddComponentWithExtendedProperties(String key, Type serviceType, Type classType, IDictionary extendedProperties);
 266
 267                 /// <summary>
 268                 /// Adds a custom made <see cref="ComponentModel"/>.
 269                 /// Used by facilities.
 270                 /// </summary>
 271                 /// <param name="model"></param>
 272                 void AddCustomComponent(ComponentModel model);
 273
 274                 /// <summary>
 275                 /// Used mostly by facilities. Adds an instance
 276                 /// to be used as a component.
 277                 /// </summary>
 278                 /// <param name="key"></param>
 279                 /// <param name="instance"></param>
 280                 void AddComponentInstance(String key, object instance);
 281
 282                 /// <summary>
 283                 /// Used mostly by facilities. Adds an instance
 284                 /// to be used as a component.
 285                 /// </summary>
 286                 /// <param name="key"></param>
 287                 /// <param name="serviceType"></param>
 288                 /// <param name="instance"></param>
 289                 void AddComponentInstance(String key, Type serviceType, object instance);
 290
 291                 /// <summary>
 292                 /// Used mostly by facilities. Adds an instance
 293                 /// to be used as a component.
 294                 /// </summary>
 295                 /// <param name="key"></param>
 296                 /// <param name="serviceType"></param>
 297                 /// <param name="instance"></param>
 298                 /// <param name="classType"></param>
 299                 void AddComponentInstance(string key, Type serviceType, Type classType, object instance);
 300
 301                 /// <summary>
 302                 /// Adds a component to be registered with the <see cref="IKernel"/>
 303                 /// using a fluent interface.
 304                 /// </summary>
 305                 /// <typeparam name="S">The service <see cref="Type"/> to manage.</typeparam>
 306                 /// <returns>The <see cref="ComponentRegistration{S,T}"/></returns>
 307                 ComponentRegistration<S, IKernel> AddComponentEx<S>();
 308
 309                 /// <summary>
 310                 /// Returns true if the specified component was
 311                 /// found and could be removed (i.e. no other component depends on it)
 312                 /// </summary>
 313                 /// <param name="key">The component's key</param>
 314                 /// <returns></returns>
 315                 bool RemoveComponent(String key);
 316
 317                 /// <summary>
 318                 /// Returns true if the specified key was registered
 319                 /// </summary>
 320                 /// <param name="key"></param>
 321                 /// <returns></returns>
 322                 bool HasComponent(String key);
 323
 324                 /// <summary>
 325                 /// Returns true if the specified service was registered
 326                 /// </summary>
 327                 /// <param name="service"></param>
 328                 /// <returns></returns>
 329                 bool HasComponent(Type service);
 330
 331                 /// <summary>
 332                 /// Returns the component instance by the key
 333                 /// </summary>
 334                 object this[String key] { get; }
 335
 336                 /// <summary>
 337                 /// Returns the component instance by the service type
 338                 /// </summary>
 339                 object this[Type service] { get; }
 340
 341                 /// <summary>
 342                 /// Returns the component instance by the service type
 343                 /// </summary>
 344                 object Resolve(Type service);
 345
 346                 /// <summary>
 347                 /// Returns all the valid component instances by
 348                 /// the service type
 349                 /// </summary>
 350                 /// <param name="service">The service type</param>
 351                 /// <param name="arguments">Arguments to resolve the services</param>
 352                 Array ResolveAll(Type service, IDictionary arguments);
 353
 354                 /// <summary>
 355                 /// Returns the component instance by the service type
 356                 /// using dynamic arguments
 357                 /// </summary>
 358                 /// <param name="service"></param>
 359                 /// <param name="arguments"></param>
 360                 /// <returns></returns>
 361                 object Resolve(Type service, IDictionary arguments);
 362
 363                 /// <summary>
 364                 /// Returns the component instance by the component key
 365                 /// using dynamic arguments
 366                 /// </summary>
 367                 /// <param name="key"></param>
 368                 /// <param name="arguments"></param>
 369                 /// <returns></returns>
 370                 object Resolve(String key, IDictionary arguments);
 371
 372                 /// <summary>
 373                 /// Returns a component instance by the key
 374                 /// </summary>
 375                 /// <param name="key"></param>
 376                 /// <param name="service"></param>
 377                 /// <returns></returns>
 378                 object Resolve(String key, Type service);
 379
 380                 /// <summary>
 381                 /// Returns the component instance by the service type
 382                 /// using dynamic arguments
 383                 /// </summary>
 384                 /// <param name="arguments"></param>
 385                 /// <returns></returns>
 386                 T Resolve<T>(IDictionary arguments);
 387
 388                 /// <summary>
 389                 /// Returns the component instance by the component key
 390                 /// </summary>
 391                 /// <returns></returns>
 392                 T Resolve<T>();
 393
 394                 /// <summary>
 395                 /// Returns component instances that implement TService
 396                 /// </summary>
 397                 /// <typeparam name="TService"></typeparam>
 398                 /// <returns></returns>
 399                 TService[] ResolveServices<TService>();
 400
 401                 /// <summary>
 402                 /// Returns a component instance by the key
 403                 /// </summary>
 404                 /// <param name="key"></param>
 405                 /// <param name="service"></param>
 406                 /// <param name="arguments"></param>
 407                 /// <returns></returns>
 408                 object Resolve(String key, Type service, IDictionary arguments);
 409
 410                 /// <summary>
 411                 /// Associates objects with a component handler,
 412                 /// allowing it to use the specified dictionary
 413                 /// when resolving dependencies
 414                 /// </summary>
 415                 /// <param name="service"></param>
 416                 /// <param name="dependencies"></param>
 417                 void RegisterCustomDependencies(Type service, IDictionary dependencies);
 418
 419                 /// <summary>
 420                 /// Associates objects with a component handler,
 421                 /// allowing it to use the specified dictionary
 422                 /// when resolving dependencies
 423                 /// </summary>
 424                 /// <param name="key"></param>
 425                 /// <param name="dependencies"></param>
 426                 void RegisterCustomDependencies(String key, IDictionary dependencies);
 427
 428                 /// <summary>
 429                 /// Releases a component instance. This allows
 430                 /// the kernel to execute the proper decomission
 431                 /// lifecycles on the component instance.
 432                 /// </summary>
 433                 /// <param name="instance"></param>
 434                 void ReleaseComponent(object instance);
 435
 436                 /// <summary>
 437                 /// Constructs an implementation of <see cref="IComponentActivator"/>
 438                 /// for the given <see cref="ComponentModel"/>
 439                 /// </summary>
 440                 /// <param name="model"></param>
 441                 /// <returns></returns>
 442                 IComponentActivator CreateComponentActivator(ComponentModel model);
 443
 444                 /// <summary>
 445                 /// Returns the implementation of <see cref="IComponentModelBuilder"/>
 446                 /// </summary>
 447                 IComponentModelBuilder ComponentModelBuilder { get; }
 448
 449                 /// <summary>
 450                 /// Returns the implementation of <see cref="IHandlerFactory"/>
 451                 /// </summary>
 452                 IHandlerFactory HandlerFactory { get; }
 453
 454                 /// <summary>
 455                 /// Gets or sets the implementation of <see cref="IConfigurationStore"/>
 456                 /// </summary>
 457                 IConfigurationStore ConfigurationStore { get; set; }
 458
 459                 /// <summary>
 460                 /// Returns the <see cref="IHandler"/>
 461                 /// for the specified component key.
 462                 /// </summary>
 463                 /// <param name="key"></param>
 464                 /// <returns></returns>
 465                 IHandler GetHandler(String key);
 466
 467                 /// <summary>
 468                 /// Returns the <see cref="IHandler"/>
 469                 /// for the specified service.
 470                 /// </summary>
 471                 /// <param name="service"></param>
 472                 /// <returns></returns>
 473                 IHandler GetHandler(Type service);
 474
 475                 /// <summary>
 476                 /// Return handlers for components that
 477                 /// implements the specified service.
 478                 /// </summary>
 479                 /// <param name="service"></param>
 480                 /// <returns></returns>
 481                 IHandler[] GetHandlers(Type service);
 482
 483                 /// <summary>
 484                 /// Return handlers for components that
 485                 /// implements the specified service.
 486                 /// The check is made using IsAssignableFrom
 487                 /// </summary>
 488                 /// <param name="service"></param>
 489                 /// <returns></returns>
 490                 IHandler[] GetAssignableHandlers(Type service);
 491
 492                 /// <summary>
 493                 /// Gets or sets the implementation for <see cref="IReleasePolicy"/>
 494                 /// </summary>
 495                 IReleasePolicy ReleasePolicy { get; set; }
 496
 497                 /// <summary>
 498                 /// Returns the implementation for <see cref="IDependencyResolver"/>
 499                 /// </summary>
 500                 IDependencyResolver Resolver { get; }
 501
 502                 /// <summary>
 503                 /// Adds a <see cref="IFacility"/> to the kernel.
 504                 /// </summary>
 505                 /// <param name="key"></param>
 506                 /// <param name="facility"></param>
 507                 void AddFacility(String key, IFacility facility);
 508
 509                 /// <summary>
 510                 /// Returns the facilities registered on the kernel.
 511                 /// </summary>
 512                 /// <returns></returns>
 513                 IFacility[] GetFacilities();
 514
 515                 /// <summary>
 516                 /// Adds (or replaces) an <see cref="ISubSystem"/>
 517                 /// </summary>
 518                 /// <param name="key"></param>
 519                 /// <param name="subsystem"></param>
 520                 void AddSubSystem(String key, ISubSystem subsystem);
 521
 522                 /// <summary>
 523                 /// Returns an implementation of <see cref="ISubSystem"/>
 524                 /// for the specified key.
 525                 /// <seealso cref="SubSystemConstants"/>
 526                 /// </summary>
 527                 /// <param name="key"></param>
 528                 /// <returns></returns>
 529                 ISubSystem GetSubSystem(String key);
 530
 531                 /// <summary>
 532                 /// Gets or sets the implementation of <see cref="IProxyFactory"/>
 533                 /// allowing different strategies for proxy creation.
 534                 /// </summary>
 535                 IProxyFactory ProxyFactory { get; set; }
 536
 537                 /// <summary>
 538                 /// Returns the parent kernel
 539                 /// </summary>
 540                 IKernel Parent { get; set; }
 541
 542                 /// <summary>
 543                 /// Support for kernel hierarchy
 544                 /// </summary>
 545                 /// <param name="kernel"></param>
 546                 void AddChildKernel(IKernel kernel);
 547
 548                 /// <summary>
 549                 /// Remove child kernel
 550                 /// </summary>
 551                 /// <param name="kernel"></param>
 552                 void RemoveChildKernel(IKernel kernel);
 553
 554                 /// <summary>
 555                 /// Graph of components and iteractions.
 556                 /// </summary>
 557                 GraphNode[] GraphNodes { get; }
 558
 559                 /// <summary>
 560                 /// Raise the hanlder registered event, required so
 561                 /// dependant handlers will be notified about their dependant moving
 562                 /// to valid state.
 563                 /// </summary>
 564                 /// <param name="handler"></param>
 565                 void RaiseHandlerRegistered(IHandler handler);
 566         }
 567 }