wadl 0.1.2 → 0.1.3.1

data/lib/wadl/documentation.rb

@@ -0,0 +1,41 @@
+#--
+###############################################################################
+#                                                                             #
+# A component of wadl, the super cheap Ruby WADL client.                      #
+#                                                                             #
+# Copyright (C) 2006-2008 Leonard Richardson                                  #
+# Copyright (C) 2010 Jens Wille                                               #
+#                                                                             #
+# Authors:                                                                    #
+#     Leonard Richardson <leonardr@segfault.org> (Original author)            #
+#     Jens Wille <jens.wille@uni-koeln.de>                                    #
+#                                                                             #
+# wadl is free software; you can redistribute it and/or modify it under the   #
+# terms of the GNU General Public License as published by the Free Software   #
+# Foundation; either version 3 of the License, or (at your option) any later  #
+# version.                                                                    #
+#                                                                             #
+# wadl is distributed in the hope that it will be useful, but WITHOUT ANY     #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more       #
+# details.                                                                    #
+#                                                                             #
+# You should have received a copy of the GNU General Public License along     #
+# with wadl. If not, see <http://www.gnu.org/licenses/>.                      #
+#                                                                             #
+###############################################################################
+#++
+
+require 'wadl'
+
+module WADL
+
+  class Documentation < CheapSchema
+
+    in_document 'doc'
+    has_attributes 'xml:lang', :title
+    contents_are_mixed_data
+
+  end
+
+end

data/lib/wadl/fault.rb

@@ -0,0 +1,48 @@
+#--
+###############################################################################
+#                                                                             #
+# A component of wadl, the super cheap Ruby WADL client.                      #
+#                                                                             #
+# Copyright (C) 2006-2008 Leonard Richardson                                  #
+# Copyright (C) 2010 Jens Wille                                               #
+#                                                                             #
+# Authors:                                                                    #
+#     Leonard Richardson <leonardr@segfault.org> (Original author)            #
+#     Jens Wille <jens.wille@uni-koeln.de>                                    #
+#                                                                             #
+# wadl is free software; you can redistribute it and/or modify it under the   #
+# terms of the GNU General Public License as published by the Free Software   #
+# Foundation; either version 3 of the License, or (at your option) any later  #
+# version.                                                                    #
+#                                                                             #
+# wadl is distributed in the hope that it will be useful, but WITHOUT ANY     #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more       #
+# details.                                                                    #
+#                                                                             #
+# You should have received a copy of the GNU General Public License along     #
+# with wadl. If not, see <http://www.gnu.org/licenses/>.                      #
+#                                                                             #
+###############################################################################
+#++
+
+require 'wadl'
+
+module WADL
+
+  class Fault < Exception
+
+    attr_accessor :code, :headers, :representation, :format
+
+    def initialize(code, headers, representation, format)
+      @code, @headers, @representation, @format = code, headers, representation, format
+    end
+
+  end
+
+  # A container for application-specific faults
+
+  module Faults
+  end
+
+end

data/lib/wadl/fault_format.rb

@@ -0,0 +1,67 @@
+#--
+###############################################################################
+#                                                                             #
+# A component of wadl, the super cheap Ruby WADL client.                      #
+#                                                                             #
+# Copyright (C) 2006-2008 Leonard Richardson                                  #
+# Copyright (C) 2010 Jens Wille                                               #
+#                                                                             #
+# Authors:                                                                    #
+#     Leonard Richardson <leonardr@segfault.org> (Original author)            #
+#     Jens Wille <jens.wille@uni-koeln.de>                                    #
+#                                                                             #
+# wadl is free software; you can redistribute it and/or modify it under the   #
+# terms of the GNU General Public License as published by the Free Software   #
+# Foundation; either version 3 of the License, or (at your option) any later  #
+# version.                                                                    #
+#                                                                             #
+# wadl is distributed in the hope that it will be useful, but WITHOUT ANY     #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more       #
+# details.                                                                    #
+#                                                                             #
+# You should have received a copy of the GNU General Public License along     #
+# with wadl. If not, see <http://www.gnu.org/licenses/>.                      #
+#                                                                             #
+###############################################################################
+#++
+
+require 'wadl'
+
+module WADL
+
+  class FaultFormat < RepresentationFormat
+
+    in_document 'fault'
+    has_attributes :id, :mediaType, :element, :status
+    has_many Param
+    may_be_reference
+
+    attr_writer :subclass
+
+    def subclass
+      attributes['href'] ? dereference.subclass : @subclass
+    end
+
+    # Define a custom subclass for this fault, so that the programmer
+    # can rescue this particular fault.
+    def self.from_element(*args)
+      me = super
+
+      me.subclass = if name = me.attributes['id']
+        begin
+          WADL::Faults.const_defined?(name) ?
+            WADL::Faults.const_get(name) :
+            WADL::Faults.const_set(name, Class.new(Fault))
+        rescue NameError
+          # This fault format's ID can't be a class name. Use the
+          # generic subclass of Fault.
+        end
+      end || Fault unless me.attributes['href']
+
+      me
+    end
+
+  end
+
+end

