amee 2.7.0 → 3.0.1

data/lib/amee/v3/collection.rb

@@ -0,0 +1,61 @@
+# Copyright (C) 2008-2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+module AMEE
+  class Collection < Array
+
+    def v3
+      collectionpath=~/^\/3/
+    end
+
+    def fetch_with_v3
+      @options.merge! @pager.options if @pager
+      retries = [1] * connection.retries
+      begin
+        if @use_v3_connection == true
+          @response = @connection.v3_get(collectionpath, @options)
+        else
+          @response= @connection.get(collectionpath, @options).body
+        end
+        if @response.is_json?
+          @json = true
+          @doc = JSON.parse(@response)
+        else
+          @doc = load_xml_doc(@response)
+        end
+      rescue JSON::ParserError, Nokogiri::XML::SyntaxError
+        @connection.expire(collectionpath)
+        if delay = retries.shift
+          sleep delay
+          retry
+        else
+          raise
+        end
+      end
+    end
+    alias_method_chain :fetch, :v3
+
+    def each_page_with_v3
+      @pager=AMEE::Limiter.new(@options) if v3
+      # in v3 need to specify limit to start with, not in v2
+      begin           
+        fetch
+        yield
+        if json
+          @pager = v3 ? AMEE::Limiter.from_json(doc,@pager.options.merge(@options)) :  # json not built
+            AMEE::Pager.from_json(doc['pager'])
+        else
+          @pager = v3 ? 
+               AMEE::Limiter.from_xml(doc.xpath('/Representation/*').first,
+               @pager.options.merge(@options)) :
+               AMEE::Pager.from_xml(doc.xpath('/Resources//Pager').first)
+        end
+        break if @max && length>=@max
+      end while @pager && @pager.next! #pager is nil if no pager in response,
+      # pager.next! is false if @pager said current=last.
+    end
+    alias_method_chain :each_page, :v3
+
+  end
+end
+

data/lib/amee/v3/connection.rb

@@ -0,0 +1,99 @@
+# Copyright (C) 2008-2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+module AMEE
+  class Connection
+    def v3_connection
+      @v3_http ||= begin
+        @v3_http = Net::HTTP.new(v3_hostname, @port)
+        if @ssl == true
+          @v3_http.use_ssl = true
+          if File.exists? RootCA
+            @v3_http.ca_file = RootCA
+            @v3_http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+            @v3_http.verify_depth = 5
+          end
+        end
+        @v3_http.set_debug_output($stdout) if @debug
+        @v3_http
+      end
+    end    
+    def v3_get(path, options = {})
+      # Create URL parameters
+      unless options.empty?
+        path += "?" + options.map { |x| "#{CGI::escape(x[0].to_s)}=#{CGI::escape(x[1].to_s)}" }.join('&')
+      end
+      cache(path) { v3_request(Net::HTTP::Get.new(path)) }
+    end
+    def v3_put(path, options = {})
+      expire_matching "#{parent_path(path)}.*"
+      put = Net::HTTP::Put.new(path)
+      if options[:body]
+        put.body = options[:body]
+        put['Content-Type'] = content_type :xml if options[:body].is_xml?
+        put['Content-Type'] = content_type :json if options[:body].is_json?
+      else
+        put.set_form_data(options)
+      end
+      v3_request put
+    end
+    def v3_post(path, options = {})
+      expire_matching "#{raw_path(path)}.*"
+      post = Net::HTTP::Post.new(path)
+      returnobj=options.delete(:returnobj) || false
+      post.set_form_data(options)
+      v3_request post,returnobj
+    end
+     def v3_delete(path, options = {})
+      expire_matching "#{parent_path(path)}.*"
+      delete = Net::HTTP::Delete.new(path)
+      v3_request delete
+    end
+    def v3_auth
+      # now the same as v2, i.e.
+      [@username,@password]
+    end
+    private
+    def v3_hostname
+      unless @server.starts_with?("platform-api-")
+        if @server.starts_with?("platform-")
+          @server.gsub("platform-", "platform-api-")
+        else
+          "platform-api-#{@server}"
+        end
+      else
+        @server
+      end
+    end
+    def v3_request(req,returnobj=false)
+      # Open HTTP connection
+      v3_connection.start
+      # Set auth
+      req.basic_auth *v3_auth
+      # Do request
+      timethen=Time.now
+      response = send_request(v3_connection, req, :xml)
+      Logger.log.debug("Requested #{req.class} at #{req.path} with #{req.body}, taking #{(Time.now-timethen)*1000} miliseconds")
+      v3_response_ok? response, req
+      returnobj ? response : response.body
+    ensure
+      v3_connection.finish if v3_connection.started?
+    end
+ 
+    def v3_response_ok?(response, request)
+      case response.code
+        when '200', '201', '204'
+          return true
+        when '404'
+          raise AMEE::NotFound.new("The URL was not found on the server.\nRequest: #{request.method} #{request.path}")
+        when '403'
+          raise AMEE::PermissionDenied.new("You do not have permission to perform the requested operation.\nRequest: #{request.method} #{request.path}\n#{request.body}\Response: #{response.body}")
+        when '401'
+          raise AMEE::AuthFailed.new("Authentication failed. Please check your username and password.")
+        when '400'
+          raise AMEE::BadRequest.new("Bad request. This is probably due to malformed input data.\nRequest: #{request.method} #{request.path}\n#{request.body}\Response: #{response.body}")
+      end
+      raise AMEE::UnknownError.new("An error occurred while talking to AMEE: HTTP response code #{response.code}.\nRequest: #{request.method} #{request.path}\n#{request.body}\Response: #{response.body}")
+    end
+  end
+end

