https://github.com/artcom/gom-client-objc
Objective-C GOM Client
https://github.com/artcom/gom-client-objc
Last synced: 9 months ago
JSON representation
Objective-C GOM Client
- Host: GitHub
- URL: https://github.com/artcom/gom-client-objc
- Owner: artcom
- License: mit
- Archived: true
- Created: 2013-09-13T15:05:47.000Z (almost 13 years ago)
- Default Branch: master
- Last Pushed: 2014-08-08T19:32:43.000Z (almost 12 years ago)
- Last Synced: 2025-10-20T22:34:05.016Z (9 months ago)
- Language: Objective-C
- Homepage:
- Size: 3.15 MB
- Stars: 0
- Watchers: 13
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Objective-C GOM Client
[](http://cocoadocs.org/docsets/gom-client-objc)
[](http://cocoadocs.org/docsets/gom-client-objc)
##Requirements
* [CocoaPods dependency manager](http://cocoapods.org)
* Xcode 4.5 or later
### 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
```objective-c
NSURL *gomURI = [NSURL URLWithString:@"http://:"];
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:
```objective-c
[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:
```objective-c
[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:
```objective-c
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:
```objective-c
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:
```objective-c
[gomClient updateAttribute:@"/tests/node_1:attribute_1" withValue:@"50" completionBlock:^(NSDictionary *response, NSError *error) {
// Your code here
}];
```
```
{status = 200}
```
* Node update:
```objective-c
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:
```objective-c
[gomClient destroy:@"/tests/node_1:attribute_3" completionBlock:^(NSDictionary *response, NSError *error) {
// Your code here
}];
```
```
{"success" = 1}
```
* Destroy existing node:
```objective-c
[gomClient destroy:@"/tests/node_1" completionBlock:^(NSDictionary *response, NSError *error) {
// Your code here
}];
```
```
{"success" = 1}
```
* Destroy non-existing attribute:
```objective-c
[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:
```objective-c
[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:
```objective-c
[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:
```objective-c
[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:
```objective-c
GOMAttribute *attribute = [GOMAttribute attributeFromDictionary:response];
```
* When receiving a node:
```objective-c
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:
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:
Accessing a GOM value - just enter the path to the node or attribute and tap 'Retrieve':
The response from the GOM will appear in the output field above:
Adding an observer - tap 'Manage Observers' to open the observer management view. Enter the path to the node or attribute and tap 'Add 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':
Deleting an observer - just swipe to the left and the 'Delete' button appears:
