Skip to content

Commit f9171cd

Browse files
author
Ian Craggs
committed
Update doc to match the master branch
1 parent c4892ac commit f9171cd

3 files changed

Lines changed: 196 additions & 76 deletions

File tree

‎CODE_OF_CONDUCT.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Community Code of Conduct
2+
3+
## Our Pledge
4+
5+
As members of the Eclipse community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting code reviews, pull requests, patches, and other activities.
6+
7+
## Our Standards
8+
9+
We are committed to making participation in the Eclipse community a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion or analogous grounds.
10+
11+
Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
12+
13+
## Our Responsibilities
14+
15+
Eclipse Foundation staff have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project leaders, committers and contributors who do not follow the Code of Conduct may be removed from the project.
16+
17+
## Scope
18+
19+
This code of conduct applies within Eclipse project spaces, or in public spaces when an individual is representing the project or the Eclipse community.
20+
21+
## Enforcement
22+
23+
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by emailing the Eclipse Management Organization: codeofconduct@eclipse.org.
24+
25+
## Attribution
26+
27+
This Code of Conduct is adapted from the Contributor Covenant (http://contributor-covenant.org), version 1.1.0, available at http://contributor-covenant.org/version/1/1/0/
28+
29+
The Eclipse Code Of Conduct can also be viewed [here](https://eclipse.org/org/documents/Community_Code_of_Conduct.php).

‎CONTRIBUTING.md‎

Lines changed: 66 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,66 @@
1-
# Contributing to Paho
2-
3-
Thanks for your interest in this project!
4-
5-
You can contribute bugfixes and new features by sending pull requests through GitHub.
6-
7-
## Legal
8-
9-
In order for your contribution to be accepted, it must comply with the Eclipse Foundation IP policy.
10-
11-
Please read the [Eclipse Foundation policy on accepting contributions via Git](http://wiki.eclipse.org/Development_Resources/Contributing_via_Git).
12-
13-
1. Sign the [Eclipse CLA](http://www.eclipse.org/legal/CLA.php)
14-
1. Register for an Eclipse Foundation User ID. You can register [here](https://dev.eclipse.org/site_login/createaccount.php).
15-
2. Log into the [Projects Portal](https://projects.eclipse.org/), and click on the '[Eclipse CLA](https://projects.eclipse.org/user/sign/cla)' link.
16-
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.
17-
3. Make sure that you _sign-off_ your Git commits in the following format:
18-
``` 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"```
19-
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.
20-
21-
## Contributing a change
22-
23-
1. [Fork the repository on GitHub](https://github.com/eclipse/paho.mqtt.java/fork)
24-
2. Clone the forked repository onto your computer: ``` git clone https://github.com/<your username>/paho.mqtt.java.git ```
25-
3. Create a new branch from the latest ```develop``` branch with ```git checkout -b YOUR_BRANCH_NAME origin/develop```
26-
4. Make your changes
27-
5. If developing a new feature, make sure to include JUnit tests.
28-
6. Ensure that all new and existing tests pass.
29-
7. Commit the changes into the branch: ``` git commit -s ``` Make sure that your commit message is meaningful and describes your changes correctly.
30-
8. If you have a lot of commits for the change, squash them into a single / few commits.
31-
9. Push the changes in your branch to your forked repository.
32-
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.
33-
34-
35-
What happens next depends on the content of the patch. If it is 100% authored
36-
by the contributor and is less than 1000 lines (and meets the needs of the
37-
project), then it can be pulled into the main repository. If not, more steps
38-
are required. These are detailed in the
39-
[legal process poster](http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf).
40-
41-
42-
43-
## Developer resources:
44-
45-
46-
Information regarding source code management, builds, coding standards, and more.
47-
48-
- [https://projects.eclipse.org/projects/iot.paho/developer](https://projects.eclipse.org/projects/iot.paho/developer)
49-
50-
Contact:
51-
--------
52-
53-
Contact the project developers via the project's development
54-
[mailing list](https://dev.eclipse.org/mailman/listinfo/paho-dev).
55-
56-
Search for bugs:
57-
----------------
58-
59-
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.
60-
61-
Create a new bug:
62-
-----------------
63-
64-
Be sure to search for existing bugs before you create another one. Remember that contributions are always welcome!
65-
66-
- [Create new Paho bug](https://github.com/eclipse/paho.mqtt.java/issues/new)
1+
# Contributing to Paho
2+
3+
Thanks for your interest in this project!
4+
5+
You can contribute bugfixes and new features by sending pull requests through GitHub.
6+
7+
## Legal
8+
9+
In order for your contribution to be accepted, it must comply with the Eclipse Foundation IP policy.
10+
11+
Please read the [Eclipse Foundation policy on accepting contributions via Git](http://wiki.eclipse.org/Development_Resources/Contributing_via_Git).
12+
13+
1. Sign the [Eclipse ECA](http://www.eclipse.org/legal/ECA.php)
14+
1. Register for an Eclipse Foundation User ID. You can register [here](https://dev.eclipse.org/site_login/createaccount.php).
15+
2. Log into the [Eclipse projects forge](https://www.eclipse.org/contribute/cla), and click on 'Eclipse Contributor Agreement'.
16+
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.
17+
3. Make sure that you _sign-off_ your Git commits in the following format:
18+
``` 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"```
19+
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.
20+
21+
## Contributing a change
22+
23+
1. [Fork the repository on GitHub](https://github.com/eclipse/paho.mqtt.java/fork)
24+
2. Clone the forked repository onto your computer: ``` git clone https://github.com/<your username>/paho.mqtt.java.git ```
25+
3. Create a new branch from the latest ```develop``` branch with ```git checkout -b YOUR_BRANCH_NAME origin/develop```
26+
4. Make your changes
27+
5. If developing a new feature, make sure to include JUnit tests.
28+
6. Ensure that all new and existing tests pass.
29+
7. Commit the changes into the branch: ``` git commit -s ``` Make sure that your commit message is meaningful and describes your changes correctly.
30+
8. If you have a lot of commits for the change, squash them into a single / few commits.
31+
9. Push the changes in your branch to your forked repository.
32+
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.
33+
34+
35+
What happens next depends on the content of the patch. If it is 100% authored
36+
by the contributor and is less than 1000 lines (and meets the needs of the
37+
project), then it can be pulled into the main repository. If not, more steps
38+
are required. These are detailed in the
39+
[legal process poster](http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf).
40+
41+
42+
43+
## Developer resources:
44+
45+
46+
Information regarding source code management, builds, coding standards, and more.
47+
48+
- [https://projects.eclipse.org/projects/iot.paho/developer](https://projects.eclipse.org/projects/iot.paho/developer)
49+
50+
Contact:
51+
--------
52+
53+
Contact the project developers via the project's development
54+
[mailing list](https://dev.eclipse.org/mailman/listinfo/paho-dev).
55+
56+
Search for bugs:
57+
----------------
58+
59+
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.
60+
61+
Create a new bug:
62+
-----------------
63+
64+
Be sure to search for existing bugs before you create another one. Remember that contributions are always welcome!
65+
66+
- [Create new Paho bug](https://github.com/eclipse/paho.mqtt.java/issues/new)

‎README.md‎

Lines changed: 101 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,16 @@
11
# Eclipse Paho Java Client
22
[![Build Status](https://travis-ci.org/eclipse/paho.mqtt.java.svg?branch=develop)](https://travis-ci.org/eclipse/paho.mqtt.java)
33

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.
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.
7+
58

69
## Project description:
710

811
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).
912
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.
1013

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-
2014

2115
## Links
2216

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

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

0 commit comments

Comments
 (0)