data/lib/amee/v3/item_definition.rb

@@ -0,0 +1,73 @@
+# Copyright (C) 2008-2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+module AMEE
+  module Admin
+    class ItemDefinition < AMEE::Object
+
+      include ParseHelper
+
+      def initialize_with_v3(data = {})
+        @usages = data[:usages] || []
+        initialize_without_v3(data)
+      end
+      alias_method_chain :initialize, :v3
+
+      attr_accessor :usages
+
+      def self.metaxmlpathpreamble
+        '/Representation/ItemDefinition/'
+      end
+
+      def self.load(connection,uid,options={})
+        ItemDefinition.v3_get(connection,uid,options)
+      end
+
+      def self.v3_get(connection, uid, options={})
+        # Load data from path
+        response = connection.v3_get("/#{AMEE_API_VERSION}/definitions/#{uid};full", options)
+        # Parse response
+        item_definition = ItemDefinition.parse(connection, response, false)
+        # Done
+        return item_definition
+      rescue
+        raise AMEE::BadData.new("Couldn't load ItemDefinition. Check that your URL is correct.\n#{$!}\n#{response}")
+      end
+
+      def self.from_xml_with_v3(xml, is_list = true)
+        return self.from_xml_without_v3(xml, is_list) if xml.include?('<Resources>')
+        # Parse data from response into hash
+        doc = load_xml_doc(xml)
+        data = {}
+        data[:uid] = x '@uid', :doc => doc, :meta => true
+        data[:created] = DateTime.parse(x '@created', :doc => doc, :meta => true)
+        data[:modified] = DateTime.parse(x '@modified', :doc => doc, :meta => true)
+        data[:name] = x 'Name', :doc => doc, :meta => true
+        data[:drillDown] = x('DrillDown', :doc => doc, :meta => true).split(",") rescue nil
+        data[:usages] = [(x 'Usages/Usage/Name', :doc => doc, :meta => true)].flatten.delete_if{|x| x.nil?}
+        # Create object
+        ItemDefinition.new(data)
+      rescue
+        raise AMEE::BadData.new("Couldn't load ItemDefinition from XML. Check that your URL is correct.\n#{$!}\n#{xml}")
+      end
+      class << self
+        alias_method_chain :from_xml, :v3
+      end
+
+      def save!
+        save_options = {
+          :usages => @usages.join(','),
+          :name => @name
+        }
+        @connection.v3_put("/#{AMEE_API_VERSION}/definitions/#{@uid}",save_options)
+      end
+
+      def expire_cache_with_v3
+        @connection.expire_matching("/#{AMEE_API_VERSION}/definitions/#{@uid}.*")
+        expire_cache_without_v3
+      end
+      alias_method_chain :expire_cache, :v3
+
+    end
+  end
+end

data/lib/amee/v3/item_value_definition.rb

