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 <tabish...@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-unsubscr...@qpid.apache.org For additional commands, e-mail: commits-h...@qpid.apache.org