converse 1.0.23 → 1.0.24

data/README.md

@@ -1,12 +1,13 @@
 # Converse
 
-Converse is an architectural / design tool that facilitates dependency inversion, seperation of concerns and decoupling
+Converse is an architectural / design tool that facilitates dependency inversion, separation of concerns and decoupling
 by providing a conversation-based API boundary.
 
 Brokers know how to talk the language of a provider, and converses with such a provider using Interactions.
 Interactions discuss topics using technology specific conversations. Brokers speak two languages: the application's and
 a provider's. A broker is taught how to speak a provider's language by defining a set of interactions, which
-use provider-specific conversations to communicate. Responses from providers are processed in the interactions.
+use provider-specific conversations to communicate. Responses from providers are processed / translated in the
+interactions. Formatting of responses and error handling are also processed in the interactions.
 Each interaction can interpret a response in a provider-specific way and translate the response into the
 application's domain language.
 
@@ -46,9 +47,9 @@ want to swap the RESTful provider out for a SQL provider, or some other provider
 
 The application specifies the API it wants to talk, and teaches a broker how to discuss transactions:
 
-    class ApplicationApi < API
+    class ApplicationApi < Converse::API
       def get_transactions(client_id)
-        substance = { 'client_id' => client_id }
+        substance = { :client_id => client_id }
         o = GetTransactions.new(@broker, substance)
         o.discuss
       end
@@ -57,8 +58,9 @@ The application specifies the API it wants to talk, and teaches a broker how to
 The GetTransactions interaction faces towards the provider, and uses a TransactionTranslator to turn JSON responses
 into a list of transactions that the application understands.
 
-    class GetTransactions < ProviderInteraction
+    class GetTransactions < Converse::Interaction
       def initialize(broker, substance)
+        ensure_that(substance).includes [:client_id]
         ask_broker(broker).concerning("transactions").about("<client_id>/transactions.json").detailed_by(substance)
       end
 
@@ -80,7 +82,27 @@ Generically, the provider interaction knows how to say and ask the provider for
       end
     end
 
-The ProviderBroker is taught how to talk the provider's language by using an HTMLConversation:
+The RESTInteraction class provides some additional interpretation of responses. Interactions can rely on the
+RESTInteraction to call handle_error if "200 OK" is not received, and a formatting hook is provided:
+
+    class GetRevisions < Converse::RESTInteraction
+      def initialize(broker, substance)
+        ensure_that(substance).includes [:server]
+        ask_broker(broker).concerning("get_revision_list").about(substance)
+      end
+
+      def format_response(response_body)
+        RevisionFormatter::format_revisions_for_html(JSON.parse(response_body))
+      end
+
+      def handle_error!(response)
+        raise RuntimeError.new "#{response.code}, #{response.body}"
+      end
+    end
+
+The ProviderBroker is taught how to talk the provider's language by using an HTMLConversation (or a technology specific
+conversation, e.g. SQL, Redis, etc.). The broker provides the mapping of concerns, actions and detail (substance) to the
+technology / domain specific format:
 
     class ProviderBroker < Broker
       attr_accessor :host
@@ -122,5 +144,5 @@ interaction with the provider:
 
 ## Contributing
 
-1. Please send me feedback by email on this project and ideas around improving the architectural facilities
+1. Please send me feedback by email (ernst.van.graan@hetzner.co.za) on this project and ideas around improving the architectural facilities
 provided by this gem.

data/lib/converse/version.rb

@@ -1,3 +1,3 @@
 module Converse
-  VERSION = "1.0.23"
+  VERSION = "1.0.24"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: converse
 version: !ruby/object:Gem::Version 
-  hash: 57
+  hash: 39
   prerelease: 
   segments: 
   - 1
   - 0
-  - 23
-  version: 1.0.23
+  - 24
+  version: 1.0.24
 platform: ruby
 authors: 
 - Ernst van Graan
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-10-30 00:00:00 Z
+date: 2012-10-31 00:00:00 Z
 dependencies: []
 
 description: Converse provides Broker/Translator classes to facilitate communication across an API by means of conversations