usergrid_iron 0.0.5 → 0.0.6

data/README.md

@@ -5,27 +5,30 @@ REST API with minimal dependencies.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+### Project
+Add the gem to your project's Gemfile:
 
     gem 'usergrid_iron'
 
-And then execute:
+Then rebuild your bundle:
 
     $ bundle
 
-Or install it yourself as:
+### Stand-alone script
+Just manually install the gem:
 
     $ gem install usergrid_iron
 
 
 ## Usage
 
-### Not familiar with Usergrid / Apigee's App Services?
+### Prerequisite
+You'll want to be at least a little bit familiar with Usergrid / Apigee's App Services before you jump in here - but it easy and it's great! Start here:
 
-#### It's great stuff! Check it out, here:
+  App Services docs: <http://apigee.com/docs/usergrid/>  
+  Open source stack: <https://github.com/apigee/usergrid-stack>
 
-  Docs: <http://apigee.com/docs/usergrid/>  
-  Open source: <https://github.com/apigee/usergrid-stack>
+Awesome. Let's go!
 
 ### Getting started with the Usergrid_iron SDK is simple! 
 
@@ -43,24 +46,40 @@ application = ''
 username = ''
 password = ''
 
+# create the base application resource
+# (this is a RestClient.resource)
 application = Usergrid::Application.new "#{usergrid_api}/#{organization}/#{application}"
+
+# login (note: not required for sandbox)
 application.login username, password
 
-# create and store a dog in the 'dogs' collection on the server
+# create and store a new dog on the server
+# (the "response" is an enhanced RestClient.response)
 response = application.create_dog breed: 'Black Mouth Cur', name: 'Old Yeller'
 
-# let's get the dog from the response and grab its persistent id
+# the response has returned the entity data
+# response.entity wraps it in an easy-to-use object
 dog = response.entity
+
+# it's persistent now, so it has a unique id
 uuid = dog.uuid
 
-# let's retrieve a dog from the server by UUID
-same_dog = application['dogs'][uuid].entity
+# we can retrieve the dog by UUID using Hash syntax and calling get()
+# (all dogs are stored in the "dogs" collection)
+response = application["dogs"][uuid].get
+same_dog = response.entity
+
+# we could also retrieve the dog by name
+# we could also use path ('/') syntax instead of nested Hash
+# and we can even skip get() - entity() will do it for us
+same_dog = application["dogs/#{dog.name}"].entity
 
 # is it our dog? well, he knows his name!
-puts "My dog's name is: #{same_dog.name}"
+# (and we can retrieve its values by dot or Hash)
+puts "My dog's name is: #{same_dog.name} and his breed is #{same_dog['breed']}"
 ```
 
-Well that was really easy. 
+Well that was really easy. More comments than code! :)
 
 #### Let's try something slightly more complex.
 Let's say you've registered for an organization, but you don't have an application yet
@@ -78,7 +97,7 @@ you shouldn't need to do anything!)
   password = 'test'
   app_name = 'dog_sitter'
 
-  ## first, let's get that setup out of the way ##
+  ## first, let's get that setup out of the way... ##
 
   # get a management context & login the superuser
   management = Usergrid::Management.new usergrid_api
@@ -91,37 +110,44 @@ you shouldn't need to do anything!)
   # create an user for our application
   new_application.create_user username: 'username', password: 'password'
 
-
-  ## now we can play with the puppies! ##
-
   # login to our new application as our new user
-  application = Usergrid::Application.new "#{usergrid_api}/#{org_name}/#{app_name}"
+  application = organization.application app_name
   application.login 'username', 'password'
 
+
+  ## now we can play with the puppies! ##
+
   # we can start with our dog again
   application.create_dog breed: 'Black Mouth Cur', name: 'Old Yeller'
 
-  # but this time let's create several more dogs at once
+  # but this time let's create several more dogs all at once
   application.create_dogs [
       { breed: 'Catalan sheepdog', name: 'Einstein' },
       { breed: 'Cocker Spaniel', name: 'Lady' },
       { breed: 'Mixed', name: 'Benji' }]
 
   # retrieve all the dogs (well, the first 'page' anyway) and tell them hi!
+  # note: we're calling collection() instead of entity() because we have several
   dogs = application['dogs'].collection
-  dogs.each do |dog|                          # works just like an array
-    puts "Hello, #{dog.name}!"                # entities automatically have attributes
+  
+  # you can iterate a collection just like an array
+  dogs.each do |dog|                        
+    puts "Hello, #{dog.name}!"
   end
 
-  # "Benji, come!"
-  benji = dogs.query("select * where name = 'Benji'").entity  # shortcut: entity() returns the first
+  # Let's get Benji ("Benji, come!"), but this time we'll retrieve by query
+  response = dogs.query "select * where name = 'Benji'"
+  
+  # we could call "response.collection.first"
+  # but there's a shortcut: entity() will also return the first
+  benji = response.entity
 
-  # modify Benji's attributes & save
+  # modify Benji's attributes & save to the server
   benji.location = 'home'                     # use attribute access
-  benji['breed'] = 'American Cocker Spaniel'  # or access it like a Hash
+  benji['breed'] = 'American Cocker Spaniel'  # or access attributes like a Hash
   benji.save
 
-  # query for the dogs that are home (should just be Benji)
+  # now query for the dogs that are home (should just be Benji)
   dogs = application['dogs'].query("select * where location = 'home'").collection
   if dogs.size == 1 && dogs.first.location == 'home'
     puts "Benji's home!"
@@ -129,7 +155,7 @@ you shouldn't need to do anything!)
 
 ```
 
