Reliant
Reliant is a Dependency Injection (DI) framework for Objective-C, both for OS X and iOS. Its goal is to make its use as simple as possible, while not limiting possibilities. It aims to have as little impact as possible on your project code. It also aims to be loyal to Objective-C's dynamic nature.
Getting started
In this section we will get you started with Reliant as quick as possible, if you want to know more (or in other words, the TL;DR version) we suggest you take a look at our wiki pages
Installation
The easiest way to install Reliant is via CocoaPods
Add the following line to your Podfile:
pod 'Reliant'
Then run pod install
or pod update
for more information about CocoaPods, go to http://cocoapods.org
Quick-start tutorial
We suggest that you first take a look at our quick-start 'Hello World' tutorial and sample app, found under the Examples folder in the Reliant repository.
Using Reliant
The following documentation is based on our more elaborate sample app, which can also be found under the Examples folder in the Reliant repository.
Configuration
You first need a context in which Reliant will look for your specific objects. The default way to configure such a context is through a configuration class. The example contains some of these. The application wide context is configured with the AppConfiguration
class.
//Header file omitted
@implementation AppConfiguration
- (id<StringProvider>)createSingletonStringProvider {
return [[DefaultStringProvider alloc] init];
}
@end
In this very simple example we have the concept of a StringProvider
which will generate some strings shown by various views in our application. We configure Reliant to create a "singleton" instance of this string provider. The reason why you would use dependency injection is that you can avoid hard dependencies to implementations. That's why we have a StringProvider
protocol. The configuration will create an actual implementation instance, but that instance is hidden from the actual dependent application code. In this case we use the DefaultStringProvider
.
Bootstrapping a context
Bootstrapping a context is very simple. Since we have a configuration for a context which is meant to be used throughout the entire application, we will bootstrap this context in the application delegate.
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[self ocsBootstrapAndBindObjectContextWithConfiguratorFromClass:[AppConfiguration class]];
}
This single line of code is the easiest way to bootstrap a context. It wil start the context with the specified configuration class, and then bind that context to self
which in this case means your application delegate.
Injection
Reliant injects all your objects specified in the configuration. Injection can be done in two ways:
- Initializer injection
- Property injection
For simplicity's sake we will use property injection in these examples.
We actually prefer initializer injection over property injection, but we will get into that in our wiki pages.
Let's say that our DefaultStringProvider
implementation needs a StringGenerator
to generate some strings. We could do this by simply adding a property named stringGenerator
on our DefaultStringProvider
.
@interface DefaultStringProvider : NSObject<StringProvider>
@property (nonatomic, strong) id<StringGenerator> stringGenerator;
@end
Now we just need to add another configuration method to our AppConfiguration
class.
//Inside the implementation of our AppConfiguration
- (id<StringGenerator>)createSingletonStringGenerator {
return [[DefaultStringGenerator alloc] init];
}
With that, when you start your application, both the DefaultStringProvider
and DefaultStringGenerator
are being created for the AppDelegate's context. Remember when we said they were created as "singletons"? Well, they are not real singletons, but they are in the AppDelegate
context. When you ask the context for this object, it will always return the same instance, guaranteed.
For those of you who prefer to put the property in an anonymous class extension, as we do, that would work as well.
After the creation of an object, it will be injected with other objects known by the context it is created for. So in this case the DefaultStringGenerator
is injected in the DefaultStringProvider
through its stringGenerator
property.
You easily succeeded in loosly coupling the StringGenerator
to your DefaultStringProvider
class.
Manual injection
It might not always be possible to configure your objects through Reliant. For instance, a view controller might get created by a storyboard or by your applications code somewhere. In these cases Reliant will not be able to inject your object automatically. However, injecting an object is a one-liner again:
[self ocsInject];
This will locate a context based on self
, and then inject self
with objects known to the found context.
Naming your objects
Reliant figures out which objects to inject by their given name. In this case, the names of our object are stringProvider
and stringGenerator
. That is why we named the property in DefaultStringProvider
as such. The names of the objects are specified by your configurator. In this case Reliant derives the name from the method names. All text which comes after the createSingleton
is seen as a name. The tentative reader might argue that the names should be StringGenerator and StringProvider (with starting capital), in fact that is true. However, Reliant has created aliases for these objects in their camelcase form.
Further reading
Do not forget to check our wiki pages for more details on what is discussed above. Our API documentation is available via cocoadocs.org
Contact
If not via GitHub, find us on twitter: @AppFoundryBE or @mikeseghers
Licence
Reliant is released under MIT licence