Merge branch 'develop'

Author: Ian Craggs

.gitattributes

@@ -0,0 +1,15 @@
+# Set the default behavior, in case people don't have core.autocrlf set.
+#* text=auto
+
+# Explicitly declare text files you want to always be normalized and converted
+# to native line endings on checkout.
+*.java text
+*.xml text
+*.md text
+*.html text
+*.yml text
+*.sh text
+
+*.class binary
+*.jar binary
+*.png binary

.gitignore

@@ -59,3 +59,6 @@ Icon
 # Maven
 log/
 target/
+
+
+*.log.*

.travis.yml

@@ -1,23 +1,31 @@
 sudo: true
 language: java
-
+install: true
 matrix:
   include:
     - os: linux
       dist: trusty
       sudo: required
+      jdk: oraclejdk8
 #    - os: osx
+#      jdk: oraclejdk8
+
+
+
 
 sudo: required
 
 before_install:
-  - ./travis-install.sh
+  - ./start-broker.sh
 
-script: 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
+script:
+  - mvn -B clean -q
+  - mvn -B --projects org.eclipse.paho.client.mqttv3,org.eclipse.paho.client.mqttv3.test test -q
+  - mvn -B --projects org.eclipse.paho.mqttv5.common,org.eclipse.paho.mqttv5.client,org.eclipse.paho.mqttv5.client.test test -q
 
-addons:
-  apt:
-    sources:
-      - sourceline: 'ppa:mosquitto-dev/mosquitto-ppa'
-    packages:
-      - mosquitto
+#addons:
+#  apt:
+#    sources:
+#      - sourceline: 'ppa:mosquitto-dev/mosquitto-ppa'
+#    packages:
+#      - mosquitto

CONTRIBUTING.md

