isbm_adaptor 1.0.rc8.7 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7ec831745863947e859edd665925317d42dbf1b7
-  data.tar.gz: 686b8452491a4b96b490af5f271283e11031f397
+  metadata.gz: 25b4c4ff55a4d6c03a3a75fd9f3a1810697b512d
+  data.tar.gz: e321d14733e13e32b151b7bebc454f45d3ef9d34
 SHA512:
-  metadata.gz: 7a204979a05e7f25d2567de9c38807969900544c2fd9b8f37e9be7acdd57f91ae137f56a3bef269281b4a7a169adbfd57c5446add2c282ea94f9cbac8bd1c7f1
-  data.tar.gz: 3b9290ce1d6100f169fa6ff9b9dfd5060444063fabc6833f8ab8435dea7c547c43031506e391555a13a137b47d5bb6aab95384580aa2d8d1e7b112ed6aa815be
+  metadata.gz: b2616d0904f557ed1838a9278d234ecb88215f18047a0259f0f0e22f3764a22c3966876c7dab35ca88141d4a80a3e94c3bb9400561b72ea09591e350341c0beb
+  data.tar.gz: 5556e2d0d28f1bf0a664cb3e33536a1a4c4f03add822b0925e76f8680c3ebc20cecc74ffc4ac16827c2507a831544a72a96c3c022408e28c463faacf6ed6a7a8

data/lib/isbm_adaptor/channel_management.rb

@@ -6,11 +6,12 @@ module IsbmAdaptor
     # Creates a new ISBM ChannelManagement client.
     #
     # @param endpoint [String] the SOAP endpoint URI
+    # @option options [Array<String>] :wsse_auth username and password, i.e. [username, password]
     # @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 = {})
-      super('ISBMChannelManagementService.wsdl', endpoint, options)
+      super('ChannelManagementService.wsdl', endpoint, options)
     end
 
     # Creates a new channel.
@@ -18,23 +19,61 @@ module IsbmAdaptor
     # @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
+    # @param tokens [Hash] username password pairs, e.g. {'u1' => 'p1', 'u2' => 'p2'}
     # @return [void]
     # @raise [ArgumentError] if uri or type are blank or type is not a valid Symbol
-    def create_channel(uri, type, description = nil)
+    def create_channel(uri, type, description = nil, tokens = {})
       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)
+      validate_inclusion_in channel_type, IsbmAdaptor::Channel::TYPES, 'Channel Type'
 
       message = { 'ChannelURI' => uri,
                   'ChannelType' => channel_type }
-      message['ChannelDescription'] = description  unless description.nil?
+      message['ChannelDescription'] = description unless description.nil?
+      message['SecurityToken'] = security_token_hash(tokens) if tokens.any?
 
       @client.call(:create_channel, message: message)
 
       return true
     end
 
+    # Adds security tokens to a channel.
+    #
+    # @param uri [String] the channel URI
+    # @param tokens [Hash] username password pairs, e.g. {'u1' => 'p1', 'u2' => 'p2'}
+    # @return [void]
+    # @raise [ArgumentError] if uri is blank or no tokens are provided
+    def add_security_tokens(uri, tokens = {})
+      validate_presence_of uri, 'Channel URI'
+      validate_presence_of tokens, 'Security Tokens'
+
+      message = { 'ChannelURI' => uri,
+                  'SecurityToken' => security_token_hash(tokens) }
+
+      @client.call(:add_security_tokens, message: message)
+
+      return true
+    end
+
+    # Removes security tokens from a channel.
+    #
+    # @param uri [String] the channel URI
+    # @param tokens [Hash] username password pairs, e.g. {'u1' => 'p1', 'u2' => 'p2'}
+    # @return [void]
+    # @raise [ArgumentError] if uri is blank or no tokens are provided
+    def remove_security_tokens(uri, tokens = {})
+      validate_presence_of uri, 'Channel URI'
+      validate_presence_of tokens, 'Security Tokens'
+
+      message = { 'ChannelURI' => uri,
+                  'SecurityToken' => security_token_hash(tokens) }
+
+      @client.call(:remove_security_tokens, message: message)
+
+      return true
+    end
+
     # Deletes the specified channel.
     #
     # @param uri [String] the channel URI
@@ -48,25 +87,27 @@ module IsbmAdaptor
       return true
     end
 
-    # Gets information about the specified channel
+    # Gets information about the specified channel.
     #
     # @param uri [String] the channel URI
+    # @yield locals local options, including :wsse_auth
     # @return [Channel] the queried channel
     # @raise [ArgumentError] if uri is blank
