Objective-C in the Cloud

Request-based Services on Objective-Cloud

This document is an introduction to request-based services.

Introduction

Before you continue

Before you continue you should have read the Objective-Cloud introduction.

Overview

Objective-Cloud makes it super easy to (remotely) invoke Objective-C methods. We have put in a lot of effort to also make this feature of Objective-Cloud very powerful. Almost everything you want to do can be accomplished with it. However there are certain situations in which you want to develop a request based web application. The good news is that Objective-Cloud has built in support for that.

For selecting the right type of service refer here.

Tutorial

As already mentioned: Every cloud application starts an HTTP server. This is done automatically and you don't have to worry about it. A default cloud application contains a class called CloudApp which is a subclass of OCFCloudApp. OCFCloudApp has a class method which allows you to add routes and handlers: +handleRequestsWithMethod:matchingPath:withBlock:. This tutorial won't go deep into the details. Instead it will guide you through the creation of your first request based application. This tutorial assumes that you know how to create new cloud applications and how to deploy them on Objective-Cloud.com.

1. Step: Make sure you have everything you need

For this tutorial to work you need a few things. Make sure you have them at hand.

  • You need a cloud application on your Mac in the form of an Xcode project.
  • You need Terrasphere (or terrasphered) on your Mac as well as the Objective-Cloud frameworks installed in /Library/Frameworks. This is normally all done by the Objective-Cloud installer.

A cloud application is by default able to handle HTTP requests. You have not to configure anything. Everything we do is add a few lines of Objective-C code to actually handle HTTP requests.

2. Step: Add a handler to your request based application

Under the hood OCFCloudApp is using an instance of OCFWebApplication which is part of the open source framework OCFWeb. This is an implementation detail but important to know because this means that +handleRequestsWithMethod:matchingPath:withBlock: works the same way -handle:requestsMatching:withBlock: (OCFWebApplication) does. At this point you should definitely check out the documentation of OCFWeb.

Open CloudApp.m in Xcode. You should see something like this:

1 #import "CloudApp.h"
2 
3 @implementation CloudApp
4 @end

Remark: If there is code between @implementation and @end and it is not yours then remove it. This is probably sample code from Objective-Cloud to get you started.

Let's now add a custom route and handler to the CloudApp:

 1 #import "CloudApp.h"
 2 #import <OCFWeb/OCFRequest.h>
 3 
 4 @implementation CloudApp
 5 
 6 // +finishLaunching is called automatically once in the lifetime
 7 // of your cloud application. This is where you do setup related
 8 // things like creating routes and handlers.
 9 
10 + (void)finishLaunching {
11   // Add the route and handler
12   [self handleRequestsWithMethod:@"GET"
13                     matchingPath:@"/hello"
14                        withBlock:^(OCFRequest *request) {
15                          // respond with "Hello World"
16                          [request respondWith:@"Hello World"];
17                        }];
18 }
19 
20 @end

3. Step: Launch and test

Now launch terrasphered (or terraspheredd) and after that your cloud app. If you look at the console you should see a log statement that looks something like this:

local.com.yourcompany.CloudApp[37113:303] Register route with path: /hello

After launching your cloud app open your favorite browser and go to: http://localhost:10000/hello. You should see something like this:

4. Step: Understand the code

As already mentioned: OCFCloudApp is using OCFWeb under the hood. So if you want to learn all of the details you should definitely check out the documentation of OCFWeb. This section of the tutorial will only describe the things that are specific to Objective-Cloud.

  • Line 12: This tells OCFCloudApp that you want to handle GET-requests which are matching the path of your cloud application. The matchingPath argument can actually be a pattern. You can find out more about path patters by reading the OCFWeb documentation.
  • Line 13: Every route you add must have a path. In the example above the path is hello. Paths can be more sophisticated though.
  • Line 16: Creating a HTTP response is easy: You call the -respondWith: method of OCFRequest and pass it your response. The response can be a simple string, an NSDictionary with special keys or an instance of OCFResponse.

5. Step: Get in touch with OCFWeb

There are much more things you can do with request based applications on Objective-Cloud. When adding a handler you can use a pattern as the path. A path pattern has placeholders which start with a :. There is also a template engine built in so that you can quickly create dynamic text content (HTML, XML/RSS, JSON). You can also easily work with HTML forms. To see what is possible you should now check out the OCFWeb documentation. You can also checkout the API documentation on OCFRequest and OCFResponse.

Talking to your app

Talking to your app is very straight forward:

  • If you are working locally you have to use http://localhost:10000/$path.
  • If you are working remotely you have to use https://$app.obcl.io/$path, where $app is the name of your application.

Architectural Overview

This architectural overview describes the big picture from your perspective as a customer of Objective-Cloud who wants to develop web applications. Before we dive in you should know that Objective-Cloud builds on a strong and open source foundation of web technologies such as OCFWebServer and OCFWeb.

Cloud applications are the basic building blocks of Objective-Cloud. You can create as many cloud applications as you want. Each cloud application starts an HTTP server on a random port when launched and is ready to receive requests. Before the HTTP server is launched you have the opportunity to add custom routes and handlers. You basically say which HTTP requests you want to handle.

When a request comes in from the internet it goes through the load balancer and ends up on one of the available servers. Every server (Server A, B and C) knows about the existence of your cloud application. If a matching request comes in the server sees that and forwards the request to your cloud application. Your cloud application should create a response which is then routed back to the internet.