This is an automated email from the ASF dual-hosted git repository.
tabish pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/qpid-protonj2.git
The following commit(s) were added to refs/heads/main by this push:
new e1c7b7dd PROTON-2767 Add some simple client usage guidance to the
README
e1c7b7dd is described below
commit e1c7b7dd61bde1ae00d33223afcf1a15419633bb
Author: Timothy Bish <[email protected]>
AuthorDate: Mon Sep 18 18:18:06 2023 -0400
PROTON-2767 Add some simple client usage guidance to the README
---
protonj2-client/README.md | 83 ++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 82 insertions(+), 1 deletion(-)
diff --git a/protonj2-client/README.md b/protonj2-client/README.md
index 42f107f7..9f610e82 100644
--- a/protonj2-client/README.md
+++ b/protonj2-client/README.md
@@ -37,6 +37,88 @@ Execute the tests and produce code coverage report:
mvn clean test jacoco:report
+## Creating a connection
+
+The entry point for creating new connections with the proton-dotnet client is
the Client
+type which provides a simple static factory method to create new instances.
+
+ Client container = Client.create();
+
+The Client instance serves as a container for connections created by your
application and
+can be used to close all active connections and provides the option of adding
configuration
+to set the AMQP container Id that will be set on connections created from a
given client
+instance.
+
+Once you have created a Client instance you can use that to create new
connections which
+will be of type Connection. The Client instance provides API for creating a
connection
+to a given host and port as well as providing connection options object that
carry a large
+set of connection specific configuration elements to customize the behavior of
your connection.
+The basic create API looks as follows:
+
+ Connection connection = container.connect(remoteAddress, remotePort, new
ConnectionOptions());
+
+From you connection instance you can then proceed to create sessions, senders
and receivers that
+you can use in your application.
+
+### Sending a message
+
+Once you have a connection you can create senders that can be used to send
messages to a remote
+peer on a specified address. The connection instance provides methods for
creating senders and
+is used as follows:
+
+ Sender sender = connection.openSender("address");
+
+A message instance must be created before you can send it and the Message
interface provides
+simple static factory methods for common message types you might want to send,
for this example
+we will create a message that carries text in an AmqpValue body section:
+
+ Message<String> message = Message<String>.create("Hello World");
+
+Once you have the message that you want to send the previously created sender
can be used as
+follows:
+
+ Tracker tracker = sender.send(message);
+
+The Send method of a sender will attempt to send the specified message and if
the connection
+is open and the send can be performed it will return a Tracker instance to
provides API for
+checking if the remote has accepted the message or applied other AMQP outcomes
to the sent
+message.
+
+### Receiving a message
+
+To receive a message sent to the remote peer a Receiver instance must be
created that listens
+on a given address for new messages to arrive. The connection instance
provides methods for
+creating receivers and is used as follows:
+
+ Receiver receiver = connection.openReceiver("address");
+
+After creating the receiver the application can then call one of the available
receive APIs to
+await the arrival of a message from a remote sender.
+
+ Delivery delivery = receiver.receive();
+
+By default receivers created from the client API have a credit window
configured and will
+manage the outstanding credit with the remote for your application however if
you have
+configured the client not to manage a credit window then your application will
need to
+provide receiver credit before invoking the receive APIs.
+
+ receiver.addCredit(1);
+
+Once a delivery arrives an Delivery instance is returned which provides API to
both access
+the delivered message and to provide a disposition to the remote indicating if
the delivered
+message is accepted or was rejected for some reason etc. The message is
obtained by calling
+the message API as follows:
+
+ Message<object> received = delivery.message();
+
+Once the message is examined and processed the application can accept delivery
by calling
+the accept method from the delivery object as follows:
+
+ delivery.accept();
+
+Other settlement options exist in the delivery API which provide the
application wil full
+access to the AMQP specification delivery outcomes for the received message.
+
## Examples
First build and install all the modules as detailed above (if running against
@@ -47,4 +129,3 @@ consult the README in the protonj2-client-examples module
itself.
There is some basic documentation in the protonj2-client-docs module.
-
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
