grouper-rest-client 0.1.0 → 0.2.0

data/.gitignore

@@ -2,4 +2,5 @@
 *.gem
 .bundle
 Gemfile.lock
+out.txt
 pkg/*

data/HISTORY

@@ -1,3 +1,16 @@
+2011-03-24 v0.2.0
+  - Added "Resource#group(name)" method
+  - Added "Resource#groups( group, [filter_type] )" method
+  - Added "Resource#stem(name)" method
+  - Added "Resource#stems( stem, [filter_type] )" method
+  - Added "Resource#subject(subject)" method
+  - Added "Resource::Group" class
+  - Added "Resource::Stem" class
+  - Added "Resource::Subject" class
+  - Changed "Resource#call( resource, [method] )" to be public.
+  - Changed "Resource#subjects(subject)" to return list of "Resource::Subject" objects or JSON error response.
+  - Moved "Resource#groups( subject, [stem_filter] )" to "Resource::Subject#group( [stem_filter] )"
+
 2011-03-18 v0.1.0
   - API namespace change.
   - Added "#subject(subject)" WS call.

data/README.rdoc

@@ -3,15 +3,43 @@
 == Usage
 
   Grouper::Rest::Client::Resource.new url, :user => user, :password => pass do |grouper|
-    # Get all group memberships.
-    groups = grouper.groups('blair')
-  
-    # Get group memberships within stem prefix.
-    filtered_groups = grouper.groups('blair', 'some:stem:')
-    
-    # Get subjects matching query.
-    subjects = grouper.subjects('blair')
-     
+    # Find all stems matching identifier.
+    stems = grouper.stems('some:approximate:stem')
+
+    # Find stem by name.
+    stem = grouper.stem('some:stem')
+
+    # UUID of stem.
+    stem['uuid']
+
+
+    # Find all groups matching identifier.
+    groups = grouper.groups('some:approximate:group')
+
+    # Find group by name.
+    group = grouper.group('some:group')
+
+    # UUID of group.
+    group['uuid']
+
+
+    # Find all subjects matching identifier.
+    subjects = grouper.subjects('foo')
+
+    # Find subject. 
+    subject = grouper.subject('blair')
+
+    # Subject's name and id.
+    subject['name']
+    subject['id']
+
+    # In what groups is this subject a member?
+    my_groups = subject.groups()
+
+    # In what groups within the specified stem is this subject a member?
+    my_filtered_groups = subject.groups('some:stem')
+
+
     # Was the last WS call successful?
     grouper.ok?
     

data/grouper-rest-client.gemspec

@@ -22,6 +22,6 @@ Gem::Specification.new do |s|
   s.add_dependency( %q<json>,         [ ">=1.5.1" ] )
   s.add_dependency( %q<rest-client>,  [ ">=1.6.1" ] )
 
-  s.add_development_dependency( %q<rspec> )
+  s.add_development_dependency( %q<rspec>,  [ ">=2.5.0" ] )
 end
 

data/lib/grouper-rest-client.rb

@@ -1,6 +1,4 @@
-require 'rubygems'
-require 'json'
-require 'rest_client'
+require File.join( File.expand_path( File.dirname(__FILE__) ), 'grouper-rest-client', 'resource' )
 
 module Grouper    # :nodoc:
   module Rest     # :nodoc:
@@ -8,89 +6,50 @@ module Grouper    # :nodoc:
     # 
     # == Usage
     #   Grouper::Rest::Client::Resource.new url, :user => user, :password => pass do |grouper|
-    #     # Get all group memberships.
-    #     groups = grouper.groups('blair')
-    #     
-    #     # Get group memberships within stem prefix.
-    #     filtered_groups = grouper.groups('blair', 'some:stem:')
+    #     # Find all stems matching identifier.
+    #     stems = grouper.stems('some:approximate:stem')
+    #
+    #     # Find stem by name.
+    #     stem = grouper.stem('some:stem')
+    #
+    #     # UUID of stem.
+    #     stem['uuid']
+    #
+    #
+    #     # Find all groups matching identifier.
+    #     groups = grouper.groups('some:approximate:group')
+    #
+    #     # Find group by name.
+    #     group = grouper.group('some:group')
+    #
+    #     # UUID of group.
+    #     group['uuid']
+    #
+    #
+    #     # Find all subjects matching identifier.
+    #     subjects = grouper.subjects('foo')
+    #
+    #     # Find subject. 
+    #     subject = grouper.subject('blair')
+    #
+    #     # Subject's name and id.
+    #     subject['name']
+    #     subject['id']
+    #
+    #     # In what groups is this subject a member?
+    #     my_groups = subject.groups()
+    #
+    #     # In what groups within the specified stem is this subject a member?
+    #     my_filtered_groups = subject.groups('some:stem')
     #
-    #     # Get subjects matching query.
-    #     subjects = grouper.subjects('blair')
     #
     #     # Was the last WS call successful?
     #     grouper.ok?
-    #
+    #      
     #     # Was there an error on the last WS call?
     #     grouper.error?
     #   end
     module Client
-      class Resource
-
-        # Response object from last request.
-        attr_reader :response
-
-        # Create Grouper REST client.
-        # Params:
-        # +url+:: Base URL for Grouper WS API.
-        # +:user => user+:: Authenticate to the API as this user.
-        # +:password => password+:: Authenticate to the API with this password.
-        def initialize( url, options={} )
-          raise ArgumentError if url.nil? || url.empty?
-          @error    = false
-          @client   = RestClient::Resource.new( url, options.merge!( :headers => { :content_type => 'text/x-json' } ) )
-          @response = nil
-          yield self if block_given?
-          self
-        end
-
-        # Was there an error on the last WS call?
-        def error?; @error; end
-
-        # Get memberships for subject(s) matching identifier.
-        # Returns array of hashes of group memberships OR JSON error response.
-        # Params:
-        # +subject+:: Get groups for this subject.
-        # +stem_filter+:: Limit groups to those within this stem prefix. (optional)
-        def groups(subject, stem_filter=nil)
-          raise ArgumentError if subject.nil? || subject.empty?
-          k1, k2 = 'WsGetGroupsLiteResult', 'wsGroups'
-          result  = call("subjects/#{subject}/groups")
-          if result.key?(k1) && result[k1].key?(k2)
-            groups  = result['WsGetGroupsLiteResult']['wsGroups']
-            groups  = groups.select { |group| group['name'] =~ /^#{stem_filter}/ } if stem_filter
-            return groups
-          end
-          return result
-        end
-
-        # Was the last WS call successful?
-        def ok?; !error?; end
-
-        # Get subject(s) matching identifier.
-        # Returns array of hashes of subjects OR JSON error response.
-        # Params:
-        # +subjects+:: Get subject(s) matching this identifier.
-        def subjects(subject)
-          raise ArgumentError if subject.nil? || subject.empty?
-          k1, k2 = 'WsGetSubjectsResults', 'wsSubjects'
-          result = call("subjects/#{subject}")
-          return result[k1][k2] if result.key?(k1) && result[k1].key?(k2)
-          return result
-        end
-
-        private
-
-        # Make WS call and return JSON response.
-        def call(resource, method = :get)
-          @response = @client[resource].send(method)
-          @error    = false
-          JSON.parse( @response.body )
-        rescue RestClient::Exception => e
-          @error    = true
-          return JSON.parse( e.response )
-        end
-
-      end # class Resource
     end # module Client
   end # module Rest
 end # module Grouper

data/lib/grouper-rest-client/resource.rb

@@ -0,0 +1,214 @@
+require 'rubygems'
+require 'json'
+require 'rest_client'
+
+module Grouper    # :nodoc:
+  module Rest     # :nodoc:
+    module Client # :nodoc:
+      class Resource
+
+        # Response object from last request.
+        attr_reader :response
+
+        # Create Grouper REST client.
+        # Params:
+        # +url+:: Base URL for Grouper WS API.
+        # +:user => user+:: Authenticate to the API as this user.
+        # +:password => password+:: Authenticate to the API with this password.
+        def initialize( url, options={} )
+          raise ArgumentError if url.nil? || url.empty?
+          @error    = false
+          @client   = RestClient::Resource.new( url, options.merge!( :headers => { :content_type => 'text/x-json' } ) )
+          @response = nil
+          yield self if block_given?
+          self
+        end
+
+        # Make WS call and return JSON response.
+        # Returns JSON response.
+        # +resource+:: Make call against this resource.
+        # +method+:: Optional HTTP method type.  Defaults to +:get+. 
+        # +request+:: Optional.
+        def call(resource, method = :get, request = nil )
+          if request
+            @response = @client[resource].send(method, JSON.generate(request) )
+          else
+            @response = @client[resource].send(method)
+          end
+          @error    = false
+          JSON.parse( @response.body )
+        rescue RestClient::Exception => e
+          @error    = true
+          return JSON.parse( e.response )
+        end
+
+        # Was there an error on the last WS call?
+        def error?; @error; end
+
+        # Get +Grouper::Rest::Client::Resource::Group+ matching name or +nil+.
+        def group(name)
+          groups = groups( name, 'FIND_BY_GROUP_NAME' )
+          return groups.first if ok? && 1 == groups.size
+          return nil
+        end
+
+        # Get group(s) matching identifier.
+        # Returns list of Grouper::Rest::Client::Resource::Group objects OR JSON error response.
+        # Params:
+        # +group+:: Get group(s) matching this identifier.
+        # +filter_type+:: Query groups with this filter type. Defaults to 'FIND_BY_GROUP_NAME_APPROXIMATE'. (optional)
+        def groups( group, filter_type = 'FIND_BY_GROUP_NAME_APPROXIMATE' )
+          raise ArgumentError if stem.nil? || group.empty?
+          k1, k2  = 'WsFindGroupsResults', 'groupResults'
+          request = { 
+                      'WsRestFindGroupsLiteRequest' => {
+                        'groupName'       => group,
+                        'queryFilterType' => filter_type 
+                      }
+                    }
+                                                  
+          result = call('groups', :post, request)
+          if result.key?(k1) && result[k1].key?(k2)
+            return result[k1][k2].collect { |r| Grouper::Rest::Client::Resource::Group.new(self, r) }
+          end
+          return result
+        end
+
+        # Was the last WS call successful?
+        def ok?; !error?; end
+
+        # Get +Grouper::Rest::Client::Resource::Stem+ matching +name+ or +nil+.
+        def stem(name)
+          stems = stems( name, 'FIND_BY_STEM_NAME' )
+          return stems.first if ok? && 1 == stems.size
+          return nil
+        end
+
+        # Get stem(s) matching identifier.
+        # Returns list of Grouper::Rest::Client::Resource::Stem objects OR JSON error response.
+        # Params:
+        # +stem+:: Get stem(s) matching this identifier.
+        # +filter_type+:: Query stems with this filter type. Defaults to 'FIND_BY_STEM_NAME_APPROXIMATE'. (optional)
+        def stems( stem, filter_type = 'FIND_BY_STEM_NAME_APPROXIMATE' )
+          raise ArgumentError if stem.nil? || stem.empty?
+          k1, k2  = 'WsFindStemsResults', 'stemResults'
+          request = { 
+                      'WsRestFindStemsLiteRequest' => {
+                        'stemName'            => stem,
+                        'stemQueryFilterType' => filter_type 
+                      }
+                    }
+                                                  
+          result = call("stems", :post, request)
+          if result.key?(k1) && result[k1].key?(k2)
+            return result[k1][k2].collect { |r| Grouper::Rest::Client::Resource::Stem.new(self, r) }
+          end
+          return result
+        end
+
+        # Get +Grouper::Rest::Client::Resource::Subject+ matching identifier or +nil+.
+        def subject(subject)
+          subjects = subjects(subject)
+          return subjects.first if ok? && 1 == subjects.size
+          return nil
+        end
+ 
+        # Get subject(s) matching identifier.
+        # Returns list of Grouper::Rest::Client::Resource::Subject objects OR JSON error response.
+        # +subjects+:: Get subject(s) matching this identifier.
+        def subjects(subject)
+          raise ArgumentError if subject.nil? || subject.empty?
+          k1, k2 = 'WsGetSubjectsResults', 'wsSubjects'
+          result = call("subjects/#{subject}")
+          if result.key?(k1) && result[k1].key?(k2)
+            return result[k1][k2].collect { |r| Grouper::Rest::Client::Resource::Subject.new(self, r) }
+          end
+          return result
+        end
+
+
+        # TODO DRY w/ "Subject" + "Stem"
+        class Group
+
+          def initialize(resource, json)
+            @resource = resource
+            @json     = json
+          end
+
+          # Return attribute value for +key+ or nil.
+          def [](key)
+            return @json[key] if @json && @json.key?(key)
+            return nil
+          end
+
+          def to_s
+            return "#{ self.class.name}: #{ @json.keys.sort.collect { |k| "#{ k }=#{ @json[k] }" }.join(', ') }" if @json
+            super
+          end
+
+        end # class Group
+
+
+        # TODO DRY w/ "Group" + "Subject"
+        class Stem
+
+          def initialize(resource, json)
+            @resource = resource
+            @json     = json
+          end
+
+          # Return attribute value for +key+ or nil.
+          def [](key)
+            return @json[key] if @json && @json.key?(key)
+            return nil
+          end
+
+          def to_s
+            return "#{ self.class.name}: #{ @json.keys.sort.collect { |k| "#{ k }=#{ @json[k] }" }.join(', ') }" if @json
+            super
+          end
+
+        end # class Stem
+
+
+        # TODO DRY w/ "Group" + "Stem"
+        class Subject
+
+          def initialize(resource, json)
+            @resource = resource
+            @json     = json
+          end
+
+          # Return attribute value for +key+ or nil.
+          def [](key)
+            return @json[key] if @json && @json.key?(key)
+            return nil
+          end
+
+          # Get memberships for this subject.
+          # Returns list of hashes of group memberships OR JSON error response.
+          # Params:
+          # +stem_filter+:: Limit groups to those within this stem prefix. (optional)
+          def groups(stem_filter=nil)
+            k1, k2 = 'WsGetGroupsLiteResult', 'wsGroups'
+            result  = @resource.call("subjects/#{ @json['id'] }/groups")
+            if result.key?(k1) && result[k1].key?(k2)
+              groups  = result['WsGetGroupsLiteResult']['wsGroups']
+              groups  = groups.select { |group| group['name'] =~ /^#{stem_filter}/ } if stem_filter
+              return groups.collect { |g| Grouper::Rest::Client::Resource::Group.new(@resource, g) }
+            end
+            return result
+          end
+
+          def to_s
+            return "#{ self.class.name}: #{ @json.keys.sort.collect { |k| "#{ k }=#{ @json[k] }" }.join(', ') }" if @json
+            super
+          end
+
+        end # class Subject
+
+      end # class Resource
+    end # module Client
+  end # module Rest
+end # module Grouper
+

data/lib/grouper-rest-client/version.rb

@@ -1,7 +1,7 @@
 module Grouper  # :nodoc:
   module Rest   # :nodoc:
     module Client
-      VERSION = "0.1.0"
+      VERSION = "0.2.0"
     end
   end
 end

data/spec/resource_spec.rb

@@ -108,4 +108,3 @@ describe "Grouper::Rest::Client::Resource#subjects()" do
 
 end # describe #subjects()
 
-

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: grouper-rest-client
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 23
   prerelease: 
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Blair Christensen
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-18 00:00:00 -05:00
+date: 2011-03-24 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -58,10 +58,12 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
+        hash: 27
         segments: 
+        - 2
+        - 5
         - 0
-        version: "0"
+        version: 2.5.0
   type: :development
   version_requirements: *id003
 description: REST client for accessing the Grouper WS API
@@ -81,6 +83,7 @@ files:
 - Rakefile
 - grouper-rest-client.gemspec
 - lib/grouper-rest-client.rb
+- lib/grouper-rest-client/resource.rb
 - lib/grouper-rest-client/version.rb
 - spec/resource_spec.rb
 - spec/spec_helper.rb