Skip to content

Commit 53f9945

Browse files
maben-mwmaben-mw
committed
Version 0.3.3
1 parent 299bd51 commit 53f9945

31 files changed

+1271
-349
lines changed

‎.github/workflows/pages.yaml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
name: Generate Documentation and Publish to Pages
2+
on:
3+
push:
4+
branches:
5+
- main
6+
jobs:
7+
pages:
8+
name: Generate Documentation and Publish to Pages
9+
runs-on: ubuntu-latest
10+
steps:
11+
- name: Check out repository
12+
uses: actions/checkout@v2
13+
- uses: actions/setup-python@v3
14+
with:
15+
python-version: '3.9'
16+
- name: Install Sphinx Python Dependencies
17+
run: pip install -r requirements.txt
18+
working-directory: Documentation
19+
- name: Build Documentation
20+
run: make html
21+
working-directory: Documentation
22+
- name: Deploy Documentation to Pages
23+
uses: peaceiris/actions-gh-pages@v3
24+
with:
25+
github_token: ${{ secrets.GITHUB_TOKEN }}
26+
publish_dir: ./Documentation/_build/html

‎Documentation/MATLABInterface.md‎

Lines changed: 132 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -27,28 +27,110 @@ When working with `rabbitmq.Producer` and `rabbitmq.Consumer` in MATLAB, various
2727
connection properties need to be specified. These can be specified with the help
2828
of the `rabbitmq.ConnectorProperties` class or using YAML configuration files.
2929

30-
#### `rabbitmq.ConnectorProperties`
31-
`rabbitmq.ConnectorProperties` takes various Name-Value pairs as inputs. All
32-
options are optional, if not specified their default value is used.
33-
34-
|Property Name | Default Value | Description |
35-
|-------------------|---------------|---------------------------------------|
36-
|**'host'** | 'localhost' | Hostname or IP of the RabbitMQ Server |
37-
|**'port'** | 5672 | Port the RabbitMQ Server runs on |
38-
|**'virtualhost'** | '/' | RabbitMQ Virtual Host |
39-
|**'exchange'** | 'amq.topic' | Exchange to work with on RabbitMQ |
40-
|**'queuename'** | 'RabbitMQ' | Name of the Queue on RabbitMQ Server |
41-
|**'username'** | 'guest' | RabbitMQ username |
42-
|**'password'** | 'guest' | RabbitMQ password |
43-
|**'routingkey'** | 'test-topic' | Routing key to subscribe to or poll on - only used for Consumer, when working with Producer the routing key is specified on a per message basis when publishing a message |
44-
45-
For example:
30+
#### rabbitmq.ConnectorProperties class
31+
32+
**rabbitmq.ConnectorProperties** has various properties:
33+
34+
:host: Hostname or IP of the RabbitMQ Server.\
35+
*Default:* `"localhost"`
36+
:port: Port the RabbitMQ Server runs on.\
37+
*Default:* `5672`
38+
:virtualhost: RabbitMQ Virtual Host.\
39+
*Default:* `"/"`
40+
:exchange: Exchange to work with on RabbitMQ.\
41+
*Default:* Default `rabbitmq.ExchangeProperties`
42+
:queue: Queue to work with on RabbitMQ Server.\
43+
*Default:* Default `rabbitmq.QueueProperties`
44+
:credentials: RabbitMQ server credentials.\
45+
*Default:* Default `rabbitmq.Credentials`
46+
:routingkey: Routing key to subscribe to or poll on - only used for Consumer, when working with Producer the routing key is specified on a per message basis when publishing a message.\
47+
*Default:* ``"test-topic"``
48+
49+
Where, as can be seen, properties `exchange`, `queue` and `credentials` are
50+
in turn other MATLAB classes:
51+
52+
**rabbitmq.ExchangeProperties**
53+
54+
:name: Name of the exchange.\
55+
*Default:* `"amq.topic"`
56+
:type: Type of exchange.\
57+
*Default:* `"topic"`
58+
:create: See [the note on create in MessageBroker](noteoncreate).\
59+
*Default:* `true`
60+
:durable: Only relevant if ``create`` = ``true``, create a durable exchange or not\
61+
*Default:* `true`
62+
:autoDelete: Only relevant if ``create`` = ``true``, create an autoDelete exchange or not\
63+
*Default:* `false`
64+
:internal: Only relevant if ``create`` = ``true``, create an internal exchange or not\
65+
*Default:* `false`
66+
:arguments: Only relevant if ``create`` = ``true``, allows setting additional arguments. Use the `put` method to add additional arguments. \
67+
*Default:* Empty `HashMap`
68+
69+
**rabbitmq.QueueProperties**
70+
71+
:name: Name of the queue.\
72+
*Default:* `"RabbitMQ"`
73+
:create: See See [the note on create in MessageBroker](noteoncreate).\
74+
*Default:* `true`
75+
:durable: Only relevant if ``create`` = ``true``, create a durable queue or not.\
76+
*Default:* `false`
77+
:exclusive: Only relevant if ``create`` = ``true``, create an exclusive queue or not.\
78+
*Default:* `false`
79+
:autoDelete: Only relevant if ``create`` = ``true``, create an autoDelete queue or not.\
80+
*Default:* `false`
81+
:arguments: Only relevant if ``create`` = ``true``, allows setting additional arguments. Use the `put` method to add additional arguments. \
82+
*Default:* Empty `HashMap`
83+
84+
**rabbitmq.Credentials**
85+
86+
:username: Username\
87+
*Default:* `"guest"`
88+
:password: Password\
89+
*Default:* `"guest"`
90+
91+
Setting properties values can be done through traditional MATLAB class syntax:
4692

