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.
- data/README.md +107 -7
- data/lib/converse/version.rb +1 -1
- metadata +3 -3
data/README.md
CHANGED
@@ -1,6 +1,27 @@
|
|
1
1
|
# Converse
|
2
2
|
|
3
|
-
|
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
|
-
|
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.
|
26
|
-
|
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.
|
data/lib/converse/version.rb
CHANGED
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:
|
4
|
+
hash: 25
|
5
5
|
prerelease:
|
6
6
|
segments:
|
7
7
|
- 1
|
8
8
|
- 0
|
9
|
-
-
|
10
|
-
version: 1.0.
|
9
|
+
- 7
|
10
|
+
version: 1.0.7
|
11
11
|
platform: ruby
|
12
12
|
authors:
|
13
13
|
- Ernst van Graan
|