Tutorial
Welcome to the Objective Cloud tutorial. In this tutorial you are going to learn the fundamentals of Objective Cloud:
- How to create a new account
- How to create new applications in the cloud
- How to test and modify your applications locally
- How to deploy your applications on Objective Cloud
- How to use your deployed applications All this should take you only about 10 to 20 minutes and then you should be able to roll your own cloud applications.
It is not required to create an Objective Cloud account in order to use Objective Cloud locally. Although creating an account right away makes it easier to get started. You create an account at Objective Cloud Connect.
The first thing you have to do after creating a new account is to login, go to your account settings and add your public key. We need your public key so that we can setup git repositories for your cloud applications automatically and so that you can securely push changes to Objective Cloud.
You may already have a public key at hand. If you are not sure about that you can check for the existence of your public key by using Terminal:
$ cd ~/.ssh
If Terminal says "No such file or directory" you do not have a public key already. Please go to step 2 in this case. Otherwise you can use the existing public key for Objective Cloud by skipping to step 3.
You do not have a public/private key pair already - so let's create one in Terminal:
$ ssh-keygen -t rsa -C "you@example.com"
ssh-keygen will ask you about several things. You can simply hit enter all the time except when you have to enter a passphrase. When asked for a passphrase pick a good password which will be used to protect your private key file. SSH is tightly integrated in OS X so you won't have to enter this passphrase again and again if you don't want to.
Now you have to get the public key to Objective Cloud Connect somehow. Luckily this is very straight forward by using Terminal:
$ cat ~/.ssh/id_rsa.pub | pbcopy -pboard general
Now the contents of the public key file are in your pasteboard. Go to your account settings on Objective Cloud Connect, click on the "Public Key" text view and hit cmd+v. Now you can click on "Save". This can take a few moments.
Having an account makes it easy to create new cloud applications:
- Got to the applications tab on Objective Cloud Connect
- Click on "New Application" purposes please use "My App" as the name. The name of the application does not really matter. It is only there so that you can use it to differentiate easily between your different cloud applications.
- The identifier is more important because it will be used later on when sending messages to your cloud application. For testing purposes please enter "com.company.test" in the identifier text field.
- Now click on "Create Application". This will take a few moments because behind the scences at lot of things are happing once you click on the button.
Once Objective Cloud has created the application for you it should appear in the applications table view. Congratulations: You have just created your first cloud application on Objective Cloud! In fact: We have automatically deployed the application on Objective Cloud and if you knew how you were able to use it already.
In order to test the application locally you first have to clone the application from Objective Cloud. The third column of the applications table view contains the command you have to execute in Terminal in order to clone the application and make it available on your Mac. The concrete command is different for each application you create. Copy the command from the third column and paste it in a Terminal window:
$ cd
# 'cd' makes sure that we are in the home directory of the current user
$ git clone git@git.objective-cloud.com:...
# make sure to copy the command from the applications table view (third column)
The command above should create a folder which you can open and view in Finder. It should look something like this:
As you can see there is an Xcode project. This is the default Objective Cloud application template.
- Open this project in Xcode.
- Before you run this application you have to download Terrasphere which is the name of the Objective Cloud application server.
- Once downloaded, start Terrasphere. You should see something like this:
- Back in Xcode: Click on "Run". This will compile and launch your cloud application.
- The cloud application should appear in Terrasphere automatically and in your menu bar.
-
The services tab shows you the running cloud application. If you had more than one cloud application (advanced topic) they would show up there as well. The default cloud application contains a service with several messages. Let's now send the message "sayHello" to the cloud application.
-
Send sayHello to the cloud application: ** Click on the entry which says "sayHello". On the right side you see an empty outline view which you can use to create messages. Since "sayHello" is a very simple message (it has no parameters) you can't do anything there. ** Click on "Copy to Pasteboard". This will copy the text above the button to the pasteboard. The text above the button is a command which will send the message "sayHello" to your cloud application on your local machine. ** Open a Terminal and paste the contents of your pasteboard in there and press enter. You should see something like this:
{ "returnValue" : "Hello Service!" }
-
This is the response generated by the message "sayHello".
-
Now click on the "Messages" tab. The messages tab shows you the messages which have been sent to Terrasphere. You should see something like this:
- The messages tab will become more useful when you are sending more complicated messages to your cloud application.
- Go back to Xcode and stop the application. Let's now modify your cloud application.
- Open the file "Service.m":
-
Every service in Objective Cloud is a subclass of "OCAService". The class "Service" is a subclass of "OCAService". By default: Every class method you put in the implementation file of the service class will be accessible via HTTP. The method +sayHello (last method in Service.m) is the method which is called every time the curl-command (see above) is executed.
-
Change the implementation of +sayHello to:
- (NSString *)sayHello { return @"Hello World!"; }
-
Now click on "Run" again and switch to Terrasphere:
-
You should see two entries in the services outline view: Don't get confused: Terrasphere does also show the entries of cloud applications which have been terminated. ** Execute the same curl-command from above. You should get a different result back:
{ "returnValue" : "Hello World!" }
You have now successfully modified the implementation of a method. You can also add your own method. This will be covered in a second tutorial. For now we are happy with what we just did.
The previous section showed you how to test and modify your cloud application locally. Let's now take it one step further and deploy the cloud application on Objective Cloud. Luckily Xcode can do this for you!
- Select "File | Source Control | Commit..." from the Xcode menu.
- Enter a commit message and click on the commit button.
- Select "File | Source Control | Push..." from the Xcode menu.
By doing so you send your modified Xcode project to Objective Cloud. Once Objective Cloud received your Xcode project it will be compiled and deployed on Objective Cloud. You can now call the modified method "sayHello" by reusing your earlier curl-command but make sure to replace "localhost:10000" with "invoke.objective-cloud.com". So for example if your previous curl-command looked like this:
curl -d "{ \"message\" : { \"selector\" : \"sayHello\", \"arguments\" : [] } }" localhost:10000/teams/1wwis1fqju1yw/apps/com.company.test/services/YourService
It now had to look like this:
curl -d "{ \"message\" : { \"selector\" : \"sayHello\", \"arguments\" : [] } }" invoke.objective-cloud.com/teams/1wwis1fqju1yw/apps/com.company.test/services/YourService
And what you should see after executing the new curl-command is this:
{
"returnValue" : "Hello World!"
}
Granted, a method like +sayHello is not really impressive: It neither has a return value nor any parameters. Let's now add a new method to your service in order to make things a bit more interesting. Navigate back to Service.m and add a new class method named sumOf:and: somewhere between @implementation Service and @end. The new method will have two NSNumber parameters. In the implementation of this method we calculate the sum of those two numbers and return the result as an NSNumber. The contents of Service.m should look something like this:
@implementation
+ (NSNumber *)sumOf:(NSNumber *)a and:(NSNumber *)b {
return @(a.integerValue + b.integerValue);
}
+ (NSString *)sayHello {
return @"Hello World!";
}
@end
You can now simply run the app from within Xcode and switch back to Terrasphere. You should see the method +sumOf:and: there. Terrasphere is not only a small application server but also a nice UI that can be used to compose new messages. This feature of Terrasphere comes in very handy once your methods get a little bit more complicated. Select the sumOf:and: in the services outline view on the left. On the right you should see the message composer which is a small property list-style editor. Since +sumOf:and: has two parameters the message composer has two entries: one for each parameter. +sumOf:and: expects two numbers so use "Numer" in the type column. The value column allows you to enter the actual values for the parameters. Enter two numbers. At the bottom you see a text view which contains a dynamically generated command that you can copy to your pasteboard. The command will send the message you composed in the message composer to Terrasphere via HTTP. Click on the button, switch to Terminal and paste the contents of the pasteboard in Terminal and press enter. You should see a return value which is the sum of the two numbers you entered in the message composer.
Isn't this great? You have just written a small web service that can add two numbers.
The cool thing about Objective-Cloud is that you can use every JSON compatible classes in your method signatures. This means that you can use
- NSString
- NSNumber (for integers, floats and booleans)
- NSDictionary
- NSArray
- NSNull
as return types and/or parameter types. Arrays and dictionaries can of course be nested. With a little bit of extra work you can also use every other class in your method signature. You only have to implement a simple protocol which tells Objective-Cloud how to encode an object to JSON. In many cases you don't even have to do that in order to support non-JSON compatible types. You can simply turn on automatic JSON serialization and in many cases this works out fine. Objective-Cloud also supports out-arguments. A typical use case for out-arguments is error handling:
@implementation
// Usually you would use BOOL instead of NSNumber but at the moment
// Objective-Cloud does not support scalar types.
+ (NSNumber *)doSomethingWith:(NSString *)string error:(NSError **)error {
if(string == nil) {
if(error != NULL) {
*error = [self createError];
}
return @NO;
}
return [self doTheActualWork];
}
@end
Objective-Cloud can even do that. In this case the response contains the actual return value and, assuming an error has been created, the error.
The documentation contains a whole chapter about those advanced topics.