### Run Travis Install Script

Source: https://github.com/eclipse-paho/paho.mqtt.java/wiki/Running-Travis-CI-Builds-Locally

Executes the `travis-install.sh` script, which typically handles project-specific setup and dependency installation as defined for Travis CI builds.

```Shell
./travis-install.sh
```

--------------------------------

### Install Mosquitto Dependencies

Source: https://github.com/eclipse-paho/paho.mqtt.java/wiki/Running-Travis-CI-Builds-Locally

Adds the Mosquitto PPA, updates the package list, and installs the Mosquitto broker along with its dependencies using apt-get. This provides the MQTT server required for testing.

```Shell
sudo -E apt-add-repository -y "ppa:mosquitto-dev/mosquitto-ppa"

sudo -E apt-get -yq update &>> ~/apt-get-update.log

sudo -E apt-get -yq --no-install-suggests --no-install-recommends --force-yes install mosquitto
```

--------------------------------

### Publish MQTT Message using Paho Java MqttClient (Synchronous API)

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/MQTTv3.md

This Java code provides a basic example of how to connect to an MQTT broker and publish a message using the synchronous `MqttClient` API from the Eclipse Paho library. It initializes the client, sets connection options, connects, publishes a message with a specified Quality of Service (QoS), and then disconnects. The example includes basic error handling for `MqttException`.

```Java
import org.eclipse.paho.client.mqttv3.MqttClient;
import org.eclipse.paho.client.mqttv3.MqttConnectOptions;
import org.eclipse.paho.client.mqttv3.MqttException;
import org.eclipse.paho.client.mqttv3.MqttMessage;
import org.eclipse.paho.client.mqttv3.persist.MemoryPersistence;

public class MqttPublishSample {

    public static void main(String[] args) {

        String topic        = "MQTT Examples";
        String content      = "Message from MqttPublishSample";
        int qos             = 2;
        String broker       = "tcp://iot.eclipse.org:1883";
        String clientId     = "JavaSample";
        MemoryPersistence persistence = new MemoryPersistence();

        try {
            MqttClient sampleClient = new MqttClient(broker, clientId, persistence);
            MqttConnectOptions connOpts = new MqttConnectOptions();
            connOpts.setCleanSession(true);
            System.out.println("Connecting to broker: "+broker);
            sampleClient.connect(connOpts);
            System.out.println("Connected");
            System.out.println("Publishing message: "+content);
            MqttMessage message = new MqttMessage(content.getBytes());
            message.setQos(qos);
            sampleClient.publish(topic, message);
            System.out.println("Message published");
            sampleClient.disconnect();
            System.out.println("Disconnected");
            System.exit(0);
        } catch(MqttException me) {
            System.out.println("reason "+me.getReasonCode());
            System.out.println("msg "+me.getMessage());
            System.out.println("loc "+me.getLocalizedMessage());
            System.out.println("cause "+me.getCause());
            System.out.println("excep "+me);
            me.printStackTrace();
        }
    }
}
```

--------------------------------

### Run Maven Tests for Paho MQTT Java

Source: https://github.com/eclipse-paho/paho.mqtt.java/wiki/Running-Travis-CI-Builds-Locally

Executes Maven tests for specific Paho MQTT Java projects. It configures server URIs and ports to run tests against a locally installed Mosquitto instance, simulating the Travis CI test phase.

```Maven
mvn --projects org.eclipse.paho.client.mqttv3,org.eclipse.paho.client.mqttv3.test test -Dtest.server_ssl_port=18885 -Dtest.server_uri=tcp://localhost:1883 -Dtest.server_websocket_uri=ws://localhost:8080 -B
```

--------------------------------

### Clone Forked Paho MQTT Java Repository

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/CONTRIBUTING.md

This command is used to clone a forked version of the Paho MQTT Java repository from GitHub to your local machine. Replace `<your username>` with your actual GitHub username to get your personal copy.

