Add SLRemoting

SLRemoting/SLAdapter.h

@@ -0,0 +1,150 @@
+/**
+ * @file SLAdapter.h
+ *
+ * @author Michael Schoonmaker
+ * @copyright (c) 2013 StrongLoop. All rights reserved.
+ */
+
+#import <Foundation/Foundation.h>
+
+/**
+ * Blocks of this type are executed for any successful method invocation, i.e.
+ * one where the remote method called the callback as `callback(null, value)`.
+ *
+ * **Example:**
+ * @code
+ * [...
+ *     success:^(id value) {
+ *         NSLog(@"The result was: %@", value);
+ *     }
+ * ...];
+ * @endcode
+ *
+ * @param value  The top-level value returned by the remote method, typed
+ *               appropriately: an NSNumber for all Numbers, an
+ *               NSDictionary for all Objects, etc.
+ */
+typedef void (^SLSuccessBlock)(id value);
+
+/**
+ * Blocks of this type are executed for any failed method invocation, i.e. one
+ * where the remote method called the callback as `callback(error, null)` or
+ * just `callback(error)`.
+ *
+ * **Example:**
+ * @code
+ * [...
+ *     success:^(id value) {
+ *         NSLog(@"The result was: %@", value);
+ *     }
+ * ...];
+ * @endcode
+ *
+ * @param error  The error received, as a properly-formatted
+ *               NSError.
+ */
+typedef void (^SLFailureBlock)(NSError *error);
+
+/**
+ * An error description for SLAdapters that are not connected to any server.
+ * Errors with this description will be passed to the SLFailureBlock associated
+ * with a request made of a disconnected Adapter.
+ */
+extern NSString *SLAdapterNotConnectedErrorDescription;
+
+/**
+ * The entry point to all networking accomplished with LoopBack. Adapters
+ * encapsulate information consistent to all networked operations, such as base
+ * URL, port, etc.
+ */
+@interface SLAdapter : NSObject
+
+/** YES if the SLAdapter is connected to a server, NO otherwise. */
+@property (readonly, nonatomic) BOOL connected;
+
+/** A flag to control if invalid SSL certificates are allowed */
+@property (readonly, nonatomic) BOOL allowsInvalidSSLCertificate;
+
+/**
+ * Returns a new, disconnected Adapter.
+ *
+ * @return A disconnected Adapter.
+ */
++ (instancetype)adapter;
+
+/**
+ * Returns a new Adapter connected to `url`.
+ *
+ * @param  url  The URL to connect to.
+ * @return      A connected Adapter.
+ */
++ (instancetype)adapterWithURL:(NSURL *)url;
+
+/**
+ * Returns a new Adapter connected to `url`.
+ *
+ * @param  url  The URL to connect to.
+ * @param  allowsInvalidSSLCertificate  Is invalid SSL certificate allowed?
+ * @return      A connected Adapter.
+ */
++ (instancetype)adapterWithURL:(NSURL *)url allowsInvalidSSLCertificate : (BOOL) allowsInvalidSSLCertificate;
+
+/**
+ * Initializes a new Adapter, connecting it to `url`.
+ *
+ * @param  url  The URL to connect to.
+ * @return      The connected Adapter.
+ */
+- (instancetype)initWithURL:(NSURL *)url allowsInvalidSSLCertificate : (BOOL) allowsInvalidSSLCertificate ;
+
+/**
+ * Connects the Adapter to `url`.
+ *
+ * @param url  The URL to connect to.
+ */
+- (void)connectToURL:(NSURL *)url;
+
+/**
+ * Invokes a remotable method exposed statically on the server.
+ *
+ * Unlike SLAdapter::invokeInstanceMethod:constructorParameters:parameters:success:failure:,
+ * no object needs to be created on the server.
+ *
+ * @param method      The method to invoke, e.g. `module.doSomething`.
+ * @param parameters  The parameters to invoke with.
+ * @param success     An SLSuccessBlock to be executed when the invocation
+ *                    succeeds.
+ * @param failure     An SLFailureBlock to be executed when the invocation
+ *                    fails.
+ */
+- (void)invokeStaticMethod:(NSString *)method
+                parameters:(NSDictionary *)parameters
+                   success:(SLSuccessBlock)success
+                   failure:(SLFailureBlock)failure;
+
+/**
+ * Invokes a remotable method exposed within a prototype on the server.
+ *
+ * This should be thought of as a two-step process. First, the server loads or
+ * creates an object with the appropriate type. Then and only then is the method
+ * invoked on that object. The two parameter dictionaries correspond to these
+ * two steps: `creationParameters` for the former, and `parameters` for the
+ * latter.
+ *
+ * @param method                 The method to invoke, e.g.
+ *                               `MyClass.prototype.doSomething`.
+ * @param constructorParameters  The parameters the virual object should be
+ *                               created with.
+ * @param parameters             The parameters to invoke with.
+ * @param success                An SLSuccessBlock to be executed when the
+ *                               invocation succeeds.
+ * @param failure                An SLFailureBlock to be executed when the
+ *                               invocation fails.
+ */
+- (void)invokeInstanceMethod:(NSString *)method
+       constructorParameters:(NSDictionary *)constructorParameters
+                  parameters:(NSDictionary *)parameters
+                     success:(SLSuccessBlock)success
+                     failure:(SLFailureBlock)failure;
+
+@end

