Recommended (new) APIs and more example code (#1191)

Author: roeschter

src/main/java/io/nats/client/Connection.java

@@ -571,6 +571,8 @@ enum Status {
 
     /**
      * Get a stream context for a specific stream.
+     * 
+     * <p><b>Recommended:</b> See {@link #getStreamContext(String, JetStreamOptions) getStreamContext(String, JetStreamOptions)} 
      * @param streamName the stream for the context
      * @return a StreamContext instance.
      * @throws IOException covers various communication issues with the NATS
@@ -580,7 +582,23 @@ enum Status {
     StreamContext getStreamContext(String streamName) throws IOException, JetStreamApiException;
 
     /**
-     * Get a stream context for a specific stream.
+     * Get a stream context for a specific stream
+     * <p><b>Recommended:</b> {@link StreamContext StreamContext} and {@link ConsumerContext ConsumerContext} are the preferred way to interact with existing streams and consume from streams. 
+     * {@link JetStreamManagement JetStreamManagement} should be used to create streams and consumers. {@link ConsumerContext#consume ConsumerContext.consume()} supports both push and pull consumers transparently.
+     * 
+     * <pre>
+     * nc = Nats.connect();
+	 * StreamContext streamContext = nc.getStreamContext("my-stream");
+	 * ConsumerContext consumerContext = streamContext.getConsumerContext("my-consumer");
+	 * // Or directly: 
+	 * // ConsumerContext consumerContext = nc.getConsumerContext("my-stream", "my-consumer"); 
+	 * consumerContext.consume(
+	 *      	msg -&gt; {
+	 *             System.out.println("   Received " + msg.getSubject());
+	 *             msg.ack();
+	 *           });
+	   </pre>         
+     * 
      * @param streamName the stream for the context
      * @param options JetStream options.
      * @return a StreamContext instance.
@@ -593,6 +611,9 @@ enum Status {
     /**
      * Get a consumer context for a specific named stream and specific named consumer.
      * Verifies that the stream and consumer exist.
+     * 
+     * <p><b>Recommended:</b> See {@link #getStreamContext(String, JetStreamOptions) getStreamContext(String, JetStreamOptions)} 
+     * 
      * @param streamName the name of the stream
      * @param consumerName the name of the consumer
      * @return a ConsumerContext object
@@ -605,6 +626,9 @@ enum Status {
     /**
      * Get a consumer context for a specific named stream and specific named consumer.
      * Verifies that the stream and consumer exist.
+     * 
+     * <p><b>Recommended:</b> See {@link #getStreamContext(String, JetStreamOptions) getStreamContext(String, JetStreamOptions)} 
+     * 
      * @param streamName the name of the stream
      * @param consumerName the name of the consumer
      * @param options JetStream options.

src/main/java/io/nats/client/api/MessageGetRequest.java

@@ -44,6 +44,8 @@ public static MessageGetRequest nextForSubject(long sequence, String subject) {
 
     /**
      * @deprecated use static method forSequence with .serialize instead
+     * @param sequence start sequence
+     * @return rendered output
      */
     @Deprecated
     public static byte[] seqBytes(long sequence) {
@@ -52,6 +54,8 @@ public static byte[] seqBytes(long sequence) {
 
     /**
      * @deprecated use static method lastForSubject with .serialize instead
+     * @param subject filter subject
+     * @return rendered output
      */
     @Deprecated
     public static byte[] lastBySubjectBytes(String subject) {
@@ -60,6 +64,8 @@ public static byte[] lastBySubjectBytes(String subject) {
 
     /**
      * @deprecated use static method forSequence instead
+     * 
+     * @param sequence start sequence number
      */
     @Deprecated
     public MessageGetRequest(long sequence) {
@@ -68,6 +74,8 @@ public MessageGetRequest(long sequence) {
 
     /**
      * @deprecated use static method lastForSubject instead
+     * 
+     * @param lastBySubject filter subject
      */
     @Deprecated
     public MessageGetRequest(String lastBySubject) {

src/main/java/io/nats/client/impl/DataPort.java

@@ -45,6 +45,10 @@ default void afterConstruct(Options options) {}
     /**
      * NOTE: the buffer will be modified if communicating over websockets and
      * the toWrite is greater than 1432.
+     * 
+     * @param src output byte[]
+     * @param toWrite number of bytes to write
+     * @throws IOException any IO error on the underlaying connection
      */
     void write(byte[] src, int toWrite) throws IOException;
 

src/main/java/io/nats/client/impl/Headers.java

@@ -106,8 +106,9 @@ public Headers add(String key, String... values) {
 	 * If the key is not present, sets the specified values for the key.
 	 * null values are ignored. If all values are null, the key is not added or updated.
 	 *
-	 * @param key the key
-	 * @return the Headers object
+	 * @param key the entry key
+	 * @param values a list of values to the entry
+	 * @return the Header object
 	 * @throws IllegalArgumentException if the key is null or empty or contains invalid characters
 	 *         -or- if any value contains invalid characters
 	 */
@@ -262,16 +263,16 @@ private void _remove(String key) {
 	/**
 	 * Returns the number of keys (case-sensitive) in the header.
 	 *
-	 * @return the number of keys
+	 * @return the number of header entries
 	 */
 	public int size() {
 		return valuesMap.size();
 	}
 
 	/**
-	 * Returns <tt>true</tt> if this map contains no keys.
+	 * Returns ture if map contains no keys.
 	 *
-	 * @return <tt>true</tt> if this map contains no keys
+	 * @return true if there are no headers
 	 */
 	public boolean isEmpty() {
 		return valuesMap.isEmpty();
@@ -291,20 +292,20 @@ public void clear() {
 	}
 
 	/**
-	 * Returns <tt>true</tt> if key (case-sensitive) is present (has values)
+	 * Returns true if key (case-sensitive) is present (has values)
 	 *
 	 * @param key key whose presence is to be tested
-	 * @return <tt>true</tt> if the key (case-sensitive) is present (has values)
+	 * @return true if the key (case-sensitive) is present (has values)
 	 */
 	public boolean containsKey(String key) {
 		return valuesMap.containsKey(key);
 	}
 
 	/**
-	 * Returns <tt>true</tt> if key (case-insensitive) is present (has values)
+	 * Returns true if key (case-insensitive) is present (has values)
 	 *
 	 * @param key exact key whose presence is to be tested
-	 * @return <tt>true</tt> if the key (case-insensitive) is present (has values)
+	 * @return true if the key (case-insensitive) is present (has values)
 	 */
 	public boolean containsKeyIgnoreCase(String key) {
 		for (String k : valuesMap.keySet()) {
@@ -341,6 +342,7 @@ public Set<String> keySetIgnoreCase() {
 	 * Returns a {@link List} view of the values for the specific (case-sensitive) key.
 	 * Will be {@code null} if the key is not found.
 	 *
+	 * @param key the key whose associated value is to be returned
 	 * @return a read-only list of the values for the case-sensitive key.
 	 */
 	public List<String> get(String key) {
@@ -351,7 +353,7 @@ public List<String> get(String key) {
 	/**
 	 * Returns the first value for the specific (case-sensitive) key.
 	 * Will be {@code null} if the key is not found.
-	 *
+	 * @param key the key whose associated value is to be returned
 	 * @return the first value for the case-sensitive key.
 	 */
 	public String getFirst(String key) {
@@ -363,6 +365,7 @@ public String getFirst(String key) {
 	 * Returns the last value for the specific (case-sensitive) key.
 	 * Will be {@code null} if the key is not found.
 	 *
+	 * @param key the key whose associated value is to be returned
 	 * @return the last value for the case-sensitive key.
 	 */
 	public String getLast(String key) {
@@ -374,6 +377,7 @@ public String getLast(String key) {
 	 * Returns a {@link List} view of the values for the specific (case-insensitive) key.
 	 * Will be {@code null} if the key is not found.
 	 *
+	 * @param key the key whose associated value is to be returned
 	 * @return a read-only list of the values for the case-insensitive key.
 	 */
 	public List<String> getIgnoreCase(String key) {
@@ -447,7 +451,10 @@ public byte[] getSerialized() {
 
 	/**
 	 * @deprecated
-	 * Appends the serialized bytes to the builder.
+	 * Used for unit testing.
+     * Appends the serialized bytes to the builder. 
+     * 
+	 * @param bab the ByteArrayBuilder to append
 	 * @return the builder
 	 */
 	@Deprecated

src/main/java/io/nats/client/impl/NatsConsumer.java

@@ -112,7 +112,7 @@ void incrementDroppedCount() {
 
     /**
      * @return the number of messages dropped from this consumer, since the last
-     *         call to {@link @clearDroppedCount}.
+     *         call to {@link #clearDroppedCount}.
      */
     public long getDroppedCount() {
         return this.droppedMessages.get();

src/main/java/io/nats/client/impl/NatsObjectStore.java

@@ -397,7 +397,7 @@ public ObjectInfo addBucketLink(String objectName, ObjectStore toStore) throws I
     /**
      * {@inheritDoc}
      *
-     * @return
+     * @return returs the new status info of the object store
      */
     @Override
     public ObjectStoreStatus seal() throws IOException, JetStreamApiException {

src/main/javadoc/overview.html

@@ -17,6 +17,10 @@
 <head></head>
 <body>
 Java API for the <a href="http://nats.io">NATs messaging system</a>.
+<p>The Java API is hosted on <a href="https://github.com/nats-io/nats.java">Github NATS Java API</a>. Before starting to code, please check the <a href="https://github.com/nats-io/nats.java/blob/main/README.md"><b>README</b></a>  for updates, hints and best practices.
+<p>Examples are collected in <a href="https://github.com/nats-io/nats.java/tree/main/src/examples/java/io/nats/examples">NATS Client API examples</a> and <a href="https://github.com/nats-io/java-nats-examples">NATS Java examples</a>
+<p>For more examples, including for other programming languages, see <a href="https://natsbyexample.com/">NATS By Example</a>, which is also hosted on <a href="https://github.com/nats-io/java-nats-examples">Github - NATS By Example</a> and open to contribution.
+
 <p><img src="large-logo.png" alt="nats logo"></p>
 
 <p>NATS Server is a simple, high performance open source messaging system for cloud native applications, IoT messaging, and microservices architectures.