representors 0.0.5

data/lib/representors/serialization/hale_deserializer.rb

@@ -0,0 +1,162 @@
+require 'json'
+require 'representors/serialization/deserializer_base'
+require 'representors/errors'
+require 'representor_support/utilities'
+
+
+module Representors
+  # Class for a Hale document deserializer.
+  # Built against Hale version 0.0.1, https://github.com/mdsol/hale/tree/0-0-stable
+  # @since 0.0.2
+  class HaleDeserializer < DeserializerBase
+    media_symbol :hale
+    media_type 'application/vnd.hale+json'
+
+    META_KEY = '_meta'.freeze
+    REF_KEY = '_ref'.freeze
+    DATA_KEY = 'data'.freeze
+    OPTIONS_KEY = 'options'.freeze
+    LINKS_KEY = '_links'.freeze
+    EMBEDDED_KEY = '_embedded'.freeze
+    CURIE_KEY = 'curies'.freeze
+    HREF = 'href'.freeze
+    @reserved_keys = [LINKS_KEY, EMBEDDED_KEY, META_KEY, REF_KEY]
+    
+    RESERVED_FIELD_VALUES = Field::SIMPLE_METHODS + [Field::NAME_KEY, Field::SCOPE_KEY, Field::OPTIONS_KEY, Field::VALIDATORS_KEY, Field::DESCRIPTORS_KEY, DATA_KEY]
+   
+    # This need to be public to support embedded data
+    # TODO: make this private
+    def to_representor_hash
+      media = @target.is_a?(Hash) ? @target : JSON.parse(@target)
+      builder_add_from_deserialized(RepresentorBuilder.new, media).to_representor_hash
+    end
+    
+    private
+    
+    def self.reserved_keys
+      @reserved_keys
+    end
+    
+    def builder_add_from_deserialized(builder, media)
+      media = dereference_meta_media(media)
+      builder = deserialize_properties(builder, media)
+      builder = deserialize_links(builder, media)
+      builder = deserialize_embedded(builder, media)
+    end
+    
+    # Properties are normal JSON keys in the Hale document. Create properties in the resulting object
+    def deserialize_properties(builder, media)
+      media.each do |k,v|
+        builder = builder.add_attribute(k, v) unless (self.class.reserved_keys.include?(k))
+      end
+      builder
+    end
+    
+    # links are under '_links' in the original document. Links always have a key (its name) but
+    # the value can be a hash with its properties or an array with several links.
+    # TODO: Figure out error handling for malformed documents
+    def deserialize_links(builder, media)
+      links = media[LINKS_KEY] || {}
+      
+      links.each do |link_rel,link_values|
+        raise(DeserializationError, 'CURIE support not implemented for HAL') if link_rel.eql?(CURIE_KEY)
+        if link_values.is_a?(Array)
+          if link_values.any? { |link| link[HREF].nil? }
+            raise DeserializationError, 'All links must contain the href attribute'
+          end
+          builder = builder.add_transition_array(link_rel, link_values)
+        else
+          href = link_values[HREF]
+          raise DeserializationError, 'All links must contain the href attribute' unless href
+          builder = builder.add_transition(link_rel, href, link_values )
+        end
+      end
+      
+      builder
+    end
+    
+    # embedded resources are under '_embedded' in the original document, similarly to links they can
+    # contain an array or a single embedded resource. An embedded resource is a full document so
+    # we create a new HaleDeserializer for each.
+    def deserialize_embedded(builder, media)
+      make_embedded_resource = ->(x) { self.class.new(x).to_representor_hash.to_h }
+      (media[EMBEDDED_KEY] || {}).each do |name, value|
+        resource_hash = map_or_apply(make_embedded_resource, value)
+        builder = builder.add_embedded(name, resource_hash)
+      end
+      builder
+    end
+    
+    def deserialize_links(builder, media)
+      (media[LINKS_KEY] || {}).each do |link_rel, link_values|
+        link_values = [link_values] unless link_values.is_a?(Array)
+        ensure_valid_links!(link_rel, link_values)
+        link_values = parse_validators(link_values)
+        link_values = parse_options(link_values)
+        builder = builder.add_transition_array(link_rel, link_values)
+      end
+      builder
+    end
+
+    def ensure_valid_links!(link_rel, link_values_array)
+      raise(DeserializationError, 'CURIE support not implemented for HAL') if link_rel.eql?(CURIE_KEY)
+
+      if link_values_array.map { |link| link[HREF] }.any?(&:nil?)
+        raise DeserializationError, 'All links must contain the href attribute'
+      end
+    end
+
+    def deep_find_and_transform!(obj, target_key, &blk)
+      if obj.respond_to?(:key) && obj.key?(target_key)
+        deep_find_and_transform!(obj[target_key], target_key, &blk)
+        yield obj
+      elsif [Array, Hash].include?(obj.class)
+        obj.each { |*el| deep_find_and_transform!(el.last, target_key, &blk) }
+      end
+    end
+
+    def dereference_meta_media(media)
+      media = deep_dup(media)
+      # Remove _meta from media to prevent serialization as property
+      if meta_info = media.delete(META_KEY)
+        deep_find_and_transform!(media, REF_KEY) do |media|
+          media.delete(REF_KEY).each { |ref| media[ref] = meta_info[ref] }
+        end
+      end
+      media
+    end
+
+    def parse_options(media)
+      media = deep_dup(media)
+      deep_find_and_transform!(media, OPTIONS_KEY) { |media| parse_options!(media) }
+      media
+    end
+
+    def parse_options!(media)
+      if media[OPTIONS_KEY].is_a?(Array) && media[OPTIONS_KEY].first.is_a?(Hash)
+        new_options = media[OPTIONS_KEY].reduce({}) { |memo, hash| memo.merge!(hash) }
+        media[OPTIONS_KEY] = { 'hash' => new_options }
+      elsif !media[OPTIONS_KEY].is_a?(Hash)
+        media[OPTIONS_KEY] = { 'list' => deep_dup(media[OPTIONS_KEY]) }
+      end
+    end
+
+    def parse_validators(media)
+      media = deep_dup(media)
+      deep_find_and_transform!(media, DATA_KEY) { |media| parse_data!(media) }
+      media
+    end
+
+    def parse_data!(media)
+      media[DATA_KEY].each do |field_key, field_value|
+        arr = []
+        field_value.each do |k,v|
+          arr << {k => media[DATA_KEY][field_key].delete(k)} unless RESERVED_FIELD_VALUES.include?(k.to_sym)
+        end
+        media[DATA_KEY][field_key][Field::VALIDATORS_KEY] = arr unless arr.empty?
+      end
+    end
+
+  end
+
+end

