wrest 4.0.0-universal-java-18

data/lib/wrest/components/container.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+# Copyright 2009 Sidu Ponnappa
+
+# 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 Wrest
+  module Components
+    module Container
+    end
+  end
+end
+
+require 'wrest/components/container/typecaster'
+require 'wrest/components/container/alias_accessors'
+
+module Wrest
+  module Components
+    # Adds behaviour allowing a class to
+    # contain attributes and providing support
+    # for dynamic getters, setters and query methods.
+    # These methods are added at runtime, on the first
+    # invocation and on a per instance basis.
+    # <tt>respond_to?</tt> however will respond as though
+    # they are all already present.
+    # This means that two different instances of the same
+    # Container could well have different attribute
+    # getters/setters/query methods.
+    #
+    # Note that the first call to a particular getter/setter/query
+    # method will be slower because the method is defined
+    # at that point; subsequent calls will be much faster.
+    #
+    # Also keep in mind that attribute getter/setter/query methods
+    # will _not_ override any existing methods on the class.
+    #
+    # In situations where this is a problem, such as a client consuming Rails
+    # REST services where <tt>id</tt> is a common attribute and clashes with
+    # Object#id, it is recommended to create getter/setter/query methods
+    # on the class (which affects all instances) using the +always_has+ macro.
+    #
+    # If you're implementing your own initialize method
+    # remember to delegate to the default initialize
+    # of Container by invoking <tt>super(attributes)</tt>
+    #
+    # Example:
+    #  class ShenCoin
+    #    include Wrest::Components::Container
+    #    include Wrest::Components::Container::Typecaster
+    #
+    #    always_has   :id
+    #    typecast         :id   =>  as_integer
+    #  end
+    #  coin = ShenCoin.new(:id => '5', :chi_count => 500, :owner => 'Kai Wren')
+    #  coin.id    # => 5
+    #  coin.owner # => 'Kai Wren'
+    module Container
+      def self.included(klass) # :nodoc:
+        klass.extend Container::ClassMethods
+        klass.extend Container::Typecaster::Helpers
+        klass.class_eval do
+          include Container::InstanceMethods
+          include Container::AliasAccessors
+        end
+      end
+
+      def self.build_attribute_getter(attribute_name) # :nodoc:
+        "def #{attribute_name};@attributes[:#{attribute_name}];end;"
+      end
+
+      def self.build_attribute_setter(attribute_name) # :nodoc:
+        "def #{attribute_name}=(value);@attributes[:#{attribute_name}] = value;end;"
+      end
+
+      def self.build_attribute_queryer(attribute_name) # :nodoc:
+        "def #{attribute_name}?;not @attributes[:#{attribute_name}].nil?;end;"
+      end
+
+      module ClassMethods
+        # This macro explicitly creates getter, setter and query methods on
+        # an Container, overriding any existing methods with the same names.
+        # This can be used when attribute names clash with existing method names;
+        # an example would be Rails REST resources which frequently make use
+        # an attribute named <tt>id</tt> which clashes with Object#id. Also,
+        # this can be used as a performance optimisation if the incoming
+        # attributes are known beforehand.
+        def always_has(*attribute_names)
+          attribute_names.each do |attribute_name|
+            class_eval(
+              Container.build_attribute_getter(attribute_name) +
+              Container.build_attribute_setter(attribute_name) +
+              Container.build_attribute_queryer(attribute_name)
+            )
+          end
+        end
+
+        # This is a convenience macro which includes
+        # Wrest::Components::Container::Typecaster into
+        # the class (effectively overwriting this method) before delegating to
+        # the actual typecast method that is a part of that module.
+        # This saves us the effort of explicitly doing the include. Easy to use API is king.
+        #
+        # Remember that using typecast carries a performance penalty.
+        # See Wrest::Components::Container::Typecaster for the actual docs.
+        def typecast(cast_map)
+          class_eval { include Wrest::Components::Container::Typecaster }
+          typecast cast_map
+        end
+
+        # This is the name of the class in snake-case, with any parent
+        # module names removed.
+        #
+        # The class will use as the root element when
+        # serialised to xml after replacing underscores with hyphens.
+        #
+        # This method can be overidden should you need a different name.
+        def element_name
+          @element_name ||= Utils.string_underscore(Utils.string_demodulize(name))
+        end
+      end
+
+      module InstanceMethods
+        # Sets up any class to act like
+        # an attributes container by creating
+        # two variables, @attributes and @interface.
+        # Remember not to use these two variable names
+        # when using Container in your own class.
+        def initialize(attributes = {})
+          @attributes = HashWithIndifferentAccess.new(attributes)
+        end
+
+        # A translator is a anything that knows how to serialise a
+        # Hash. It must needs have a method named 'serialise' that
+        # accepts a hash and configuration options, and returns the serialised
+        # result (leaving the hash unchanged, of course).
+        #
+        # Examples for JSON and XML can be found under Wrest::Components::Translators.
+        # These serialised output of these translators will work out of the box for Rails
+        # applications; you may need to roll your own for anything else.
+        #
+        # Note: When serilising to XML, if you want the name of the class as the name of the root node
+        # then you should use the Container#to_xml helper.
+        def serialise_using(translator, options = {})
+          payload = {
+            self.class.element_name => @attributes.dup
+          }
+          translator.serialise(payload, options)
+        end
+
+        def to_xml(options = {})
+          serialise_using(Wrest::Components::Translators::Xml, { root: self.class.element_name }.merge(options))
+        end
+
+        def [](key)
+          @attributes[key.to_sym]
+        end
+
+        def []=(key, value)
+          @attributes[key.to_sym] = value
+        end
+
+        def respond_to_missing?(method_name, *)
+          if super.respond_to?(method_name)
+            true
+          else
+            @attributes.include?(method_name.to_s.gsub(/(\?$)|(=$)/,
+                                                       '').to_sym)
+          end
+        end
+
+        # Creates getter, setter and query methods for
+        # attributes on the first call.
+        def method_missing(method_sym, *arguments)
+          method_name = method_sym.to_s
+          attribute_name = method_name.gsub(/(\?$)|(=$)/, '')
+          if @attributes.include?(attribute_name.to_sym) || method_name[-1] == '=' || method_name[-1] == '?'
+            generate_methods!(attribute_name, method_name)
+            send(method_sym, *arguments)
+          else
+            super(method_sym, *arguments)
+          end
+        end
+
+        private
+
+        def generate_methods!(attribute_name, method_name)
+          case method_name[-1]
+          when '='
+            instance_eval Container.build_attribute_setter(attribute_name)
+          when '?'
+            instance_eval Container.build_attribute_queryer(attribute_name)
+          else
+            instance_eval Container.build_attribute_getter(attribute_name)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/wrest/components/mutators/base.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Copyright 2009 Sidu Ponnappa
+
+# 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 Wrest
+  module Components
+    # This is a base implementation of a
+    # hash mutator that ensures that the <tt>mutate</tt> method
+    # will chain to the next mutator by using a
+    # template method.
+    module Mutators
+      class Base
+        attr_reader :next_mutator
+
+        # Registers all subclasses of Mutators::Base in
+        # Mutators::REGISTRY making it easy to reference
+        # and chain them later.
+        #
+        # See Mutators#chain for more information.
+        def self.inherited(subklass)
+          super
+          return if Utils.string_blank?(subklass.name)
+
+          key = Utils.string_underscore(Utils.string_demodulize(subklass.name)).to_sym
+          Wrest::Components::Mutators.registry[key] = subklass
+        end
+
+        def initialize(next_mutator = nil)
+          @next_mutator = next_mutator
+        end
+
+        # This is a template method which operates on a tuple (well, pair)
+        # from a hash map and guarantees mutator chaining.
+        #
+        # Iterating over any hash using <tt>each</tt> injects
+        # each key/value pair from the hash in the
+        # form of an array.
+        # This method expects of this form as an argument, i.e.
+        # an array with the structure [:key, :value]
+        #
+        # The implementation of the mutation is achieved by
+        # overriding the <tt>do_mutate</tt> method in a subclass.
+        # Note that failing to do so will result in an exception
+        # at runtime.
+        def mutate(tuple)
+          out_tuple = do_mutate(tuple)
+          next_mutator ? next_mutator.mutate(out_tuple) : out_tuple
+        end
+
+        protected
+
+        def do_mutate(_tuple)
+          raise Wrest::Exceptions::MethodNotOverridden
+        end
+      end
+    end
+  end
+end

