dub-mirrors/poodinis
1
0
Fork 0
mirror of https://github.com/mbierlee/poodinis.git synced 2024-11-15 04:04:01 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

Change link to hypodermic repository

Browse source
This commit is contained in:
Mike Bierlee 2015-05-14 15:45:04 +02:00
parent a34df573fe
commit 7effc264ef
1 changed files with 167 additions and 167 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

334
README.md
View file

@ -1,167 +1,167 @@
Poodinis Dependency Injection Framework Poodinis Dependency Injection Framework
======================================= =======================================
Version 2.1.0 Version 2.1.0
Copyright 2014-2015 Mike Bierlee Copyright 2014-2015 Mike Bierlee
Licensed under the terms of the MIT license - See [LICENSE.txt](LICENSE.txt) Licensed under the terms of the MIT license - See [LICENSE.txt](LICENSE.txt)
[![Build Status](https://api.travis-ci.org/mbierlee/poodinis.png)](https://travis-ci.org/mbierlee/poodinis) [![Build Status](https://api.travis-ci.org/mbierlee/poodinis.png)](https://travis-ci.org/mbierlee/poodinis)
Poodinis is a dependency injection framework for the D programming language. It is inspired by the [Spring Framework] and [Hypodermic] IoC container for C++. Poodinis supports registering and resolving classes either by concrete type or interface. Automatic injection of dependencies is supported through the use of UDAs (Referred to as autowiring). Poodinis is a dependency injection framework for the D programming language. It is inspired by the [Spring Framework] and [Hypodermic] IoC container for C++. Poodinis supports registering and resolving classes either by concrete type or interface. Automatic injection of dependencies is supported through the use of UDAs (Referred to as autowiring).
Developed for D 2.067.1 Developed for D 2.067.1
Uses the Phobos standard library. Uses the Phobos standard library.
Can be built with DUB 0.9.22. Can be built with DUB 0.9.22.
History History
------- -------
For a full overview of changes, see [CHANGES.md](CHANGES.md) For a full overview of changes, see [CHANGES.md](CHANGES.md)
Getting started Getting started
--------------- ---------------
###DUB Dependency ###DUB Dependency
See the Poodinis [DUB project page] for instructions on how to include Poodinis into your project. See the Poodinis [DUB project page] for instructions on how to include Poodinis into your project.
###Quickstart ###Quickstart
The following example shows the typical usage of Poodinis: The following example shows the typical usage of Poodinis:
```d ```d
import poodinis.dependency; import poodinis.dependency;
interface Database{}; interface Database{};
class RelationalDatabase : Database {} class RelationalDatabase : Database {}
class DataWriter { class DataWriter {
@Autowire @Autowire
public Database database; // Automatically injected when class is resolved public Database database; // Automatically injected when class is resolved
} }
void main() { void main() {
auto dependencies = DependencyContainer.getInstance(); auto dependencies = DependencyContainer.getInstance();
dependencies.register!DataWriter; dependencies.register!DataWriter;
dependencies.register!(Database, RelationalDatabase); dependencies.register!(Database, RelationalDatabase);
auto writer = dependencies.resolve!DataWriter; auto writer = dependencies.resolve!DataWriter;
} }
``` ```
For more examples, see the [examples](example) directory. For more examples, see the [examples](example) directory.
### The container ### The container
To register a class, a new dependency container must be instantiated: To register a class, a new dependency container must be instantiated:
```d ```d
// Register a private container // Register a private container
auto dependencies = new DependencyContainer(); auto dependencies = new DependencyContainer();
// Or use the singleton container // Or use the singleton container
dependencies = DependencyContainer.getInstance(); dependencies = DependencyContainer.getInstance();
``` ```
###Registering dependencies ###Registering dependencies
To make dependencies available, they have to be registered: To make dependencies available, they have to be registered:
```d ```d
// Register concrete class // Register concrete class
dependencies.register!ExampleClass; dependencies.register!ExampleClass;
// Register by interface // Register by interface
dependencies.register!(ExampleInterface, ExampleClass); 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. 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 ###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: 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 ```d
auto exampleClassInstance = dependencies.resolve!ExampleClass; 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: 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 ```d
auto exampleClassInstance = dependencies.resolve!ExampleClass; auto exampleClassInstance = dependencies.resolve!ExampleClass;
auto exampleClassInstance2 = dependencies.resolve!ExampleInterface; auto exampleClassInstance2 = dependencies.resolve!ExampleInterface;
assert(exampleClassInstance !is exampleClassInstance2); assert(exampleClassInstance !is exampleClassInstance2);
``` ```
You can solve this by adding the ADD_CONCRETE_TYPE_REGISTRATION option when registering: You can solve this by adding the ADD_CONCRETE_TYPE_REGISTRATION option when registering:
```d ```d
dependencies.register!(ExampleInterface, ExampleClass)(RegistrationOptions.ADD_CONCRETE_TYPE_REGISTRATION); dependencies.register!(ExampleInterface, ExampleClass)(RegistrationOptions.ADD_CONCRETE_TYPE_REGISTRATION);
auto exampleClassInstance = dependencies.resolve!ExampleClass; auto exampleClassInstance = dependencies.resolve!ExampleClass;
auto exampleClassInstance2 = dependencies.resolve!ExampleInterface; auto exampleClassInstance2 = dependencies.resolve!ExampleInterface;
assert(exampleClassInstance is exampleClassInstance2); assert(exampleClassInstance is exampleClassInstance2);
``` ```
###Dependency scopes ###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: 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): * Resolve a dependency using a single instance (default):
```d ```d
dependencies.register!(ExampleClass).singleInstance(); dependencies.register!(ExampleClass).singleInstance();
``` ```
* Resolve a dependency with a new instance each time it is resolved: * Resolve a dependency with a new instance each time it is resolved:
```d ```d
dependencies.register!(ExampleClass).newInstance(); dependencies.register!(ExampleClass).newInstance();
``` ```
* Resolve a dependency using a pre-existing instance * Resolve a dependency using a pre-existing instance
```d ```d
auto preExistingInstance = new ExampleClass(); auto preExistingInstance = new ExampleClass();
dependencies.register!(ExampleClass).existingInstance(preExistingInstance); dependencies.register!(ExampleClass).existingInstance(preExistingInstance);
``` ```
###Autowiring ###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: 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 ```d
class ExampleClassA {} class ExampleClassA {}
class ExampleClassB { class ExampleClassB {
@Autowire @Autowire
public ExampleClassA dependency; public ExampleClassA dependency;
} }
dependencies.register!ExampleClassA; dependencies.register!ExampleClassA;
auto exampleInstance = new ExampleClassB(); auto exampleInstance = new ExampleClassB();
dependencies.autowire(exampleInstance); dependencies.autowire(exampleInstance);
assert(exampleInstance.dependency !is null); assert(exampleInstance.dependency !is null);
``` ```
At the moment, it is only possible to autowire public members or properties. 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: Dependencies are automatically autowired when a class is resolved. So when you register ExampleClassB, its member, *dependency*, is automatically autowired:
```d ```d
dependencies.register!ExampleClassA; dependencies.register!ExampleClassA;
dependencies.register!ExampleClassB; dependencies.register!ExampleClassB;
auto instance = dependencies.resolve!ExampleClassB; auto instance = dependencies.resolve!ExampleClassB;
assert(instance.dependency !is null); 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. 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 ###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. 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 ###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: 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 ```d
// Color is an interface, Blue and Red are classes implementing that interface // Color is an interface, Blue and Red are classes implementing that interface
dependencies.register!(Color, Blue); dependencies.register!(Color, Blue);
dependencies.register!(Color, Red); dependencies.register!(Color, Red);
auto blueInstance = dependencies.resolve!(Color, Blue); 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: If you want to autowire a type registered to multiple concrete types, specify a qualified type as template argument:
```d ```d
class BluePaint { class BluePaint {
@Autowire!Blue @Autowire!Blue
public Color color; 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. 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.
Documentation Documentation
------------- -------------
You can generate Public API documentation from the source code using DUB: You can generate Public API documentation from the source code using DUB:
``` ```
dub build --build=ddox dub build --build=ddox
``` ```
The documentation can then be found in docs/ The documentation can then be found in docs/
Future Work Future Work
----------- -----------
* Component scan (auto-registration) * Component scan (auto-registration)
[Spring Framework]: http://projects.spring.io/spring-framework/ [Spring Framework]: http://projects.spring.io/spring-framework/
[Hypodermic]: https://code.google.com/p/hypodermic/ [Hypodermic]: https://github.com/ybainier/hypodermic/
[DUB]: http://code.dlang.org/ [DUB]: http://code.dlang.org/
[DUB project page]: http://code.dlang.org/packages/poodinis [DUB project page]: http://code.dlang.org/packages/poodinis
[Github issue tracker]: https://github.com/mbierlee/poodinis/issues [Github issue tracker]: https://github.com/mbierlee/poodinis/issues