```Shell
git clone https://github.com/<your username>/paho.mqtt.java.git
```

--------------------------------

### Hudson Build Goal for Nexus Staging Release

Source: https://github.com/eclipse-paho/paho.mqtt.java/wiki/Steps-for-Creating-a-Release

An example of a Maven build goal configured within Hudson CI to release a previously staged repository to Nexus. It specifies the project to release and requires a staging repository ID obtained from a prior step.

```Shell
nexus-staging:release -pl org.eclipse.paho.client.mqttv3 -am -DstagingRepositoryId=orgeclipsepaho-1023
```

--------------------------------

### Publish MQTT Message Asynchronously in Java

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/MQTTv5.md

This Java example demonstrates how to connect to an MQTT broker, publish a message to a specified topic with a given QoS, and then disconnect, using the Eclipse Paho MQTT v5 asynchronous API. It utilizes `MqttAsyncClient` for non-blocking operations and `MemoryPersistence` for client state. The code handles `MqttException` for error reporting, printing details like reason code, message, and cause.

```java
import org.eclipse.paho.mqttv5.client.MqttAsyncClient;
import org.eclipse.paho.mqttv5.client.MqttConnectionOptions;
import org.eclipse.paho.mqttv5.client.IMqttToken;
import org.eclipse.paho.mqttv5.client.persist.MemoryPersistence;
import org.eclipse.paho.mqttv5.common.MqttException;
import org.eclipse.paho.mqttv5.common.MqttMessage;
import org.eclipse.paho.mqttv5.common.packet.MqttProperties;

public class MqttPublishSample {

    public static void main(String[] args) {

        String topic        = "MQTT Examples";
        String content      = "Message from MqttPublishSample";
        int qos             = 2;
        String broker       = "tcp://iot.eclipse.org:1883";
        String clientId     = "JavaSample";
        MemoryPersistence persistence = new MemoryPersistence();

        try {
            MqttConnectionOptions connOpts = new MqttConnectionOptions();
            connOpts.setCleanStart(false);
            MqttAsyncClient sampleClient = new MqttAsyncClient(broker, clientId, persistence);
            System.out.println("Connecting to broker: " + broker);
            IMqttToken token = sampleClient.connect(connOpts);
            token.waitForCompletion();
            System.out.println("Connected");
            System.out.println("Publishing message: "+content);
            MqttMessage message = new MqttMessage(content.getBytes());
            message.setQos(qos);
            token = sampleClient.publish(topic, message);
            token.waitForCompletion();
            System.out.println("Disconnected");
            System.out.println("Close client.");
            sampleClient.close();
            System.exit(0);
        } catch(MqttException me) {
            System.out.println("reason "+me.getReasonCode());
            System.out.println("msg "+me.getMessage());
            System.out.println("loc "+me.getLocalizedMessage());
            System.out.println("cause "+me.getCause());
            System.out.println("excep "+me);
            me.printStackTrace();
        }
    }
}
```

--------------------------------

### Publish MQTT Message with QoS 0 (Shell)

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/org.eclipse.paho.sample.mqttclient/README.md

Publishes a simple 'Hello World' message to the 'world' topic with a Quality of Service (QoS) level of 0, ensuring at-most-once delivery.

```Shell
./mqtt-client -pub -h tcp://iot.eclipse.org:1883 -t world -m "Hello World" -q 0
```

--------------------------------

### Eclipse Paho Java Sample Programs for MQTT Client Usage

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/org.eclipse.paho.client.mqttv3/src/main/java/org/eclipse/paho/client/mqttv3/package-info.html

Lists various sample programs available within the Eclipse Paho project that demonstrate different ways to implement MQTT applications. These samples showcase the use of blocking clients, asynchronous clients with callbacks, and asynchronous clients that wait on operation tokens.

