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 2022/10/27 16:40:48 UTC

[qpid-protonj2] branch main updated: PROTON-2634 Javadocs fixups and additions

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 cf701c11 PROTON-2634 Javadocs fixups and additions
cf701c11 is described below

commit cf701c11319193225afd8efb96a5bb8b3d958960
Author: Timothy Bish <ta...@gmail.com>
AuthorDate: Thu Oct 27 12:40:31 2022 -0400

    PROTON-2634 Javadocs fixups and additions
---
 .../main/java/org/apache/qpid/protonj2/client/Connection.java  |  5 +++++
 .../src/main/java/org/apache/qpid/protonj2/client/Session.java | 10 ++++++++--
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Connection.java b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Connection.java
index 2cac3b4e..6054a19e 100644
--- a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Connection.java
+++ b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Connection.java
@@ -406,6 +406,11 @@ public interface Connection extends AutoCloseable {
      * create the default anonymous connection {@link Sender} as well as creating those
      * resources created from the {@link Connection} such as {@link Sender} and {@link Receiver}
      * instances not married to a specific {@link Session}.
+     * <p>
+     * While it is possible to use the returned Session to cause Connection level resources
+     * to operate within a transaction it is strongly discouraged. Transactions should be
+     * performed from a user created Session with a single {@link Sender} or {@link Receiver}
+     * link for best results.
      *
      * @return a new {@link Session} instance.
      *
diff --git a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Session.java b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Session.java
index 568b93df..543cb8ae 100644
--- a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Session.java
+++ b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Session.java
@@ -21,11 +21,17 @@ import java.util.concurrent.Future;
 import java.util.concurrent.TimeUnit;
 
 import org.apache.qpid.protonj2.client.exceptions.ClientException;
+import org.apache.qpid.protonj2.client.exceptions.ClientIllegalStateException;
 import org.apache.qpid.protonj2.client.exceptions.ClientTransactionNotActiveException;
 import org.apache.qpid.protonj2.client.exceptions.ClientUnsupportedOperationException;
 
 /**
  * Session object used to create {@link Sender} and {@link Receiver} instances.
+ * <p>
+ * A session can serve as a context for a running transaction in which case care should be
+ * taken to ensure that work done is inside the scope of the transaction begin and end calls
+ * such as ensuring that receivers accept and settle before calling transaction commit if
+ * the work is meant to be within the transaction scope.
  */
 public interface Session extends AutoCloseable {
 
@@ -281,9 +287,9 @@ public interface Session extends AutoCloseable {
      *
      * A {@link Session} that has an active transaction will perform all sends and all delivery dispositions
      * under that active transaction.  If the user wishes to send with the same session but outside of a
-     * transaction they user must commit the active transaction and not request that a new one be started.
+     * transaction the user must commit the active transaction and not request that a new one be started.
      * A session can only have one active transaction at a time and as such any call to begin while there is
-     * a currently active transaction will throw an {@link ClientTransactionNotActiveException} to indicate that
+     * a currently active transaction will throw an {@link ClientIllegalStateException} to indicate that
      * the operation being requested is not valid at that time.
      *
      * This is a blocking method that will return successfully only after a new transaction has been started.


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org