mirror of
https://github.com/mbierlee/poodinis.git
synced 2024-11-15 04:04:01 +01:00
Split off extensive examples in README.md to a separate tutorial
This commit is contained in:
Mike Bierlee
parent
71ac539f2a
commit
9abd329fba
105
README.md
105
README.md
|
|
@ -44,109 +44,8 @@ void main() {
|
|||
```
|
||||
For more examples, see the [examples](example) directory.
|
||||
|
||||
### The container
|
||||
To register a class, a new dependency container must be instantiated:
|
||||
```d
|
||||
// Register a private container
|
||||
auto dependencies = new DependencyContainer();
|
||||
// Or use the singleton container
|
||||
dependencies = DependencyContainer.getInstance();
|
||||
```
|
||||
###Registering dependencies
|
||||
To make dependencies available, they have to be registered:
|
||||
```d
|
||||
// Register concrete class
|
||||
dependencies.register!ExampleClass;
|
||||
// Register by interface
|
||||
dependencies.register!(ExampleInterface, ExampleClass);
|
||||
```
|
||||
In the above example, dependencies on the concrete class and interface will resolve an instance of class ExampleClass. Registering a class by interface does not automatically register by concrete type.
|
||||
|
||||
###Resolving dependencies
|
||||
To manually resolve a dependency, all you have to do is resolve the dependency's type using the container in which it is registered:
|
||||
```d
|
||||
auto exampleClassInstance = dependencies.resolve!ExampleClass;
|
||||
```
|
||||
If the class is registered by interface and not by concrete type, you cannot resolve the class by concrete type. Registration of both a concrete type and interface type will resolve different registrations, returning different instances:
|
||||
|
||||
```d
|
||||
auto exampleClassInstance = dependencies.resolve!ExampleClass;
|
||||
auto exampleClassInstance2 = dependencies.resolve!ExampleInterface;
|
||||
assert(exampleClassInstance !is exampleClassInstance2);
|
||||
```
|
||||
You can solve this by adding the ADD_CONCRETE_TYPE_REGISTRATION option when registering:
|
||||
```d
|
||||
dependencies.register!(ExampleInterface, ExampleClass)(RegistrationOptions.ADD_CONCRETE_TYPE_REGISTRATION);
|
||||
auto exampleClassInstance = dependencies.resolve!ExampleClass;
|
||||
auto exampleClassInstance2 = dependencies.resolve!ExampleInterface;
|
||||
assert(exampleClassInstance is exampleClassInstance2);
|
||||
```
|
||||
|
||||
###Dependency scopes
|
||||
With dependency scopes, you can control how a dependency is resolved. The scope determines which instance is returned, be it the same each time or a new one. The following scopes are available:
|
||||
|
||||
* Resolve a dependency using a single instance (default):
|
||||
|
||||
```d
|
||||
dependencies.register!(ExampleClass).singleInstance();
|
||||
```
|
||||
* Resolve a dependency with a new instance each time it is resolved:
|
||||
|
||||
```d
|
||||
dependencies.register!(ExampleClass).newInstance();
|
||||
```
|
||||
* Resolve a dependency using a pre-existing instance
|
||||
|
||||
```d
|
||||
auto preExistingInstance = new ExampleClass();
|
||||
dependencies.register!(ExampleClass).existingInstance(preExistingInstance);
|
||||
```
|
||||
|
||||
###Autowiring
|
||||
The real value of any dependency injection framework comes from its ability to autowire dependencies. Poodinis supports autowiring by simply applying the **@Autowire** UDA to a member of a class:
|
||||
```d
|
||||
class ExampleClassA {}
|
||||
|
||||
class ExampleClassB {
|
||||
@Autowire
|
||||
public ExampleClassA dependency;
|
||||
}
|
||||
|
||||
dependencies.register!ExampleClassA;
|
||||
auto exampleInstance = new ExampleClassB();
|
||||
dependencies.autowire(exampleInstance);
|
||||
assert(exampleInstance.dependency !is null);
|
||||
```
|
||||
At the moment, it is only possible to autowire public members or properties.
|
||||
|
||||
Dependencies are automatically autowired when a class is resolved. So when you register ExampleClassB, its member, *dependency*, is automatically autowired:
|
||||
```d
|
||||
dependencies.register!ExampleClassA;
|
||||
dependencies.register!ExampleClassB;
|
||||
auto instance = dependencies.resolve!ExampleClassB;
|
||||
assert(instance.dependency !is null);
|
||||
```
|
||||
If an interface is to be autowired, you must register a concrete class by interface. Any class registered by concrete type can only be injected when a dependency on a concrete type is autowired.
|
||||
|
||||
###Circular dependencies
|
||||
Poodinis can autowire circular dependencies when they are registered with singleInstance or existingInstance registration scopes. Circular dependencies in registrations with newInstance scopes will not be autowired, as this would cause an endless loop.
|
||||
|
||||
###Registering and resolving using qualifiers
|
||||
You can register multiple concrete types to a super type. When doing so, you will need to specify a qualifier when resolving that type:
|
||||
```d
|
||||
// Color is an interface, Blue and Red are classes implementing that interface
|
||||
dependencies.register!(Color, Blue);
|
||||
dependencies.register!(Color, Red);
|
||||
auto blueInstance = dependencies.resolve!(Color, Blue);
|
||||
```
|
||||
If you want to autowire a type registered to multiple concrete types, specify a qualified type as template argument:
|
||||
```d
|
||||
class BluePaint {
|
||||
@Autowire!Blue
|
||||
public Color color;
|
||||
}
|
||||
```
|
||||
If you registered multiple concrete types to the same supertype and you do not resolve using a qualifier, a ResolveException is thrown stating that there are multiple candidates for the type to be resolved.
|
||||
###Tutorial
|
||||
For an extended tutorial walking you through all functionality offered by Poodinis, see [TUTORIAL.md](TUTORIAL.md)
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
|
|
|
|||
113
TUTORIAL.md
Normal file
113
TUTORIAL.md
Normal file
|
|
@ -0,0 +1,113 @@
|
|||
Poodinis Tutorial
|
||||
=================
|
||||
This tutorial will give you an overview of all functionality offered by Poodinis and how to use them.
|
||||
|
||||
The container
|
||||
-------------
|
||||
To register a class, a new dependency container must be instantiated:
|
||||
```d
|
||||
// Register a private container
|
||||
auto dependencies = new DependencyContainer();
|
||||
// Or use the singleton container
|
||||
dependencies = DependencyContainer.getInstance();
|
||||
```
|
||||
###Registering dependencies
|
||||
To make dependencies available, they have to be registered:
|
||||
```d
|
||||
// Register concrete class
|
||||
dependencies.register!ExampleClass;
|
||||
// Register by interface
|
||||
dependencies.register!(ExampleInterface, ExampleClass);
|
||||
```
|
||||
In the above example, dependencies on the concrete class and interface will resolve an instance of class ExampleClass. Registering a class by interface does not automatically register by concrete type.
|
||||
|
||||
Resolving dependencies
|
||||
----------------------
|
||||
To manually resolve a dependency, all you have to do is resolve the dependency's type using the container in which it is registered:
|
||||
```d
|
||||
auto exampleClassInstance = dependencies.resolve!ExampleClass;
|
||||
```
|
||||
If the class is registered by interface and not by concrete type, you cannot resolve the class by concrete type. Registration of both a concrete type and interface type will resolve different registrations, returning different instances:
|
||||
|
||||
```d
|
||||
auto exampleClassInstance = dependencies.resolve!ExampleClass;
|
||||
auto exampleClassInstance2 = dependencies.resolve!ExampleInterface;
|
||||
assert(exampleClassInstance !is exampleClassInstance2);
|
||||
```
|
||||
You can solve this by adding the ADD_CONCRETE_TYPE_REGISTRATION option when registering:
|
||||
```d
|
||||
dependencies.register!(ExampleInterface, ExampleClass)(RegistrationOptions.ADD_CONCRETE_TYPE_REGISTRATION);
|
||||
auto exampleClassInstance = dependencies.resolve!ExampleClass;
|
||||
auto exampleClassInstance2 = dependencies.resolve!ExampleInterface;
|
||||
assert(exampleClassInstance is exampleClassInstance2);
|
||||
```
|
||||
|
||||
Dependency scopes
|
||||
-----------------
|
||||
With dependency scopes, you can control how a dependency is resolved. The scope determines which instance is returned, be it the same each time or a new one. The following scopes are available:
|
||||
|
||||
* Resolve a dependency using a single instance (default):
|
||||
|
||||
```d
|
||||
dependencies.register!(ExampleClass).singleInstance();
|
||||
```
|
||||
* Resolve a dependency with a new instance each time it is resolved:
|
||||
|
||||
```d
|
||||
dependencies.register!(ExampleClass).newInstance();
|
||||
```
|
||||
* Resolve a dependency using a pre-existing instance
|
||||
|
||||
```d
|
||||
auto preExistingInstance = new ExampleClass();
|
||||
dependencies.register!(ExampleClass).existingInstance(preExistingInstance);
|
||||
```
|
||||
|
||||
Autowiring
|
||||
----------
|
||||
The real value of any dependency injection framework comes from its ability to autowire dependencies. Poodinis supports autowiring by simply applying the **@Autowire** UDA to a member of a class:
|
||||
```d
|
||||
class ExampleClassA {}
|
||||
|
||||
class ExampleClassB {
|
||||
@Autowire
|
||||
public ExampleClassA dependency;
|
||||
}
|
||||
|
||||
dependencies.register!ExampleClassA;
|
||||
auto exampleInstance = new ExampleClassB();
|
||||
dependencies.autowire(exampleInstance);
|
||||
assert(exampleInstance.dependency !is null);
|
||||
```
|
||||
At the moment, it is only possible to autowire public members or properties.
|
||||
|
||||
Dependencies are automatically autowired when a class is resolved. So when you register ExampleClassB, its member, *dependency*, is automatically autowired:
|
||||
```d
|
||||
dependencies.register!ExampleClassA;
|
||||
dependencies.register!ExampleClassB;
|
||||
auto instance = dependencies.resolve!ExampleClassB;
|
||||
assert(instance.dependency !is null);
|
||||
```
|
||||
If an interface is to be autowired, you must register a concrete class by interface. Any class registered by concrete type can only be injected when a dependency on a concrete type is autowired.
|
||||
|
||||
Circular dependencies
|
||||
---------------------
|
||||
Poodinis can autowire circular dependencies when they are registered with singleInstance or existingInstance registration scopes. Circular dependencies in registrations with newInstance scopes will not be autowired, as this would cause an endless loop.
|
||||
|
||||
Registering and resolving using qualifiers
|
||||
------------------------------------------
|
||||
You can register multiple concrete types to a super type. When doing so, you will need to specify a qualifier when resolving that type:
|
||||
```d
|
||||
// Color is an interface, Blue and Red are classes implementing that interface
|
||||
dependencies.register!(Color, Blue);
|
||||
dependencies.register!(Color, Red);
|
||||
auto blueInstance = dependencies.resolve!(Color, Blue);
|
||||
```
|
||||
If you want to autowire a type registered to multiple concrete types, specify a qualified type as template argument:
|
||||
```d
|
||||
class BluePaint {
|
||||
@Autowire!Blue
|
||||
public Color color;
|
||||
}
|
||||
```
|
||||
If you registered multiple concrete types to the same supertype and you do not resolve using a qualifier, a ResolveException is thrown stating that there are multiple candidates for the type to be resolved.
|
||||
Loading…
Reference in a new issue