```APIDOC
Sample Programs:
  - org.eclipse.paho.sample.mqttv3app.Sample: Uses the blocking client interface.
  - org.eclipse.paho.sample.mqttv3app.SampleAsyncCallBack: Uses the asynchronous client with callbacks which are notified when an operation completes.
  - org.eclipse.paho.sample.mqttv3app.SampleAsyncWait: Uses the asynchronous client and shows how to use the token returned from each operation to block until the operation completes.
```

--------------------------------

### Basic MQTT Client Operation Flow

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/org.eclipse.paho.client.mqttv3/src/main/java/org/eclipse/paho/client/mqttv3/package-info.html

Describes the fundamental steps to interact with an MQTT server using the Paho Java client, including instantiation, connection, message exchange (publish/subscribe), and disconnection.

```APIDOC
1. Create an instance of {@link org.eclipse.paho.client.mqttv3.MqttClient} or {@link org.eclipse.paho.client.mqttv3.MqttAsyncClient}, providing the address of an MQTT server and a unique client identifier.
2. `connect` to the server
3. Exchange messages with the server:
    *   `publish messages` to the server specifying a `topic` as the destination on the server
    *   `subscribe` to one more `topics`. The server will send any messages it receives on those topics to the client. The client will be informed when a message arrives via a `callback`
4. `disconnect` from the server.
```

--------------------------------

### Publish File Content to MQTT Topic (Shell)

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/org.eclipse.paho.sample.mqttclient/README.md

Publishes the entire content of the 'alice.txt' file as a single message to the 'world' topic.

```Shell
./mqtt-client -pub -h tcp://iot.eclipse.org:1883 -t world -f alice.txt
```

--------------------------------

### Run Paho MQTT Utility JAR

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/org.eclipse.paho.sample.utility/utility.md

Command to execute the Paho MQTT Utility JAR file from the command line after downloading or building it. Users must substitute the correct filename based on the version.

```Shell
java -jar org.eclipse.paho.mqtt.utility-1.2.6-SNAPSHOT.jar
```

--------------------------------

### Publish All Stdin Content to MQTT Topic (Shell)

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/org.eclipse.paho.sample.mqttclient/README.md

Pipes all content from standard input (e.g., a file) as a single message to the 'world' MQTT topic.

```Shell
cat alice.txt | ./mqtt-client -pub -h tcp://iot.eclipse.org:1883 -t world --stdin
```

--------------------------------

### Subscribe to MQTT Topic with QoS 0 (Shell)

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/org.eclipse.paho.sample.mqttclient/README.md

Subscribes to the 'world' topic with a Quality of Service (QoS) level of 0, meaning messages will be delivered at-most-once.

```Shell
./mqtt-client -sub -h tcp://iot.eclipse.org:1883 -t world -q 0
```

--------------------------------

### Build Paho Java Client with Maven

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/MQTTv5.md

Maven command to build the Paho Java client library from source, specifically skipping tests. The compiled JARs, including source and Javadoc, will be generated and located in the `org.eclipse.paho.mqttv5.client/target` directory.

```Bash
mvn package -DskipTests
```

--------------------------------

### Publish Stdin Line-by-Line to MQTT Topic (Shell)

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/org.eclipse.paho.sample.mqttclient/README.md

Pipes input from standard input (e.g., a continuously updated log file) line by line to the 'world' MQTT topic. Each line becomes a separate message.

```Shell
tail -f /var/log/system.log | ./mqtt-client -pub -h tcp://iot.eclipse.org:1883 -t world --stdin-line
```

--------------------------------

### MQTT Topic Subscription Rules

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/org.eclipse.paho.client.mqttv3/src/main/java/org/eclipse/paho/client/mqttv3/package-info.html

Explains the rules for subscribing and unsubscribing to MQTT topics, including the use of absolute and wildcarded topics.

```APIDOC
When subscribing for messages the subscription can be for an absolute topic or a wildcarded topic.
When unsubscribing the topic to be unsubscribed must match one specified on an earlier subscribe.
```

--------------------------------

