Skip to content

Commit da951ea

Browse files
jpwsuttonjpwsutton
committed
Updating package.html to work with latest javadoc standard
Signed-off-by: James Sutton <james.sutton@uk.ibm.com>
1 parent 6c4fa16 commit da951ea

2 files changed

Lines changed: 143 additions & 136 deletions

File tree

‎org.eclipse.paho.client.mqttv3/src/main/java/org/eclipse/paho/client/mqttv3/package-info.html‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
<!DOCTYPE html>
2+
<html>
3+
4+
<head>
5+
<title>Eclipse Paho MQTTv3 Java Client</title>
6+
</head>
7+
8+
<body>
9+
Contains a programming interface enabling applications to communicate with an MQTT server.
10+
<p>The MQ Telemetry Transport (MQTT) is a lightweight broker-based publish/subscribe messaging protocol designed to be open,
11+
simple, lightweight and easy to implement. These characteristics make it ideal for use in constrained environments,
12+
for example, but not limited to:</p>
13+
<ul>
14+
<li>Where the network is expensive, has low bandwidth or is unreliable such as mobile and vsat networks</li>
15+
<li>When run on an embedded or mobile device with limited processor, memory or battery</li>
16+
</ul>
17+
<p>Features of the protocol include:</p>
18+
<ul>
19+
<li>The publish/subscribe message pattern to provide one-to-many message distribution and decoupling of applications</li>
20+
<li>A messaging transport that is agnostic to the content of the payload</li>
21+
<li>The use of TCP/IP to provide network connectivity</li>
22+
<li>The use of SSL/TLS to provide network security and trust</li>
23+
<li>Three qualities of service for message delivery which are maintained across network, client and server breaks.
24+
<ul>
25+
<li>"At most once", where messages are delivered according to the best efforts of the underlying TCP/IP network.
26+
Message loss or duplication can occur. This level could be used, for example, with ambient sensor data
27+
where it does not matter if an individual reading is lost as the next one will be published soon after.</li>
28+
<li>"At least once", where messages are assured to arrive but duplicates may occur.</li>
29+
<li>"Exactly once", where message are assured to arrive exactly once. This level could be used, for example,
30+
with billing systems where duplicate or lost messages could lead to incorrect charges being applied.</li>
31+
</ul>
32+
The quality of service for message delivery is met even if the network connection breaks, or the client or the server stop
33+
while a message is being delivered</li>
34+
<li>A small transport overhead (the fixed-length header is just 2 bytes), and protocol exchanges minimised to reduce
35+
network traffic</li>
36+
<li>A mechanism to notify interested parties to an abnormal disconnection of a client using the Last Will and Testament
37+
feature</li>
38+
</ul>
39+
<p>The basic means of operating the client is:</p>
40+
<ol>
41+
<li>Create an instance of {@link org.eclipse.paho.client.mqttv3.MqttClient} or {@link org.eclipse.paho.client.mqttv3.MqttAsyncClient},
42+
providing the address of an MQTT server and a unique client identifier.</li>
43+
<li>
44+
<code>connect</code> to the server</li>
45+
<li>Exchange messages with the server:
46+
<ul>
47+
<li>
48+
<code>publish messages</code> to the server specifying a
49+
<code>topic</code> as the destination on the server</li>
50+
<li>
51+
<code>subscribe</code> to one more
52+
<code>topics</code>. The server will send any messages it receives on those topics to the client. The client
53+
will be informed when a message arrives via a
54+
<code>callback</code>
55+
</li>
56+
</ul>
57+
</li>
58+
<li>
59+
<code>disconnect</code> from the server.</li>
60+
</ol>
61+
<p>The programming model and concepts like the protocol are small and easy to use. Key concepts to use when creating MQTT
62+
application include:</p>
63+
<ul>
64+
<li>Every client instance that connects to an MQTT server must have a unique client identifier. If a second instance
65+
of a client with the same ID connects to a server the first instance will be disconnected.</li>
66+
<li>For message delivery to be reliable and withstand normal and abnormal network breaks together with client and server
67+
outages the client must use a persistent store to hold messages while they are being delivered. This is the default
68+
case where a file based persistent store {@link org.eclipse.paho.client.mqttv3.persist.MqttDefaultFilePersistence
69+
MqttDefaultFilePersistence} is used.</li>
70+
<li>When connecting the {@link org.eclipse.paho.client.mqttv3.MqttConnectOptions#setCleanSession(boolean) cleansession}
71+
option has a big impact on the operation of the client. If set to false:
72+
<ul>
73+
<li>Message delivery will match the quality of service specified when the message was published even across failures
74+
of the network, client or server</li>
75+
<li>The server will store messages for active subscriptions on behalf of the client when the client is not connected.
76+
The server will deliver these messages to the client the next time it connects.</li>
77+
</ul>
78+
If set to true:
79+
<ul>
80+
<li>Any state stored on the client and server related to the client will be cleansed before the connection is
81+
fully started. Subscriptions from earlier sessions will be unsubscribed and any messages still in-flight
82+
from previous sessions will be deleted.</li>
83+
<li>When the client disconnects either as the result of the application requesting a disconnect or a network
84+
failure, state related to the client will be cleansed just as at connect time.</li>
85+
<li>Messages will only be delivered to the quality of service requested at publish time if the connection is
86+
maintained while the message is being delivered</li>
87+
</ul>
88+
</li>
89+
<li>When subscribing for messages the subscription can be for an absolute topic or a wildcarded topic.</li>
90+
<li>When unsubscribing the topic to be unsubscribed must match one specified on an earlier subscribe.</li>
91+
<li>There are two MQTT client libraries to choose from:
92+
<ol>
93+
<li>{@link org.eclipse.paho.client.mqttv3.IMqttAsyncClient MqttAsyncClient} which provides a non-blocking interface
94+
where methods return before the requested operation has completed. The completion of the operation can
95+
be monitored by in several ways:
96+
<ul>
97+
<li>Use the {@link org.eclipse.paho.client.mqttv3.IMqttToken#waitForCompletion waitForCompletion} call
98+
on the token returned from the operation. This will block until the operation completes.</li>
99+
<li>Pass a {@link org.eclipse.paho.client.mqttv3.IMqttActionListener IMqttActionListener} to the operation.
100+
The listener will then be called back when the operation completes.</li>
101+
<li>Set a {@link org.eclipse.paho.client.mqttv3.MqttCallback MqttCallback} on the client. It will be
102+
notified when a message arrives, a message have been delivered to the server and when the connection
103+
to the server is lost.</li>
104+
</ul>
105+
</li>
106+
<li>{@link org.eclipse.paho.client.mqttv3.IMqttClient MqttClient} where methods block until the operation has
107+
completed.</li>
108+
</ol>
109+
</li>
110+
<li>For both the blocking and non-blocking clients some operations are asynchronous. This includes:
111+
<ul>
112+
<li>Notification that a new message has arrived: {@link org.eclipse.paho.client.mqttv3.MqttCallback#messageArrived
113+
messageArrived}.</li>
114+
<li>Notification that the connection to the server has broken: {@link org.eclipse.paho.client.mqttv3.MqttCallback#connectionLost
115+
connectionLost}.</li>
116+
<li>Notification that a message has been delivered to the server: {@link org.eclipse.paho.client.mqttv3.MqttCallback#deliveryComplete
117+
deliveryComplete}.</li>
118+
</ul>
119+
A client registers interest in these notifications by registering a {@link org.eclipse.paho.client.mqttv3.MqttCallback MqttCallback}
120+
on the client</li>
121+
<li>There are a number of programs that demonstrate the different modes of writing MQTT applications
122+
<ul>
123+
<li>{@link org.eclipse.paho.sample.mqttv3app.Sample} uses the blocking client interface</li>
124+
<li>{@link org.eclipse.paho.sample.mqttv3app.SampleAsyncCallBack} uses the asynchronous client with callbacks
125+
which are notified when an operation completes</li>
126+
<li>{@link org.eclipse.paho.sample.mqttv3app.SampleAsyncWait} uses the asynchronous client and shows how to use
127+
the token returned from each operation to block until the operation completes.</li>
128+
</ul>
129+
</li>
130+
<li>{@link org.eclipse.paho.client.mqttv3.MqttConnectOptions MqttConnectOptions} can be used to override the default
131+
connection options. This includes:
132+
<ul>
133+
<li>Setting the cleansession flag</li>
134+
<li>Specifying a list of MQTT servers that the client can attempt to connect to</li>
135+
<li>Set a keepalive interval</li>
136+
<li>Setting the last will and testament</li>
137+
<li>Setting security credentials</li>
138+
</ul>
139+
</li>
140+
</ul>
141+
</body>
142+
143+
</html>

‎org.eclipse.paho.client.mqttv3/src/main/java/org/eclipse/paho/client/mqttv3/package.html‎

Lines changed: 0 additions & 136 deletions
This file was deleted.

0 commit comments

Comments
 (0)