-    def get_channel(uri)
+    def get_channel(uri, &block)
       validate_presence_of uri, 'Channel URI'
 
-      response = @client.call(:get_channel, message: { 'ChannelURI' => uri })
+      response = @client.call(:get_channel, message: { 'ChannelURI' => uri }, &block)
 
       hash = response.to_hash[:get_channel_response][:channel]
       IsbmAdaptor::Channel.from_hash(hash)
     end
 
-    # Gets information about all channels
+    # Gets information about all channels.
     #
-    # @return [Array<Channel>] all channels on the ISBM
-    def get_channels
-      response = @client.call(:get_channels)
+    # @yield locals local options, including :wsse_auth
+    # @return [Array<Channel>] all authorized channels on the ISBM
+    def get_channels(&block)
+      response = @client.call(:get_channels, {}, &block)
 
       channels = response.to_hash[:get_channels_response][:channel]
       channels = [channels].compact unless channels.is_a?(Array)
@@ -74,5 +115,20 @@ module IsbmAdaptor
         IsbmAdaptor::Channel.from_hash(hash)
       end
     end
+
+    private
+    # Returns tokens mapped to wsse:UsernameToken hash.
+    def security_token_hash(tokens)
+      wsse = Akami.wsse
+      tokens.map do |username, password|
+        wsse.credentials(username, password)
+        # Extract the UsernameToken element
+        username_token = wsse.send(:wsse_username_token)['wsse:Security']
+        # Restore the wsse namespace
+        ns = {'xmlns:wsse' => Akami::WSSE::WSE_NAMESPACE}
+        username_token[:attributes!]['wsse:UsernameToken'].merge!(ns)
+        username_token
+      end
+    end
   end
 end

data/lib/isbm_adaptor/client.rb

@@ -18,13 +18,34 @@ module IsbmAdaptor
 
     # Validates the presence of the passed value.
     #
-    # @param value [Object] presence of object to validate
+    # @param value [Object] object to validate presence
     # @param name [String] name of value to include in error message if not present
     # @return [void]
     # @raise [ArgumentError] if value is not present
     def validate_presence_of(value, name)
-      if value.blank?
-        raise ArgumentError, "#{name} must be specified"
+      if value.respond_to?(:each)
+        value.each do |v|
+          if v.blank?
+            raise ArgumentError, "Values in #{name} must not be blank"
+          end
+        end
+      else
+        if value.blank?
+          raise ArgumentError, "#{name} must not be blank"
+        end
+      end
+    end
+
+    # Validates the inclusion of the passed value in a given set.
+    #
+    # @param value [Object] object to validate inclusion
+    # @param set [Array] set to validate inclusion
+    # @param name [String] name of value to include in error message if not present
+    # @return [void]
+    # @raise [ArgumentError] if value is not included
+    def validate_inclusion_in(value, set, name)
+      unless set.include?(value)
+        raise ArgumentError, "#{value} is not a valid #{name}. Must be #{set[0..-2].join(', ')} or #{set.last}."
       end
     end
 
@@ -45,12 +66,12 @@ module IsbmAdaptor
     def extract_message(response)
       # Extract the message element
       # e.g. /Envelope/Body/ReadPublicationResponse/PublicationMessage
-      message = response.doc.root.element_children.first.element_children.first.element_children.first
+      message = response.doc.root.first_element_child.first_element_child.first_element_child
 
       return nil unless message
 
       id = message.element_children[0].text
-      content = message.element_children[1].element_children.first
+      content = message.element_children[1].first_element_child
       topics = message.element_children[2..-1].map {|e| e.text}
 
       # Retain any ancestor namespaces in case they are applicable for the element
@@ -59,9 +80,9 @@ module IsbmAdaptor
       # There may be unnecessary namespaces carried across (e.g. ISBM, SOAP), but we
       # can't tell if the content uses them without parsing the content itself.
       content.namespaces.each do |key, value|
-        prefix = key.gsub(/xmlns:?/, '')
-        prefix = nil if prefix.empty?
-        content.add_namespace_definition(prefix, value)
+        # Don't replace default namespace if it already exists
+        next if key == 'xmlns' && content['xmlns']
+        content[key] = value
       end
 
       # Wrap content in a separate Nokogiri document. This allows the ability to

data/lib/isbm_adaptor/consumer_publication.rb

@@ -6,23 +6,31 @@ module IsbmAdaptor
     # Creates a new ISBM ConsumerPublication client.
     #
     # @param endpoint [String] the SOAP endpoint URI
