converse 1.0.6 → 1.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. data/README.md +107 -7
  2. data/lib/converse/version.rb +1 -1
  3. metadata +3 -3
data/README.md CHANGED
@@ -1,6 +1,27 @@
1
1
  # Converse
2
2
 
3
- TODO: Write a gem description
3
+ Converse is an architectural / design tool that facilitates dependency inversion, seperation of concerns and decoupling
4
+ by providing a conversation-based API boundary.
5
+
6
+ Brokers know how to talk the language of a provider, and converses with such a provider using Interactions.
7
+ Interactions discuss topics using technology specific conversations. Brokers speak two languages: the application's and
8
+ a provider's. A broker is taught how to speak a provider's language by defining a set of interactions, which
9
+ use provider-specific conversations to communicate. Responses from providers are processed in the interactions.
10
+ Each interaction can interpret a response in a provider-specific way and translate the response into the
11
+ application's domain language.
12
+
13
+ An application then relies on brokers to engage providers around topics, concerns and actions, by saying or asking and
14
+ receiving the interpreted responses.
15
+
16
+ Modeling API interaction this way decouples the application from the providers. The brokers are in essence adapters
17
+ that allow the creation of an application-specified API for interacting with providers, removing the application's
18
+ dependency on providers. The application only depends on the API it specifies, i.e. the language it wants to talk.
19
+
20
+ Brokers become plug-in adapters to providers and can be swapped out at will, provided they can speak the application's
21
+ language as well as the provider's language,. The set of interactions a broker is aware of specifies the API towards
22
+ the provider. The application specifies its API through a set of methods that ask brokers to act on its behalf.
23
+
24
+ Brokers can be chained for multiple translation / technology bridging.
4
25
 
5
26
  ## Installation
6
27
 
@@ -18,12 +39,91 @@ Or install it yourself as:
18
39
 
19
40
  ## Usage
20
41
 
21
- TODO: Write usage instructions here
42
+ In this example, a provider communicates RESTfully over HTTP. An application wants to talk with the provider,
43
+ without engaging in the details of setting up an HTML conversation, and without specifying URL details. Specifically,
44
+ the application wants to request a list of transactions from the RESTful transaction provider. The application might
45
+ want to swap the RESTful provider out for a SQL provider, or some other provider at some stage.
46
+
47
+ The application specifies the API it wants to talk, and teaches a broker how to discuss transactions:
48
+
49
+ class ApplicationApi < API
50
+ def get_transactions(client_id)
51
+ substance = { 'client_id' => client_id }
52
+ o = GetTransactions.new(@broker, substance)
53
+ o.discuss
54
+ end
55
+ end
56
+
57
+ The GetTransactions interaction faces towards the provider, and uses a TransactionTranslator to turn JSON responses
58
+ into a list of transactions that the application understands.
59
+
60
+ class GetTransactions < ProviderInteraction
61
+ def initialize(broker, substance)
62
+ discuss_with_broker_concerning(broker, "transactions")
63
+ about("<client_id>/transactions.json")
64
+ detailed_by(substance)
65
+ by_asking
66
+ end
67
+
68
+ def interpret_conversation(response)
69
+ return [] if response.code == '404'
70
+ TransactionTranslator::build_financial_entries_from(response)
71
+ end
72
+ end
73
+
74
+ Generically, the provider interaction knows how to say and ask the provider for information:
75
+
76
+ class ProviderInteraction < Interaction
77
+ def ask
78
+ @conversation.ask(broker.prepare_content(@concern, @action), broker.generate_parameters(@substance))
79
+ end
80
+
81
+ def say
82
+ @conversation.say(broker.prepare_content(@concern, @action), broker.generate_parameters(@substance))
83
+ end
84
+ end
85
+
86
+ The ProviderBroker is taught how to talk the provider's language by using an HTMLConversation:
87
+
88
+ class ProviderBroker < Broker
89
+ attr_accessor :host
90
+ attr_accessor :port
91
+ attr_accessor :username
92
+ attr_accessor :password
93
+
94
+ def initialize(host, port , username, password)
95
+ @version = "v1"
96
+ @host = host
97
+ @port = port
98
+ @username = username
99
+ @password = password
100
+ end
101
+
102
+ def broker_conversation(topic)
103
+ conversation = HTMLConversation.new(topic)
104
+ conversation.username = @username
105
+ conversation.password = @password
106
+ conversation
107
+ end
108
+
109
+ def open_topic(concern, action)
110
+ "https://#{@host}:#{@port}/" + concern + "/" + action
111
+ end
112
+
113
+ def prepare_content(concern, action)
114
+ "/" + concern + "/" + action;
115
+ end
116
+ end
117
+
118
+ The application, a dependency injector or a factory at some point decides to use the ProviderBroker to facilitate
119
+ interaction with the provider:
120
+
121
+ broker = ProviderBroker.new(@host, @port, @username, @password)
122
+ api = ApplicationApi.new(broker)
123
+ api.get_transactions('C0000001')
124
+
22
125
 
23
126
  ## Contributing
24
127
 
25
- 1. Fork it
26
- 2. Create your feature branch (`git checkout -b my-new-feature`)
27
- 3. Commit your changes (`git commit -am 'Added some feature'`)
28
- 4. Push to the branch (`git push origin my-new-feature`)
29
- 5. Create new Pull Request
128
+ 1. Please send me feedback by email on this project and ideas around improving the architectural facilities
129
+ provided by this gem.
@@ -1,3 +1,3 @@
1
1
  module Converse
2
- VERSION = "1.0.6"
2
+ VERSION = "1.0.7"
3
3
  end
metadata CHANGED
@@ -1,13 +1,13 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: converse
3
3
  version: !ruby/object:Gem::Version
4
- hash: 27
4
+ hash: 25
5
5
  prerelease:
6
6
  segments:
7
7
  - 1
8
8
  - 0
9
- - 6
10
- version: 1.0.6
9
+ - 7
10
+ version: 1.0.7
11
11
  platform: ruby
12
12
  authors:
13
13
  - Ernst van Graan