Skip to content

Commit 556fa63

Browse files
author
Maik Scheibler
committed
Merge remote-tracking branch 'eclipse/develop' into NetworkModule_SPI
Conflicts: org.eclipse.paho.client.mqttv3/src/main/java/org/eclipse/paho/client/mqttv3/MqttConnectOptions.java Signed-off-by: Maik Scheibler <eclipse@scheibler-family.de>
2 parents 314246c + 7416251 commit 556fa63

214 files changed

Lines changed: 31476 additions & 140 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.travis.yml‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,12 @@ matrix:
1111
sudo: required
1212

1313
before_install:
14-
- ./travis-install.sh
14+
- ./start-broker.sh
1515

16-
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
16+
script:
17+
- mvn clean
18+
- mvn --projects org.eclipse.paho.client.mqttv3,org.eclipse.paho.client.mqttv3.test test
19+
- mvn --projects org.eclipse.paho.mqttv5.common,org.eclipse.paho.mqttv5.client test
1720

1821
addons:
1922
apt:

‎MQTTv3.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Eclipse Paho Java MQTTv3 Client
2+
3+
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+
5+
## Using the Paho Java MQTTv3 Client
6+
7+
### Downloading
8+
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+
11+
Add the repository definition and the dependency definition shown below to your pom.xml.
12+
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 .
14+
The latest release version is ```1.2.0``` and the current snapshot version is ```1.2.1-SNAPSHOT```.
15+
16+
```
17+
<project ...>
18+
<repositories>
19+
<repository>
20+
<id>Eclipse Paho Repo</id>
21+
<url>%REPOURL%</url>
22+
</repository>
23+
</repositories>
24+
...
25+
<dependencies>
26+
<dependency>
27+
<groupId>org.eclipse.paho</groupId>
28+
<artifactId>org.eclipse.paho.client.mqttv3</artifactId>
29+
<version>%VERSION%</version>
30+
</dependency>
31+
</dependencies>
32+
</project>
33+
34+
```
35+
36+
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.
37+
38+
### Building from source
39+
40+
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 ```
41+
42+
To then build the library run the following maven command: ```mvn package -DskipTests```
43+
44+
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.
45+
46+
## Documentation
47+
Reference documentation is online at: [http://www.eclipse.org/paho/files/javadoc/index.html](http://www.eclipse.org/paho/files/javadoc/index.html)
48+
49+
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)
50+
51+
## Getting Started
52+
53+
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.
54+
55+
56+
```
57+
import org.eclipse.paho.client.mqttv3.MqttClient;
58+
import org.eclipse.paho.client.mqttv3.MqttConnectOptions;
59+
import org.eclipse.paho.client.mqttv3.MqttException;
60+
import org.eclipse.paho.client.mqttv3.MqttMessage;
61+
import org.eclipse.paho.client.mqttv3.persist.MemoryPersistence;
62+
63+
public class MqttPublishSample {
64+
65+
public static void main(String[] args) {
66+
67+
String topic = "MQTT Examples";
68+
String content = "Message from MqttPublishSample";
69+
int qos = 2;
70+
String broker = "tcp://iot.eclipse.org:1883";
71+
String clientId = "JavaSample";
72+
MemoryPersistence persistence = new MemoryPersistence();
73+
74+
try {
75+
MqttClient sampleClient = new MqttClient(broker, clientId, persistence);
76+
MqttConnectOptions connOpts = new MqttConnectOptions();
77+
connOpts.setCleanSession(true);
78+
System.out.println("Connecting to broker: "+broker);
79+
sampleClient.connect(connOpts);
80+
System.out.println("Connected");
81+
System.out.println("Publishing message: "+content);
82+
MqttMessage message = new MqttMessage(content.getBytes());
83+
message.setQos(qos);
84+
sampleClient.publish(topic, message);
85+
System.out.println("Message published");
86+
sampleClient.disconnect();
87+
System.out.println("Disconnected");
88+
System.exit(0);
89+
} catch(MqttException me) {
90+
System.out.println("reason "+me.getReasonCode());
91+
System.out.println("msg "+me.getMessage());
92+
System.out.println("loc "+me.getLocalizedMessage());
93+
System.out.println("cause "+me.getCause());
94+
System.out.println("excep "+me);
95+
me.printStackTrace();
96+
}
97+
}
98+
}
99+
```
100+

‎MQTTv5.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Eclipse Paho Java Client for MQTTv5
2+
3+
_Warning: The Paho MQTTv5 client is under active development and so can expect breaking changes whilst in the develop branch._
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.
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.
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.
10+
11+
## Plan
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.
18+
19+
## Help, something doesn't work! / This looks terrible! / What about x!
20+
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.
22+
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.
24+
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!

‎README.md‎

Lines changed: 11 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,22 @@
11
# Eclipse Paho Java Client
2-
[![Build Status](https://travis-ci.org/eclipse/paho.mqtt.java.svg?branch=master)](https://travis-ci.org/eclipse/paho.mqtt.java)
3-
4-
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
5-
6-
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.
2+
[![Build Status](https://travis-ci.org/eclipse/paho.mqtt.java.svg?branch=develop)](https://travis-ci.org/eclipse/paho.mqtt.java)
73

4+
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. This Project contains a number of Maven projects allowing you to use and test MQTTv3 and MQTTv5.
85

96
## Project description:
107

118
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).
129
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.
1310

11+
## Client Libraries and Utilities
12+
- [MQTTv3 Library](MQTTv3.md) - The Original Paho MQTTv3 Library, supports MQTT version 3.1 and 3.1.1.
13+
- [MQTTv5 Library](MQTTv5.md) - The New Paho MQTTv5 Library based on the original, Currently under active development, supports MQTT version 5.
14+
- [Paho Utility App](org.eclipse.paho.sample.utility/utility.md) - A useful lightweight MQTT GUI utility. (V3 Only)
15+
- [Paho Eclipse View](org.eclipse.paho.client.eclipse.view) - An Eclipse View similar to the Utility. (V3 Only)
16+
- [Mqttv3app](org.eclipse.paho.sample.mqttv3app) - Sample Application using the MQTTv3 Client.
17+
18+
19+
1420

1521
## Links
1622

@@ -22,98 +28,3 @@ Paho reflects the inherent physical and cost constraints of device connectivity.
2228
- Issues: [https://github.com/eclipse/paho.mqtt.java/issues](https://github.com/eclipse/paho.mqtt.java/issues)
2329
- Mailing-list: [https://dev.eclipse.org/mailman/listinfo/paho-dev](https://dev.eclipse.org/mailman/listinfo/paho-dev)
2430

25-
## Using the Paho Java Client
26-
27-
### Downloading
28-
29-
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.
30-
31-
Add the repository definition and the dependency definition shown below to your pom.xml.
32-
33-
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 .
34-
The latest release version is ```1.2.0``` and the current snapshot version is ```1.2.1-SNAPSHOT```.
35-
36-
```
37-
<project ...>
38-
<repositories>
39-
<repository>
40-
<id>Eclipse Paho Repo</id>
41-
<url>%REPOURL%</url>
42-
</repository>
43-
</repositories>
44-
...
45-
<dependencies>
46-
<dependency>
47-
<groupId>org.eclipse.paho</groupId>
48-
<artifactId>org.eclipse.paho.client.mqttv3</artifactId>
49-
<version>%VERSION%</version>
50-
</dependency>
51-
</dependencies>
52-
</project>
53-
54-
```
55-
56-
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.
57-
58-
### Building from source
59-
60-
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 ```
61-
62-
To then build the library run the following maven command: ```mvn package -DskipTests```
63-
64-
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.
65-
66-
## Documentation
67-
Reference documentation is online at: [http://www.eclipse.org/paho/files/javadoc/index.html](http://www.eclipse.org/paho/files/javadoc/index.html)
68-
69-
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)
70-
71-
## Getting Started
72-
73-
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.
74-
75-
76-
```
77-
import org.eclipse.paho.client.mqttv3.MqttClient;
78-
import org.eclipse.paho.client.mqttv3.MqttConnectOptions;
79-
import org.eclipse.paho.client.mqttv3.MqttException;
80-
import org.eclipse.paho.client.mqttv3.MqttMessage;
81-
import org.eclipse.paho.client.mqttv3.persist.MemoryPersistence;
82-
83-
public class MqttPublishSample {
84-
85-
public static void main(String[] args) {
86-
87-
String topic = "MQTT Examples";
88-
String content = "Message from MqttPublishSample";
89-
int qos = 2;
90-
String broker = "tcp://iot.eclipse.org:1883";
91-
String clientId = "JavaSample";
92-
MemoryPersistence persistence = new MemoryPersistence();
93-
94-
try {
95-
MqttClient sampleClient = new MqttClient(broker, clientId, persistence);
96-
MqttConnectOptions connOpts = new MqttConnectOptions();
97-
connOpts.setCleanSession(true);
98-
System.out.println("Connecting to broker: "+broker);
99-
sampleClient.connect(connOpts);
100-
System.out.println("Connected");
101-
System.out.println("Publishing message: "+content);
102-
MqttMessage message = new MqttMessage(content.getBytes());
103-
message.setQos(qos);
104-
sampleClient.publish(topic, message);
105-
System.out.println("Message published");
106-
sampleClient.disconnect();
107-
System.out.println("Disconnected");
108-
System.exit(0);
109-
} catch(MqttException me) {
110-
System.out.println("reason "+me.getReasonCode());
111-
System.out.println("msg "+me.getMessage());
112-
System.out.println("loc "+me.getLocalizedMessage());
113-
System.out.println("cause "+me.getCause());
114-
System.out.println("excep "+me);
115-
me.printStackTrace();
116-
}
117-
}
118-
}
119-
```