data/lib/representors/serialization/hale_serializer.rb

@@ -0,0 +1,110 @@
+require 'representors/serialization/hal_serializer'
+
+module Representors
+  module Serialization
+    class HaleSerializer < HalSerializer
+      media_symbol :hale_json
+      media_type 'application/vnd.hale+json'
+
+      SEMANTIC_TYPES = {
+        select: "text", #No way in Crichton to distinguish [Int] and [String]
+        search:"text",
+        text: "text",
+        boolean: "bool", #a Server should accept ?cat&dog or ?cat=cat&dog=dog
+        number: "number",
+        email: "text",
+        tel: "text",
+        datetime: "text",
+        time: "text",
+        date: "text",
+        month: "text",
+        week: "text",
+        object: "object",
+        :"datetime-local" => "text"
+      }
+      # This is public and returning a hash to be able to implement embedded resources
+      # serialization
+      # TODO: make this private and merge with to_media_type
+      # The name is quite misleading,
+      def to_hash(options ={})
+        base_hash, links, embedded_hales = common_serialization(@target)
+        meta = get_data_lists(@target)
+        base_hash.merge!(meta).merge!(links).merge!(embedded_hales.(options))
+        base_hash
+      end
+
+
+      # This is the main entry of this class. It returns a serialization of the data
+      # in a given media type.
+      def to_media_type(options = {})
+        to_hash(options).to_json
+      end
+
+      private
+
+      def get_data_lists(representor)
+        meta = {}
+        representor.datalists.each do |datalist|
+          meta[datalist.id] = datalist.to_data
+        end
+        meta.empty? ? {} : {'_meta' => meta }
+      end
+
+      def elemental_renderer(etype)
+        {
+          type: ->(element) { render_type(element.field_type,element.type) if element.field_type || element.type },
+          scope: ->(element) { element.scope unless element.scope == 'attribute' },
+          value: ->(element) { element.value unless element.value.nil? },
+          multi: ->(element) { true if element.cardinality == "multiple" },
+          data: ->(element) { render_data_elements(element.descriptors) if element.type == 'object' },
+        }[etype]
+      end
+      
+      def get_data_validators(element)
+        element.validators.reduce({}) do |results, validator| 
+          results.merge( validator.is_a?(Hash) ? validator : {validator => true} )
+        end
+      end
+      
+      def get_data_properties(element)
+        [:type, :scope, :value, :multi, :data].reduce({}) do |result, symbol|
+          elemental = elemental_renderer(symbol).call(element) 
+          result.merge( elemental.nil? ? {} : {symbol => elemental} )
+        end
+      end
+
+      def get_data_element(element)
+        options = if element.options.datalist?
+          { '_ref' => [element.options.id] }
+        elsif element.options.type == Representors::Options::HASH_TYPE
+          element.options.to_hash.map { |option| Hash[*option] }
+        else
+          element.options.to_list
+        end
+        element_data = get_data_validators(element)
+        elementals = get_data_properties(element)
+        elementals[:options] = options unless options.empty?
+        { element.name => element_data.merge(elementals) }
+      end
+
+      def render_data_elements(elements)
+        elements.reduce({}) do |results, element|
+          results.merge( get_data_element(element) )
+        end
+      end
+
+      def build_links_for_this_media_type(transition)
+        link = super(transition) #default Hal serialization
+        # below add fields specific for Hale
+        data_elements = render_data_elements(transition.descriptors)
+        link[:data] = data_elements unless data_elements.empty?
+        link[:method] = transition.interface_method unless transition.interface_method == Transition::DEFAULT_METHOD
+        link
+      end
+      
+      def render_type(field_type, type = SEMANTIC_TYPES[field_type.to_sym])
+        field_type ? "#{type}:#{field_type}" : "#{type}"
+      end
+    end
+  end
+end

