ARTEMIS-3954: add more detail to core-client javadoc around the session and children thread model being like the JMS client

artemis-core-client/src/main/java/org/apache/activemq/artemis/api/core/client/ClientConsumer.java

@@ -96,6 +96,9 @@ public interface ClientConsumer extends AutoCloseable {
    /**
     * Sets the MessageHandler for this consumer to consume messages asynchronously.
     * <p>
+    * Note that setting a handler dedicates the parent session, and its child producers
+    * and consumers, to the session-wide handler delivery thread of control.
+    * <p>
     * Calling this method on a closed consumer will throw a ActiveMQException.
     *
     * @param handler a MessageHandler

artemis-core-client/src/main/java/org/apache/activemq/artemis/api/core/client/ClientSession.java

@@ -28,7 +28,12 @@ import org.apache.activemq.artemis.api.core.SimpleString;
 import org.apache.activemq.artemis.api.core.RoutingType;
 
 /**
- * A ClientSession is a single-thread object required for producing and consuming messages.
+ * A ClientSession is a single-threaded parent object required for producing and consuming messages.
+ * <p>
+ * Only a single thread may be used to operate on the session and its child producers and consumers,
+ * other than close() methods which may be called from another thread. Setting a MessageHandler on a
+ * consumer renders the session, and all its child producers and consumers, to be dedicated to the
+ * session-wide handler delivery thread of control.
  */
 public interface ClientSession extends XAResource, AutoCloseable {