You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by ta...@apache.org on 2023/09/27 19:28:59 UTC
[qpid-protonj2] branch main updated: PROTON-2767 Update documentation pages with links to others
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 e59d5a08 PROTON-2767 Update documentation pages with links to others
e59d5a08 is described below
commit e59d5a08851fb5e3c6978745122d5c3b21e56a4f
Author: Timothy Bish <ta...@gmail.com>
AuthorDate: Wed Sep 27 15:27:07 2023 -0400
PROTON-2767 Update documentation pages with links to others
Provides some initial structure for various documentation pages and guides
for using the client and some advanced features.
---
README.md | 7 +--
apache-qpid-protonj2/README.md | 2 +-
protonj2-client-docs/README.md | 19 ++++++--
protonj2-client-examples/README.md | 1 -
protonj2-client/README.md | 93 +-------------------------------------
protonj2-test-driver/README.md | 38 ++++++++++++++++
protonj2/README.md | 38 ++++++++++++++++
7 files changed, 95 insertions(+), 103 deletions(-)
diff --git a/README.md b/README.md
index 85650892..6e6af736 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,6 @@
-# Apache Qpid ProtonJ2
-=======================
+# Apache Qpid protonj2
-Qpid ProtonJ2 is a high-performance, lightweight AMQP protocol library. It can be
-used in the widest range of messaging applications, including brokers, client
-libraries, routers, bridges, proxies, and more.
+Qpid protonj2 is a high-performance, lightweight AMQP protocol library. It can be used in the widest range of messaging applications, including brokers, client libraries, routers, bridges, proxies, and more. This project provides an AMQP [protocol engine](protonj2/README.md) for building your own AMQP client and servers as well as a full featured imperative API [client](protonj2-client/README.md). If you want to test your AMQP implementation the project also provides an AMQP [test framew [...]
Please see http://qpid.apache.org/proton for more information.
diff --git a/apache-qpid-protonj2/README.md b/apache-qpid-protonj2/README.md
index 051048ec..007d29f9 100644
--- a/apache-qpid-protonj2/README.md
+++ b/apache-qpid-protonj2/README.md
@@ -1 +1 @@
-This module is used to produce the Apache Qpid ProtonJ2 release assemblies.
+This module is used to produce the Apache Qpid protonj2 release assemblies.
diff --git a/protonj2-client-docs/README.md b/protonj2-client-docs/README.md
index 500ca2b0..a29b427e 100644
--- a/protonj2-client-docs/README.md
+++ b/protonj2-client-docs/README.md
@@ -1,7 +1,16 @@
-# Qpid ProtonJ2 client documentation
+# Qpid protonj2 client documentation
+
+The protonj2 client is a feature rich AMQP v1.0 client implementing an imperative API that offers users full access to the AMQP protocol while attempting to be easy to use even if you are just getting started with AMQP or Messaging.
+
+The documentation is split up into various section to make finding help easier, if you are new then it is recommended that you read the getting started guide first to get a basic overview of the client API.
+
+If you are viewing this documentation from an archive the most current versions can be found in the project [source repository](https://github.com/apache/qpid-protonj2).
+
+## Where to go next
+
++ [Getting Started Guide](GettingStarted.md)
++ [Configuration Guide](Configuration.md)
++ [Reconnection Support](Reconnection.md)
++ [Large Message Handling](LargeMessages.md)
-The docs are raw Markdown right now, we still need to put stuff in place to convert
-to other formats like HTML.
-Until then you might find it easier to view them by browsing the GitHub repository:
-https://github.com/apache/qpid-protonj2
diff --git a/protonj2-client-examples/README.md b/protonj2-client-examples/README.md
index 2528e4a2..f9b4ced2 100644
--- a/protonj2-client-examples/README.md
+++ b/protonj2-client-examples/README.md
@@ -1,5 +1,4 @@
# Running the client examples
-----------------------------------------------
Use maven to build the module, and additionally copy the dependencies
alongside their output:
diff --git a/protonj2-client/README.md b/protonj2-client/README.md
index e8e6c590..79612d88 100644
--- a/protonj2-client/README.md
+++ b/protonj2-client/README.md
@@ -37,95 +37,6 @@ 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 protonj2 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 your 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
-a source checkout/release, rather than against released binaries) and then
-consult the README in the protonj2-client-examples module itself.
-
-## Documentation
-
-There is some basic documentation in the protonj2-client-docs module.
+## Client Documentation
+The full client documentation is located in the Qpid protonj2 client [documentation](../protonj2-client-docs/README.md) module.
\ No newline at end of file
diff --git a/protonj2-test-driver/README.md b/protonj2-test-driver/README.md
new file mode 100644
index 00000000..9b7a08c3
--- /dev/null
+++ b/protonj2-test-driver/README.md
@@ -0,0 +1,38 @@
+# Qpid protonj2 test driver
+
+This library provides a test framework which can be used to build both client and server tests for implementations of the AMQP v1.0 protocol.
+
+Below are some quick pointers you might find useful.
+
+## Using the protocol engine library
+
+To use the protonj2 test driver library in your projects you can include the maven
+dependency in your project pom file:
+
+ <dependency>
+ <groupId>org.apache.qpid</groupId>
+ <artifactId>protonj2-test-driver</artifactId>
+ <version>${protonj2-version}</version>
+ </dependency>
+
+## Building the code
+
+The project requires Maven 3. Some example commands follow.
+
+Clean previous builds output and install all modules to local repository without
+running the tests:
+
+ mvn clean install -DskipTests
+
+Install all modules to the local repository after running all the tests:
+
+ mvn clean install
+
+Perform a subset tests on the packaged release artifacts without
+installing:
+
+ mvn clean verify -Dtest=TestNamePattern*
+
+Execute the tests and produce code coverage report:
+
+ mvn clean test jacoco:report
diff --git a/protonj2/README.md b/protonj2/README.md
new file mode 100644
index 00000000..79b54a23
--- /dev/null
+++ b/protonj2/README.md
@@ -0,0 +1,38 @@
+# Qpid protonj2 protocol engine
+
+This library provides a protocol engine which can be used to build both clients and server that communicate over the AMQP v1.0 standard protocol.
+
+Below are some quick pointers you might find useful.
+
+## Using the protocol engine library
+
+To use the protonj2 protocol engine library in your projects you can include the maven
+dependency in your project pom file:
+
+ <dependency>
+ <groupId>org.apache.qpid</groupId>
+ <artifactId>protonj2</artifactId>
+ <version>${protonj2-version}</version>
+ </dependency>
+
+## Building the code
+
+The project requires Maven 3. Some example commands follow.
+
+Clean previous builds output and install all modules to local repository without
+running the tests:
+
+ mvn clean install -DskipTests
+
+Install all modules to the local repository after running all the tests:
+
+ mvn clean install
+
+Perform a subset tests on the packaged release artifacts without
+installing:
+
+ mvn clean verify -Dtest=TestNamePattern*
+
+Execute the tests and produce code coverage report:
+
+ mvn clean test jacoco:report
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org