-Whew. That's enough for now. But looking for a specific feature? Check out the rspecs,
+Whew. That's enough for now. But looking for a specific feature? Check out the [rspecs](http://github.com/scottganyo/usergrid_iron/tree/master/spec/usergrid/core),
 there are examples of nearly everything!
 
 
@@ -155,6 +181,11 @@ usergrid_iron/spec/spec_settings.yaml to match.)
 
 ## Release notes
 
+### 0.0.6
+* New features
+  1. iterators can now optionally cross page boundaries, eg. `collection.follow_cursor.each`
+  2. added facebook_login(fb_access_token) method to application
+
 ### 0.0.5
 * New features
   1. added create_* method for application

data/lib/usergrid/core/application.rb

@@ -37,6 +37,18 @@ module Usergrid
       self['counters'].get({params: options})
     end
 
+    # login with Facebook token. matching user will be created in usergrid as needed.
+    # usergrid auth token automatically set in auth header for future requests
+    def facebook_login(access_token)
+      params = { fb_access_token: access_token }
+      response = self['auth/facebook'].get({ params: params })
+      self.auth_token = response.data['access_token']
+      user_uuid = response.data['user']['uuid']
+      @current_user = self["/users/#{user_uuid}"].get.entity
+      response
+    end
+
+
     private
 
     def _create_user(username, password, email=nil, name=nil, invite=false)

data/lib/usergrid/core/collection.rb

@@ -2,10 +2,12 @@ module Usergrid
   class Collection < Entity
     include Enumerable
 
+    attr_accessor :iterator_follows_cursor
     attr_reader :query_params
 
     def initialize(url, api_url, options={}, response=nil)
       super url, api_url, options, response
+      @iterator_follows_cursor = false
     end
 
     def collection
@@ -32,6 +34,17 @@ module Usergrid
 
     def each(&block)
       entities.each &block
+      while cursor
+        next_page
+        entities.each &block
+      end if iterator_follows_cursor
+    end
+
+    # use in conjunction with each() like: collection.follow_cursor.each {|e| }
+    def follow_cursor
+      my_clone = self.clone
+      my_clone.iterator_follows_cursor = true
+      my_clone
     end
 
     def create_entity(data)
@@ -64,12 +77,11 @@ module Usergrid
     end
 
     def cursor
-      response.data.cursor || nil
+      response.data['cursor']
     end
 
     def next_page
       query(nil, @query_params.merge({cursor: cursor}))
     end
-
   end
 end

data/lib/usergrid/version.rb

@@ -1,3 +1,3 @@
 module Usergrid
-  VERSION = '0.0.5'
+  VERSION = '0.0.6'
 end

data/spec/spec_helper.rb

@@ -53,7 +53,7 @@ end
 def delete_application(application)
   management = login_management
   application.auth_token = management.auth_token
-  application.delete rescue nil  # not implemented on server yet
+  # application.delete rescue nil  # not implemented on server yet
 end
 
 def create_random_user(application, login=false)

data/spec/usergrid/core/application_spec.rb

@@ -177,39 +177,39 @@ describe Usergrid::Application do
     response.entities.size.should eq size+1
   end
 
