Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Updates and adds documentation to classes and individual methods.

git-svn-id: http://opensocial-ruby-client.googlecode.com/svn/trunk@17 f65e88d0-acf7-11dd-a0fe-71d3f493a0de
  • Loading branch information...
commit 60900c63b73612291db368a181852b595c0aa5b5 1 parent 7870017
api.dwh@google.com authored
View
22 lib/opensocial/activity.rb
@@ -26,6 +26,9 @@ module OpenSocial #:nodoc:
class Activity < Base
+
+ # Initializes the Activity 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|
@@ -41,38 +44,49 @@ def initialize(json)
end
end
- # Provides the ability to request a collection of activities for a given
+ # Provides the ability to request a Collection of activities for a given
# user or set of users.
#
# The FetchActivitiesRequest wraps a simple request to an OpenSocial
- # endpoint for a collection of activities. As parameters, it accepts
+ # endpoint for a Collection of activities. As parameters, it accepts
# a user ID and selector (and optionally an ID of a particular activity).
# This request may be used, standalone, by calling send, or bundled into
- # an RPC request.
+ # an RpcRequest.
#
class FetchActivitiesRequest < Request
+ # Defines the service fragment for use in constructing the request URL or
+ # JSON
SERVICE = 'activities'
# This is only necessary because of a spec inconsistency
RPC_SERVICE = 'activity'
+ # Initializes a request to fetch activities for the specified user and
+ # group, 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',
pid = nil)
super
end
+ # Sends the request, passing in the appropriate SERVICE and specified
+ # instance variables.
def send
json = send_request(SERVICE, @guid, @selector, @pid)
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 RpcRequest.
def to_json(*a)
value = {
'method' => RPC_SERVICE + GET,
@@ -87,6 +101,8 @@ def to_json(*a)
private
+ # Converts the JSON response into a Collection of activities, indexed by
+ # id.
def parse_response(response)
activities = Collection.new
for entry in response
View
22 lib/opensocial/appdata.rb
@@ -29,6 +29,8 @@ module OpenSocial #:nodoc:
class AppData < Base
attr_accessor :id
+ # Initializes the AppData entry based on the provided id and json fragment.
+ # If no JSON is provided, an empty object (with only an ID) is created.
def initialize(id, json)
@id = id
@@ -45,34 +47,46 @@ def initialize(id, json)
end
end
- # Provides the ability to request a collection of appdata for a given
+ # Provides the ability to request a Collection of AppData for a given
# user or set of users.
#
# The FetchAppData wraps a simple request to an OpenSocial
- # endpoint for a collection of appdata. As parameters, it accepts
+ # endpoint for a Collection of AppData. As parameters, it accepts
# a user ID and selector. This request may be used, standalone, by calling
- # send, or bundled into an RPC request.
+ # send, or bundled into an RpcRequest.
#
class FetchAppDataRequest < Request
+ # Defines the service fragment for use in constructing the request URL or
+ # JSON
SERVICE = 'appdata'
+ # Initializes a request to fetch appdata for the specified user and
+ # group, 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',
aid = '@app')
super(connection, guid, selector, aid)
end
+ # Sends the request, passing in the appropriate SERVICE and specified
+ # instance variables. Accepts an unescape parameter, defaulting to true,
+ # if the returned data should be unescaped.
def send(unescape = true)
json = send_request(SERVICE, @guid, @selector, @pid, unescape)
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,
@@ -88,6 +102,8 @@ def to_json(*a)
private
+ # Converts the JSON response into a Collection of AppData entries, indexed
+ # by id.
def parse_response(response)
appdata = Collection.new
response.each do |key, value|
View
4 lib/opensocial/base.rb
@@ -29,6 +29,8 @@ module OpenSocial #:nodoc:
class Base
+
+ # Creates an attr_accessor for the specified variable name.
def add_attr(name)
self.class.class_eval "attr_accessor :#{name}"
end
@@ -42,6 +44,8 @@ def add_attr(name)
class Collection < Hash
+
+ # Converts the Collection to an Array by
def to_array
values
end
View
17 lib/opensocial/connection.rb
@@ -44,12 +44,25 @@ class Connection
: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, secret, and token for OAuth.
attr_accessor :consumer_key, :consumer_secret, :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|
@@ -71,6 +84,8 @@ def initialize(options = {})
end
end
+ # Constructs a URI to the OpenSocial endpoint given a service, guid,
+ # selector, and pid.
def service_uri(service, guid, selector, pid)
uri = [@container[:endpoint], service, guid, selector, pid].compact.
join('/')
@@ -85,6 +100,8 @@ def service_uri(service, guid, selector, pid)
private
+ # Verifies that the consumer key, consumer secret and requestor id are all
+ # non-blank.
def has_valid_hmac_triple?
return (!@consumer_key.empty? && !@consumer_secret.empty? &&
!@xoauth_requestor_id.empty?)
View
15 lib/opensocial/group.rb
@@ -24,7 +24,11 @@ module OpenSocial #:nodoc:
# 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|
@@ -40,23 +44,30 @@ def initialize(json)
end
end
- # Provides the ability to request a collection of groups for a given
+ # 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 RPC request.
+ # 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)
View
41 lib/opensocial/person.rb
@@ -34,6 +34,9 @@ module OpenSocial #:nodoc:
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|
@@ -48,6 +51,8 @@ def initialize(json)
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']
@@ -58,6 +63,8 @@ def long_name
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']
@@ -69,33 +76,44 @@ def short_name
end
end
- # Provides the ability to request a single person.
+ # 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 RPC request.
+ # 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'
+ # 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)
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,
@@ -109,38 +127,50 @@ def to_json(*a)
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
+ # 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
+ # 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 RPC request.
+ # 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')
super
end
+ # Sends the request, passing in the appropriate SERVICE and specified
+ # instance variables.
def send
json = send_request(SERVICE, @guid, @selector)
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,
@@ -154,6 +184,7 @@ def to_json(*a)
private
+ # Converts the JSON response into a Collection of people, indexed by id.
def parse_response(response)
people = Collection.new
for entry in response
View
42 lib/opensocial/request.rb
@@ -30,11 +30,18 @@ module OpenSocial #:nodoc:
class Request
GET = '.get'
+ # Defines the connection that will be used in the request.
attr_accessor :connection
+
+ # Defines the guid, selector, and pid that specify which data is being
+ # requested.
attr_accessor :guid, :selector, :pid
+ # Defines the key used to lookup the request result in an RPC request.
attr_accessor :key
+ # Initializes a request using the optionally supplied connection, guid,
+ # selector, and pid.
def initialize(connection = nil, guid = nil, selector = nil, pid = nil)
@connection = connection
@guid = guid
@@ -42,6 +49,10 @@ def initialize(connection = nil, guid = nil, selector = nil, pid = nil)
@pid = pid
end
+ # Generates a request given the service, guid, selector, and pid, to the
+ # OpenSocial endpoint by constructing the service URI and dispatching the
+ # request. When data is returned, it is parsed as JSON after being
+ # optionally unescaped.
def send_request(service, guid, selector = nil, pid = nil,
unescape = false)
if !@connection
@@ -61,6 +72,9 @@ def send_request(service, guid, selector = nil, pid = nil,
private
+ # Dispatches a request to a given URI with optional POST data. If a
+ # request's connection has specified HMAC-SHA1 authentication, OAuth
+ # parameters and signature are appended to the request.
def dispatch(uri, post_data = nil)
http = Net::HTTP.new(uri.host)
@@ -89,6 +103,8 @@ def dispatch(uri, post_data = nil)
return resp.body
end
+ # Checks the response object's status code. If the response is is
+ # unauthorized, an exception is raised.
def check_for_http_error!(resp)
if !resp.kind_of?(Net::HTTPSuccess)
if resp.is_a?(Net::HTTPUnauthorized)
@@ -100,6 +116,8 @@ def check_for_http_error!(resp)
end
end
+ # Checks the JSON response for a status code. If a code is present an
+ # exception is raised.
def check_for_json_error!(resp)
json = JSON.parse(resp.body)
if json.is_a?(Hash) && json.has_key?('code') && json.has_key?('message')
@@ -129,18 +147,29 @@ def check_for_json_error!(resp)
class RpcRequest < Request
+
+ # Defines the requests sent in the single RpcRequest. The requests are
+ # stored a key/value pairs.
attr_accessor :requests
+ # Initializes an RpcRequest with the supplied connection and an optional
+ # hash of requests.
def initialize(connection, requests = {})
@connection = connection
@requests = requests
end
+ # Adds one or more requests to the RpcRequest. Expects a hash of key/value
+ # pairs (key used to refernece the data when it returns => the Request).
def add(requests = {})
@requests.merge!(requests)
end
+ # Sends an RpcRequest to the OpenSocial endpoint by constructing JSON for
+ # the POST body and delegating the request to send_request. If an
+ # RpcRequest is sent with an empty list of requests, an exception is
+ # thrown. The response JSON is optionally unescaped (defaulting to true).
def send(unescape = true)
if @requests.length == 0
raise RequestException.new('RPC request requires a non-empty hash ' +
@@ -150,6 +179,10 @@ def send(unescape = true)
json = send_request(request_json, unescape)
end
+ # Sends an RpcRequest to the OpenSocial endpoint by constructing the
+ # service URI and dispatching the request. This method is public so that
+ # an arbitrary POST body can be constructed and sent. The response JSON is
+ # optionally unescaped.
def send_request(post_data, unescape)
uri = @connection.service_uri(@connection.container[:rpc], nil, nil, nil)
data = dispatch(uri, post_data)
@@ -159,6 +192,11 @@ def send_request(post_data, unescape)
private
+ # Parses the response JSON. First, the JSON is unescaped, when specified,
+ # then for each element specified in @requests, the appropriate response
+ # is selected from the larger JSON response. This element is then delegated
+ # to the appropriate class to be turned into a native object (Person,
+ # Activity, etc.)
def parse_response(response, unescape)
if unescape
parsed = JSON.parse(response.os_unescape)
@@ -176,6 +214,8 @@ def parse_response(response, unescape)
return native_objects
end
+ # Constructs a hash of the elements in data referencing each element
+ # by its 'id' attribute.
def key_by_id(data)
keyed_by_id = {}
for entry in data
@@ -185,6 +225,8 @@ def key_by_id(data)
return keyed_by_id
end
+ # Modifies each request in an outgoing RpcRequest so that its key is set
+ # to the value specified when added to the RpcRequest.
def request_json
keyed_requests = []
@requests.each_pair do |key, request|
View
1  lib/opensocial/string/os_string.rb
@@ -13,6 +13,7 @@
# limitations under the License.
class String #:nodoc:
+ # Removes backslash escaping.
def os_unescape
unescaped = self.gsub(/\\\"/, '"')
unescaped = unescaped.gsub('"{', "{")
Please sign in to comment.
Something went wrong with that request. Please try again.