### Build Paho MQTT Utility JAR with Maven

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/org.eclipse.paho.sample.utility/utility.md

Instructions to build the Paho MQTT Utility JAR locally using Maven, skipping tests. This command should be executed from the parent directory of the project.

```Shell
mvn package -DskipTests
```

--------------------------------

### Subscribe with Wildcard and Print Topic Name (Shell)

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/org.eclipse.paho.sample.mqttclient/README.md

Subscribes to topics matching the 'world/#' wildcard with QoS 0. The -V flag ensures that the incoming topic name is printed along with the message, which is useful when using wildcards.

```Shell
./mqtt-client -sub -h tcp://iot.eclipse.org:1883 -t world/# -q 0 -V
```

--------------------------------

### Navigate to Repository Directory

Source: https://github.com/eclipse-paho/paho.mqtt.java/wiki/Running-Travis-CI-Builds-Locally

Changes the current working directory to the cloned 'paho.mqtt.java' repository. This is a prerequisite for running project-specific build commands.

```Shell
cd paho.mqtt.java
```

--------------------------------

### Maven Release Preparation Commands

Source: https://github.com/eclipse-paho/paho.mqtt.java/wiki/Steps-for-Creating-a-Release

Commands used to prepare the Maven project for a new release, which typically involves updating POM files with the new release version. The second command serves as a fallback if the primary 'release:prepare' command encounters issues.

```Maven
mvn release:prepare
mvn release:update-versions -DautoVersionSubmodules=true
```

--------------------------------

### Publish MQTTv5 Message (Shell)

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/org.eclipse.paho.sample.mqttclient/README.md

Publishes a message using the MQTT version 5 protocol to a compatible broker, specifying the protocol version with the -v 5 flag.

```Shell
./mqtt-client -pub -h tcp://iot.eclipse.org:1883 -t world -m "This is an MQTTv5 message" -v 5
```

--------------------------------

### Add Maven Dependency for Paho MQTTv5 Client

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/MQTTv5.md

Instructions for adding the Eclipse Paho MQTTv5 Java client as a dependency in a Maven `pom.xml` file. This includes defining a repository for Paho releases or snapshots and the artifact dependency. Users must replace placeholders for the repository URL and version.

```XML
<project ...>
<repositories>
    <repository>
        <id>Eclipse Paho Repo</id>
        <url>%REPOURL%</url>
    </repository>
</repositories>
...
<dependencies>
    <dependency>
        <groupId>org.eclipse.paho</groupId>
        <artifactId>org.eclipse.paho.mqttv5.client</artifactId>
        <version>%VERSION%</version>
    </dependency>
</dependencies>
</project>
```

--------------------------------

### Build Paho Java Client from Source using Maven

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/README.md

This Maven command compiles the Paho Java Client library from its source code. The `-DskipTests` flag ensures that the build process completes without running the extensive test suite, which can significantly reduce build time during development or when only the compiled artifacts are needed.

```Shell
mvn package -DskipTests
```

--------------------------------

### Run Travis CI Docker Container

Source: https://github.com/eclipse-paho/paho.mqtt.java/wiki/Running-Travis-CI-Builds-Locally

Downloads and runs the specified Travis CI Docker image in detached interactive mode, naming it 'travis-debug'. This command initializes the local Travis environment.

```Shell
docker run --name travis-debug -dit travisci/ci-garnet:packer-1499451976 /sbin/init
```

--------------------------------

### Connect MQTT Client with Will Message (Shell)

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/org.eclipse.paho.sample.mqttclient/README.md

Demonstrates how to connect the MQTT client to a broker including a will message. The will message (-wp) and will topic (-wt) are specified. Optional arguments for will retain (-wr) and will QoS (-wq) can also be used. If the connection is lost, the broker will forward the will message to subscribers.

```Shell
./mqtt-client -sub -h tcp://iot.eclipse.org:1883 -t world -q 0 -wt status -wp "I have disconnected"
```

