[qpid-protonj2] branch main updated: PROTON-2767 Add some simple client usage guidance to the README

[ta...@apache.org]

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 <ta...@gmail.com>
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: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org