qoobaa-opensocial 0.1.0

data/lib/opensocial/base.rb

@@ -0,0 +1,50 @@
+# Copyright (c) 2008 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "net/http"
+require "uri"
+
+# Use json/pure if you opt-out of including the validation code in
+# opensocial/auth. This gem adds standard to_json behavior for the
+# request classes, instead of using ActiveSupport.
+require "rubygems"
+
+module OpenSocial #:nodoc:
+
+  # Provides base functionality for the OpenSocial child classes.
+  #
+
+  class Base
+
+    # Creates an attr_accessor for the specified variable name.
+    def add_attr(name)
+      self.class.class_eval "attr_accessor :#{name}"
+    end
+  end
+
+  # Wraps the functionality of an OpenSocial collection as defined by the
+  # specification. In practical uses, a Collection serves as a Hash (usually
+  # index by ID) with the added benefit of being convertable to an Array, when
+  # it's necessary to iterate over all of the values.
+  #
+
+  class Collection < Hash
+
+    # Converts the Collection to an Array by returning each of the values from
+    # key/value pairs.
+    def to_array
+      values
+    end
+  end
+end

data/lib/opensocial/connection.rb

@@ -0,0 +1,128 @@
+# Copyright (c) 2008 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module OpenSocial #:nodoc:
+
+  # Describes a connection to an OpenSocial container, including the ability to
+  # declare an authorization mechanism and appropriate credentials.
+  #
+
+  class Connection
+    ORKUT = { :endpoint => "http://sandbox.orkut.com/social",
+              :rest => "rest/",
+              :rpc => "rpc/" }
+    IGOOGLE = { :endpoint => "http://gmodules.com/api",
+                :rest => "",
+                :rpc => "rpc" }
+    MYSPACE = { :endpoint => "http://api.myspace.com/v2",
+                :rest => "",
+                :rpc => "",
+                :base_uri => "http://api.myspace.com",
+                :request_token_path => "/request_token",
+                :authorize_path => "/authorize",
+                :access_token_path => "/access_token",
+                :http_method => :get }
+
+    AUTH_HMAC = 0
+    AUTH_ST = 1
+
+    DEFAULT_OPTIONS = { :container => ORKUT,
+                        :st => "",
+                        :consumer_key => "",
+                        :consumer_secret => "",
+                        :consumer_token => OAuth::Token.new("", ""),
+                        :xoauth_requestor_id => "",
+                        :auth => AUTH_HMAC }
+
+    # Defines the container that will be used in requests.
+    attr_accessor :container
+
+    # Defines the security token, for when OAuth is not in use.
+    attr_accessor :st
+
+    # Defines the consumer key for OAuth.
+    attr_accessor :consumer_key
+
+    # Defines the consumer secret for OAuth.
+    attr_accessor :consumer_secret
+
+    # Defines the consumer token for OAuth.
+    attr_accessor :consumer_token
+
+    # Defines the ID of the requestor (required by some implementations when
+    # using OAuth).
+    attr_accessor :xoauth_requestor_id
+
+    # Defines the authentication scheme: HMAC or security token.
+    attr_accessor :auth
+
+    # Initializes the Connection using the supplied options hash, or the
+    # defaults. Verifies that the supplied authentication type has proper
+    # (ie. non-blank) credentials, and that the authentication type is known.
+    def initialize(options = {})
+      options = DEFAULT_OPTIONS.merge(options)
+      options.each do |key, value|
+        self.send("#{key}=", value)
+      end
+
+      if @auth == AUTH_HMAC && !has_valid_hmac_double?
+        raise ArgumentError.new("Connection authentication is set to " +
+                                "HMAC-SHA1, but a valid consumer_key and" +
+                                "secret pair was not supplied.")
+      elsif @auth == AUTH_ST && @st.empty?
+        raise ArgumentError.new("Connection authentication is set to " +
+                                "security token, but a security token was " +
+                                "not supplied.")
+      elsif ![AUTH_HMAC, AUTH_ST].include?(@auth)
+        raise ArgumentError.new("Connection authentication is set to an " +
+                                "unknown value.")
+      end
+    end
+
+    # Constructs a URI to the OpenSocial endpoint given a service, guid,
+    # selector, and pid.
+    def service_uri(service, guid, selector, pid, extra_fields = {})
+      uri = [@container[:endpoint], service, guid, selector, pid].compact.
+              join("/")
+
+      if @auth == AUTH_HMAC && !xoauth_requestor_id.empty?
+        uri << "?xoauth_requestor_id=" + @xoauth_requestor_id
+      elsif @auth == AUTH_ST
+        uri << "?st=" + self.st
+      end
+
+      extra_fields.each do |name, value|
+        uri << "&#{name}=#{value}"
+      end
+
+      URI.parse(uri)
+    end
+
+    # Signs a request using OAuth.
+    def sign!(http, req)
+      if @auth == AUTH_HMAC
+        consumer = OAuth::Consumer.new(@consumer_key, @consumer_secret)
+        req.oauth!(http, consumer, @consumer_token, :scheme => "query_string")
+      end
+    end
+
+    private
+
+    # Verifies that the consumer key, consumer secret and requestor id are all
+    # non-blank.
+    def has_valid_hmac_double?
+      return (!@consumer_key.empty? && !@consumer_secret.empty?)
+    end
+  end
+end