--------------------------------

### Add Maven Dependency for Eclipse Paho Java MQTTv3 Client

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/MQTTv3.md

This XML snippet demonstrates how to configure a Maven `pom.xml` file to include the Eclipse Paho Java MQTTv3 client as a project dependency. It specifies the repository URL for Paho releases/snapshots and the artifact coordinates. Users must replace placeholders for the repository URL and version.

```XML
<project ...>
<repositories>
    <repository>
        <id>Eclipse Paho Repo</id>
        <url>%REPOURL%</url>
    </repository>
</repositories>
...
<dependencies>
    <dependency>
        <groupId>org.eclipse.paho</groupId>
        <artifactId>org.eclipse.paho.client.mqttv3</artifactId>
        <version>%VERSION%</version>
    </dependency>
</dependencies>
</project>
```

--------------------------------

### Switch Git Branch for Paho Java Development

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/MQTTv5.md

Command to switch to the `develop` branch of the Paho Java client repository for active development. This allows users to work with the latest features and bug fixes before they are included in stable releases.

```Bash
git checkout -b develop remotes/origin/develop
```

--------------------------------

### Clone Paho MQTT Java Repository

Source: https://github.com/eclipse-paho/paho.mqtt.java/wiki/Running-Travis-CI-Builds-Locally

Clones the Eclipse Paho MQTT Java repository from GitHub. The command limits the history depth for faster cloning and checks out the 'develop' branch.

```Shell
git clone --depth=50 --branch=develop https://github.com/eclipse/paho.mqtt.java.git
```

--------------------------------

### Add Maven Dependency for Paho MQTTv5 Java Client

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/README.md

This XML snippet shows how to add the Eclipse Paho MQTTv5 Java client library as a dependency in a Maven `pom.xml` file. It includes the necessary repository definition and the dependency artifact for MQTTv5. Ensure you replace `%REPOURL%` with the correct Paho repository URL and `%VERSION%` with the specific library version you intend to use.

```XML
<project ...>
<repositories>
    <repository>
        <id>Eclipse Paho Repo</id>
        <url>%REPOURL%</url>
    </repository>
</repositories>
...
<dependencies>
    <dependency>
        <groupId>org.eclipse.paho</groupId>
        <artifactId>org.eclipse.paho.mqttv5.client</artifactId>
        <version>%VERSION%</version>
    </dependency>
</dependencies>
</project>
```

--------------------------------

### Add Maven Dependency for Paho MQTTv3 Java Client

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/README.md

This XML snippet demonstrates how to include the Eclipse Paho MQTTv3 Java client library as a dependency in a Maven `pom.xml` file. It requires adding the Paho repository and the specific MQTTv3 artifact. Remember to substitute `%REPOURL%` with the appropriate Paho repository URL (e.g., `https://repo.eclipse.org/content/repositories/paho-releases/`) and `%VERSION%` with the desired library version (e.g., `1.2.5`).

```XML
<project ...>
<repositories>
    <repository>
        <id>Eclipse Paho Repo</id>
        <url>%REPOURL%</url>
    </repository>
</repositories>
...
<dependencies>
    <dependency>
        <groupId>org.eclipse.paho</groupId>
        <artifactId>org.eclipse.paho.client.mqttv3</artifactId>
        <version>%VERSION%</version>
    </dependency>
</dependencies>
</project>
```

--------------------------------

### Set Travis Environment Variables

Source: https://github.com/eclipse-paho/paho.mqtt.java/wiki/Running-Travis-CI-Builds-Locally

Sets the `TRAVIS_OS_NAME` environment variable to 'linux' and prepends `/usr/sbin` to the `PATH`. These variables configure the environment to mimic a standard Travis CI build.

```Shell
export TRAVIS_OS_NAME=linux && export PATH="/usr/sbin:$PATH"
```

--------------------------------

### Switch Git Branch to Develop for Paho Java Client

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/README.md