SLRemoting/SLAdapter.m

@@ -0,0 +1,76 @@
+/**
+ * @file SLAdapter.m
+ *
+ * @author Michael Schoonmaker
+ * @copyright (c) 2013 StrongLoop. All rights reserved.
+ */
+
+#import "SLAdapter.h"
+
+NSString *SLAdapterNotConnectedErrorDescription = @"Adapter not connected.";
+
+@interface SLAdapter()
+
+@property (readwrite, nonatomic) BOOL connected;
+@property (readwrite, nonatomic) BOOL allowsInvalidSSLCertificate;
+
+@end
+
+@implementation SLAdapter
+
++ (instancetype)adapter {
+    return [self adapterWithURL:nil];
+}
+
++ (instancetype)adapterWithURL:(NSURL *)url {
+    return [self adapterWithURL:url allowsInvalidSSLCertificate:NO];
+}
+
++ (instancetype)adapterWithURL:(NSURL *)url allowsInvalidSSLCertificate : (BOOL) allowsInvalidSSLCertificate {
+    return [[self alloc] initWithURL:url allowsInvalidSSLCertificate:allowsInvalidSSLCertificate];
+}
+
+- (instancetype)init {
+    return [self initWithURL:nil];
+}
+
+- (instancetype)initWithURL:(NSURL *)url {
+    return [self initWithURL:url allowsInvalidSSLCertificate:NO];
+}
+
+- (instancetype)initWithURL:(NSURL *)url  allowsInvalidSSLCertificate : (BOOL) allowsInvalidSSLCertificate {
+    self = [super init];
+
+    if (self) {
+        self.allowsInvalidSSLCertificate = allowsInvalidSSLCertificate;
+        self.connected = NO;
+
+        if(url) {
+            [self connectToURL:url];
+        }
+    }
+
+    return self;
+}
+
+- (void)connectToURL:(NSURL *)url {
+    // TODO(schoon) - Break out and document error description.
+    NSAssert(NO, @"Invalid Adapter.");
+}
+
+- (void)invokeStaticMethod:(NSString *)path
+                parameters:(NSDictionary *)parameters
+                   success:(SLSuccessBlock)success
+                   failure:(SLFailureBlock)failure {
+    NSAssert(NO, @"Invalid Adapter.");
+}
+
+- (void)invokeInstanceMethod:(NSString *)path
+       constructorParameters:(NSDictionary *)constructorParameters
+                  parameters:(NSDictionary *)parameters
+                     success:(SLSuccessBlock)success
+                     failure:(SLFailureBlock)failure {
+    NSAssert(NO, @"Invalid Adapter.");
+}
+
+@end

SLRemoting/SLObject.h

