| TestsTested | ✓ |
| LangLanguage | Obj-CObjective C |
| License | Custom |
| ReleasedLast Release | Jul 2015 |
Maintained by Justin DeWind.
Objection is a lightweight dependency injection framework for Objective-C for MacOS X and iOS. For those of you that have used Guice, Objection will feel familiar. Objection was built to stay out of your way and alleviate the need to maintain a large XML container or manually construct objects.
For questions, visit the mailing list
A class can be registered with objection using the macros objection_register (optional) or objection_register_singleton. The objection_requires macro can be used to declare what dependencies objection should provide to all instances it creates of that class. objection_requires can be used safely with inheritance.
@class Engine, Brakes;
@interface Car : NSObject
{
Engine *engine;
Brakes *brakes;
BOOL awake;
}
// Will be filled in by objection
@property(nonatomic, strong) Engine *engine;
// Will be filled in by objection
@property(nonatomic, strong) Brakes *brakes;
@property(nonatomic) BOOL awake;
@implementation Car
objection_requires(@"engine", @"brakes")
@synthesize engine, brakes, awake;
@endYou can alternatively use selectors to define dependencies. The compiler will generate a warning if a given selector is not visible or cannot be found.
@implementation Car
objection_requires_sel(@selector(engine), @selector(brakes))
@synthesize engine, brakes, awake;
@endAn object can be fetched from objection by creating an injector and then asking for an instance of a particular class or protocol. An injector manages its own object context. Which means that a singleton is per injector and is not necessarily a true singleton.
- (void)someMethod {
JSObjectionInjector *injector = [JSObjection createInjector];
id car = [injector getObject:[Car class]];
}A default injector can be registered with Objection which can be used throughout your application or library.
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
JSObjectionInjector *injector = [JSObjection createInjector];
[JSObjection setDefaultInjector:injector];
}
- (void)viewDidLoad {
id myModel = [[JSObjection defaultInjector] getObject:[MyModel class]];
}There may be instances where an object is allocated outside of the injector's life cycle. If the object's class declared its dependencies using objection_requires an injector can satisfy its dependencies via the injectDependencies: method.
@implementation JSTableModel
objection_requires(@"RESTClient")
- (void)awakeFromNib {
[[JSObjection defaultInjector] injectDependencies:self];
}
@endObjection has support for the subscripting operator to retrieve objects from the injection context.
- (void)someMethod {
JSObjectionInjector *injector = [JSObjection createInjector];
id car = injector[[Car class]];
}If an object is interested in knowing when it has been fully instantiated by objection it can implement the method awakeFromObjection.
@implementation Car
//...
objection_register_singleton(Car)
- (void)awakeFromObjection {
awake = YES;
}
@end A class can get objects from the injector context through an object factory.
@interface RequestDispatcher
@property(nonatomic, strong) JSObjectFactory *objectFactory
@end
@implementation RequestDispatcher
- (void)dispatch:(NSDictionary *)params
{
Request *request = [self.objectFactory getObject:[Request class]];
request.params = params;
[request send];
}
@endA module is a set of bindings which contributes additional configuration information to the injector. It is especially useful for integrating external depencies and binding protocols to classes or instances.
@interface MyAppModule : JSObjectionModule {
}
@end
@implementation MyAppModule
- (void)configure {
[self bind:[UIApplication sharedApplication] toClass:[UIApplication class]];
[self bind:[UIApplication sharedApplication].delegate toProtocol:@protocol(UIApplicationDelegate)];
[self bindClass:[MyAPIService class] toProtocol:@protocol(APIService)];
}
@end
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
JSObjectionInjector *injector = [JSObjection createInjector:[[MyAppModule alloc] init]];
[JSObjection setDefaultInjector:injector];
}There are times when a dependency -- usually external -- is implemented using only class methods. Objection can explicitly support binding to the meta class instance through a protocol. This avoids having to unnecessarily create a wrapper class that passes through to the class methods. The catch, of course, is that it requires a protocol definition so that Objection knows how to bind the meta class to objects in the injector context.
@protocol ExternalUtility
- (void)doSomething;
@end
@interface ExternalUtility
+ (void)doSomething;
@end
@implementation ExternalUtility
+ (void)doSomething {...}
@end
// Module Configuration
- (void)configure {
[self bindMetaClass:[ExternalUtility class] toProtocol:@protocol(ExternalUtility)];
}
@interface SomeClass
{
...
}
// Use 'assign' because a meta class is not subject to the normal retain/release lifecycle.
// It will exist until the application is terminated (Class Initialization -> Application Termination)
// regardless of the number of objects in the runtime that reference it.
@property (nonatomic, assign) id<ExternalUtility> externalUtility
@endOccasionally you'll want to manually construct an object within Objection. Providers allow you to use a custom mechanism for building objects that are bound to a type. You can create a class that conforms to the ObjectionProvider protocol or you can use a block to build the object.
@interface CarProvider : NSObject <JSObjectionProvider>
@end
@implementation CarProvider
- (id)provide:(JSObjectionInjector *)context arguments:(NSArray *)arguments {
// Manually build object
return car;
}
@end
@implementation MyAppModule
- (void)configure {
[self bindProvider:[[CarProvider alloc] init] toClass:[Car class]];
[self bindBlock:^(JSObjectionInjector *context) {
// Manually build object
return car;
} toClass:[Car class]];
}
@endA class can be scoped as a singleton in a module. Conversely, a registered singleton can be demoted to a normal lifecycle with in the injector's context.
@implementation MyAppModule
- (void)configure {
[self bindClass:[Singleton class] inScope:JSObjectionScopeNormal];
[self bindClass:[Car class] inScope:JSObjectionScopeSingleton];
}
@endDependencies of the same class or protocol can be identified using the objection_requires_names macro, which takes a dictionary of names to properties as a parameter.
@interface ShinyCar : NSObject
@property (nonatomic, strong) Headlight *leftHeadlight;
@property (nonatomic, strong) Headlight *rightHeadlight;
@end
@implementation ShinyCar
objection_register(ShinyCar)
objection_requires_names((@{@"LeftHeadlight":@"leftHeadlight", @"RightHeadlight":@"rightHeadlight"}))
@synthesize leftHeadlight, rightHeadlight;
@end
@implementation NamedModule
- (void)configure
{
[self bind:[[Headlight alloc]init] toClass:[Headlight class] named:@"RightHeadlight"];
[self bindClass:[HIDHeadlight class] toClass:[Headlight class] named:@"LeftHeadlight"];
}
@end
You can mark registered singleton classes as eager singletons. Eager singletons will be instantiated during the creation of the injector rather than being lazily instantiated.
@implementation MyAppModule
- (void)configure {
[self registerEagerSingleton:[Car class]];
}
@endA new injector can be created from an existing injector using the withModule: method. A new injector will be created containing the same bindings as the injector it was derived from. The new injector will also contain additional bindings provided by the new module.
Conversley, if withoutModuleOfType: is used the new injector will not contain the bindings of the removed module.
injector = [otherInjector withModule:[[Level18Module alloc] init]]
withoutModuleOfType:[Level17Module class]];
By default, Objection allocates objects with the default initializer init. If you'd like to instantiate an object with an alternate ininitializer the objection_initializer macro can be used to do so. The macro supports passing in default arguments (scalar values are not currently supported) as well.
@implementation ViewController
objection_initializer(initWithNibName:bundle:, @"ViewController")
@end@implementation ConfigurableCar
objection_requires(@"engine", @"brakes")
objection_initializer(initWithMake:model:)
@synthesize make;
@synthesize model;
- (instancetype)initWithMake:(NSString *)make model:(NSString *)model {
...
}
@end
- (void)buildCar {
ConfigurableCar *car = [self.objectFactory getObjectWithArgs:[ConfigurableCar class], @"VW", @"Passat", nil];
NSLog(@"Make: %@ Model: %@", car.make, car.model);
}@implementation Truck
objection_requires(@"engine", @"brakes")
objection_initializer(truckWithMake:model:)
+ (instancetype)truckWithMake:(NSString *) make model: (NSString *)model {
...
}
@end
@implementation ConfigurableCar
- (instancetype) initWithModel:(NSString *)model {
//....
}
@end
- (void)buildCar {
ConfigurableCar *car = [self.objectFactory getObject:[ConfigurableCar class], initializer: @selector(initWithModel:) withArgumentList:@[@"VW", @"Passat"]];
}If you're using Kiwi for testing, checkout MSSpec. It provides a convenient way inject mocks into your specs using Objection.
It can be downloaded here
git clone git://github.com/atomicobject/objection.git
git checkout 1.5
#import <Objection-iOS/Objection.h>
#import <Objection/Objection.h>
#import <Objection/Objection.h>
Learn more at CocoaPods.
A companion library for Objection was created called motion-objection
gem install motion-objectionOne only has to search GitHub