@@ -0,0 +1,99 @@
+# Copyright (C) 2008-2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+module AMEE
+  module Admin
+    class ItemValueDefinition
+      include MetaHelper
+
+      def initialize_with_v3(data = {})
+        storemeta(data[:meta]) if data[:meta]
+        initialize_without_v3(data)
+      end
+      alias_method_chain :initialize, :v3
+
+      def metapath
+        "/#{AMEE_API_VERSION}/definitions/#{itemdefuid}/values/#{uid};wikiDoc;usages"
+      end
+      def metaxmlpathpreamble
+        '/Representation/ItemValueDefinition/'
+      end
+      def storemeta(options)
+        @meta=OpenStruct.new
+        @meta.wikidoc= options[:wikidoc]
+        @usages = options[:usages] || []
+      end
+      def parsemeta
+        data = {}
+        data[:wikidoc]=x 'WikiDoc', :meta => true
+        names = x('Usages/Usage/Name', :meta => true)
+        types = x('Usages/Usage/Type', :meta => true)
+        data[:usages] = names && types ? Hash[*(names.zip(types.map{|x| x.downcase.to_sym})).flatten] : {}
+        storemeta(data)
+      end
+      def putmeta_args
+        str = <<EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<ItemValueDefinition>
+  <WikiDoc>#{meta.wikidoc}</WikiDoc>
+  <Usages>
+EOF
+        @usages.each_pair do |name, type|
+          str += <<EOF
+    <Usage>
+      <Name>#{name}</Name>
+      <Type>#{type.to_s.upcase}</Type>
+    </Usage>
+EOF
+        end
+        str += <<EOF
+  </Usages>
+</ItemValueDefinition>
+EOF
+        {:body => str}
+      end
+      def usages
+        @usages.keys
+      end
+      def clear_usages!
+        @usages = {}
+      end
+      def set_usage_type(usage, type)
+        loadmeta if @usages.nil?
+        @usages[usage] = type
+      end
+      def usage_type(usage)
+        loadmeta if @usages.nil?
+        @usages[usage] || :optional
+      end
+      def optional?(usage)
+        usage_type(usage) == :optional
+      end
+      def compulsory?(usage)
+        usage_type(usage) == :compulsory
+      end
+      def forbidden?(usage)
+        usage_type(usage) == :forbidden
+      end
+      def ignored?(usage)
+        usage_type(usage) == :ignored
+      end
+      def default
+        return nil if @default.nil?
+        case valuetype
+        when "DECIMAL", "DOUBLE"
+          @default.to_f rescue nil
+        else
+          @default
+        end
+      end
+
+      def expire_cache_with_v3
+        @connection.expire_matching("/#{AMEE_API_VERSION}/definitions/#{itemdefuid}/values/#{uid}.*")
+        expire_cache_without_v3
+      end
+      alias_method_chain :expire_cache, :v3
+
+    end
+  end
+end

data/lib/amee/v3/item_value_definition_list.rb

@@ -0,0 +1,53 @@
+# Copyright (C) 2008-2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+module AMEE
+  module Admin
+
+    class ItemValueDefinitionList < AMEE::Collection
+
+      def initialize_with_v3(connection,uid,options={}, &block)
+        @use_v3_connection = true
+        initialize_without_v3(connection, uid, options, &block)
+      end
+      alias_method_chain :initialize, :v3
+
+      def collectionpath
+        "/#{AMEE_API_VERSION}/definitions/#{@uid}/values;full"
+      end
+
+      def xmlcollectorpath
+        '/Representation/ItemValueDefinitions/ItemValueDefinition'
+      end
+
+      def parse_json(p)
+        raise AMEE::NotSupported
+      end
+      
+      def parse_xml(p)
+        # This should really be handed off to ItemValueDefinition fully
+        data = {}
+        data[:itemdefuid] = @uid
+        data[:uid] = x '@uid',:doc => p
+        data[:name] = x 'Name',:doc => p  || data[:uid]
+        data[:path] = x 'Path',:doc => p
+        data[:default] = x 'Value',:doc => p
+        data[:unit] = x 'Unit',:doc => p
+        data[:perunit] = x 'PerUnit',:doc => p
+        data[:valuetype] =x 'ValueDefinition/ValueType',:doc => p
+        data[:choices] =(x('Choices',:doc => p)||'').split(',')        
+        data[:versions] =[(x('Versions/Version/Version',:doc => p))].flatten
+        data[:meta] = {}
+        data[:meta][:wikidoc]=x 'WikiDoc', :doc => p
+        names = x('Usages/Usage/Name', :doc => p)
+        types = x('Usages/Usage/Type', :doc => p)
+        data[:meta][:usages] = names && types ? Hash[*(names.zip(types.map{|x| x.downcase.to_sym})).flatten] : {}
+        data[:drill]=(x('DrillDown',:doc => p)=='true')
+        data[:from_profile]=(x('FromProfile',:doc => p)=='true')
+        data[:from_data]=(x('FromData',:doc => p)=='true')
+        data
+      end
+    end
+    
+  end
+end

data/lib/amee/v3/meta_helper.rb