This shell command allows developers to switch their local Git repository to the `develop` branch, which is used for active development of the Paho Java Client. This is necessary when building from source if you want to access the latest features or bug fixes not yet included in a stable release.

```Shell
git checkout -b develop remotes/origin/develop
```

--------------------------------

### Eclipse Paho Java MqttConnectOptions for Connection Configuration

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/org.eclipse.paho.client.mqttv3/src/main/java/org/eclipse/paho/client/mqttv3/package-info.html

Describes the `MqttConnectOptions` class, which allows users to customize various aspects of the MQTT connection beyond default settings. This includes configuring the clean session flag, specifying a list of alternative MQTT servers, setting a keepalive interval, defining a last will and testament message, and providing security credentials.

```APIDOC
org.eclipse.paho.client.mqttv3.MqttConnectOptions MqttConnectOptions:
  Description: Can be used to override the default connection options.
  Configurable Options:
    - Setting the cleansession flag.
    - Specifying a list of MQTT servers that the client can attempt to connect to.
    - Set a keepalive interval.
    - Setting the last will and testament.
    - Setting security credentials.
```

--------------------------------

### Publish MQTT Message using Paho Java Synchronous API

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/README.md

This Java code snippet demonstrates how to connect to an MQTT broker, publish a message to a specified topic with a given Quality of Service (QoS), and then disconnect. It utilizes the Eclipse Paho MQTTv3 synchronous API and includes basic exception handling for MQTT operations.

```Java
import org.eclipse.paho.client.mqttv3.MqttClient;
import org.eclipse.paho.client.mqttv3.MqttConnectOptions;
import org.eclipse.paho.client.mqttv3.MqttException;
import org.eclipse.paho.client.mqttv3.MqttMessage;
import org.eclipse.paho.client.mqttv3.persist.MemoryPersistence;

public class MqttPublishSample {

    public static void main(String[] args) {

        String topic        = "MQTT Examples";
        String content      = "Message from MqttPublishSample";
        int qos             = 2;
        String broker       = "tcp://iot.eclipse.org:1883";
        String clientId     = "JavaSample";
        MemoryPersistence persistence = new MemoryPersistence();

        try {
            MqttClient sampleClient = new MqttClient(broker, clientId, persistence);
            MqttConnectOptions connOpts = new MqttConnectOptions();
            connOpts.setCleanSession(true);
            System.out.println("Connecting to broker: "+broker);
            sampleClient.connect(connOpts);
            System.out.println("Connected");
            System.out.println("Publishing message: "+content);
            MqttMessage message = new MqttMessage(content.getBytes());
            message.setQos(qos);
            sampleClient.publish(topic, message);
            System.out.println("Message published");
            sampleClient.disconnect();
            System.out.println("Disconnected");
            System.exit(0);
        } catch(MqttException me) {
            System.out.println("reason "+me.getReasonCode());
            System.out.println("msg "+me.getMessage());
            System.out.println("loc "+me.getLocalizedMessage());
            System.out.println("cause "+me.getCause());
            System.out.println("excep "+me);
            me.printStackTrace();
        }
    }
}
```

--------------------------------

### Open Login Shell in Docker Container

Source: https://github.com/eclipse-paho/paho.mqtt.java/wiki/Running-Travis-CI-Builds-Locally

Executes a login bash shell inside the running 'travis-debug' Docker container, allowing interactive access to the emulated Travis environment.

```Shell
docker exec -it travis-debug bash -l
```

--------------------------------

### MQTT Message Persistence for Reliability

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/org.eclipse.paho.client.mqttv3/src/main/java/org/eclipse/paho/client/mqttv3/package-info.html

Details how the Paho client ensures reliable message delivery across network, client, and server outages by using a persistent store, defaulting to a file-based persistence mechanism.