4793
```matlab
48-
% Create a configuration with mostly default options but custom host and
49-
% routingkey settings
50-
configuration = rabbitmq.ConnectorProperties('host','myhost',...
51-
'routingkey','my-key');```
94+
% Create an instance
95+
c = rabbitmq.ConnectorProperties;
96+
% Set a property value
97+
c.host = "myHost";
98+
% Set a property of one of the "nested" settings
99+
c.queue.name = "myQueue";
100+
```
101+
102+
But (with the exception of the `arguments` property) they can also be set by providing Name-Value pairs corresponding to property
103+
name and the value it is to be set to as inputs to the constructor.
104+
105+
```matlab
106+
% Create instance and immediately set host to myHost and port to 1234
107+
c = rabbitmq.ConnectorProperties("host","myHost","port",1234);
108+
```
109+
110+
To immediately set "nested" settings, use the same trick on one of the nested
111+
classes:
112+
113+
```matlab
114+
% Create the QueueProperties with name and durable set
115+
qp = rabbitmq.QueueProperties("name","myQueue","durable",true);
116+
% Create ConnectorProperties with these QueueProperties set
117+
c = rabbitmq.ConnectorProperties("queue",qp);
118+
119+
% Or this could even be done one big single call then
120+
c = rabbitmq.ConnectorProperties("queue", ...
121+
rabbitmq.QueueProperties("name","myQueue","durable",true));
122+
```
123+
124+
To add additional arguments through the `arguments` property, use the put method:
125+
126+
```matlab
127+
% Create QueueProperties with some properties already set
128+
c = rabbitmq.ConnectorProperties("queue", ...
129+
rabbitmq.QueueProperties("name","myQueue","durable",true));
130+
% Then in a separate step add additional arguments, for example
131+
c.queue.arguments.put('x-max-length',42);
132+
% Similarly for exchange
133+
c.exchange.arguments.put('alternate-exchange', 'my-ea');
52134
```
53135

54136
#### Configuration Files
@@ -59,19 +141,33 @@ configuration file for the MATLAB Production Server interface:
59141
```yaml
60142
# Messaging connection and routing properties
61143
messageQueue:
62-
queueName: RabbitMQ # Name of the Queue on RabbitMQ Server
63-
host: localhost # Hostname or IP of the RabbitMQ Server
64-
port: 5672 # Port the RabbitMQ Server runs on
65-
virtualhost: / # RabbitMQ Virtual Host
66-
credentials:
67-
username: guest # RabbitMQ username
68-
password: guest # RabbitMQ password
69-
exchange: amq.topic # Exchange to work with on RabbitMQ
70-
routingkey: test-topic # Routing key to subscribe to or poll on,
71-
# only relevant/required/used when working with
72-
# Consumer, when working with Producer, the
73-
# routingkey is specified on a per message basis
74-
# when publishing the message
144+
queue:
145+
name: RabbitMQ # Name of the Queue on RabbitMQ Server
146+
create: true # Creates/verifies whether queue exists
147+
durable: false # Work with a durable queue or not
148+
exclusive: false # Work with an exclusive queue or not
149+
autoDelete: false # Work with an auto delete queue or not
150+
arguments: # Set additional arguments, can be omitted entirely
151+
x-max-length: 42 # For example, set the maximum queue length
152+
host: localhost # Hostname or IP of the RabbitMQ Server
153+
port: 5672 # Port the RabbitMQ Server runs on
154+
virtualhost: / # RabbitMQ Virtual Host
155+
credentials:
156+
username: guest # RabbitMQ username
157+
password: guest # RabbitMQ password
158+
exchange:
159+
name: amq.topic # Exchange to work with on RabbitMQ
160+
create: true # Creates/verifies whether exchange exists
161+
durable: true # Work with a durable exchange or not
162+
autoDelete: false # Work with an auto delete exchange or not
163+
internal: false # Work with an internal exchange or not
164+
arguments: # Set additional arguments, can be omitted entirely
165+
alternate-exchange: my-ea # For example alternate-exchange
166+
routingkey: test-topic # Routing key to subscribe to
167+
```
168+
169+
```{note}
170+
The `arguments` option can be omitted entirely for both `queue` and `exchange` if it is not necessary to set additional arguments. There is no fixed set of arguments which can be added and the entered argument names are not checked by the interface; they are passed on the server as-is. Check the RabbitMQ documentation to learn more about which exact arguments can be configured.
75171
```
76172

77173
### RabbitMQ Producer for publishing messages `rabbitmq.Producer`
@@ -86,11 +182,11 @@ configuration = rabbitmq.ConnectorProperties();
86182
producer = rabbitmq.Producer(configuration);
87183
```
88184