data/lib/representors/serialization/serialization_base.rb

@@ -0,0 +1,27 @@
+require 'representor_support/utilities'
+
+module Representors
+  class SerializationBase
+    include RepresentorSupport::Utilities
+
+    attr_reader :target
+
+    def self.media_symbols
+      @media_symbols ||= Set.new
+    end
+
+    def self.media_types
+      @media_types ||= Set.new
+    end
+
+    private
+    def self.media_symbol(*symbol)
+      @media_symbols = media_symbols | symbol
+    end
+
+    def self.media_type(*media)
+      @media_types = media_types | media
+    end
+
+  end
+end

data/lib/representors/serialization/serialization_factory_base.rb

@@ -0,0 +1,54 @@
+require 'representors/errors'
+
+module Representors
+  ##
+  # Base class for factories that manages the registration of serialization classes and the common factory interface.
+  class SerializationFactoryBase
+    def self.build(media_type, object)
+      klass = serialization_class(media_type)
+      if klass
+        klass.new(object)
+      else
+        raise UnknownMediaTypeError, "Unknown media-type: #{media_type}."
+      end
+    end
+
+    def self.media_symbol_mapping
+      @media_symbol_mapping ||= registered_serialization_classes.map do |serialization_class|
+        serialization_class.media_symbols.map { |media_symbol| { media_symbol => serialization_class } }.reduce(:merge)
+      end.reduce(:merge)
+    end
+
+    def self.media_type_mapping
+      @media_type_mapping ||= registered_serialization_classes.map do |serializer|
+        serializer.media_types.map { |media_type| { media_type => serializer.media_symbols.first } }.reduce(:merge)
+      end.reduce(:merge)
+    end
+
+
+    private  
+    def self.register_serialization_classes(*serializers)
+      clear_memoization
+      @_registered_serialization_classes ||= []
+      @_registered_serialization_classes |= serializers
+    end
+
+    def self.clear_memoization
+      @registered_serialization_classes = nil
+      @media_symbol_mapping = nil
+      @media_type_mapping = nil
+    end
+
+    def self.registered_serialization_classes
+      @registered_serialization_classes ||= @_registered_serialization_classes.dup.freeze
+    end
+   
+    # If a client send directly a Content-Type it may have encodings or other things so we want
+    # to be more flexible
+    def self.serialization_class(media_type)
+      symbol =  media_type.is_a?(Symbol) ? media_type : media_type_mapping[media_type]
+      media_symbol_mapping[symbol]
+    end
+  end
+end
+

data/lib/representors/serialization/serializer_base.rb

@@ -0,0 +1,20 @@
+require 'representors/serialization/serialization_base'
+require 'representors/serialization/serializer_factory'
+
+module Representors
+  class SerializerBase < SerializationBase
+
+    def initialize(target)
+      @target = target.empty? ? Representor.new({}) : target
+    end
+
+    def self.inherited(subclass)
+      SerializerFactory.register_serializers(subclass)
+    end
+
+    def to_hash(options = {})
+      raise "Abstract method #to_hash not implemented in #{self.class.to_s} serializer class."
+    end
+
+  end
+end

data/lib/representors/serialization/serializer_factory.rb

@@ -0,0 +1,17 @@
+require 'representors/serialization/serialization_factory_base'
+
+module Representors
+  class SerializerFactory < SerializationFactoryBase
+    def self.register_serializers(*serializers)
+      register_serialization_classes(*serializers)
+    end
+
+    def self.registered_serializers
+      registered_serialization_classes
+    end
+
+    def self.serializer?(serializer_name)
+      registered_serializers.any? { |serializer| serializer.media_symbol.include?(serializer_name.to_sym) }
+    end
+  end
+end

