Latest 0.6.0
Homepage https://github.com/artcom/gom-client-objc
License MIT
Platforms ios 5.0, osx 10.7, requires ARC
Dependencies SocketRocket
Authors

Objective-C GOM Client

Version
Platform

Requirements

Using the GOM client in your app project

To use the Objective-C GOM client in your project add the line

pod "gom-client-objc"

to your Podfile and install all necessary dependencies from the CocoaPods dependency manager.

All dependencies are defined in the file gom-client-objc.podspec

Usage

Initialization

NSURL *gomURI = [NSURL URLWithString:@"http://<ip-or-name>:<port>"];
GOMClient *gomClient = [[GOMClient alloc] initWithGomURI:gomURI delegate:self];

As soon as the GOMClient object is initialized and completely set up it will communicate its state through the GOMClientDelegate protocol method - (void)gomClientDidBecomeReady:(GOMClient *)gomClient returning a reference of the GOMClient object in question.

Errorhandling

Errors that occur during GOM requests are passed to the sender through the completion blocks of the respective methods.

Fundamental errors are returned to the delegate through the GOMClientDelegate protocol method - (void)gomClient:(GOMClient *)gomClient didFailWithError:(NSError *)error

RESTful operations

  • GET/retrieve

    • Attribute retrieval:
    [gomClient retrieve:@"/tests/node_1:attribute_1" completionBlock:^(NSDictionary *response, NSError *error) {
    
        // Your code here
    
    }];
    {attribute = {
        ctime = "2013-12-29T17:48:52+01:00";
        mtime = "2013-12-29T17:48:52+01:00";
        name = "attribute_1";
        node = "/tests/node_1";
        type = string;
        value = 100;
    }}
    
    • Retrieve a non-existing attribute:
    NSError Domain=de.artcom.gom-client-objc Code=404 "not found"
    • Node retrieval:
    [gomClient retrieve:@"/tests/node_1" completionBlock:^(NSDictionary *response, NSError *error) {
    
        // Your code here
    
     }];
     {node = {
        ctime = "2013-12-29T17:49:07+01:00";
        entries = (
            {
                attribute = {
                    ctime = "2013-12-29T17:48:52+01:00";
                    mtime = "2013-12-29T17:48:52+01:00";
                    name = "attribute_1";
                    node = "/tests/node_1";
                    type = string;
                    value = 100;
                };
            },
            {
                attribute = {
                    ctime = "2013-12-29T17:49:00+01:00";
                    mtime = "2013-12-29T17:49:00+01:00";
                    name = "attribute_2";
                    node = "/tests/node_1";
                    type = string;
                    value = 20;
                };
            },
            {
                attribute = {
                    ctime = "2013-12-29T17:49:07+01:00";
                    mtime = "2013-12-29T17:49:07+01:00";
                    name = "attribute_3";
                    node = "/tests/node_1";
                    type = string;
                    value = 50;
                };
            }
        );
        mtime = "2013-12-29T17:49:07+01:00";
        uri = "/tests/node_1";
    }}
    • Retrieve a non-existing node:
    NSError Domain=de.artcom.gom-client-objc Code=404 "not found"
  • POST/create

    • Create empty node:
    gomClient create:@"/tests/node_1/test" withAttributes:nil completionBlock:^(NSDictionary *response, NSError *error) {
    
        // Your code here
    
    }];
    {node = {
        ctime = "2013-12-29T17:54:16+01:00";
        entries = (
        );
        mtime = "2013-12-29T17:54:16+01:00";
        uri = "/tests/node_1/test/75d4fb2d-6b4d-4bc0-9e12-91817f90da1d";
    }}
    • Create node with attributes:
    NSDictionary *attributes = @{@"attribute1": @"value1", @"attribute2" : @"value2", @"attribute3" : @"value3"};
    gomClient create:@"/tests/node_1/test" withAttributes:attributes completionBlock:^(NSDictionary *response, NSError *error) {
    
        // Your code here
    
    }];
    {node = {
        ctime = "2013-12-29T17:56:04+01:00";
        entries = (
            {
                attribute = {
                    ctime = "2013-12-29T17:56:04+01:00";
                    mtime = "2013-12-29T17:56:04+01:00";
                    name = attribute1;
                    node = "/tests/node_1/test/b382502c-6732-46ae-bef4-31d9d77ad97b";
                    type = string;
                    value = value1;
                };
            },
            {
                attribute = {
                    ctime = "2013-12-29T17:56:04+01:00";
                    mtime = "2013-12-29T17:56:04+01:00";
                    name = attribute2;
                    node = "/tests/node_1/test/b382502c-6732-46ae-bef4-31d9d77ad97b";
                    type = string;
                    value = value2;
                };
            },
            {
                attribute = {
                    ctime = "2013-12-29T17:56:04+01:00";
                    mtime = "2013-12-29T17:56:04+01:00";
                    name = attribute3;
                    node = "/tests/node_1/test/b382502c-6732-46ae-bef4-31d9d77ad97b";
                    type = string;
                    value = value3;
                };
            }
        );
        mtime = "2013-12-29T17:56:04+01:00";
        uri = "/tests/node_1/test/b382502c-6732-46ae-bef4-31d9d77ad97b";
    }}
  • PUT/update

    • Attribute update:
    [gomClient updateAttribute:@"/tests/node_1:attribute_1" withValue:@"50" completionBlock:^(NSDictionary *response, NSError *error) {
    
        // Your code here
    
    }];        
    {status = 200}
    • Node update:
    NSDictionary *attributes = @{@"attribute1": @"100", @"attribute2" : @"200", @"attribute3" : @"300"};
    [gomClient updateNode:@"/tests/node_1/test/b382502c-6732-46ae-bef4-31d9d77ad97b" withAttributesValue:attributes completionBlock:^(NSDictionary *response, NSError *error) {
    
        // Your code here
    
    }];
    {status = 200}
  • DELETE/destroy

    • Destroy existing attribute:
    [gomClient destroy:@"/tests/node_1:attribute_3" completionBlock:^(NSDictionary *response, NSError *error) {
    
        // Your code here
    
    }];
    {"success" = 1}
    • Destroy existing node:
    [gomClient destroy:@"/tests/node_1" completionBlock:^(NSDictionary *response, NSError *error) {
    
        // Your code here
    
    }];
    {"success" = 1}
    • Destroy non-existing attribute:
    [gomClient destroy:@"/tests/node_1:attribute_x" completionBlock:^(NSDictionary *response, NSError *error) {
    
        // Your code here
    
    }];
    NSError Domain=de.artcom.gom-client-objc Code=404 "not found"
    • Destroy non-existing node:
    [gomClient destroy:@"/tests/node_x" completionBlock:^(NSDictionary *response, NSError *error) {
    
        // Your code here
    
    }];
    NSError Domain=de.artcom.gom-client-objc Code=404 "not found"