89-
Then to send a message use `sendMessage` with a routingkey and the actual
185+
Then to send a message use `publish` with a routingkey and the actual
90186
message as input:
91187

92188
```matlab
93-
producer.sendMessage('my-routing-key','Hello World');
189+
producer.publish('my-routing-key','Hello World');
94190
```
95191

96192
### RabbitMQ Consumer for receiving messages `rabbitmq.Consumer`
@@ -177,4 +273,4 @@ added to the *static* class path but there may be circumstances in which this is
177273
not possible and then it is loaded on the *dynamic* class path; this may make
178274
the event based consumer approach unavailable.
179275

180-
[//]: # (Copyright 2022 The MathWorks, Inc.)
276+
[//]: # (Copyright 2022-2023 The MathWorks, Inc.)

‎Documentation/Makefile‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
SOURCEDIR = .
8+
BUILDDIR = _build
9+
10+
# Put it first so that "make" without argument is like "make help".
11+
help:
12+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
13+
14+
.PHONY: help Makefile
15+
16+
# Catch-all target: route all unknown targets to Sphinx using the new
17+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
18+
%: Makefile
19+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎Documentation/MessageBroker.md‎

Lines changed: 69 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ messages from a RabbitMQ Server which it then passes along as input to a
66
function deployed ot MATLAB Production Server. The MATLAB function is assumed to
77
have exactly one input which is the message as character array.
88

9-
```mermaid
9+
```{mermaid}
1010
flowchart
1111
client(Message Producer) -- publish message --> server[(RabbitMQ Server)]-- deliver message --> MessageBroker[MessageBroker] --"call with message as input"--> mps(MATLAB Production Server)
1212
MessageBroker -. subscribe .-> server
@@ -26,7 +26,7 @@ used to parse the JSON string into a MATLAB structure.
2626
## Dataflow
2727
A full workflow with this package could look like the following:
2828

29-
```mermaid
29+
```{mermaid}
3030
sequenceDiagram
3131
autonumber
3232
participant MessageSender
@@ -75,11 +75,13 @@ sequenceDiagram
7575
can use `rabbitmq.Producer` to send a message with the `routingkey` the
7676
client is bound to, to the RabbitMQ Server.
7777

78-
> Note: this bypasses `MessageBroker`. `MessageBroker` does not do anything
79-
> with the "MATLAB style output" of the function deployed to MATLAB
80-
> Production Server. The MATLAB code deployed to MATLAB Production Server
81-
> has to explicitly use `rabbitmq.Producer` in the MATLAB code if a reply is
82-
> to be send over RabbitMQ.
78+
```{note}
79+
Note: this bypasses `MessageBroker`. `MessageBroker` does not do anything
80+
with the "MATLAB style output" of the function deployed to MATLAB
81+
Production Server. The MATLAB code deployed to MATLAB Production Server
82+
has to explicitly use `rabbitmq.Producer` in the MATLAB code if a reply is
83+
to be send over RabbitMQ.
84+
```
8385
8486
7. If the `routingkey`, `queue` and `exchange` match the one the client has
8587
subscribed to, the RabbitMQ server will deliver the reply to the client.
@@ -97,9 +99,11 @@ running correctly and can be accessed, for example by accessing the Web Admin
9799
console which typically runs on port 15672, so for a local server check
98100
http://localhost:15672/.
99101
100-
> Please see the [RabbitMQ Authentication, Authorization, Access Control
101-
> documentation](https://www.rabbitmq.com/access-control.html) on how to
102-
> configure credentials for remote access, TLS support, authentication, etc.
102+
```{hint}
103+
See the [RabbitMQ Authentication, Authorization, Access Control
104+
documentation](https://www.rabbitmq.com/access-control.html) on how to
105+
configure credentials for remote access, TLS support, authentication, etc.
106+
```
103107
104108
2. For an initial test, MATLAB Compiler SDK's MATLAB Production Server testing
105109
interface can be used rather than an actual MATLAB Production Server
@@ -112,7 +116,11 @@ http://localhost:15672/.
112116
5. Click `Start` to start the test server.
113117
114118
3. Open `Software/Java/RabbitMQClient/src/main/resources/mps.yaml` and update
115-
the options to match your configuration.
119+
the options to match your configuration.
120+
121+
```{note}
122+
The `arguments` for `queue` and `exchange` will likely have to be removed, they are not often used and shown here mainly for illustrative purposes to show *where* these can be added *if* they are needed. There is no fixed set of arguments which can be added and argument names are not verified by `MessageBroker`; they are send to the server as-is. Check the RabbitMQ documentation to learn more about the argument its supports.
123+
```
116124
117125
```yaml
118126
# MATLAB Production Server connection properties
@@ -130,17 +138,64 @@ the options to match your configuration.
130138
131139
# Messaging connection and routing properties
132140
messageQueue:
133-
queueName: RabbitMQ # Name of the Queue on RabbitMQ Server
141+
queue:
142+
name: RabbitMQ # Name of the Queue on RabbitMQ Server
143+
create: true # Creates/verifies whether queue exists
144+
durable: false # Work with a durable queue or not
145+
exclusive: false # Work with an exclusive queue or not
146+
autoDelete: false # Work with an auto delete queue or not
147+
arguments: # Set additional arguments, can be omitted entirely
148+
x-max-length: 42 # For example, set the maximum queue length
134149
host: localhost # Hostname or IP of the RabbitMQ Server
135150
port: 5672 # Port the RabbitMQ Server runs on
136151
virtualhost: / # RabbitMQ Virtual Host
137152
credentials:
138153
username: guest # RabbitMQ username
139154
password: guest # RabbitMQ password
140-
exchange: amq.topic # Exchange to work with on RabbitMQ
155+
exchange:
156+
name: amq.topic # Exchange to work with on RabbitMQ
157+
create: true # Creates/verifies whether exchange exists
158+
durable: true # Work with a durable exchange or not
159+
autoDelete: false # Work with an auto delete exchange or not
160+
internal: false # Work with an internal exchange or not
161+
arguments: # Set additional arguments, can be omitted entirely
162+
alternate-exchange: my-ea # For example alternate-exchange
141163
routingkey: test-topic # Routing key to subscribe to
142164
```
143165
166+
```{note}
167+
---
168+
name: noteoncreate
169+
---
170+
For both `queue` and `exchange`, `name` must be set and the `create` option has the following effects:
171+
172+
* If set to `false`:
173+
174+
* The broker will not try to create the queue or exchange with the specified `name`.
175+
They must already exist with the correct name on the server end for the broker to work
176+
correctly.
177+
* The other settings (`durable`, `autoDelete`, etc.) are ignored entirely and can also simply
178+
be omitted from the configuration file then.
179+
* This allows a certain flexibility if from the client end the exact configuration does
180+
not matter and is allowed to be set by the server or other clients entirely. Do **not** use this option
181+
if it is imperative for the client that the queue/exchange is configured with specific
182+
options. In that case set `create` to `true` and specify the exact settings such that the broker will
183+
refuse to start if there is a configuration mismatch.
184+
185+
* If set to `true`:
186+
187+
* The broker will ensure that the specified queue or exchange with the specific settings
188+
exists or error out:
189+
190+
* If there is no exchange/queue with the specified name yet, it is created with the
191+
settings as specified in the other properties (`durable`, `autoDelete`, etc.).
192+
* If there is an exchange/queue with the specified name already, and the existing instance
193+
was created with the same settings (`durable`, `autoDelete`, etc.), the existing
194+
instance is used.
195+
* If there is an exchange/queue with the specified name already, but there is a mismatch
196+
in settings the broker will error out and refuse to start.
197+
```
198+
144199
If indeed working with the MATLAB Compiler SDK MATLAB Production Server testing
145200
interface on your local machine configured as described in step 4, the `MATLAB
146201
Production Server connection properties` settings should be correct already.
@@ -175,4 +230,4 @@ system:
175230
server inside MATLAB, the message should be displayed in the MATLAB Command
176231
Window.
177232
178-
[//]: # (Copyright 2022 The MathWorks, Inc.)
233+
[//]: # (Copyright 2022-2023 The MathWorks, Inc.)

‎Documentation/ReleaseNotes.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
% This document includes the root RELEASENOTES.md in the HTML version of the documentation. When viewing the Markdown version,please refer to [../RELEASENOTES.md](../RELEASENOTES.md)
2+
```{include} ../RELEASENOTES.md
3+
:relative-docs: Documentation/
4+
```
5+
6+
[//]: # (Copyright 2022-2023 The MathWorks, Inc.)

0 commit comments

Comments
 (0)