isbm_adaptor 1.0.rc8.5

data/README.md

@@ -0,0 +1,24 @@
+Assetricity ISBM-Adaptor Gem  
+![travis](https://travis-ci.org/assetricity/isbm_adaptor.png)
+
+Copyright 2013 Assetricity, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

data/lib/isbm_adaptor/channel.rb

@@ -0,0 +1,30 @@
+module IsbmAdaptor
+  class Channel
+    TYPES = ['Publication', 'Request']
+
+    attr_accessor :uri, :type, :description
+
+    # Creates a new Channel.
+    #
+    # @param uri [String] the channel URI
+    # @param type [String] the channel type, either 'Publication' or 'Request'
+    # @param description [String] the channel description
+    def initialize(uri, type, description)
+      @uri = uri.to_s
+      @type = type
+      @description = description.to_s unless description.nil?
+    end
+
+    # Creates a new Channel based on a hash.
+    #
+    # @options hash [String] :channel_uri the channel URI
+    # @options hash [String] :channel_type the channel type, either 'Publication' or 'Request'
+    # @options hash [String] :channel_description the channel description
+    def self.from_hash(hash)
+      uri = hash[:channel_uri]
+      type = hash[:channel_type]
+      description = hash[:channel_description]
+      new(uri, type, description)
+    end
+  end
+end

data/lib/isbm_adaptor/channel_management.rb

@@ -0,0 +1,83 @@
+require 'isbm_adaptor/service'
+require 'isbm_adaptor/channel'
+
+module IsbmAdaptor
+  class ChannelManagement
+    include IsbmAdaptor::Service
+
+    # Creates a new ISBM ChannelManagement client.
+    #
+    # @param endpoint [String] the SOAP endpoint URI
+    # @option options [Object] :logger (Rails.logger or $stdout) location where log should be output
+    # @option options [Boolean] :log (true) specify whether requests are logged
+    # @option options [Boolean] :pretty_print_xml (false) specify whether request and response XML are formatted
+    def initialize(endpoint, options = {})
+      options[:wsdl] = wsdl_dir + 'ISBMChannelManagementService.wsdl'
+      options[:endpoint] = endpoint
+      default_savon_options(options)
+      @client = Savon.client(options)
+    end
+
+    # Creates a new channel.
+    #
+    # @param uri [String] the channel URI
+    # @param type [Symbol] the channel type, either publication or request (symbol or titleized string)
+    # @param description [String] the channel description, defaults to nil
+    # @return [void]
+    # @raise [ArgumentError] if uri or type are nil/empty or type is not a valid Symbol
+    def create_channel(uri, type, description = nil)
+      validate_presence_of uri, 'Channel URI'
+      validate_presence_of type, 'Channel Type'
+      channel_type = type.to_s.downcase.capitalize
+      raise ArgumentError, "#{channel_type} is not a valid type. Must be either Publication or Request." unless IsbmAdaptor::Channel::TYPES.include?(channel_type)
+
+      message = { 'ChannelURI' => uri,
+                  'ChannelType' => channel_type }
+      message['ChannelDescription'] = description  unless description.nil?
+
+      @client.call(:create_channel, message: message)
+
+      return true
+    end
+
+    # Deletes the specified channel.
+    #
+    # @param uri [String] the channel URI
+    # @return [void]
+    # @raise [ArgumentError] if uri is nil/empty
+    def delete_channel(uri)
+      validate_presence_of uri, 'Channel URI'
+
+      @client.call(:delete_channel, message: { 'ChannelURI' => uri })
+
+      return true
+    end
+
+    # Gets information about the specified channel
+    #
+    # @param uri [String] the channel URI
+    # @return [Channel] the queried channel
+    # @raise [ArgumentError] if uri is nil/empty
+    def get_channel(uri)
+      validate_presence_of uri, 'Channel URI'
+
+      response = @client.call(:get_channel, message: { 'ChannelURI' => uri })
+
+      hash = response.to_hash[:get_channel_response][:channel]
+      IsbmAdaptor::Channel.from_hash(hash)
+    end
+
+    # Gets information about all channels
+    #
+    # @return [Array<Channel>] all channels on the ISBM
+    def get_channels
+      response = @client.call(:get_channels)
+
+      channels = response.to_hash[:get_channels_response][:channel]
+      channels = [channels].compact unless channels.is_a?(Array)
+      channels.map do |hash|
+        IsbmAdaptor::Channel.from_hash(hash)
+      end
+    end
+  end
+end

data/lib/isbm_adaptor/consumer_publication.rb

@@ -0,0 +1,95 @@
+require 'isbm_adaptor/service'
+require 'isbm_adaptor/message'
+
+module IsbmAdaptor
+  class ConsumerPublication
+    include IsbmAdaptor::Service
+
+    # Creates a new ISBM ConsumerPublication client.
+    #
+    # @param endpoint [String] the SOAP endpoint URI
+    # @option options [Object] :logger (Rails.logger or $stdout) location where log should be output
+    # @option options [Boolean] :log (true) specify whether requests are logged
+    # @option options [Boolean] :pretty_print_xml (false) specify whether request and response XML are formatted
+    def initialize(endpoint, options = {})
+      options[:wsdl] = wsdl_dir + 'ISBMConsumerPublicationService.wsdl'
+      options[:endpoint] = endpoint
+      default_savon_options(options)
+      @client = Savon.client(options)
+    end
+
+    # Opens a subscription session for a channel.
+    #
+    # @param topics [Array<String>] an array of topics
+    # @return [String] the session id
+    # @raise [ArgumentError] if uri or topics are nil/empty
+    def open_session(uri, topics, listener_uri = nil)
+      validate_presence_of uri, 'Channel URI'
+      validate_presence_of topics, 'Topics'
+
+      # Use Builder to generate XML body as we may have multiple Topic elements
+      xml = Builder::XmlMarkup.new
+      xml.isbm :ChannelURI, uri
+      topics.each do |topic|
+        xml.isbm :Topic, topic
+      end
+      xml.isbm :ListenerURI, listener_uri unless listener_uri.nil?
+
+      response = @client.call(:open_subscription_session, message: xml.target!)
+
+      response.to_hash[:open_subscription_session_response][:session_id].to_s
+    end
+
+    # Reads the first message after the specified last message in the message
+    # queue.
+    #
+    # @param session_id [String] the session id
+    # @param last_message_id [String] the id of the last message. When set to
+    #   nil, returns the first publication in the message queue
+    # @return [Message] first message after specified last message. nil if no message.
+    # @raise [ArgumentError] if session_id is nil/empty
+    def read_publication(session_id, last_message_id)
+      validate_presence_of session_id, 'Session Id'
+
+      message = { 'SessionID' => session_id }
+      message['LastMessageID'] = last_message_id unless last_message_id.nil?
+
+      response = @client.call(:read_publication, message: message)
+
+      hash = response.to_hash[:read_publication_response][:publication_message]
+      message = nil
+      if hash
+        id = hash[:message_id]
+        topics = hash[:topic]
+
+        # Extract the child element in message content
+        # //isbm:ReadPublicationResponse/isbm:PublicationMessage/isbm:MessageContent/child::*
+        content = response.doc.root.element_children.first.element_children.first.element_children.first.element_children[1].element_children.first
+
+        # Retain any ancestor namespaces in case they are applicable for the element and/or children
+        # This is because content#to_xml does not output ancestor namespaces
+        content.namespaces.each do |key, value|
+          prefix = key.gsub(/xmlns:?/, '')
+          prefix = nil if prefix.empty?
+          content.add_namespace_definition(prefix, value)
+        end
+
+        message = IsbmAdaptor::Message.new(id, content, topics)
+      end
+      message
+    end
+
+    # Closes a subscription session.
+    #
+    # @param session_id [String] the session id
+    # @return [void]
+    # @raise [ArgumentError] if session_id is nil/empty
+    def close_session(session_id)
+      validate_presence_of session_id, 'Session Id'
+
+      @client.call(:close_subscription_session, message: { 'SessionID' => session_id })
+
+      return true
+    end
+  end
+end

data/lib/isbm_adaptor/duration.rb

@@ -0,0 +1,69 @@
+module IsbmAdaptor
+  class Duration
+    attr_accessor :years, :months, :days, :hours, :minutes, :seconds
+
+    # Creates a new Duration based on specified time components.
+    #
+    # @option duration [Numeric] :years duration in years
+    # @option duration [Numeric] :months duration in months
+    # @option duration [Numeric] :days duration in days
+    # @option duration [Numeric] :hours duration in hours
+    # @option duration [Numeric] :minutes duration in minutes
+    # @option duration [Numeric] :seconds duration in seconds
+    def initialize(duration)
+      duration.keys.each do |key|
+        raise ArgumentError.new "Invalid key: #{key}" unless VALID_SYMBOLS.include?(key)
+      end
+
+      duration.each do |key, value|
+        raise ArgumentError.new "Value for #{key} cannot be less than 0" if value < 0
+      end
+
+      @years = duration[:years]
+      @months = duration[:months]
+      @days = duration[:days]
+      @hours = duration[:hours]
+      @minutes = duration[:minutes]
+      @seconds = duration[:seconds]
+    end
+
+    # @return [String] ISO 8601 formatted duration
+    def to_s
+      date = []
+      date << "#{@years}Y" unless @years.nil?
+      date << "#{@months}M" unless @months.nil?
+      date << "#{@days}D" unless @days.nil?
+
+      time = []
+      time << "#{@hours}H" unless @hours.nil?
+      time << "#{@minutes}M" unless @minutes.nil?
+      time << "#{@seconds}S" unless @seconds.nil?
+
+      result = nil
+
+      if !date.empty? || !time.empty?
+        result = 'P'
+        result += date.join unless date.empty?
+        result += 'T' + time.join unless time.empty?
+      end
+
+      result
+    end
+
+    # @return [Hash] all specified time components
+    def to_hash
+      hash = {}
+      hash.merge!(years: @years) if @years
+      hash.merge!(months: @months) if @months
+      hash.merge!(days: @days) if @days
+      hash.merge!(hours: @hours) if @hours
+      hash.merge!(minutes: @minutes) if @minutes
+      hash.merge!(seconds: @seconds) if @seconds
+      hash
+    end
+
+    private
+
+    VALID_SYMBOLS = [:years, :months, :days, :hours, :minutes, :seconds]
+  end
+end

data/lib/isbm_adaptor/message.rb

@@ -0,0 +1,20 @@
+module IsbmAdaptor
+  class Message
+    attr_accessor :id, :content, :topics
+
+    # Creates a new ISBM Message container.
+    #
+    # @param id [String] message id
+    # @param content [String] XML content
+    # @param topics [Array<String>] collection of topics
+    def initialize(id, content, topics)
+      @id = id.to_s
+      @content = content
+      if (topics.is_a?(Array))
+        @topics.each { |t| t.to_s }
+      else
+        @topics = [topics.to_s]
+      end
+    end
+  end
+end

data/lib/isbm_adaptor/provider_publication.rb

@@ -0,0 +1,94 @@
+require 'isbm_adaptor/service'
+require 'isbm_adaptor/duration'
+
+module IsbmAdaptor
+  class ProviderPublication
+    include IsbmAdaptor::Service
+
+    # Creates a new ISBM ProviderPublication client.
+    #
+    # @param endpoint [String] the SOAP endpoint URI
+    # @option options [Object] :logger (Rails.logger or $stdout) location where log should be output
+    # @option options [Boolean] :log (true) specify whether requests are logged
+    # @option options [Boolean] :pretty_print_xml (false) specify whether request and response XML are formatted
+    def initialize(endpoint, options = {})
+      options[:wsdl] = wsdl_dir + 'ISBMProviderPublicationService.wsdl'
+      options[:endpoint] = endpoint
+      default_savon_options(options)
+      @client = Savon.client(options)
+    end
+
+    # Opens a publication session for a channel.
+    #
+    # @param [String] uri the channel URI
+    # @return [String] the session id
+    # @raise [ArgumentError] if uri is nil/empty
+    def open_session(uri)
+      validate_presence_of uri, 'Channel URI'
+
+      response = @client.call(:open_publication_session, message: { 'ChannelURI' => uri })
+
+      response.to_hash[:open_publication_session_response][:session_id].to_s
+    end
+
+    # Posts a publication message.
+    #
+    # @param content [String] a valid XML string as message contents
+    # @param topics [Array<String>, String] a collection of topics or single topic
+    # @param expiry [Duration] when the message should expire
+    # @return [String] the message id
+    # @raise [ArgumentError] if session_id, content, topics is nil/empty or content is not valid XML
+    def post_publication(session_id, content, topics, expiry = nil)
+      validate_presence_of session_id, 'Session Id'
+      validate_presence_of content, 'Content'
+      validate_presence_of topics, 'Topics'
+      validate_xml content
+
+      topics = [topics] unless topics.is_a?(Array)
+
+      # Use Builder to generate XML body as we need to concatenate XML message content
+      xml = Builder::XmlMarkup.new
+      xml.isbm :SessionID, session_id
+      xml.isbm :MessageContent do
+        xml << content
+      end
+      topics.each do |topic|
+        xml.isbm :Topic, topic
+      end
+      duration = expiry.to_s
+      xml.isbm :Expiry, duration unless duration.nil?
+
+      response = @client.call(:post_publication, message: xml.target!)
+
+      response.to_hash[:post_publication_response][:message_id].to_s
+    end
+
+    # Expires a posted publication message.
+    #
+    # @param session_id [String] the session id used to post the publication
+    # @param message_id [String] the message id received after posting the publication
+    # @return [void]
+    # @raise [ArgumentError] if session_id or message_id are nil/empty
+    def expire_publication(session_id, message_id)
+      validate_presence_of session_id, 'Session Id'
+      validate_presence_of message_id, 'Message Id'
+
+      @client.call(:expire_publication, message: { 'SessionID' => session_id, 'MessageID' => message_id })
+
+      return true
+    end
+
+    # Closes a publication session.
+    #
+    # @param session_id [String] the session id
+    # @return [void]
+    # @raise [ArgumentError] if session_id is nil/empty
+    def close_session(session_id)
+      validate_presence_of session_id, 'Session Id'
+
+      @client.call(:close_publication_session, message: { 'SessionID' => session_id })
+
+      return true
+    end
+  end
+end

data/lib/isbm_adaptor/service.rb

@@ -0,0 +1,42 @@
+module IsbmAdaptor
+  module Service
+    # Indicates the directory of the ISBM WSDL files
+    #
+    # @return [String] directory of ISBM WSDL files
+    def wsdl_dir
+      File.expand_path(File.dirname(__FILE__)) + '/../../wsdls/'
+    end
+
+    # Sets default values for certain Savon options.
+    #
+    # @param options [Hash] the options to set defaults on
+    # @return [Hash] options hash with defaults set
+    def default_savon_options(options)
+      options[:logger] = Rails.logger if defined?(Rails)
+      options[:log] ||= true
+      options[:pretty_print_xml] ||= false
+    end
+
+    # Validates the presence of the passed value.
+    #
+    # @param value [Object] presence of object to validate
+    # @param name [String] name of value to include in error message if not present
+    # @return [void]
+    # @raises [ArgumentError] if value is not present
+    def validate_presence_of(value, name)
+      if value.blank?
+        raise ArgumentError, "#{name} must be specified"
+      end
+    end
+
+    # Validates the well formedness of the XML string and raises an error if
+    # any errors are encountered.
+    #
+    # @param xml [String] the XML string to parse
+    # @return [void]
+    def validate_xml(xml)
+      doc = Nokogiri.XML(xml)
+      raise ArgumentError, "XML is not well formed: #{xml}" unless doc.errors.empty?
+    end
+  end
+end

data/lib/isbm_adaptor/version.rb

@@ -0,0 +1,3 @@
+module IsbmAdaptor
+  VERSION = '1.0.rc8.5'
+end

data/lib/isbm_adaptor.rb

@@ -0,0 +1,10 @@
+require 'active_support/core_ext/object/blank'
+require 'isbm_adaptor/version'
+require 'savon'
+
+module IsbmAdaptor
+  autoload :ChannelManagement, 'isbm_adaptor/channel_management'
+  autoload :ProviderPublication, 'isbm_adaptor/provider_publication'
+  autoload :ConsumerPublication, 'isbm_adaptor/consumer_publication'
+  autoload :Duration, 'isbm_adaptor/duration'
+end