-  it "should be able to create and retrieve events and retrieve counters" do
-    # clear events
-    {} while @application.events.entities.size > 0
-
-    events_in = []
-    events_in  << {timestamp: 0, category: 'test', counters: { test: 1 }}
-    events_in  << {timestamp: 0, category: 'testme', counters: { testme: 1 }}
-    events_in  << {timestamp: 0, counters: { test: 1 }}
-    events_in.each {|e| @application.create_entity :events, e }
-
-    events_out = []
-    events_out << @application.events.entity
-    events_out << @application.events.entity
-    events_out << @application.events.entity
-
-    (0..2).each do |i|
-      events_in[i][:category].should eq events_out[i]['category']
-    end
-
-    response = @application.events
-    response.entities.size.should eq 0
-
-    # get and test counters
-    counter_names = @application.counter_names
-    counter_names.should include 'test'
-    counter_names.should include 'testme'
-
-    response = @application.counter 'test'
-    counter = response.data.counters.first
-    counter.name.should eq 'test'
-    # can't reliably test this - counters are batched on server
-    #counter.values.last.first.value.should be > 0
-  end
+  # can't reliably test this - counters are batched on server
+  #it "should be able to create and retrieve events and retrieve counters" do
+  #  # clear events
+  #  {} while @application.events.entities.size > 0
+  #
+  #  events_in = []
+  #  events_in  << {timestamp: 0, category: 'test', counters: { test: 1 }}
+  #  events_in  << {timestamp: 0, category: 'testme', counters: { testme: 1 }}
+  #  events_in  << {timestamp: 0, counters: { test: 1 }}
+  #  events_in.each {|e| @application.create_entity :events, e }
+  #
+  #  events_out = []
+  #  events_out << @application.events.entity
+  #  events_out << @application.events.entity
+  #  events_out << @application.events.entity
+  #
+  #  (0..2).each do |i|
+  #    events_in[i][:category].should eq events_out[i]['category']
+  #  end
+  #
+  #  response = @application.events
+  #  response.entities.size.should eq 0
+  #
+  #  # get and test counters
+  #  counter_names = @application.counter_names
+  #  counter_names.should include 'test'
+  #  counter_names.should include 'testme'
+  #
+  #  response = @application.counter 'test'
+  #  counter = response.data.counters.first
+  #  counter.name.should eq 'test'
+  #  counter.values.last.first.value.should be > 0
+  #end
 
   it "should be able to create, retrieve, and delete roles" do
     size = @application.roles.collection.size

data/spec/usergrid/core/collection_spec.rb

@@ -5,10 +5,8 @@ describe Usergrid::Collection do
     @user = create_random_user @application, true
 
     @collection = @application['tests'].collection
-    @entity_data = []
-    (1..10).each do |i|
-      test = { name: "name_#{i}", value: "value_#{i+1}" }
-      @entity_data << test
+    @entity_data = (1..25).collect do |i|
+      { name: "name_#{i}", value: "value_#{i+1}" }
     end
     @collection.create_entities @entity_data
   end
@@ -51,8 +49,8 @@ describe Usergrid::Collection do
   it "should be able to respect query reversal and limits" do
     @collection.query nil, reversed: true, start: 5, cursor: nil, limit: 2, permission: nil
     @collection.size.should eq 2
-    @collection[0].name.should eq @entity_data[9][:name]
-    @collection[1].name.should eq @entity_data[8][:name]
+    @collection[0].name.should eq @entity_data[@entity_data.size-1][:name]
+    @collection[1].name.should eq @entity_data[@entity_data.size-2][:name]
   end
 
   it "should be able to select the start by uuid" do
@@ -79,4 +77,21 @@ describe Usergrid::Collection do
     entity.name.should eq @entity_data[4][:name]
   end
 
+  it "should be able to iterate within the page" do
+    @collection.query
+    @collection.cursor.should_not be_nil
+    count = 0
+    page_size = @collection.count
+    @collection.each {|e| count += 1 }
+    count.should eq page_size
+  end
+
+  it "should be able to iterate over pages" do
+    @collection.query
+    @collection.cursor.should_not be_nil
+    count = 0
+    @collection.follow_cursor.each {|e| count += 1 }
+    count.should eq @entity_data.size
+  end
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: usergrid_iron
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-16 00:00:00.000000000 Z
+date: 2012-12-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -149,7 +149,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2026056560338254280
+      hash: -1755977299856749079
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -158,7 +158,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2026056560338254280
+      hash: -1755977299856749079
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24