@@ -0,0 +1,135 @@
+/**
+ * @file SLObject.h
+ *
+ * @author Michael Schoonmaker
+ * @copyright (c) 2013 StrongLoop. All rights reserved.
+ */
+
+#import <Foundation/Foundation.h>
+
+#import "SLAdapter.h"
+
+/**
+ * An error description for SLObjects with an invalid repository, which happens
+ * when SLObjects are created improperly.
+ */
+extern NSString *SLObjectInvalidRepositoryDescription;
+
+@class SLRepository;
+
+/**
+ * A local representative of a single virtual object. The behaviour of this
+ * object is defined through a prototype defined on the server, and the identity
+ * of this instance is defined through its `creationParameters`.
+ */
+@interface SLObject : NSObject
+
+/** The SLRepository defining the type of this object. */
+@property (readonly, nonatomic, weak) SLRepository *repository;
+
+/**
+ * The complete set of parameters to be used to identify/create this object on
+ * the server.
+ */
+@property (readonly, nonatomic, strong) NSDictionary *creationParameters;
+
+/**
+ * Returns a new object with the type defined by given repository.
+ *
+ * @param  repository  The repository this object is associated with.
+ * @param  parameters  The creationParameters of the new object.
+ * @return             A new object.
+ */
++ (instancetype)objectWithRepository:(SLRepository *)repository
+                         parameters:(NSDictionary *)parameters;
+
+/**
+ * Initializes a new object with the type defined by the given repository.
+ *
+ * @param  repository  The repository this object is associated with.
+ * @param  parameters  The creationParameters of the new object.
+ * @return             The new object.
+ */
+- (instancetype)initWithRepository:(SLRepository *)repository
+                       parameters:(NSDictionary *)parameters;
+
+/**
+ * Invokes a remotable method exposed within instances of this class on the
+ * server.
+ *
+ * @see SLAdapter::invokeInstanceMethod:constructorParameters:parameters:success:failure:
+ *
+ * @param name        The method to invoke (without the prototype), e.g.
+ *                    `doSomething`.
+ * @param parameters  The parameters to invoke with.
+ * @param success     An SLSuccessBlock to be executed when the invocation
+ *                    succeeds.
+ * @param failure     An SLFailureBlock to be executed when the invocation
+ *                    fails.
+ */
+- (void)invokeMethod:(NSString *)name
+          parameters:(NSDictionary *)parameters
+             success:(SLSuccessBlock)success
+             failure:(SLFailureBlock)failure;
+
+@end
+
+/**
+ * A local representative of classes ("prototypes" in JavaScript) defined and
+ * made remotable on the server.
+ */
+@interface SLRepository : NSObject
+
+/** The name given to this class on the server. */
+@property (readonly, nonatomic, copy) NSString *className;
+
+/**
+ * The SLAdapter that should be used for invoking methods, both for static
+ * methods on this repository and all methods on all instances of this class.
+ */
+@property (readwrite, nonatomic) SLAdapter *adapter;
+
+/**
+ * Returns a new Repository representing the named remote class.
+ *
+ * @param  name  The remote class name.
+ * @return       A repository.
+ */
++ (instancetype)repositoryWithClassName:(NSString *)name;
+
+/**
+ * Initializes a new Repository, associating it with the named remote class.
+ *
+ * @param  name  The remote class name.
+ * @return       The repository.
+ */
+- (instancetype)initWithClassName:(NSString *)name;
+
+/**
+ * Returns a new SLObject as a virtual instance of this remote class.
+ *
+ * @param  parameters  The `creationParameters` of the new SLObject.
+ * @return             A new SLObject based on this class.
+ */
+- (SLObject *)objectWithParameters:(NSDictionary *)parameters;
+
+/**
+ * Invokes a remotable method exposed statically within this class on the
+ * server.
+ *
+ * @see SLAdapter::invokeStaticMethod:parameters:success:failure:
+ *
+ * @param name        The method to invoke (without the class name), e.g.
+ *                    `doSomething`.
+ * @param parameters  The parameters to invoke with.
+ * @param success     An SLSuccessBlock to be executed when the invocation
+ *                    succeeds.
+ * @param failure     An SLFailureBlock to be executed when the invocation
+ *                    fails.
+ */
+- (void)invokeStaticMethod:(NSString *)name
+                parameters:(NSDictionary *)parameters
+                   success:(SLSuccessBlock)success
+                   failure:(SLFailureBlock)failure;
+
+@end