data/lib/representors/transition.rb

@@ -0,0 +1,130 @@
+require 'addressable/template'
+
+module Representors
+  ##
+  # Manages the respresentation of link elements for hypermedia messages.
+  class Transition
+    REL_KEY = :rel
+    HREF_KEY = :href
+    LINKS_KEY = :links
+    METHOD_KEY = :method
+    DESCRIPTORS_KEY = :descriptors
+    DEFAULT_METHOD = 'GET'
+    PARAMETER_FIELDS = 'href'
+    ATTRIBUTE_FIELDS = 'attribute'
+    URL_TEMPLATE = "%s{?%s}"
+
+    # @example
+    #   hash =  {rel: "self", href: "http://example.org"}
+    #   Transition.new(hash)
+    # Must contain at least the property :href
+    # @param [Hash] the abstract representor hash defining a transition
+    def initialize(transition_hash)
+      @transition_hash = transition_hash
+    end
+
+    # @return [String] so the user can 'puts' this object
+    def to_s
+      @transition_hash.inspect
+    end
+
+    # @return [Hash] useful in cucumber steps where the feature file provides a hash
+    def to_hash
+      Hash[@transition_hash.map{ |k, v| [k.to_s, v] }]
+    end
+
+    # @return [String] The name of the Relationship
+    def rel
+      retrieve(REL_KEY)
+    end
+
+    # @return [String] The URI for the object
+    def uri(data={})
+      template = Addressable::Template.new(retrieve(HREF_KEY))
+      template.expand(data).to_str
+    end
+
+    # @param [String] key on the transitions hash to retrieve
+    # @return [String] with the value of the key
+    def [](key)
+      retrieve(key)
+    end
+
+    # @param [String] key on the transitions hash to retrieve
+    # @return [Bool] false if there is no key
+    def has_key?(key)
+      !retrieve(key).nil?
+    end
+
+    # @return [String] The URI for the object templated against #parameters
+    def templated_uri
+      #URL as it is, it will be the templated URL of the document if it was templated
+      retrieve(HREF_KEY)
+    end
+
+    def templated?
+      # if we have any variable then it is not a templated url
+      !Addressable::Template.new(retrieve(HREF_KEY)).variables.empty?
+    end
+
+    # @return [Array] who's elements are all <Crichton:Transition> objects
+    def meta_links
+      @meta_links ||= (retrieve(LINKS_KEY) || []).map do |link_key, link_href|
+        Transition.new({rel: link_key, href: link_href})
+      end
+    end
+
+    # @return [String] representing the Uniform Interface Method
+    def interface_method
+      retrieve(METHOD_KEY) || DEFAULT_METHOD
+    end
+    # The Parameters (i.e. GET variables)
+    #
+    # @return [Array] who's elements are all <Crichton:Field> objects
+    # Variables in the URI template rules this method, we are going to return a field for each of them
+    # if we find a field inside the 'data' of the document describing that variable, we use that information
+    # else we return a field with default information about a variable.
+    def parameters
+      data_fields = descriptors_fields.select{|field| field.scope == PARAMETER_FIELDS }
+      Addressable::Template.new(retrieve(HREF_KEY)).variables.map do |template_variable_name|
+        field_specified = data_fields.find{|field| field.name.to_s == template_variable_name.to_s}
+        if field_specified
+          field_specified
+        else
+          Field.new({template_variable_name.to_sym => {type: 'string', scope: 'href'}})
+        end
+      end
+     # descriptors_fields.select{|field| field.scope == PARAMETER_FIELDS }
+    end
+
+    # The Parameters (i.e. POST variables)
+    #
+    # @return [Array] who's elements are all <Crichton:Field> objects
+    def attributes
+      @attributes ||= descriptors_fields.select{|field| field.scope == ATTRIBUTE_FIELDS }
+    end
+
+    # The Parameters (i.e. GET variables)
+    #
+    # @return [Array] who's elements are all <Crichton:Field> objects
+    def descriptors
+      @descriptions ||= (attributes + parameters)
+    end
+
+    private
+
+    def descriptors_fields
+      @fields_hash ||= descriptors_hash.map { |k, v| Field.new({k => v }) }
+    end
+
+    def descriptors_hash
+      @transition_hash[DESCRIPTORS_KEY] || []
+    end
+
+    # accept retrieving keys by symbol or string
+    def retrieve(key)
+      @transition_hash[key.to_sym] || @transition_hash[key.to_s]
+    end
+
+  end
+end