|
1 | 1 | # Eclipse Paho Java Client for MQTTv5 |
2 | 2 |
|
3 | | -_Warning: The Paho MQTTv5 client is under active development and so can expect breaking changes whilst in the develop branch._ |
| 3 | +The v5 client is build on the same foundations as the v3 client is, however it is being heavily refactored using lessons learnt from the v3 client and feedback from the community. Like v3 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. |
4 | 4 |
|
5 | | -This branch of the Paho Java client is the home of the new MQTTv5 client implementation. This is very much a work in progress, so any feedback / and contributions will be appreciated. |
| 5 | +## Using the Paho Java MQTTv5 Client |
6 | 6 |
|
7 | | -The Committee Specification for MQTT Version 5.0 is available to read here: http://docs.oasis-open.org/mqtt/mqtt/v5.0/cs01/mqtt-v5.0-cs01.html. |
| 7 | +### Downloading |
8 | 8 |
|
9 | | -The v5 client is build on the same foundations as the v3 client is, however it is targeting Java 8 and above, allowing us to take advantages of more modern Java APIs to aid development and use. Any important fixes for the core engine can be ported between the two clients to take advantage of any performance or stability improvements. It is also being heavily refactored using lessons learnt from the v3 client and feedback from the community. |
| 9 | +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. |
10 | 10 |
|
11 | | -## Plan |
| 11 | +Add the repository definition and the dependency definition shown below to your pom.xml. |
12 | 12 |
|
13 | | -#### Project Modules: |
14 | | -* `org.eclipse.paho.mqttv5.client` - A full client similar to the existing mqttv3 client |
15 | | -* `org.eclipse.paho.mqttv5.common` - A common library that could be used by both a client and server, contains a packet implementation that encodes and decodes all MQTTv5 packet types. |
16 | | -* `org.eclipse.paho.mqttv5.testClient` - A number of examples written that show off features of the v5 client. |
17 | | -* `org.eclipse.paho.mqttv5.server` - Not yet implemented. There has been some interest in the community for a Java MQTTv5 server using the vert.x framework. Contributions are very welcome. |
| 13 | +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 . |
18 | 14 |
|
19 | | -## Help, something doesn't work! / This looks terrible! / What about x! |
| 15 | +The latest release version is ```1.2.5``` and the current snapshot version is ```1.2.6-SNAPSHOT```. |
20 | 16 |
|
21 | | -This client is under active development and as such may be incomplete / broken a lot of the time right now. However, the more feedback and help we get on it, the better it will get! If you have any issues, please raise a bug against the client [here](https://github.com/eclipse/paho.mqtt.java/issues), but **please** prefix it with 'MQTTv5' so we know that it's not an issue with the current v3.1.1 client. |
| 17 | +``` |
| 18 | +<project ...> |
| 19 | +<repositories> |
| 20 | + <repository> |
| 21 | + <id>Eclipse Paho Repo</id> |
| 22 | + <url>%REPOURL%</url> |
| 23 | + </repository> |
| 24 | +</repositories> |
| 25 | +... |
| 26 | +<dependencies> |
| 27 | + <dependency> |
| 28 | + <groupId>org.eclipse.paho</groupId> |
| 29 | + <artifactId>org.eclipse.paho.mqttv5.client</artifactId> |
| 30 | + <version>%VERSION%</version> |
| 31 | + </dependency> |
| 32 | + <dependency> |
| 33 | + <groupId>org.eclipse.paho</groupId> |
| 34 | + <artifactId>org.eclipse.paho.mqttv5.common</artifactId> |
| 35 | + <version>%VERSION%</version> |
| 36 | + </dependency> |
| 37 | +</dependencies> |
| 38 | +</project> |
22 | 39 |
|
23 | | -If you have any ideas about how the API should be designed going forward, then please chip in on [this](https://github.com/eclipse/paho.mqtt.java/issues/389) issue. |
| 40 | +``` |
| 41 | + |
| 42 | +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. |
| 43 | + |
| 44 | +### Building from source |
| 45 | + |
| 46 | +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 ``` |
| 47 | + |
| 48 | +To then build the library run the following maven command: ```mvn package -DskipTests``` |
| 49 | + |
| 50 | +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.mqttv5.client/target``` and ```org.eclipse.paho.mqttv5.common/target``` directories. |
| 51 | + |
| 52 | +## Documentation |
| 53 | +Reference documentation is online at: [http://www.eclipse.org/paho/files/javadoc/index.html](http://www.eclipse.org/paho/files/javadoc/index.html) |
| 54 | + |
| 55 | +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) |
| 56 | + |
| 57 | +## Getting Started |
| 58 | + |
| 59 | +The included code below is a very basic sample that connects to a server and publishes a message using the MqttClient asynchronous API. More extensive samples demonstrating the use of the Asynchronous API will be added in the ```org.eclipse.paho.sample.mqttv5app``` directory of the source soon. |
| 60 | + |
| 61 | + |
| 62 | +``` |
| 63 | +import org.eclipse.paho.mqttv5.client.MqttAsyncClient; |
| 64 | +import org.eclipse.paho.mqttv5.client.MqttConnectionOptions; |
| 65 | +import org.eclipse.paho.mqttv5.client.IMqttToken; |
| 66 | +import org.eclipse.paho.mqttv5.client.persist.MemoryPersistence; |
| 67 | +import org.eclipse.paho.mqttv5.common.MqttException; |
| 68 | +import org.eclipse.paho.mqttv5.common.MqttMessage; |
| 69 | +import org.eclipse.paho.mqttv5.common.packet.MqttProperties; |
| 70 | +
|
| 71 | +public class MqttPublishSample { |
| 72 | +
|
| 73 | + public static void main(String[] args) { |
| 74 | +
|
| 75 | + String topic = "MQTT Examples"; |
| 76 | + String content = "Message from MqttPublishSample"; |
| 77 | + int qos = 2; |
| 78 | + String broker = "tcp://iot.eclipse.org:1883"; |
| 79 | + String clientId = "JavaSample"; |
| 80 | + MemoryPersistence persistence = new MemoryPersistence(); |
| 81 | +
|
| 82 | + try { |
| 83 | + MqttConnectionOptions connOpts = new MqttConnectionOptions(); |
| 84 | + connOpts.setCleanStart(false); |
| 85 | + MqttAsyncClient sampleClient = new MqttAsyncClient(broker, clientId, persistence); |
| 86 | + System.out.println("Connecting to broker: " + broker); |
| 87 | + IMqttToken token = sampleClient.connect(connOpts); |
| 88 | + token.waitForCompletion(); |
| 89 | + System.out.println("Connected"); |
| 90 | + System.out.println("Publishing message: "+content); |
| 91 | + MqttMessage message = new MqttMessage(content.getBytes()); |
| 92 | + message.setQos(qos); |
| 93 | + token = sampleClient.publish(topic, message); |
| 94 | + token.waitForCompletion(); |
| 95 | + System.out.println("Disconnected"); |
| 96 | + System.out.println("Close client."); |
| 97 | + sampleClient.close(); |
| 98 | + System.exit(0); |
| 99 | + } catch(MqttException me) { |
| 100 | + System.out.println("reason "+me.getReasonCode()); |
| 101 | + System.out.println("msg "+me.getMessage()); |
| 102 | + System.out.println("loc "+me.getLocalizedMessage()); |
| 103 | + System.out.println("cause "+me.getCause()); |
| 104 | + System.out.println("excep "+me); |
| 105 | + me.printStackTrace(); |
| 106 | + } |
| 107 | + } |
| 108 | +} |
| 109 | +``` |
24 | 110 |
|
25 | | -And of course, if you think of an amazing new feature for the v5 client, have a go at implementing it and submit a Pull Request against the develop branch! |
|
0 commit comments