@@ -1,66 +1,134 @@
-# Contributing to Paho
-
-Thanks for your interest in this project!
-
-You can contribute bugfixes and new features by sending pull requests through GitHub.
-
-## Legal
-
-In order for your contribution to be accepted, it must comply with the Eclipse Foundation IP policy.
-
-Please read the [Eclipse Foundation policy on accepting contributions via Git](http://wiki.eclipse.org/Development_Resources/Contributing_via_Git).
-
-1. Sign the [Eclipse ECA](http://www.eclipse.org/legal/ECA.php)
-  1. Register for an Eclipse Foundation User ID. You can register [here](https://dev.eclipse.org/site_login/createaccount.php).
-  2. Log into the [Eclipse projects forge](https://www.eclipse.org/contribute/cla), and click on 'Eclipse Contributor Agreement'.
-2. Go to your [account settings](https://dev.eclipse.org/site_login/myaccount.php#open_tab_accountsettings) and add your GitHub username to your account.
-3. Make sure that you _sign-off_ your Git commits in the following format:
-  ``` Signed-off-by: Alex Smith <alexsmith@nowhere.com> ``` This is usually at the bottom of the commit message. You can automate this by adding the '-s' flag when you make the commits. e.g.   ```git commit -s -m "Adding a cool feature"```
-4. Ensure that the email address that you make your commits with is the same one you used to sign up to the Eclipse Foundation website with.
-
-## Contributing a change
-
-1. [Fork the repository on GitHub](https://github.com/eclipse/paho.mqtt.java/fork)
-2. Clone the forked repository onto your computer: ``` git clone https://github.com/<your username>/paho.mqtt.java.git ```
-3. Create a new branch from the latest ```develop``` branch with ```git checkout -b YOUR_BRANCH_NAME origin/develop```
-4. Make your changes
-5. If developing a new feature, make sure to include JUnit tests.
-6. Ensure that all new and existing tests pass.
-7. Commit the changes into the branch: ``` git commit -s ``` Make sure that your commit message is meaningful and describes your changes correctly.
-8. If you have a lot of commits for the change, squash them into a single / few commits.
-9. Push the changes in your branch to your forked repository.
-10. Finally, go to [https://github.com/eclipse/paho.mqtt.java](https://github.com/eclipse/paho.mqtt.java) and create a pull request from your "YOUR_BRANCH_NAME" branch to the ```develop``` one to request review and merge of the commits in your pushed branch.
-
-
-What happens next depends on the content of the patch. If it is 100% authored
-by the contributor and is less than 1000 lines (and meets the needs of the
-project), then it can be pulled into the main repository. If not, more steps
-are required. These are detailed in the
-[legal process poster](http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf).
-
-
-
-## Developer resources:
-
-
-Information regarding source code management, builds, coding standards, and more.
-
-- [https://projects.eclipse.org/projects/iot.paho/developer](https://projects.eclipse.org/projects/iot.paho/developer)
-
-Contact:
---------
-
-Contact the project developers via the project's development
-[mailing list](https://dev.eclipse.org/mailman/listinfo/paho-dev).
-
-Search for bugs:
-----------------
-
-This project uses GitHub Issues here: [github.com/eclipse/paho.mqtt.java/issues](https://github.com/eclipse/paho.mqtt.java/issues) to track ongoing development and issues.
-
-Create a new bug:
------------------
-
-Be sure to search for existing bugs before you create another one. Remember that contributions are always welcome!
-
-- [Create new Paho bug](https://github.com/eclipse/paho.mqtt.java/issues/new)
+# Contributing to Paho
+
+Thanks for your interest in this project!
+
+You can contribute bugfixes and new features by sending pull requests through GitHub.
+
+## Legal
+
+In order for your contribution to be accepted, it must comply with the Eclipse Foundation IP policy.
+
+Please read the [Eclipse Foundation policy on accepting contributions via Git](http://wiki.eclipse.org/Development_Resources/Contributing_via_Git).
+
+1. Sign the [Eclipse ECA](http://www.eclipse.org/legal/ECA.php)
+  1. Register for an Eclipse Foundation User ID. You can register [here](https://dev.eclipse.org/site_login/createaccount.php).
+  2. Log into the [Eclipse projects forge](https://www.eclipse.org/contribute/cla), and click on 'Eclipse Contributor Agreement'.
+2. Go to your [account settings](https://dev.eclipse.org/site_login/myaccount.php#open_tab_accountsettings) and add your GitHub username to your account.
+3. Make sure that you _sign-off_ your Git commits in the following format:
+  ``` Signed-off-by: Alex Smith <alexsmith@nowhere.com> ``` This is usually at the bottom of the commit message. You can automate this by adding the '-s' flag when you make the commits. e.g.   ```git commit -s -m "Adding a cool feature"```
+4. Ensure that the email address that you make your commits with is the same one you used to sign up to the Eclipse Foundation website with.
+
+## Contributing a change
+
+1. [Fork the repository on GitHub](https://github.com/eclipse/paho.mqtt.java/fork)
+2. Clone the forked repository onto your computer: ``` git clone https://github.com/<your username>/paho.mqtt.java.git ```
+3. Create a new branch from the latest ```develop``` branch with ```git checkout -b YOUR_BRANCH_NAME origin/develop```
+4. Make your changes
+5. If developing a new feature, make sure to include JUnit tests.
+6. Ensure that all new and existing tests pass.
+7. Commit the changes into the branch: ``` git commit -s ``` Make sure that your commit message is meaningful and describes your changes correctly.
+8. If you have a lot of commits for the change, squash them into a single / few commits.
+9. Push the changes in your branch to your forked repository.
+10. Finally, go to [https://github.com/eclipse/paho.mqtt.java](https://github.com/eclipse/paho.mqtt.java) and create a pull request from your "YOUR_BRANCH_NAME" branch to the ```develop``` one to request review and merge of the commits in your pushed branch.
+
+
+What happens next depends on the content of the patch. If it is 100% authored
+by the contributor and is less than 1000 lines (and meets the needs of the
+project), then it can be pulled into the main repository. If not, more steps
+are required. These are detailed in the
+[legal process poster](http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf).
+
+
+
+## Developer resources:
+
+
+Information regarding source code management, builds, coding standards, and more.
+
+- [https://projects.eclipse.org/projects/iot.paho/developer](https://projects.eclipse.org/projects/iot.paho/developer)
+
+Contact:
+--------
+
+Contact the project developers via the project's development
+[mailing list](https://dev.eclipse.org/mailman/listinfo/paho-dev).
+
+Search for bugs:
+----------------
+
+This project uses GitHub Issues here: [github.com/eclipse/paho.mqtt.java/issues](https://github.com/eclipse/paho.mqtt.java/issues) to track ongoing development and issues.
+
+Create a new bug:
+-----------------
+
+Be sure to search for existing bugs before you create another one. Remember that contributions are always welcome!
+
+- [Create new Paho bug](https://github.com/eclipse/paho.mqtt.java/issues/new)
+=======
+# Contributing to Paho
+
+Thanks for your interest in this project!
+
+You can contribute bugfixes and new features by sending pull requests through GitHub.
+
+## Legal
+
+In order for your contribution to be accepted, it must comply with the Eclipse Foundation IP policy.
+
+Please read the [Eclipse Foundation policy on accepting contributions via Git](http://wiki.eclipse.org/Development_Resources/Contributing_via_Git).
+
+1. Sign the [Eclipse ECA](http://www.eclipse.org/legal/ECA.php)
+  1. Register for an Eclipse Foundation User ID. You can register [here](https://dev.eclipse.org/site_login/createaccount.php).
+  2. Log into the [Eclipse projects forge](https://www.eclipse.org/contribute/cla), and click on 'Eclipse Contributor Agreement'.
+2. Go to your [account settings](https://dev.eclipse.org/site_login/myaccount.php#open_tab_accountsettings) and add your GitHub username to your account.
+3. Make sure that you _sign-off_ your Git commits in the following format:
+  ``` Signed-off-by: Alex Smith <alexsmith@nowhere.com> ``` This is usually at the bottom of the commit message. You can automate this by adding the '-s' flag when you make the commits. e.g.   ```git commit -s -m "Adding a cool feature"```
+4. Ensure that the email address that you make your commits with is the same one you used to sign up to the Eclipse Foundation website with.
+
+## Contributing a change
+
+1. [Fork the repository on GitHub](https://github.com/eclipse/paho.mqtt.java/fork)
+2. Clone the forked repository onto your computer: ``` git clone https://github.com/<your username>/paho.mqtt.java.git ```
+3. Create a new branch from the latest ```develop``` branch with ```git checkout -b YOUR_BRANCH_NAME origin/develop```
+4. Make your changes
+5. If developing a new feature, make sure to include JUnit tests.
+6. Ensure that all new and existing tests pass.
+7. Commit the changes into the branch: ``` git commit -s ``` Make sure that your commit message is meaningful and describes your changes correctly.
+8. If you have a lot of commits for the change, squash them into a single / few commits.
+9. Push the changes in your branch to your forked repository.
+10. Finally, go to [https://github.com/eclipse/paho.mqtt.java](https://github.com/eclipse/paho.mqtt.java) and create a pull request from your "YOUR_BRANCH_NAME" branch to the ```develop``` one to request review and merge of the commits in your pushed branch.
+
+
+What happens next depends on the content of the patch. If it is 100% authored
+by the contributor and is less than 1000 lines (and meets the needs of the
+project), then it can be pulled into the main repository. If not, more steps
+are required. These are detailed in the
+[legal process poster](http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf).
+
+
+
+## Developer resources:
+
+
+Information regarding source code management, builds, coding standards, and more.
+
+- [https://projects.eclipse.org/projects/iot.paho/developer](https://projects.eclipse.org/projects/iot.paho/developer)
+
+Contact:
+--------
+
+Contact the project developers via the project's development
+[mailing list](https://dev.eclipse.org/mailman/listinfo/paho-dev).
+
+Search for bugs:
+----------------
+
+This project uses GitHub Issues here: [github.com/eclipse/paho.mqtt.java/issues](https://github.com/eclipse/paho.mqtt.java/issues) to track ongoing development and issues.
+
+Create a new bug:
+-----------------
+
+Be sure to search for existing bugs before you create another one. Remember that contributions are always welcome!
+
+- [Create new Paho bug](https://github.com/eclipse/paho.mqtt.java/issues/new)
+

MQTTv3.md

@@ -0,0 +1,117 @@
+# Eclipse Paho Java MQTTv3 Client
+
+The Paho Java Client provides two APIs: MqttAsyncClient provides a fully asychronous API where completion of activities is notified via registered callbacks. MqttClient is a synchronous wrapper around MqttAsyncClient where functions appear synchronous to the application.
+
+## Using the Paho Java MQTTv3 Client
+
+### Downloading
+
+Eclipse hosts a Nexus repository for those who want to use Maven to manage their dependencies. The released libraries are also available in the Maven Central repository.
+
+Add the repository definition and the dependency definition shown below to your pom.xml.
+
+Replace %REPOURL% with either ``` https://repo.eclipse.org/content/repositories/paho-releases/ ``` for the official releases, or ``` https://repo.eclipse.org/content/repositories/paho-snapshots/  ``` for the nightly snapshots. Replace %VERSION% with the level required .
+The latest release version is ```1.2.0``` and the current snapshot version is ```1.2.1-SNAPSHOT```.
+
+```
+<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>
+
+```
+
+If you find that there is functionality missing or bugs in the release version, you may want to try using the snapshot version to see if this helps before raising a feature request or an issue.
+
+### Building from source
+
+There are two active branches on the Paho Java git repository, ```master``` which is used to produce stable releases, and ```develop``` where active development is carried out. By default cloning the git repository will download the ```master``` branch, to build from ```develop``` make sure you switch to the remote branch: ``` git checkout -b develop remotes/origin/develop ```
+
+To then build the library run the following maven command: ```mvn package -DskipTests```
+
+This will build the client library without running the tests. The jars for the library, source and javadoc can be found in the ```org.eclipse.paho.client.mqttv3/target``` directory.
+
+## Documentation
+Reference documentation is online at: [http://www.eclipse.org/paho/files/javadoc/index.html](http://www.eclipse.org/paho/files/javadoc/index.html)
+
+Log and Debug in the Java Client: [https://wiki.eclipse.org/Paho/Log_and_Debug_in_the_Java_client](https://wiki.eclipse.org/Paho/Log_and_Debug_in_the_Java_client)
+
+## Getting Started
+
+The included code below is a very basic sample that connects to a server and publishes a message using the MqttClient synchronous API. More extensive samples demonstrating the use of the Asynchronous API can be found in the ```org.eclipse.paho.sample.mqttv3app``` directory of the source.
+
+
+```
+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();
+        }
+    }
+}
+```
+
+## Adding custom headers for Websocket connection
+
+The included code below is a extended basic sample that connects to a server with custom headers.
+
+```
+MqttClient client = new MqttClient("wss://<BROKER_URI>", "MyClient");
+
+MqttConnectOptions connectOptions = new MqttConnectOptions();
+Properties properties = new Properties();
+properties.setProperty("X-Amz-CustomAuthorizer-Name", <SOME_VALUE>);
+properties.setProperty("X-Amz-CustomAuthorizer-Signature", <SOME_VALUE>);
+properties.setProperty(<SOME_VALUE>, <SOME_VALUE>);
+connectOptions.setCustomWebSocketHeaders(properties);
+
+client.connect(connectOptions);
+
+```