```APIDOC
For message delivery to be reliable and withstand normal and abnormal network breaks together with client and server outages the client must use a persistent store to hold messages while they are being delivered. This is the default case where a file based persistent store {@link org.eclipse.paho.client.mqttv3.persist.MqttDefaultFilePersistence MqttDefaultFilePersistence} is used.
```

--------------------------------

### MQTT Client Identifier Requirements

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/org.eclipse.paho.client.mqttv3/src/main/java/org/eclipse/paho/client/mqttv3/package-info.html

Explains the requirement for a unique client identifier for each MQTT client instance connecting to a server and the implications of duplicate IDs.

```APIDOC
Every client instance that connects to an MQTT server must have a unique client identifier. If a second instance of a client with the same ID connects to a server the first instance will be disconnected.
```

--------------------------------

### Git Command to Tag and Sign Release

Source: https://github.com/eclipse-paho/paho.mqtt.java/wiki/Steps-for-Creating-a-Release

A Git command used to create an annotated and cryptographically signed tag for a new release version on GitHub. This tag includes a descriptive message for the release.

```Git
git tag -a -s v1.2.2 -m "Version 1.2.2 - service release"
```

--------------------------------

### Switch to Travis User in Container

Source: https://github.com/eclipse-paho/paho.mqtt.java/wiki/Running-Travis-CI-Builds-Locally

Switches the current user to 'travis' within the Docker container. This is crucial as Travis CI typically runs builds under this specific user.

```Shell
su - travis
```

--------------------------------

### Eclipse Paho Java MqttAsyncClient for Non-Blocking Operations

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/org.eclipse.paho.client.mqttv3/src/main/java/org/eclipse/paho/client/mqttv3/package-info.html

Describes the `MqttAsyncClient` interface, which provides a non-blocking approach to MQTT operations. It outlines three primary methods for monitoring the completion of these asynchronous operations: using `IMqttToken#waitForCompletion`, providing an `IMqttActionListener`, or setting a `MqttCallback` on the client.

```APIDOC
org.eclipse.paho.client.mqttv3.IMqttAsyncClient MqttAsyncClient:
  Description: Provides a non-blocking interface where methods return before the requested operation has completed.
  Completion Monitoring:
    - Use org.eclipse.paho.client.mqttv3.IMqttToken#waitForCompletion on the token returned from the operation. This will block until the operation completes.
    - Pass a org.eclipse.paho.client.mqttv3.IMqttActionListener to the operation. The listener will then be called back when the operation completes.
    - Set a org.eclipse.paho.client.mqttv3.MqttCallback on the client. It will be notified when a message arrives, a message has been delivered to the server, and when the connection to the server is lost.
```

--------------------------------

### Checkout Specific Git Commit (Optional)

Source: https://github.com/eclipse-paho/paho.mqtt.java/wiki/Running-Travis-CI-Builds-Locally

Checks out a specific commit by its hash. This step is optional but useful for testing against a particular version of the codebase that might have issues.

```Shell
git checkout ec51902
```

--------------------------------

### Connect to MQTT over WebSocket with Custom Headers in Java

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/MQTTv3.md

This Java code snippet illustrates how to establish an MQTT connection over WebSocket while including custom HTTP headers. It utilizes `MqttConnectOptions` to set a `Map` of string key-value pairs for headers such as `X-Amz-CustomAuthorizer-Name` and `X-Amz-CustomAuthorizer-Signature` before initiating the connection with `MqttClient`.

```Java
MqttClient client = new MqttClient("wss://<BROKER_URI>", "MyClient");

MqttConnectOptions connectOptions = new MqttConnectOptions();
Map<String, String> properties = new HashMap<>();
properties.put("X-Amz-CustomAuthorizer-Name", <SOME_VALUE>);
properties.put("X-Amz-CustomAuthorizer-Signature", <SOME_VALUE>);
properties.put(<SOME_KEY>, <SOME_VALUE>);
connectOptions.setCustomWebSocketHeaders(properties);

client.connect(connectOptions);
```

--------------------------------