@@ -0,0 +1,28 @@
+# Copyright (C) 2008-2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+require 'ostruct'
+
+module MetaHelper
+  def putmeta(args = {})
+    tags=args.delete(:tags)
+    args.merge! putmeta_args # Added in order to abstract PUTs away from providing arguments in the call. Eventually args param will be deprecated.
+    @connection.v3_put(metapath,args)
+    puttags(tags) if tags
+    loadmeta
+  end
+  def puttags(tags)
+    existing_tags=AMEE::Tags.new(@connection,:category=>uid)
+    existing_tags.reset_to(tags)
+  end
+  def loadmeta
+    resp=@connection.v3_get(metapath)
+    @doc=load_xml_doc(resp)
+    parsemeta
+    @meta
+  end
+  private :loadmeta
+  def meta
+    @meta||=loadmeta
+  end
+end

data/lib/amee/v3/return_value_definition.rb

@@ -0,0 +1,202 @@
+# Copyright (C) 2008-2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+module AMEE
+  module Admin
+
+    class ReturnValueDefinitionList < AMEE::Collection
+      # TODO this class does not yet page through multiple pages
+      def initialize(connection,uid,options={})
+        @uid=uid
+        @use_v3_connection=true
+        super(connection,options)
+      end
+      def klass
+        ReturnValueDefinition
+      end
+      def collectionpath
+        "/#{AMEE_API_VERSION}/definitions/#{@uid}/returnvalues;full"
+      end
+
+      def jsoncollector
+        @doc['returnValueDefinitions']
+      end
+      def xmlcollectorpath
+        '/Representation/ReturnValueDefinitions/ReturnValueDefinition'
+      end
+
+      def parse_json(p)
+        data = {}
+        data[:itemdefuid] = @uid
+        data[:uid] = p['uid']
+        data[:name] = p['type']
+        data[:unit] = p['unit']
+        data[:perunit] = p['perunit']
+        data[:valuetype] = p['valueDefinition']['valueType']
+        data
+      end
+      def parse_xml(p)
+        data = {}
+        data[:itemdefuid] = @uid
+        data[:uid] = x '@uid',:doc => p
+        data[:name] = x 'Type',:doc => p  || data[:uid]
+        data[:unit] = x 'Unit',:doc => p
+        data[:perunit] = x 'PerUnit',:doc => p
+        data
+      end
+    end
+
+    class ReturnValueDefinition < AMEE::Object
+
+      def initialize(data = {})
+        @itemdefuid=data[:itemdefuid]
+        @name = data[:name]
+        @uid = data[:uid]       
+        @type = data[:type]
+        @unit = data[:unit]
+        @perunit = data[:perunit]
+        @valuetype = data[:valuetype]
+        
+        super
+      end
+
+      attr_reader :name,:uid,:itemdefuid, :type, :valuetype, :unit, :perunit
+     
+      def self.list(connection)
+        ReturnValueDefinitionList.new(connection)
+      end
+
+      def self.parse(connection, response)
+        # Parse data from response
+        if response.is_json?
+          item_definition = ReturnValueDefinition.from_json(response)
+        else
+          item_definition = ReturnValueDefinition.from_xml(response)
+        end
+        # Store connection in object for future use
+        item_definition.connection = connection
+        # Done
+        return item_definition
+      end
+
+      def self.from_json(json)
+        # Read JSON
+        doc = JSON.parse(json)
+        data = {}
+        p=doc['returnValueDefinition']
+        data[:uid] = p['uid']
+        data[:itemdefuid] = p['itemDefinition']['uid']
+        data[:type] = p['type']
+        data[:path] = p['path']
+        data[:unit] = p['unit']
+        data[:perunit] = p['perUnit']
+        data[:valuetype] = p['valueDefinition']['valueType']
+        data[:default] = p['value']
+        
+        # Create object
+        ReturnValueDefinition.new(data)
+      rescue
+        raise AMEE::BadData.new("Couldn't load ReturnValueDefinition from JSON. Check that your URL is correct.\n#{json}")
+      end
+
+      def self.xmlpathpreamble
+        "/Representation/ReturnValueDefinition/"
+      end
+
+      def self.from_xml(xml)
+      
+       
+        # Parse data from response into hash
+        doc = load_xml_doc(xml)
+        data = {}
+        data[:uid] = x "@uid",:doc=>doc
+        data[:itemdefuid] = x "ItemDefinition/@uid",:doc=>doc
+        data[:type] = x "Type",:doc=>doc
+        data[:unit] = x "Unit",:doc=>doc
+        data[:perunit] =  x "PerUnit",:doc=>doc
+        data[:valuetype] = x  "ValueDefinition/ValueType",:doc=>doc
+        data[:default] = x "ReturnValueDefinition/Default",:doc=>doc
+        
+       
+        # Create object
+        ReturnValueDefinition.new(data)
+      rescue => err
+        raise AMEE::BadData.new("Couldn't load ReturnValueDefinition from XML. Check that your URL is correct.\n#{xml}\n#{err}")
+      end
+
+      def self.get(connection, path, options = {})
+        # Load data from path
+        response = connection.v3_get(path, options)
+        # Parse response
+        item_definition = ReturnValueDefinition.parse(connection, response)
+        # Done
+        return item_definition
+      rescue => err
+        raise AMEE::BadData.new("Couldn't load ReturnValueDefinition. Check that your URL is correct.\n#{response}\n#{err}")
+      end
+
+ 
+
+      def self.load(connection,itemdefuid,ivduid,options={})
+        ReturnValueDefinition.get(connection,"/#{AMEE_API_VERSION}/definitions/#{itemdefuid}/returnvalues/#{ivduid};full",options)
+      end
+
+      def reload(connection)
+        ReturnValueDefinition.load(connection,itemdefuid,uid)
+      end
+
+      def self.update(connection, path, options = {})
+        
+        # Do we want to automatically fetch the item afterwards?
+        get_item = options.delete(:get_item)
+        get_item = true if get_item.nil?
+        # Go
+        response = connection.v3_put(path, options)
+        if get_item
+          if response.empty?
+            return ReturnValueDefinition.get(connection, path)
+          else
+            return ReturnValueDefinition.parse(connection, response)
+          end
+        end
+      rescue
+        raise AMEE::BadData.new("Couldn't update ReturnValueDefinition. Check that your information is correct.\n#{response}")
+      end
+
+      def self.create(connection,itemdefuid, options = {})
+        
+        unless options.is_a?(Hash)
+          raise AMEE::ArgumentError.new("Second argument must be a hash of options!")
+        end
+        # Send data
+        vt=options.delete(:valuetype)
+        case vt
+        when 'text'
+          options.merge!( :valueDefinition=>"CCEB59CACE1B")
+        else
+          options.merge!( :valueDefinition=>"45433E48B39F")
+        end
+        
+        options.merge!(:returnobj=>true)
+        response = connection.v3_post("/#{AMEE_API_VERSION}/definitions/#{itemdefuid}/returnvalues", options)
+        return ReturnValueDefinition.load(connection,itemdefuid , response['Location'].split('/')[7])
+      rescue
+        raise AMEE::BadData.new("Couldn't create ReturnValueDefinition. Check that your information is correct.\n#{response}")
+      end
+
+      def self.delete(connection, itemdefuid,return_value_definition)
+        
+        # Deleting takes a while... up the timeout to 120 seconds temporarily
+        t = connection.timeout
+        connection.timeout = 120
+        connection.v3_delete("/#{AMEE_API_VERSION}/definitions/#{itemdefuid}/returnvalues/" + return_value_definition.uid)
+        connection.timeout = t
+      rescue
+        raise AMEE::BadData.new("Couldn't delete ReturnValueDefinition. Check that your information is correct.")
+      end
+
+    end
+
+  end
+
+end