Handling observers

  • Register an observer:

    [gomClient registerGOMObserverForPath:@"/tests/node_1:attribute_2" clientCallback:^(NSDictionary *dict) {
    
        // Your code here
    
    }];

    The first GOM notifcation is received immediately:

    {
        event_type = "initial"
        path = "/tests/node_1:attribute_2"
        payload = {
            attribute = {
                ctime = "2013-12-29T18:00:27+01:00";
                mtime = "2013-12-29T18:00:27+01:00";
                name = "attribute_2";
                node = "/tests/node_1";
                type = string;
                value = 20;
            }
        }
    }}
  • Unregister an observer:

    [gomClient unregisterGOMObserverForPath:@"/tests/node_1:attribute_2"];

Mapping response dictionaries to data objects

If the response dictionaries from the GOM are to cumbersome to handle you can use the following classes to map the dictionaries to data objects.

  • When receiving an attribute:

    GOMAttribute *attribute = [GOMAttribute attributeFromDictionary:response];
  • When receiving a node:

    GOMNode *node = [GOMNode nodeFromDictionary:response];

Handling websocket reconnects

If the gom client’s websocket fails it sends the delegate the message - (BOOL)gomClientShouldReconnect:(GOMClient *)gomClient. Return YES to reconnect. You can also trigger the reconnect later by calling - (void)reconnectWebSocket.

When the gom client reconnects and finds existing bindings it sends the delegate the message - (BOOL)gomClient:(GOMClient *)gomClient shouldReRegisterObserverWithBinding:(GOMBinding *)binding.

Return YES to re-register an observer for the path in question.
Re-registration will be silent, no initial GNP will be received. Return NO to discard the existing binding.

If the method is not implemented all bindings will be discarded.

Setting up for client development

To setup the project for GOM client development open the terminal and clone the repo:

$ git clone https://github.com/artcom/gom-client-objc.git

and install all necessary dependencies from the CocoaPods dependency manager:

$ cd demo-projects/gom-client-demo_iOS
$ pod install

You can use the demo app contained in this project to run and test your work.

All dependencies are defined in the file Podfile

Demo app

Setting the GOM root address:

Setting the GOM root

Startup – the demo app offers input fields for GOM node or attriute and a value. Four buttons below represent the commands you can send to the GOM:

  • Retrieve
  • Create
  • Update
  • Del(ete)

All responses and GNPs from the GOM will appear in the output field above:

Startup

Accessing a GOM value – just enter the path to the node or attribute and tap ‘Retrieve’:

Accessing GOM values

The response from the GOM will appear in the output field above:

Retrieving GOM values

Adding an observer – tap ‘Manage Observers’ to open the observer management view. Enter the path to the node or attribute and tap ‘Add Observer’:

Adding a GOM observer

List with observers – registered observers will appear in the table above. Each additional observer on the same path will only increase the number of handles, shown as the item ‘Handles’:

GOM observer added

Deleting an observer – just swipe to the left and the ‘Delete’ button appears:

Deleting a GOM observer

Latest podspec

{
    "name": "gom-client-objc",
    "version": "0.6.0",
    "summary": "A GOM client written in Objective-C for the Cocoa framework.",
    "description": "                    This project contains a GOM client written in Objective-C for the Cocoa framework. This client can be used in iOS and OS X projects.n",
    "homepage": "https://github.com/artcom/gom-client-objc",
    "license": {
        "type": "MIT",
        "file": "LICENSE"
    },
    "authors": {
        "Julian Krumow": "[email protected]"
    },
    "platforms": {
        "ios": "5.0",
        "osx": "10.7"
    },
    "source": {
        "git": "https://github.com/artcom/gom-client-objc.git",
        "tag": "0.6.0"
    },
    "source_files": "Classes/**/*.{h,m}",
    "requires_arc": true,
    "dependencies": {
        "SocketRocket": [
            "~> 0.3"
        ]
    }
}

Pin It on Pinterest

Share This