data/lib/opensocial/group.rb

@@ -0,0 +1,80 @@
+# Copyright (c) 2008 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module OpenSocial #:nodoc:
+
+  # Acts as a wrapper for an OpenSocial group.
+  #
+  # The Group class takes input JSON as an initialization parameter, and
+  # iterates through each of the key/value pairs of that JSON. For each key
+  # that is found, an attr_accessor is constructed, allowing direct access
+  # to the value. Each value is stored in the attr_accessor, either as a
+  # String, Fixnum, Hash, or Array.
+  #
+
+  class Group < Base
+
+    # Initializes the Group based on the provided json fragment. If no JSON
+    # is provided, an empty object (with no attributes) is created.
+    def initialize(json)
+      if json
+        json.each do |key, value|
+          proper_key = key.snake_case
+          begin
+            self.send("#{proper_key}=", value)
+          rescue NoMethodError
+            add_attr(proper_key)
+            self.send("#{proper_key}=", value)
+          end
+        end
+      end
+    end
+  end
+
+  # Provides the ability to request a Collection of groups for a given
+  # user.
+  #
+  # The FetchGroupsRequest wraps a simple request to an OpenSocial
+  # endpoint for a collection of groups. As parameters, it accepts
+  # a user ID. This request may be used, standalone, by calling send, or
+  # bundled into an RpcRequest.
+  #
+
+  class FetchGroupsRequest < Request
+    # Defines the service fragment for use in constructing the request URL or
+    # JSON
+    SERVICE = "groups"
+
+    # Initializes a request to fetch groups for the specified user, or the
+    # default (@me). A valid Connection is not necessary if the request is to
+    # be used as part of an RpcRequest.
+    def initialize(connection = nil, guid = "@me")
+      super
+    end
+
+    # Sends the request, passing in the appropriate SERVICE and specified
+    # instance variables.
+    def send
+      json = send_request(SERVICE, @guid)
+
+      groups = Collection.new
+      for entry in json["entry"]
+        group = Group.new(entry)
+        groups[group.id] = group
+      end
+
+      return groups
+    end
+  end
+end

data/lib/opensocial/person.rb