‎org.eclipse.paho.client.mqttv3.test/src/test/java/org/eclipse/paho/client/mqttv3/internal/NetworkModuleServiceTest.java‎

Lines changed: 32 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
import static org.junit.Assert.assertEquals;
1111
import static org.junit.Assert.assertNull;
1212
import static org.junit.Assert.assertTrue;
13+
import static org.junit.Assert.fail;
1314

1415
public class NetworkModuleServiceTest {
1516

@@ -21,24 +22,49 @@ public void testValidateURI() {
2122
NetworkModuleService.validateURI("wss://host_literal:443/path/to/ws");
2223
}
2324

24-
@Test(expected = IllegalArgumentException.class)
25+
public void failEmptyUri() {
26+
try {
27+
NetworkModuleService.validateURI("");
28+
fail("Must fail: Empty URI");
29+
} catch (IllegalArgumentException e) {
30+
assertEquals("missing scheme in broker URI: ", e.getMessage());
31+
}
32+
}
33+
34+
@Test
2535
public void failInvalidUri() {
26-
NetworkModuleService.validateURI("no URI at all");
36+
try {
37+
NetworkModuleService.validateURI("no URI at all");
38+
fail("Must fail: Can't parse string to URI");
39+
} catch (IllegalArgumentException e) {
40+
assertEquals("Can't parse string to URI \"no URI at all\"", e.getMessage());
41+
}
2742
}
2843

29-
@Test(expected = IllegalArgumentException.class)
44+
@Test
3045
public void failWithPathOnTcpUri() {
31-
NetworkModuleService.validateURI("tcp://host_literal:1883/somePath");
46+
try {
47+
NetworkModuleService.validateURI("tcp://host_literal:1883/somePath");
48+
fail("Must fail: URI path must be empty");
49+
} catch (IllegalArgumentException e) {
50+
assertEquals("URI path must be empty \"tcp://host_literal:1883/somePath\"", e.getMessage());
51+
}
3252
}
3353

3454
@Test(expected = IllegalArgumentException.class)
3555
public void failWithPathOnSslUri() {
3656
NetworkModuleService.validateURI("ssl://host_literal:1883/somePath");
3757
}
3858

39-
@Test(expected = IllegalArgumentException.class)
59+
@Test
4060
public void failWithUnsuppurtedSchemeUri() {
41-
NetworkModuleService.validateURI("unknown://host_literal:1883");
61+
try {
62+
NetworkModuleService.validateURI("unknown://host_literal:1883");
63+
fail("Must fail: Unknow scheme");
64+
} catch (IllegalArgumentException e) {
65+
assertEquals("no NetworkModule installed for scheme \"unknown\" of URI \"unknown://host_literal:1883\"", e
66+
.getMessage());
67+
}
4268
}
4369

4470
/**

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

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,8 @@ SERVER_URI=tcp://localhost:1883
44
CLIENT_KEY_STORE=clientkeystore.jks
55
CLIENT_KEY_STORE_PASSWORD=password
66
CLIENT_TRUST_STORE=clientkeystore.jks
7-
SERVER_SSL_PORT=18884
8-
SERVER_WEBSOCKET_URI=ws://localhost:8080
9-
7+
SERVER_SSL_PORT=18885
8+
SERVER_WEBSOCKET_URI=ws://localhost:1883
109

1110
# The list of server URIs which may be set in the MQTT ConnectOptions for an HA testcase.
1211
# There is no default value

‎org.eclipse.paho.client.mqttv3/src/main/java/org/eclipse/paho/client/mqttv3/IMqttAsyncClient.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -116,7 +116,7 @@
116116
* also be notified when a message has been delivered to the requested quality of service.</p>
117117
*
118118
*/
119-
public interface IMqttAsyncClient {
119+
public interface IMqttAsyncClient extends AutoCloseable {
120120
/**
121121
* Connects to an MQTT server using the default options.
122122
* <p>The default options are specified in {@link MqttConnectOptions} class.

‎org.eclipse.paho.client.mqttv3/src/main/java/org/eclipse/paho/client/mqttv3/IMqttClient.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@
5959
* style. The blocking client provides compatibility with earlier versions
6060
* of the MQTT client.</p>
6161
*/
62-
public interface IMqttClient { //extends IMqttAsyncClient {
62+
public interface IMqttClient extends AutoCloseable { //extends IMqttAsyncClient {
6363
/**
6464
* Connects to an MQTT server using the default options.
6565
* <p>The default options are specified in {@link MqttConnectOptions} class.

‎org.eclipse.paho.client.mqttv3/src/main/java/org/eclipse/paho/client/mqttv3/MqttClientPersistence.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@
3232
* It is up to the persistence interface to log any exceptions or error information
3333
* which may be required when diagnosing a persistence failure.</p>
3434
*/
35-
public interface MqttClientPersistence {
35+
public interface MqttClientPersistence extends AutoCloseable {
3636
/**
3737
* Initialise the persistent store.
3838
* If a persistent store exists for this client ID then open it, otherwise

‎org.eclipse.paho.client.mqttv3/src/main/java/org/eclipse/paho/client/mqttv3/internal/NetworkModuleService.java‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -67,9 +67,10 @@ public static void validateURI(String brokerUri) throws IllegalArgumentException
6767
return;
6868
}
6969
}
70-
throw new IllegalArgumentException("no NetworkModule installed for URI scheme: " + brokerUri);
70+
throw new IllegalArgumentException("no NetworkModule installed for scheme \"" + scheme
71+
+ "\" of URI \"" + brokerUri + "\"");
7172
} catch (URISyntaxException e) {
72-
throw new IllegalArgumentException(brokerUri, e);
73+
throw new IllegalArgumentException("Can't parse string to URI \"" + brokerUri + "\"", e);
7374
}
7475
}
7576

0 commit comments

Comments
 (0)