+    # @option options [Array<String>] :wsse_auth username and password, i.e. [username, password]
     # @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 = {})
-      super('ISBMConsumerPublicationService.wsdl', endpoint, options)
+      super('ConsumerPublicationService.wsdl', endpoint, options)
     end
 
     # Opens a subscription session for a channel.
     #
     # @param uri [String] the channel URI
-    # @param topics [Array<String>] an array of topics
-    # @param listener_uri [String] the URI for notification callbacks
+    # @param topics [Array<String>, String] a collection of topics or single topic
+    # @param listener_url [String] the URL for notification callbacks
+    # @param xpath_expression [String] the XPath filter expression
+    # @param xpath_namespaces [Array<Hash>] the prefixes and namespaces used by the XPath expression. The hash key
+    #   represents the namespace prefix while the value represents the namespace name. For example,
+    #   ["xs" => "http://www.w3.org/2001/XMLSchema", "isbm" => "http://www.openoandm.org/xml/ISBM/"]
     # @return [String] the session id
     # @raise [ArgumentError] if uri or topics are blank
-    def open_session(uri, topics, listener_uri = nil)
+    def open_session(uri, topics, listener_url = nil, xpath_expression = nil, xpath_namespaces = [])
       validate_presence_of uri, 'Channel URI'
       validate_presence_of topics, 'Topics'
+      validate_presence_of xpath_expression, 'XPath Expression' if xpath_namespaces.present?
+
+      topics = [topics].flatten
 
       # Use Builder to generate XML body as we may have multiple Topic elements
       xml = Builder::XmlMarkup.new
@@ -30,31 +38,46 @@ module IsbmAdaptor
       topics.each do |topic|
         xml.isbm :Topic, topic
       end
-      xml.isbm :ListenerURI, listener_uri unless listener_uri.nil?
+      xml.isbm :ListenerURL, listener_url unless listener_url.nil?
+      xml.isbm :XPathExpression, xpath_expression unless xpath_expression.nil?
+      xpath_namespaces.each do |prefix, name|
+        xml.isbm :XPathNamespace do
+          xml.isbm :NamespacePrefix, prefix
+          xml.isbm :NamespaceName, name
+        end
+      end
 
       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.
+    # Reads the first message, if any, in the session 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.
+    # @return [Message] first message in session queue. nil if no message.
     # @raise [ArgumentError] if session_id is blank
-    def read_publication(session_id, last_message_id)
+    def read_publication(session_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)
+      response = @client.call(:read_publication, message: { 'SessionID' => session_id })
 
       extract_message(response)
     end
 
+    # Removes the first message, if any, in the session queue.
+    #
+    # @param session_id [String] the session id
+    # @return [void]
+    # @raise [ArgumentError] if session_id is blank
+    def remove_publication(session_id)
+      validate_presence_of session_id, 'Session Id'
+
+      @client.call(:remove_publication, message: { 'SessionID' => session_id })
+
+      return true
+    end
+
     # Closes a subscription session.
     #
     # @param session_id [String] the session id

data/lib/isbm_adaptor/consumer_request.rb

@@ -6,25 +6,26 @@ module IsbmAdaptor
     # Creates a new ISBM ConsumerRequest client.
     #
     # @param endpoint [String] the SOAP endpoint URI
+    # @option options [Array<String>] :wsse_auth username and password, i.e. [username, password]
     # @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 = {})
-      super('ISBMConsumerRequestService.wsdl', endpoint, options)
+      super('ConsumerRequestService.wsdl', endpoint, options)
     end
 
     # Opens a consumer request session for a channel for posting requests and
     # reading responses.
     #
     # @param uri [String] the channel URI
-    # @param listener_uri [String] the URI for notification callbacks
+    # @param listener_url [String] the URL for notification callbacks
     # @return [String] the session id
     # @raise [ArgumentError] if uri is blank
-    def open_session(uri, listener_uri = nil)
+    def open_session(uri, listener_url = nil)
       validate_presence_of uri, 'Channel URI'
 
       message = { 'ChannelURI' => uri }
-      message['ListenerURI'] = listener_uri if listener_uri
+      message['ListenerURL'] = listener_url if listener_url
 
       response = @client.call(:open_consumer_request_session, message: message)
 
@@ -36,10 +37,11 @@ module IsbmAdaptor
     # @param session_id [String] the session id
     # @param content [String] a valid XML string as message contents
     # @param topic [String] the topic
+    # @param expiry [Duration] when the message should expire
     # @return [String] the request message id
     # @raise [ArgumentError] if session_id, content or topics are blank, or
     #   content is not valid XML