@@ -0,0 +1,197 @@
+# Copyright (c) 2008 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Extends the OpenSocial module, providing a wrapper for OpenSocial people.
+#
+#    Person:             Acts as a wrapper for an OpenSocial person.
+#    FetchPersonRequest: Provides the ability to request a single person.
+#    FetchPeopleRequest: Provides the ability to request a collection of people
+#                        by describing their relationship to a single person.
+#
+
+module OpenSocial #:nodoc:
+
+  # Acts as a wrapper for an OpenSocial person.
+  #
+  # The Person class takes input JSON as an initialization parameter, and
+  # iterates through each of the key/value pairs of that JSON. For each key
+  # that is found, an attr_accessor is constructed, allowing direct access
+  # to the value. Each value is stored in the attr_accessor, either as a
+  # String, Fixnum, Hash, or Array.
+  #
+
+  class Person < Base
+
+    # Initializes the Person based on the provided json fragment. If no JSON
+    # is provided, an empty object (with no attributes) is created.
+    def initialize(json)
+      if json
+        json.each do |key, value|
+          proper_key = key.snake_case
+          begin
+            self.send("#{proper_key}=", value)
+          rescue NoMethodError
+            add_attr(proper_key)
+            self.send("#{proper_key}=", value)
+          end
+        end
+      end
+    end
+
+    # Returns the complete name of the Person, to the best ability, given
+    # available fields.
+    def long_name
+      if @name && @name["givenName"] && @name["familyName"]
+        return @name["givenName"] + " " + @name["familyName"]
+      elsif @nickname
+        return @nickname
+      else
+        return ""
+      end
+    end
+
+    # Returns the first name or nickname of the Person, to the best ability,
+    # given available fields.
+    def short_name
+      if @name && @name["givenName"]
+        return @name["givenName"]
+      elsif @nickname
+        return @nickname
+      else
+        return ""
+      end
+    end
+  end
+
+  # Provides the ability to request a single Person.
+  #
+  # The FetchPeopleRequests wraps a simple request to an OpenSocial
+  # endpoint for a single person. As parameters, it accepts a user ID and
+  # selector and optionally an ID of a particular person, in order to display
+  # the user ID"s view of that person. This request may be used, standalone,
+  # by calling send, or bundled into an RpcRequest.
+  #
+
+  class FetchPersonRequest < Request
+    # Defines the service fragment for use in constructing the request URL or
+    # JSON
+    SERVICE = "people"
+    DEFAULT_FIELDS = [:id, :dateOfBirth, :name, :emails, :gender, :state, :postalCode, :ethnicity, :relationshipStatus, :thumbnailUrl, :displayName]
+
+    # Initializes a request to the specified user, or the default (@me, @self).
+    # A valid Connection is not necessary if the request is to be used as part
+    # of an RpcRequest.
+    def initialize(connection = nil, guid = "@me", selector = "@self")
+      super
+    end
+
+    # Sends the request, passing in the appropriate SERVICE and specified
+    # instance variables.
+    def send
+      json = send_request(SERVICE, @guid, @selector, nil, false, :fields => DEFAULT_FIELDS.join(","))
+
+      return parse_response(json["entry"])
+    end
+
+    # Selects the appropriate fragment from the JSON response in order to
+    # create a native object.
+    def parse_rpc_response(response)
+      return parse_response(response["data"])
+    end
+
+    # Converts the request into a JSON fragment that can be used as part of a
+    # larger RpcRequest.
+    def to_json(*a)
+      value = {
+        "method" => SERVICE + GET,
+        "params" => {
+          "userId" => ["#{@guid}"],
+          "groupId" => "#{@selector}"
+        },
+        "id" => @key
+      }.to_json(*a)
+    end
+
+    private
+
+    # Converts the JSON response into a person.
+    def parse_response(response)
+      return Person.new(response)
+    end
+  end
+
+  # Provides the ability to request a Collection of people by describing their
+  # relationship to a single person.
+  #
+  #  The FetchPeopleRequests wraps a simple request to an OpenSocial
+  #  endpoint for a Collection of people. As parameters, it accepts
+  #  a user ID and selector. This request may be used, standalone, by calling
+  #  send, or bundled into an RpcRequest.
+  #
+
+  class FetchPeopleRequest < Request
+    # Defines the service fragment for use in constructing the request URL or
+    # JSON
+    SERVICE = "people"
+
+    # Initializes a request to the specified user's group, or the default (@me,
+    # @friends). A valid Connection is not necessary if the request is to be
+    # used as part of an RpcRequest.
+    def initialize(connection = nil, guid = "@me", selector = "@friends", extra_fields = {})
+      super
+      @extra_fields = extra_fields
+    end
+
+    # Sends the request, passing in the appropriate SERVICE and specified
+    # instance variables.
+    def send
+      @extra_fields[:fields] ||= FetchPersonRequest::DEFAULT_FIELDS.join(",")
+      json = send_request(SERVICE, @guid, @selector, nil, false, @extra_fields)
+
+      return parse_response(json["entry"])
+    end
+
+    # Selects the appropriate fragment from the JSON response in order to
+    # create a native object.
+    def parse_rpc_response(response)
+      return parse_response(response["data"]["list"])
+    end
+
+    # Converts the request into a JSON fragment that can be used as part of a
+    # larger RPC request.
+    def to_json(*a)
+      value = {
+        "method" => SERVICE + GET,
+        "params" => {
+          "userId" => ["#{@guid}"],
+          "groupId" => "#{@selector}"
+        },
+        "id" => @key
+      }.to_json(*a)
+    end
+
+    private
+
+    # Converts the JSON response into a Collection of people, indexed by id.
+    def parse_response(response)
+      people = Collection.new
+      for entry in response
+        person = Person.new(entry)
+        people[person.id] = person
+      end
+
+      return people
+    end
+  end
+end