Merge pull request #2 from jpwsutton/develop

Updating the Contributing and Readme files

Author: icraggs

CONTRIBUTING.md

@@ -1,83 +1,62 @@
-Contributing to Paho
-====================
+# Contributing to Paho
 
-Thanks for your interest in this project.
+Thanks for your interest in this project!
 
-Project description:
---------------------
+You can contribute bugfixes and new features by sending pull requests through GitHub.
 
-The Paho project has been created to provide reliable open-source implementations of open and standard messaging protocols aimed at new, existing, and emerging applications for Machine-to-Machine (M2M) and Internet of Things (IoT).
-Paho reflects the inherent physical and cost constraints of device connectivity. Its objectives include effective levels of decoupling between devices and applications, designed to keep markets open and encourage the rapid growth of scalable Web and Enterprise middleware and applications. 
+## Legal
 
-- [Project web site](https://www.eclipse.org/paho)
-- [Project information](https://projects.eclipse.org/projects/iot.paho)
+In order for your contribution to be accepted, it must comply with the Eclipse Foundation IP policy.
 
-Source
-------
+Please read the [Eclipse Foundation policy on accepting contributions via Git](http://wiki.eclipse.org/Development_Resources/Contributing_via_Git).
 
-The Paho Java client and Android service are stored in a git repository. The URLs to access it are:
+1. Sign the [Eclipse CLA](http://www.eclipse.org/legal/CLA.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 [Projects Portal](https://projects.eclipse.org/), and click on the '[Eclipse CLA](https://projects.eclipse.org/user/sign/cla)' link.
+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: John Smith <johnsmith@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.
 
-ssh://<username>@git.eclipse.org:29418/paho/org.eclipse.paho.mqtt.java
-https://<username>@git.eclipse.org/r/paho/org.eclipse.paho.mqtt.java
+## Contributing a change
 
-A [web browsable repository](http://git.eclipse.org/c/paho/org.eclipse.paho.mqtt.java.git) is available.
+1. Fork the repository on GitHub
+2. Clone the forked repository onto your computer: ``` git clone https://github.com/eclipse/paho.mqtt.java.git ```
+3. Checkout the remote ```develop``` branch: ``` git checkout -b develop remotes/origin/develop ```
+4. Make your changes
+5. If developing a new feature, make sure to include JUnit tests.
+6. Ensure that all 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 commit.
+9. Push the changes to the develop branch in your forked repository.
+10. Finally, submit a pull request using the normal GitHub Web Interface.
 
-Contributing a patch
---------------------
-
-The Paho repositories are accessed through Gerrit, the code review
-project, which makes it possible for anybody to clone the repository, make
-changes and push them back for review and eventual acceptance into the project.
-
-To do this, you must follow a few steps. The first of these are described at
-
-- [Contributing via git](https://wiki.eclipse.org/Development_Resources/Contributing_via_Git)
-
-* Sign the Eclipse CLA
-* Use a valid commit record, including a signed-off-by entry.
-
-There are further details at
-
-- [Handling Git Contributions](https://wiki.eclipse.org/Development_Resources/Handling_Git_Contributions)
-
-Once the patch is pushed back to Gerrit, the project committers will be
-informed and they will undertake a review of the code. The patch may need
-modifying for some reason. In order to make amending commits more
-straightforward, the steps at
-https://git.eclipse.org/r/Documentation/cmd-hook-commit-msg.html should be
-followed. This automatically inserts a "Change-Id" entry to your commit message
-which allows you to amend commits and have Gerrit track them as the same
-change.
 
 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 committed to the main repository. If not, more steps
-are required. These are detailed in 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.
+## Developer resources:
 
-- [https://projects.eclipse.org/projects/iot.paho/developer](https://projects.eclipse.org/projects/iot.paho/developer)
 
-Contributor License Agreement:
-------------------------------
+Information regarding source code management, builds, coding standards, and more.
 
-Before your contribution can be accepted by the project, you need to create and electronically sign the Eclipse Foundation [Contributor License Agreement (CLA)](http://www.eclipse.org/legal/CLA.php).
+- [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 
+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 [Bugzilla](https://bugs.eclipse.org/bugs/buglist.cgi?product=Paho) to track ongoing development and issues.
+This project currently uses [Bugzilla](https://bugs.eclipse.org/bugs/buglist.cgi?product=Paho) to track ongoing development and issues.
 
 Create a new bug:
 -----------------

README.md

@@ -1 +1,118 @@
-Paho Java client for MQTT
+# Eclipse Paho Java Client
+
+The Paho Java Client is an MQTT client library written in Java for developing applications that run on the JVM or other Java compatible platforms such as Android
+
+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.
+
+
+## Project description:
+
+The Paho project has been created to provide reliable open-source implementations of open and standard messaging protocols aimed at new, existing, and emerging applications for Machine-to-Machine (M2M) and Internet of Things (IoT).
+Paho reflects the inherent physical and cost constraints of device connectivity. Its objectives include effective levels of decoupling between devices and applications, designed to keep markets open and encourage the rapid growth of scalable Web and Enterprise middleware and applications.
+
+
+## Links
+
+- Project Website: [https://www.eclipse.org/paho](https://www.eclipse.org/paho)
+- Eclipse Project Information: [https://projects.eclipse.org/projects/iot.paho](https://projects.eclipse.org/projects/iot.paho)
+- Paho Java Client Page: [https://eclipse.org/paho/clients/java/](https://eclipse.org/paho/clients/java)
+- GitHub: [https://github.com/eclipse/paho.mqtt.java](https://github.com/eclipse/paho.mqtt.java)
+- Twitter: [@eclipsepaho](https://twitter.com/eclipsepaho)
+- Issues: Currently [https://bugs.eclipse.org/bugs/buglist.cgi?component=MQTT-Java](https://bugs.eclipse.org/bugs/buglist.cgi?component=MQTT-Java), though will soon be GitHub Issues.
+- Mailing-list: [https://dev.eclipse.org/mailman/listinfo/paho-dev](https://dev.eclipse.org/mailman/listinfo/paho-dev)
+
+## Using the Paho Java 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.0.2``` and the current snapshot version is ```1.0.3```.
+
+```
+<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.
+
+### Builing 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();
+        }
+    }
+}
+```

org.eclipse.paho.client.mqttv3.test/src/test/resources/test.properties

@@ -4,7 +4,7 @@ SERVER_URI=tcp://iot.eclipse.org:1883
 CLIENT_KEY_STORE=clientkeystore.jks
 CLIENT_KEY_STORE_PASSWORD=password
 CLIENT_TRUST_STORE=clientkeystore.jks
-SERVER_SSL_PORT=8883
+SERVER_SSL_PORT=18884
 SERVER_WEBSOCKET_URI=ws://iot.eclipse.org:80
 
 # The list of server URIs which may be set in the MQTT ConnectOptions for an HA testcase.