data/lib/wrest/components/mutators/camel_to_snake_case.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Copyright 2009 Sidu Ponnappa
+
+# 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 Wrest
+  module Components
+    # Converts the key to snake case
+    #
+    # Example:
+    #  Mutators::CamelToSnakeCase.new.mutate(['Spirit-Sword', 'true'])  # => ['spirit_sword', 'true']**
+    module Mutators
+      class CamelToSnakeCase < Mutators::Base
+        def do_mutate(tuple)
+          [Utils.string_underscore(tuple.first), tuple.last]
+        end
+      end
+    end
+  end
+end

data/lib/wrest/components/mutators/xml_type_caster.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Copyright 2009 Sidu Ponnappa
+
+# 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 Wrest
+  module Components
+    # This mutator undertands how do type casting
+    # using the type data embedded in a hash
+    # created by deserialising an xml using
+    # ActiveSupport::XmlMini
+    module Mutators
+      class XmlTypeCaster < Mutators::Base
+        def do_mutate(tuple)
+          out_key, in_value = tuple
+
+          out_value = case in_value
+                      when Hash
+                        process_hash_value(in_value)
+                      when Array
+                        in_value.collect { |hash| hash.mutate_using(self) }
+                      else
+                        in_value
+                      end
+
+          [out_key, out_value]
+        end
+
+        private
+
+        def process_hash_value(in_value)
+          if in_value['nil'] == 'true'
+            nil
+          elsif in_value.key?('type')
+            typecast_value(in_value)
+          elsif in_value.key?('__content__')
+            in_value['__content__']
+          else
+            in_value.mutate_using(self)
+          end
+        end
+
+        def typecast_value(in_value)
+          caster = Container::Typecaster::PARSING[in_value['type']]
+          caster ? caster.call(in_value['__content__']) : in_value
+        end
+      end
+    end
+  end
+end

