| Declared in | OCClient/OCCService.h |
| Base class | NSObject |
| Guides | Client LibrariesClient Libraries Conceptual Guide |
Subclasses of OCCService builds the local counterpart of service classes inside the cloud application. Every used service of the cloud application has to be represented by a local stand-in subclass at the client application:
#import <Cocoa/Cocoa.h>
#import <OCClient/OCClient.h> // Import OCCService
// Subclass with messaging infrastructure
@interface Service : OCCService // Local subclass
@endTo import the API of the cloud application's service class you have to add a category interface, which promises to implement the exported cloud interface.
#import "ServiceCloudInterface.h" // Import the cloud interface
// Add service's API
@interface Service (CloudInterface) <ServiceCloudInterface> // Add cloud interface to subclass
@endAt runtime you have to link the local stand-in class to the remote service class:
[Service linkToCloudApp:@"clienttutorial" protocol:@protocol(ServiceCloudInterface) handler:
^(__unsafe_unretained Class serviceClass, NSError *error)
{
…
}From this point you can send messages to that service directly …:
#import "Service.h"
…
[Service sayHello];… or asynchronously using an invocation object:
#import "Service.h"
…
id<ServiceCloudInterface> invocation = [Service invokeWithHandler:
^(BOOL success, id response)
{
…
}];
[invocation sayHello];Additionally you can group a bunch of invocations into invocation groups.
+setLocalHost:
+setRemoteHost:
+setUsesRemoteHost:
+completeHostName
+linkToCloudApp:protocol:URLSession:handler:
+linkToCloudApp:protocol:handler:
OCCConnectionHandler
+invokeWithHandler:
+invokeAndDispatchOnMainQueue:handler:
+invokeWithReturnHandler:errorHandler:
Returns the composed URL as a string used for sending messages to the cloud application's service.
+ (NSString *)completeHostName
The composed URL string.
The result of the method depends on +setUsesRemoteHost:, +setRemoteHost: and +setLocalHost:. The content is an implementation detail and you should not rely on a concrete format. You can use the result to build an URL for sending messages with Cocoa's URL loading system.
Returns an invocation object.
+(id)invokeAndDispatchOnMainQueue:(BOOL)dispatchOnMainQueue handler:(OCCInvocationResponseHandler)handler;
YES, the completion handler is executed on the main queue otherwise on the queue on which the message is sent.A proxy object you can sent the service's messages to.
This method starts the asynchronous messaging mechanism. It returns an object that can receive all messages for the receiver class and sends them to the cloud. It then returns immediately. If the the response is received it calls the handler.
The handler is called with its parameter success being set to YES, if the message has been dispatched. In this case the responseValue parameter of the handler contains the return value of the method.
If the dispatching failed, success is set to NO and the response value contains an instance of NSError.
Before you can use this method the receiver class has to be linked to the cloud service class using +linkToCloudApp:protocol:handler: et al.
Returns an invocation object.
+(id)invokeWithHandler:(OCCInvocationResponseHandler)handler
A proxy object you can sent the service's messages to.
Simply sends +invokeAndDispatchOnMainQueue:handler: with dispatchOnMainQueue set to YES.
+invokeAndDispatchOnMainQueue:handler:
Returns an invocation object that calls separate handlers for success and error.
+(id)invokeWithReturnHandler:(OCCInvocationReturnHandler)returnHandler errorHandler:(OCCInvocationErrorHandler)errorHandler
A proxy object you can sent the service's messages to.
The returned invocation object calls it handlers on the main thread, but uses separate handlers for success and fail. This is useful, when a global standard error handling can be applied.
Links the receiver to a remote class.
+(BOOL)linkToCloudApp:(NSString*)cloudApp protocol:(Protocol*)protocol URLSession:(NSURLSession *)URLSession
handler:(OCCConnectionHandler)handler
YES, if successfully linked, otherwise NO.
Links the receiver against the eponymous class in the cloud application applying the protocol. Messages to the remote class are sent using the given URL session.
By now the linking is done only locally. That means that no communication is necessary. Consequently providing correct arguments the return value is YES even there is no connection to the server.
The method itself appends a block operation with the handler to the main operation queue and then returns. Therefore the handler is executed after returning from the method, if the message is sent on the main thread. Otherwise the order is undefined.
Future implementations may communicate with the server causing a longer delay between returning from the method and execution of the handler.
Links the receiver to a remote class
+ (BOOL)linkToCloudApp:(NSString*)cloudApp protocol:(Protocol*)protocol handler:(OCCConnectionHandler)handler
YES, if successfully linked, otherwise NO.
Uses +linkToCloudApp:protocol:URSLSession:handler with a private URL session.
Sets the domain and port of a local Terrasphere.
+ (void)setLocalHost:(NSString*)host;
Sets the domain of the local host. A port number can be assigned. The default is @"localhost:10000". The local host is used for messages to the cloud application, when setUsesRemoteHost: hasn't been sent to the receiver with NO.
You can use this method to let the client application talk with a dedicated Terrasphere in your local area network or to use a Terrasphere on your Mac, when running the client application on an iOS device.
Sets the domain and port of a remote (production) Terrasphere.
+ (void)setRemoteHost:(NSString*)host;
Sets the domain of the remote host. A port number can be assigned. The default is @"obcl.io". The remote host is used for messages to the cloud application, when setUsesRemoteHost: has been sent to the receiver with YES.
You have to send this message only if you are self-hosting Objective-Cloud for production. If you want to set the host for development and debugging, use +setLocalHost:.
Switches between local (development) and remote (production) Terrasphere.
+(void)setUsesRemoteHost:(BOOL)worksRemotly
YES messages are sent to the remote Terrasphere, otherwise to the local instance.The client framework has to modes: Local mode and remote mode. The local mode is used for development and debugging, the remote mode for production.
There are some changes in the behavior of the client framework (and Terrasphere) depending on the mode. In local mode HTTP is used instead of HTTPS, no subdomains are applied to the host's domain and the local host domain is used instead of the remote host domain.
Block that is called after a class is linked to a cloud application's class.
typedef void (^OCCConnectionHandler)(Class serviceClass, NSError *error);
This block is called after a linkToCloudApp:… message successfully run. The first parameter is a class object of the linked class. The second parameter takes an instance of NSError, if something failed or nil.