data/lib/wadl/has_docs.rb

@@ -0,0 +1,49 @@
+#--
+###############################################################################
+#                                                                             #
+# A component of wadl, the super cheap Ruby WADL client.                      #
+#                                                                             #
+# Copyright (C) 2006-2008 Leonard Richardson                                  #
+# Copyright (C) 2010 Jens Wille                                               #
+#                                                                             #
+# Authors:                                                                    #
+#     Leonard Richardson <leonardr@segfault.org> (Original author)            #
+#     Jens Wille <jens.wille@uni-koeln.de>                                    #
+#                                                                             #
+# wadl is free software; you can redistribute it and/or modify it under the   #
+# terms of the GNU General Public License as published by the Free Software   #
+# Foundation; either version 3 of the License, or (at your option) any later  #
+# version.                                                                    #
+#                                                                             #
+# wadl is distributed in the hope that it will be useful, but WITHOUT ANY     #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more       #
+# details.                                                                    #
+#                                                                             #
+# You should have received a copy of the GNU General Public License along     #
+# with wadl. If not, see <http://www.gnu.org/licenses/>.                      #
+#                                                                             #
+###############################################################################
+#++
+
+require 'wadl'
+
+module WADL
+
+  class HasDocs < CheapSchema
+
+    has_many Documentation
+
+    # Convenience method to define a no-argument singleton method on
+    # this object.
+    def define_singleton(r, sym, method)
+      name = r.send(sym)
+
+      if name && name !~ /\W/ && !r.respond_to?(name) && !respond_to?(name)
+        instance_eval(%Q{def #{name}\n#{method}('#{name}')\nend})
+      end
+    end
+
+  end
+
+end

data/lib/wadl/http_method.rb

@@ -0,0 +1,108 @@
+#--
+###############################################################################
+#                                                                             #
+# A component of wadl, the super cheap Ruby WADL client.                      #
+#                                                                             #
+# Copyright (C) 2006-2008 Leonard Richardson                                  #
+# Copyright (C) 2010 Jens Wille                                               #
+#                                                                             #
+# Authors:                                                                    #
+#     Leonard Richardson <leonardr@segfault.org> (Original author)            #
+#     Jens Wille <jens.wille@uni-koeln.de>                                    #
+#                                                                             #
+# wadl is free software; you can redistribute it and/or modify it under the   #
+# terms of the GNU General Public License as published by the Free Software   #
+# Foundation; either version 3 of the License, or (at your option) any later  #
+# version.                                                                    #
+#                                                                             #
+# wadl is distributed in the hope that it will be useful, but WITHOUT ANY     #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more       #
+# details.                                                                    #
+#                                                                             #
+# You should have received a copy of the GNU General Public License along     #
+# with wadl. If not, see <http://www.gnu.org/licenses/>.                      #
+#                                                                             #
+###############################################################################
+#++
+
+require 'yaml'
+require 'rest-open-uri'
+require 'wadl'
+
+module WADL
+
+  class HTTPMethod < HasDocs
+
+    OAUTH_HEADER = 'Authorization'
+    OAUTH_PREFIX = 'OAuth:'
+
+    in_document 'method'
+    as_collection 'http_methods'
+    has_required :id, :name
+    has_one RequestFormat, ResponseFormat
+    may_be_reference
+
+    # Args:
+    #  :path - Values for path parameters
+    #  :query - Values for query parameters
+    #  :headers - Values for header parameters
+    #  :send_representation
+    #  :expect_representation
+    def call(resource, args = {})
+      unless parent.respond_to?(:uri)
+        raise "You can't call a method that's not attached to a resource! (You may have dereferenced a method when you shouldn't have)"
+      end
+
+      resource ||= parent
+      method = dereference
+
+      uri = method.request ? method.request.uri(resource, args) : resource.uri(args)
+      headers = uri.headers.dup
+
+      headers['Accept']       = expect_representation.mediaType if args[:expect_representation]
+      headers['User-Agent']   = 'Ruby WADL client' unless headers['User-Agent']
+      headers['Content-Type'] = 'application/x-www-form-urlencoded'
+      headers[:method]        = name.downcase.to_sym
+      headers[:body]          = args[:send_representation]
+
+      set_oauth_header(headers, uri)
+
+      response = begin
+        open(uri, headers)
+      rescue OpenURI::HTTPError => err
+        err.io
+      end
+
+      method.response.build(response)
+    end
+
+    def set_oauth_header(headers, uri)
+      args = headers[OAUTH_HEADER] or return
+
+      yaml = args.dup
+      yaml.sub!(/\A#{OAUTH_PREFIX}/, '') or return
+
+      consumer_key, consumer_secret, access_token, token_secret = YAML.load(yaml)
+
+      require 'oauth/client/helper'
+
+      request = OpenURI::Methods[headers[:method]].new(uri.to_s)
+
+      consumer = OAuth::Consumer.new(consumer_key, consumer_secret)
+      token    = OAuth::AccessToken.new(consumer, access_token, token_secret)
+
+      helper = OAuth::Client::Helper.new(request,
+        :request_uri      => request.path,
+        :consumer         => consumer,
+        :token            => token,
+        :scheme           => 'header',
+        :signature_method => 'HMAC-SHA1'
+      )
+
+      headers[OAUTH_HEADER] = helper.header
+    end
+
+  end
+
+end

data/lib/wadl/link.rb

@@ -0,0 +1,40 @@
+#--
+###############################################################################
+#                                                                             #
+# A component of wadl, the super cheap Ruby WADL client.                      #
+#                                                                             #
+# Copyright (C) 2006-2008 Leonard Richardson                                  #
+# Copyright (C) 2010 Jens Wille                                               #
+#                                                                             #
+# Authors:                                                                    #
+#     Leonard Richardson <leonardr@segfault.org> (Original author)            #
+#     Jens Wille <jens.wille@uni-koeln.de>                                    #
+#                                                                             #
+# wadl is free software; you can redistribute it and/or modify it under the   #
+# terms of the GNU General Public License as published by the Free Software   #
+# Foundation; either version 3 of the License, or (at your option) any later  #
+# version.                                                                    #
+#                                                                             #
+# wadl is distributed in the hope that it will be useful, but WITHOUT ANY     #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more       #
+# details.                                                                    #
+#                                                                             #
+# You should have received a copy of the GNU General Public License along     #
+# with wadl. If not, see <http://www.gnu.org/licenses/>.                      #
+#                                                                             #
+###############################################################################
+#++
+
+require 'wadl'
+
+module WADL
+
+  class Link < HasDocs
+
+    in_document 'link'
+    has_attributes :href, :rel, :rev
+
+  end
+
+end

data/lib/wadl/option.rb

@@ -0,0 +1,40 @@
+#--
+###############################################################################
+#                                                                             #
+# A component of wadl, the super cheap Ruby WADL client.                      #
+#                                                                             #
+# Copyright (C) 2006-2008 Leonard Richardson                                  #
+# Copyright (C) 2010 Jens Wille                                               #
+#                                                                             #
+# Authors:                                                                    #
+#     Leonard Richardson <leonardr@segfault.org> (Original author)            #
+#     Jens Wille <jens.wille@uni-koeln.de>                                    #
+#                                                                             #
+# wadl is free software; you can redistribute it and/or modify it under the   #
+# terms of the GNU General Public License as published by the Free Software   #
+# Foundation; either version 3 of the License, or (at your option) any later  #
+# version.                                                                    #
+#                                                                             #
+# wadl is distributed in the hope that it will be useful, but WITHOUT ANY     #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more       #
+# details.                                                                    #
+#                                                                             #
+# You should have received a copy of the GNU General Public License along     #
+# with wadl. If not, see <http://www.gnu.org/licenses/>.                      #
+#                                                                             #
+###############################################################################
+#++
+
+require 'wadl'
+
+module WADL
+
+  class Option < HasDocs
+
+    in_document 'option'
+    has_required :value
+
+  end
+
+end

data/lib/wadl/param.rb

@@ -0,0 +1,134 @@
+#--
+###############################################################################
+#                                                                             #
+# A component of wadl, the super cheap Ruby WADL client.                      #
+#                                                                             #
+# Copyright (C) 2006-2008 Leonard Richardson                                  #
+# Copyright (C) 2010 Jens Wille                                               #
+#                                                                             #
+# Authors:                                                                    #
+#     Leonard Richardson <leonardr@segfault.org> (Original author)            #
+#     Jens Wille <jens.wille@uni-koeln.de>                                    #
+#                                                                             #
+# wadl is free software; you can redistribute it and/or modify it under the   #
+# terms of the GNU General Public License as published by the Free Software   #
+# Foundation; either version 3 of the License, or (at your option) any later  #
+# version.                                                                    #
+#                                                                             #
+# wadl is distributed in the hope that it will be useful, but WITHOUT ANY     #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more       #
+# details.                                                                    #
+#                                                                             #
+# You should have received a copy of the GNU General Public License along     #
+# with wadl. If not, see <http://www.gnu.org/licenses/>.                      #
+#                                                                             #
+###############################################################################
+#++
+
+require 'wadl'
+
+module WADL
+
+  class Param < HasDocs
+
+    in_document 'param'
+    has_required :name
+    has_attributes :type, :default, :style, :path, :required, :repeating, :fixed
+    has_many Option, Link
+    may_be_reference
+
+    # cf. <http://www.w3.org/TR/xmlschema-2/#boolean>
+    BOOLEAN_RE = %r{\A(?:true|1)\z}
+
+    # A default Param object to use for a path parameter that is
+    # only specified as a name in the path of a resource.
+    def self.default
+      @default ||= begin
+        default = Param.new
+
+        default.required = 'true'
+        default.style    = 'plain'
+        default.type     = 'xsd:string'
+
+        default
+      end
+    end
+
+    def required?
+      required =~ BOOLEAN_RE
+    end
+
+    def repeating?
+      repeating =~ BOOLEAN_RE
+    end
+
+    def inspect
+      %Q{Param "#{name}"}
+    end
+
+    # Validates and formats a proposed value for this parameter. Returns
+    # the formatted value. Raises an ArgumentError if the value
+    # is invalid.
+    #
+    # The 'name' and 'style' arguments are used in conjunction with the
+    # default Param object.
+    def format(value, name = nil, style = nil)
+      name  ||= self.name
+      style ||= self.style
+
+      value = fixed if fixed
+      value ||= default if default
+
+      unless value
+        if required?
+          raise ArgumentError, %Q{No value provided for required param "#{name}"!}
+        else
+          return '' # No value provided and none required.
+        end
+      end
+
+      if value.respond_to?(:each) && !value.respond_to?(:to_str)
+        if repeating?
+          values = value
+        else
+          raise ArgumentError, %Q{Multiple values provided for single-value param "#{name}"}
+        end
+      else
+        values = [value]
+      end
+
+      # If the param lists acceptable values in option tags, make sure that
+      # all values are found in those tags.
+      if options && !options.empty?
+        values.each { |value|
+          unless find_option(value)
+            acceptable = options.map { |o| o.value }.join('", "')
+            raise ArgumentError, %Q{"#{value}" is not among the acceptable parameter values ("#{acceptable}")}
+          end
+        }
+      end
+
+      if style == 'query' || parent.is_a?(RequestFormat) || (
+        parent.respond_to?(:is_form_representation?) && parent.is_form_representation?
+      )
+        values.map { |v| "#{URI.escape(name)}=#{URI.escape(v.to_s)}" }.join('&')
+      elsif style == 'matrix'
+        if type == 'xsd:boolean'
+          values.map { |v| ";#{name}" if v =~ BOOLEAN_RE }.compact.join
+        else
+          values.map { |v| ";#{URI.escape(name)}=#{URI.escape(v.to_s)}" if v }.compact.join
+        end
+      elsif style == 'header'
+        values.join(',')
+      else
+        # All other cases: plain text representation.
+        values.map { |v| URI.escape(v.to_s) }.join(',')
+      end
+    end
+
+    alias_method :%, :format
+
+  end
+
+end