Java Nats Examples

This folder contains a number of examples:

Regular Nats Examples

ConnectTime.java - how to build a listener that will track connect time.
NatsPub.java - publishes messages
NatsPubMany.java - publishes many messages
NatsReply.java - sends a reply when a request is received
NatsReq.java - sends a request and prints the reply
NatsReqFuture.java - sends a request async using a future
NatsSub.java - reads messages synchronously
NatsSubDispatch.java - uses asynchronous dispatching for incoming messages
NatsSubQueue.java - subscribes on a queue for message load balancing
NatsSubQueueFull.java - fuller publish and queue subscribe example

JetStream Examples

In the io.nats.examples.jetstream package...

NatsJsPub.java - publish JetStream messages
NatsJsPubAsync.java - publish JetStream messages asynchronously
NatsJsPubAsync2.java - publish JetStream messages asynchronously
NatsJsPubVersusCorePub.java - publish JetStream messages versus core publish to the same stream.
NatsJsPubWithOptionsUseCases - publish JetStream with examples on using publish options
NatsJsPullSubBatchSize.java - pull subscription example specifying batch size and manual handling
NatsJsPullSubBatchSizeUseCases.java - pull subscription example specifying batch size with examples of manual handling various cases of available messages
NatsJsPullSubExpiresIn.java - pull subscription example specifying expiration and manual handling
NatsJsPullSubExpiresInUseCases.java - pull subscription example specifying expiration with examples of manual handling various cases of available messages
NatsJsPullSubFetch.java - pull subscription example using fetch list macro function
NatsJsPullSubFetchUseCases.java - pull subscription example using fetch list macro function with examples of various cases of available messages
NatsJsPullSubIterate.java - pull subscription example using iterate macro function
NatsJsPullSubIterateUseCases.java - pull subscription example using iterate macro function with examples of various cases of available messages
NatsJsPullSubMultipleWorkers.java - pull subscribing using a durable consumer and sharing processing of the messages
NatsJsPullSubNoWaitUseCases.java - pull subscription example specifying no wait with examples of manual handling various cases of available messages
NatsJsPushSubAsyncQueueDurable.java - push async subscribing using a durable consumer and a queue
NatsJsPushSubBasicAsync.java - basic asynchronous push subscribing with a handler
NatsJsPushSubBasicSync.java - push subscribing to read messages synchronously and manually acknowledges messages
NatsJsPushSubBindDurable.java - push subscribing with the bind options
NatsJsPushSubDeliverSubject.java - push subscribing with a deliver subject and how the subject can be read as a regular Nats Message
NatsJsPushSubFilterSubject.java - push subscribing with a filter on the subjects
NatsJsPushSubFlowControl.java - listening to flow control messages through the Error Listener
NatsJsPushSubQueueDurable.java - push subscribing to read messages in a load balance queue using a durable consumer

JetStream Management / Admin Examples

NatsJsManageConsumers.java - demonstrate the management of consumers
NatsJsManageStreams.java - demonstrate the management of streams
NatsJsMirrorSubUseCases.java -
NatsJsPrefix.java - demonstrate connecting on an account that uses a custom prefix

Key Value / Object Store

NatsKeyValueFull.java -

Other examples

autobench - benchmarks the current system/setup in several scenarios
benchmark - benchmark that supports multiple threads
stability - a small producer and subscriber that run forever printing some status every so often. These are intended for long running tests without burning the CPU.
jsmulti - a multi-faceted tool that allows you to do a variety of publishing and subscribing to both core NATS and JetStream subjects. Please see the JsMultiTool README

Example Support

ExampleArgs.java - Helper to manage command line arguments.
ExampleAuthHandler.java - Example of an auth handler.
ExampleUtils.java - Miscellaneous utils used to start or in running examples.
NatsJsUtils.java - Miscellaneous utils specific to JetStream examples.

All of these examples take the server URL on the command line, which means that you can use the tls and opentls schemas to test over a secure connection.

Running the examples

The examples require both the client library and the examples to be compiled and then the jars be used in the classpath. When you build locally, -SNAPSHOT is appended to the version. See the project README for specifics on building these.
When you run, if you supply an unknown parameter or miss a required parameter, the usage string will be shown and the program will exit.
If you purposefully want to see the usage string run the program with -h, -help, -u, -usage.
All examples require a server url, but it's always optional to provide one as part of the command. If not supplied, the program will use nats://localhost:4222
If you want to run the program from an ide, you can take advantage of the ide runner to provide arguments. You can also just insert some code before the arguments are processed to set the arguments directly. For example;
```
args = "-arg1 myArg1 -arg2 myArg2".split(" ");
args = new String[] {"-arg1", "myArg1", "-arg2", "myArg2"};
```

Classpath

In the examples, the usage will show java <program> -cp <classpath> ... Make sure you add both the client library and examples into the classpath. Replace {major.minor.patch} with the correct version. For example:

java -cp build/libs/jnats-{major.minor.patch}-SNAPSHOT.jar:build/libs/jnats-{major.minor.patch}-SNAPSHOT-examples.jar io.nats.examples.NatsPub nats://localhost:4222 test "hello world"

Some examples depend on others

To see how queues split messages, run the NatsQSub in multiple windows and then run NatsPub. Messages should be distributed between the clients. On the other hand, if you run NatsSub in multiple shells and then run NatsPub you will get the message at all subscribers.

Running with TLS

A set of sample certificates are provided in the repo for testing. These use the highly secure password password. To run with the full client and trust default keystore you can use command line arguments to set System properties.

java -Djavax.net.ssl.keyStore=src/test/resources/keystore.jks -Djavax.net.ssl.keyStorePassword=password -Djavax.net.ssl.trustStore=src/test/resources/truststore.jks -Djavax.net.ssl.trustStorePassword=password io.nats.examples.NatsPub tls://localhost:4443 test "hello world"

To run with the completely unverified client:

java -cp build/libs/jnats-{major.minor.patch}-SNAPSHOT.jar:build/libs/jnats-{major.minor.patch}-SNAPSHOT-examples.jar io.nats.examples.NatsSub opentls://localhost:4443 test 3

There are a set tls configuration for the server in the test files that can be used to run the NATS server.

nats-server --conf src/test/resources/tls.conf

As well as one with the verify flag set.

nats-server --conf src/test/resources/tlsverify.conf

which will require client certificates.

pFad - (p)hone/(F)rame/(a)nonymizer/(d)eclutterfier! Saves Data!