data/lib/amee/v3.rb

@@ -0,0 +1,12 @@
+# Copyright (C) 2008-2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+AMEE_API_VERSION = '3.3'
+
+require 'amee/v3/meta_helper'
+require 'amee/v3/collection'
+require 'amee/v3/connection'
+require 'amee/v3/item_definition'
+require 'amee/v3/item_value_definition'
+require 'amee/v3/item_value_definition_list'
+require 'amee/v3/return_value_definition'

data/lib/amee.rb

@@ -1,3 +1,6 @@
+# Copyright (C) 2008-2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
 require 'rexml/document'
 require 'nokogiri'
 require 'active_support'
@@ -49,6 +52,7 @@ require 'amee/pager'
 require 'amee/item_definition'
 require 'amee/item_value_definition'
 require 'amee/user'
+require 'amee/v3'
 
 class Date
   def amee1_date

data/rails/init.rb

@@ -1,3 +1,6 @@
+# Copyright (C) 2008-2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
 require 'amee'
 require 'amee/rails'
 

data/spec/amee_spec.rb

@@ -1,3 +1,6 @@
+# Copyright (C) 2008-2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
 require File.dirname(__FILE__) + '/spec_helper.rb'
 
 describe "AMEE module" do

data/spec/cache_spec.rb

@@ -1,3 +1,6 @@
+# Copyright (C) 2008-2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
 require File.dirname(__FILE__) + '/spec_helper.rb'
 require 'ostruct'
 

data/spec/connection_spec.rb

@@ -1,3 +1,6 @@
+# Copyright (C) 2008-2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
 require File.dirname(__FILE__) + '/spec_helper.rb'
 
 describe AMEE::Connection do