-    def post_request(session_id, content, topic)
+    def post_request(session_id, content, topic, expiry = nil)
       validate_presence_of session_id, 'Session Id'
       validate_presence_of content, 'Content'
       validate_presence_of topic, 'Topic'
@@ -52,12 +54,29 @@ module IsbmAdaptor
         xml << content
       end
       xml.isbm :Topic, topic
+      duration = expiry.to_s
+      xml.isbm :Expiry, duration unless duration.nil?
 
       response = @client.call(:post_request, message: xml.target!)
 
       response.to_hash[:post_request_response][:message_id].to_s
     end
 
+    # Expires a posted request message.
+    #
+    # @param session_id [String] the session id used to post the request
+    # @param message_id [String] the message id received after posting the request
+    # @return [void]
+    # @raise [ArgumentError] if session_id or message_id are blank
+    def expire_request(session_id, message_id)
+      validate_presence_of session_id, 'Session Id'
+      validate_presence_of message_id, 'Message Id'
+
+      @client.call(:expire_request, message: { 'SessionID' => session_id, 'MessageID' => message_id })
+
+      return true
+    end
+
     # Returns the first response message, if any, in the message queue
     # associated with the request.
     #

data/lib/isbm_adaptor/provider_publication.rb

@@ -7,11 +7,12 @@ module IsbmAdaptor
     # Creates a new ISBM ProviderPublication client.
     #
     # @param endpoint [String] the SOAP endpoint URI
+    # @option options [Array<String>] :wsse_auth username and password, i.e. [username, password]
     # @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 = {})
-      super('ISBMProviderPublicationService.wsdl', endpoint, options)
+      super('ProviderPublicationService.wsdl', endpoint, options)
     end
 
     # Opens a publication session for a channel.

data/lib/isbm_adaptor/provider_request.rb

@@ -6,24 +6,32 @@ module IsbmAdaptor
     # Creates a new ISBM ProviderRequest client.
     #
     # @param endpoint [String] the SOAP endpoint URI
+    # @option options [Array<String>] :wsse_auth username and password, i.e. [username, password]
     # @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 = {})
-      super('ISBMProviderRequestService.wsdl', endpoint, options)
+      super('ProviderRequestService.wsdl', endpoint, options)
     end
 
     # Opens a provider request session for a channel for reading requests and
     # posting responses.
     #
     # @param uri [String] the channel URI
-    # @param topics [Array<String>] an array of topics
-    # @param listener_uri [String] the URI for notification callbacks
+    # @param topics [Array<String>, String] a collection of topics or single topic
+    # @param listener_url [String] the URL for notification callbacks
+    # @param xpath_expression [String] the XPath filter expression
+    # @param xpath_namespaces [Array<Hash>] the prefixes and namespaces used by the XPath expression. The hash key
+    #   represents the namespace prefix while the value represents the namespace name. For example,
+    #   ["xs" => "http://www.w3.org/2001/XMLSchema", "isbm" => "http://www.openoandm.org/xml/ISBM/"]
     # @return [String] the session id
     # @raise [ArgumentError] if uri or topics are blank
-    def open_session(uri, topics, listener_uri = nil)
+    def open_session(uri, topics, listener_url = nil, xpath_expression = nil, xpath_namespaces = [])
       validate_presence_of uri, 'Channel URI'
       validate_presence_of topics, 'Topics'
+      validate_presence_of xpath_expression, 'XPath Expression' if xpath_namespaces.present?
+
+      topics = [topics].flatten
 
       # Use Builder to generate XML body as we may have multiple Topic elements
       xml = Builder::XmlMarkup.new
@@ -31,7 +39,14 @@ module IsbmAdaptor
       topics.each do |topic|
         xml.isbm :Topic, topic
       end
-      xml.isbm :ListenerURI, listener_uri unless listener_uri.nil?
+      xml.isbm :ListenerURL, listener_url unless listener_url.nil?
+      xml.isbm :XPathExpression, xpath_expression unless xpath_expression.nil?
+      xpath_namespaces.each do |prefix, name|
+        xml.isbm :XPathNamespace do
+          xml.isbm :NamespacePrefix, prefix
+          xml.isbm :NamespaceName, name
+        end
+      end
 
       response = @client.call(:open_provider_request_session, message: xml.target!)
 

data/lib/isbm_adaptor/version.rb

@@ -1,4 +1,4 @@
 module IsbmAdaptor
   # Version should match the ISBM spec version, with a patch level
-  VERSION = '1.0.rc8.7'
+  VERSION = '1.0.0'
 end