data/lib/wrest/components/mutators.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Copyright 2009 Sidu Ponnappa
+
+# 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 Wrest
+  module Components
+    # A mutator understands how to transform
+    # one tuple(key/value pair) from a hash
+    # into another
+    module Mutators
+      # All sublasses of Mutators::Base are automatically
+      # registered here by underscored, symbolised class name.
+      def self.registry
+        @registry ||= {}
+      end
+
+      # Makes referencing and chaining mutators easy.
+      #
+      # Example:
+      #  Mutators.chain(:xml_type_caster, :camel_to_snake_case)
+      # is equivalent to
+      #  Wrest::Components::Mutators::XmlTypeCaster.new(Wrest::Components::Mutators::CamelToSnakeCase.new)
+      def self.chain(*mutator_keys)
+        mutator_key = mutator_keys.pop
+        mutator_keys.reverse.inject(registry[mutator_key].new) do |next_instance, next_key|
+          registry[next_key].new(next_instance)
+        end
+      end
+    end
+  end
+end
+require 'wrest/core_ext/hash'
+require 'wrest/components/mutators/base'
+require 'wrest/components/mutators/xml_type_caster'
+require 'wrest/components/mutators/camel_to_snake_case'

data/lib/wrest/components/translators/content_types.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Copyright 2009 Sidu Ponnappa
+
+# 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 Wrest
+  module Components
+    module Translators
+      # Maps content types to deserialisers
+      CONTENT_TYPES = {
+        'application/xml' => Wrest::Components::Translators::Xml,
+        'text/xml' => Wrest::Components::Translators::Xml,
+        'application/json' => Wrest::Components::Translators::Json,
+        'text/javascript' => Wrest::Components::Translators::Json,
+        'text/plain' => Wrest::Components::Translators::Txt
+      }.freeze
+    end
+  end
+end

data/lib/wrest/components/translators/json.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Copyright 2009 Sidu Ponnappa
+
+# 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 Wrest
+  module Components
+    module Translators
+      module Json
+        module_function
+
+        def deserialise(response, _options = {})
+          JSON.parse(response.body)
+        end
+
+        def deserialize(response, options = {})
+          deserialise(response, options)
+        end
+
+        def serialise(hash, options = {})
+          hash.to_json(options)
+        end
+
+        def serialize(hash, options = {})
+          serialise(hash, options)
+        end
+      end
+    end
+  end
+end

data/lib/wrest/components/translators/txt.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Copyright 2009 Sidu Ponnappa
+
+# 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 Wrest
+  module Components
+    module Translators
+      module Txt
+        module_function
+
+        def deserialise(response, _options = {})
+          response.body
+        end
+
+        def deserialize(response, options = {})
+          deserialise(response, options)
+        end
+
+        def serialise(hash, _options = {})
+          hash.inspect
+        end
+
+        def serialize(hash, options = {})
+          serialise(hash, options)
+        end
+      end
+    end
+  end
+end