### Automate Git Commit Sign-off

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/CONTRIBUTING.md

This command demonstrates how to automatically add the 'Signed-off-by' line to a Git commit message using the '-s' flag. This simplifies the process of ensuring compliance with contribution policies during development.

```Shell
git commit -s -m "Adding a cool feature"
```

--------------------------------

### Specify Git Commit Sign-off Format

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/CONTRIBUTING.md

This snippet illustrates the required format for the 'Signed-off-by' line in Git commit messages. This is crucial for complying with the Eclipse Foundation's IP policy and acknowledging contributions.

```Shell
Signed-off-by: Alex Smith <alexsmith@nowhere.com>
```

--------------------------------

### Impact of MqttConnectOptions.setCleanSession(boolean)

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/org.eclipse.paho.client.mqttv3/src/main/java/org/eclipse/paho/client/mqttv3/package-info.html

Describes the significant effects of the 'clean session' option on client operation, including message delivery guarantees, server-side state storage, and session cleansing upon connection or disconnection.

```APIDOC
When connecting the {@link org.eclipse.paho.client.mqttv3.MqttConnectOptions#setCleanSession(boolean) cleansession} option has a big impact on the operation of the client. If set to false:
    *   Message delivery will match the quality of service specified when the message was published even across failures of the network, client or server
    *   The server will store messages for active subscriptions on behalf of the client when the client is not connected. The server will deliver these messages to the client the next time it connects.
If set to true:
    *   Any state stored on the client and server related to the client will be cleansed before the connection is fully started. Subscriptions from earlier sessions will be unsubscribed and any messages still in-flight from previous sessions will be deleted.
    *   When the client disconnects either as the result of the application requesting a disconnect or a network failure, state related to the client will be cleansed just as at connect time.
    *   Messages will only be delivered to the quality of service requested at publish time if the connection is maintained while the message is being delivered
```

--------------------------------

### Eclipse Paho Java MqttClient for Blocking Operations

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/org.eclipse.paho.client.mqttv3/src/main/java/org/eclipse/paho/client/mqttv3/package-info.html

Details the `MqttClient` interface, which offers a blocking approach to MQTT operations. With this client, methods will pause execution until the requested operation has successfully completed.

```APIDOC
org.eclipse.paho.client.mqttv3.IMqttClient MqttClient:
  Description: Methods block until the operation has completed.
```

--------------------------------

### Create New Feature Branch from Develop

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/CONTRIBUTING.md

This command creates a new Git branch named `YOUR_BRANCH_NAME` based on the latest `develop` branch. It's an essential step for isolating your changes and preparing them for a pull request.

```Shell
git checkout -b YOUR_BRANCH_NAME origin/develop
```

--------------------------------

### Eclipse Paho Java MqttCallback for Asynchronous Notifications

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/org.eclipse.paho.client.mqttv3/src/main/java/org/eclipse/paho/client/mqttv3/package-info.html

Explains the role of `MqttCallback` in receiving asynchronous notifications for both blocking and non-blocking clients. This callback mechanism is crucial for handling events such as incoming messages (`messageArrived`), connection disconnections (`connectionLost`), and confirmation of message delivery (`deliveryComplete`).

```APIDOC
Asynchronous Operations (common to both blocking and non-blocking clients):
  Notifications via org.eclipse.paho.client.mqttv3.MqttCallback:
    - messageArrived: Notification that a new message has arrived.
    - connectionLost: Notification that the connection to the server has broken.
    - deliveryComplete: Notification that a message has been delivered to the server.
  Client registers interest in these notifications by registering a MqttCallback on the client.
```

--------------------------------

### Commit Changes with Sign-off

Source: https://github.com/eclipse-paho/paho.mqtt.java/blob/master/CONTRIBUTING.md

This command commits the staged changes to the current Git branch, automatically adding the sign-off line. After executing, you will be prompted to provide a meaningful commit message describing your changes.

```Shell
git commit -s
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.