data/lib/wrest/components/translators/xml/conversions.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Wrest
+  module Components
+    module Translators
+      module Xml
+        module Conversions # :nodoc:
+          module Document # :nodoc:
+            def to_hash
+              root.to_hash
+            end
+          end
+
+          module Node # :nodoc:
+            CONTENT_ROOT = '__content__'
+
+            # Convert XML document to hash.
+            #
+            # hash::
+            #   Hash to merge the converted element into.
+            def to_hash(hash = {})
+              node_hash = {}
+
+              # Insert node hash into parent hash correctly.
+              case hash[name]
+              when Array then hash[name] << node_hash
+              when Hash then hash[name] = [hash[name], node_hash]
+              when nil then hash[name] = node_hash
+              end
+
+              # Handle child elements
+              children.each do |c|
+                if c.element?
+                  c.to_hash(node_hash)
+                elsif c.text? || c.cdata?
+                  node_hash[CONTENT_ROOT] ||= +''
+                  node_hash[CONTENT_ROOT] << c.content
+                end
+              end
+
+              # Remove content node if it is blank and there are child tags
+              node_hash.delete(CONTENT_ROOT) if node_hash.length > 1 && Utils.object_blank?(node_hash[CONTENT_ROOT])
+
+              # Handle attributes
+              attribute_nodes.each { |a| node_hash[a.node_name] = a.value }
+
+              hash
+            end
+          end
+        end
+        Nokogiri::XML::Document.include(Conversions::Document)
+        Nokogiri::XML::Node.include(Conversions::Node)
+      end
+    end
+  end
+end

data/lib/wrest/components/translators/xml.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# Copyright 2009 Sidu Ponnappa
+
+# 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_relative 'xml/conversions'
+
+module Wrest
+  module Components
+    module Translators
+      module Xml
+        module_function
+
+        def deserialise(response, options = {})
+          data = response.body
+          data = StringIO.new(data || '') unless data.respond_to?(:read)
+          return {} if data.eof?
+
+          if options[:xpath].nil?
+            parse(data)
+          else
+            search(data, options[:xpath])
+          end
+        end
+
+        def deserialize(response, options = {})
+          deserialise(response, options)
+        end
+
+        def serialise(hash, _options = {})
+          to_xml(hash)
+        end
+
+        def serialize(hash, options = {})
+          serialise(hash, options)
+        end
+
+        def to_xml(hash, builder = nil)
+          builder ||= Nokogiri::XML::Builder.new
+          hash.each_with_object(builder) do |(key, value), inner_builder|
+            if value.is_a?(Hash)
+              inner_builder.send(key.to_s) do |child_builder|
+                to_xml(value, child_builder)
+              end
+            else
+              inner_builder.send(key.to_s, value.to_s)
+            end
+          end.to_xml
+        end
+
+        # Parse an XML Document string or IO into a simple hash using libxml / nokogiri.
+        # data::
+        #   XML Document string or IO to parse
+        def parse(data)
+          build_nokogiri_doc(data).to_hash
+        end
+
+        def search(data, xpath)
+          build_nokogiri_doc(data).xpath(xpath)
+        end
+
+        def build_nokogiri_doc(data)
+          doc = Nokogiri::XML(data)
+          raise doc.errors.join("\n") if doc.errors.length.positive?
+
+          doc
+        end
+      end
+    end
+  end
+end

data/lib/wrest/components/translators.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Copyright 2009 Sidu Ponnappa
+
+# 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 Wrest
+  module Components
+    # Contains strategies/lambdas which know how to deserialise
+    # different content types.
+    module Translators
+      # Loads the appropriate desirialisation strategy based on
+      # the content type
+      def self.lookup(content_type)
+        translator = CONTENT_TYPES[content_type]
+        translator || (raise Wrest::Exceptions::UnsupportedContentType, "Unsupported content type #{content_type}")
+      end
+    end
+  end
+end
+
+require 'wrest/components/translators/txt'
+require 'wrest/components/translators/xml'
+require 'wrest/components/translators/json'
+require 'wrest/components/translators/content_types'

data/lib/wrest/components.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Copyright 2009 Sidu Ponnappa
+
+# 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 Wrest
+  # A component is a building block that can
+  # be used while building an object oriented wrapper
+  # around a REST service
+  module Components
+  end
+end
+
+require 'wrest/components/container'
+require 'wrest/components/mutators'
+require 'wrest/components/translators'