{"id":13470568,"url":"https://github.com/fusesource/mqtt-client","last_synced_at":"2025-05-14T06:11:49.446Z","repository":{"id":2061275,"uuid":"2999669","full_name":"fusesource/mqtt-client","owner":"fusesource","description":"A Java MQTT Client","archived":false,"fork":false,"pushed_at":"2021-09-15T02:33:11.000Z","size":407,"stargazers_count":1275,"open_issues_count":92,"forks_count":368,"subscribers_count":133,"default_branch":"master","last_synced_at":"2025-04-15T08:45:08.023Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://mqtt-client.fusesource.org/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fusesource.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-12-17T05:12:58.000Z","updated_at":"2025-02-13T07:40:41.000Z","dependencies_parsed_at":"2022-08-08T04:00:02.404Z","dependency_job_id":null,"html_url":"https://github.com/fusesource/mqtt-client","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fusesource%2Fmqtt-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fusesource%2Fmqtt-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fusesource%2Fmqtt-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fusesource%2Fmqtt-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fusesource","download_url":"https://codeload.github.com/fusesource/mqtt-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254080065,"owners_count":22011315,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T16:00:32.091Z","updated_at":"2025-05-14T06:11:49.407Z","avatar_url":"https://github.com/fusesource.png","language":"Java","readme":"## Overview\n\nMQTT is a machine-to-machine (M2M)/\"Internet of Things\" connectivity\nprotocol. It was designed as an extremely lightweight publish/subscribe\nmessaging transport. It is useful for connections with remote locations where\na small code footprint is required and/or network bandwidth is at a premium.\n\nmqtt-client provides an ASL 2.0 licensed API to MQTT. It takes care of\nautomatically reconnecting to your MQTT server and restoring your client\nsession if any network failures occur. Applications can use a blocking API\nstyle, a futures based API, or a callback/continuations passing API style.\n\n## Using from Maven\n\nAdd the following to your maven `pom.xml` file.\n\n    \u003cdependency\u003e\n      \u003cgroupId\u003eorg.fusesource.mqtt-client\u003c/groupId\u003e\n      \u003cartifactId\u003emqtt-client\u003c/artifactId\u003e\n      \u003cversion\u003e1.12\u003c/version\u003e\n    \u003c/dependency\u003e\n\t\n## Using from Gradle\n\nAdd the following to your gradle file.\n\n    compile 'org.fusesource.mqtt-client:mqtt-client:1.12'\n\n\n## Using from any Other Build System\n\nDownload the \n[uber jar file](https://repository.jboss.org/nexus/content/groups/fs-public/org/fusesource/mqtt-client/mqtt-client/1.7/mqtt-client-1.7-uber.jar) \nand add it to your build. The uber contains all the stripped down dependencies\nwhich the mqtt-client depends on from other projects.\n\n## Using on Java 1.4\n\nWe also provide an \n[java 1.4 uber jar file](https://repository.jboss.org/nexus/content/groups/fs-public/org/fusesource/mqtt-client/mqtt-client-java1.4-uber/1.7/mqtt-client-java1.4-uber-1.7.jar) \nwhich is compatible with Java 1.4 JVMs.  This version of the jar\ndoes not support SSL connections since the SSLEngine class used to implement SSL on NIO\nwas not introduced until Java 1.5.\n\n## Configuring the MQTT Connection\n\nThe blocking, future, and callback APIs all share the same connection setup.\nYou create a new instance of the `MQTT` class and configure it with connection\nand socket related options. At a minimum the `setHost` method be called before\nattempting to connect.\n\n    MQTT mqtt = new MQTT();\n    mqtt.setHost(\"localhost\", 1883);\n    // or \n    mqtt.setHost(\"tcp://localhost:1883\");\n    \n### Controlling MQTT Options\n\n\n* `setClientId` : Use to set the client Id of the session.  This is what an MQTT server\n  uses to identify a session where `setCleanSession(false);` is being used.  The id must be\n  23 characters or less.  Defaults to auto generated id (based on your socket address, port \n  and timestamp).\n\n* `setCleanSession` : Set to false if you want the MQTT server to persist topic subscriptions\n  and ack positions across client sessions. Defaults to true.\n\n* `setKeepAlive` : Configures the Keep Alive timer in seconds. Defines the maximum time \n  interval between messages received from a client. It enables the server to detect that the \n  network connection to a client has dropped, without having to wait for the long TCP/IP timeout. \n\n* `setUserName` : Sets the user name used to authenticate against the server. \n\n* `setPassword` : Sets the password used to authenticate against the server. \n\n* `setWillTopic`: If set the server will publish the client's Will \n  message to the specified topics if the client has an unexpected \n  disconnection.\n\n* `setWillMessage`:  The Will message to send. Defaults to a zero length message.\n\n* `setWillQos` : Sets the quality of service to use for the Will message.  Defaults\n  to QoS.AT_MOST_ONCE.\n\n* `setWillRetain`: Set to true if you want the Will to be published with the retain \n  option.\n\n* `setVersion`: Set to \"3.1.1\" to use MQTT version 3.1.1.  Otherwise defaults to the\n  3.1 protocol version.\n\n### Controlling Connection Reconnects\n\nConnection will automatically reconnect and re-establish messaging session\nif any network error occurs.  You can control how often the reconnect\nis attempted and define maximum number of attempts of reconnects using\nthe following methods:\n\n* `setConnectAttemptsMax` : The maximum number of reconnect attempts before an error \n  is reported back to the client on the first attempt by the client to connect to a server. Set\n  to -1 to use unlimited attempts.  Defaults to -1.\n* `setReconnectAttemptsMax` : The maximum number of reconnect attempts before an error \n  is reported back to the client after a server connection had previously been established. Set\n  to -1 to use unlimited attempts.  Defaults to -1.\n* `setReconnectDelay` : How long to wait in ms before the first reconnect \n   attempt. Defaults to 10.\n* `setReconnectDelayMax` : The maximum amount of time in ms to wait between \n   reconnect attempts.  Defaults to 30,000.\n* `setReconnectBackOffMultiplier` : The Exponential backoff be used between reconnect \n  attempts. Set to 1 to disable exponential backoff. Defaults to 2.\n\n### Configuring Socket Options\n\nYou can adjust some socket options by using the following methods:\n\n* `setReceiveBufferSize` : Sets the size of the internal socket receive \n   buffer.  Defaults to 65536 (64k)\n\n* `setSendBufferSize` : Sets the size of the internal socket send buffer.  \n   Defaults to 65536 (64k)\n\n* `setTrafficClass` : Sets traffic class or type-of-service octet in the IP \n  header for packets sent from the transport.  Defaults to `8` which\n  means the traffic should be optimized for throughput.\n\n### Throttling Connections\n\nIf you want slow down the read or write rate of your connections, use \nthe following methods:\n\n* `setMaxReadRate` : Sets the maximum bytes per second that this transport will\n  receive data at.  This setting throttles reads so that the rate is not exceeded.\n  Defaults to 0 which disables throttling.\n\n* `setMaxWriteRate` : Sets the maximum bytes per second that this transport will\n  send data at.  This setting throttles writes so that the rate is not exceeded.\n  Defaults to 0 which disables throttling.\n\n### Using SSL connections\n\nIf you want to connect over SSL/TLS instead of TCP, use an \"ssl://\" or\n\"tls://\" URI prefix instead of \"tcp://\" for the `host` field. For finer\ngrained control of which algorithm is used. Supported protocol values are:\n\n* `ssl://`    - Use the JVM default version of the SSL algorithm.\n* `sslv*://`  - Use a specific SSL version where `*` is a version\n  supported by your JVM.  Example: `sslv3`\n* `tls://`    - Use the JVM default version of the TLS algorithm.\n* `tlsv*://`  - Use a specific TLS version where `*` is a version\n  supported by your JVM.  Example: `tlsv1.1`\n\nThe client will use the default JVM `SSLContext` which is configured via JVM\nsystem properties unless you configure the MQTT instance using the\n`setSslContext` method.\n\nSSL connections perform blocking operations against internal thread pool\nunless you call the `setBlockingExecutor` method to configure that executor\nthey will use instead.\n\n### Selecting the Dispatch Queue\n\nA [HawtDispatch](http://hawtdispatch.fusesource.org/) dispatch queue is used\nto synchronize access to the connection. If an explicit queue is not\nconfigured via the `setDispatchQueue` method, then a new queue will be created\nfor the connection. Setting an explicit queue might be handy if you want\nmultiple connection to share the same queue for synchronization.\n\n## Using the Blocking API\n\nThe `MQTT.connectBlocking` method establishes a connection and provides you a connection\nwith an blocking API.\n\n    BlockingConnection connection = mqtt.blockingConnection();\n    connection.connect();\n\nPublish messages to a topic using the `publish` method:\n\n    connection.publish(\"foo\", \"Hello\".getBytes(), QoS.AT_LEAST_ONCE, false);\n\nYou can subscribe to multiple topics using the the `subscribe` method:\n    \n    Topic[] topics = {new Topic(\"foo\", QoS.AT_LEAST_ONCE)};\n    byte[] qoses = connection.subscribe(topics);\n\nThen receive and acknowledge consumption of messages using the `receive`, and `ack`\nmethods:\n    \n    Message message = connection.receive();\n    System.out.println(message.getTopic());\n    byte[] payload = message.getPayload();\n    // process the message then:\n    message.ack();\n\nFinally to disconnect:\n\n    connection.disconnect();\n\n## Using the Future based API\n\nThe `MQTT.connectFuture` method establishes a connection and provides you a connection\nwith an futures style API.  All operations against the connection are non-blocking and\nreturn the result via a Future.\n\n    FutureConnection connection = mqtt.futureConnection();\n    Future\u003cVoid\u003e f1 = connection.connect();\n    f1.await();\n\n    Future\u003cbyte[]\u003e f2 = connection.subscribe(new Topic[]{new Topic(utf8(\"foo\"), QoS.AT_LEAST_ONCE)});\n    byte[] qoses = f2.await();\n\n    // We can start future receive..\n    Future\u003cMessage\u003e receive = connection.receive();\n\n    // send the message..\n    Future\u003cVoid\u003e f3 = connection.publish(\"foo\", \"Hello\".getBytes(), QoS.AT_LEAST_ONCE, false);\n\n    // Then the receive will get the message.\n    Message message = receive.await();\n    message.ack();\n    \n    Future\u003cVoid\u003e f4 = connection.disconnect();\n    f4.await();\n\n\n## Using the Callback/Continuation Passing based API\n\nThe `MQTT.connectCallback` method establishes a connection and provides you a connection with\nan callback style API. This is the most complex to use API style, but can provide the best\nperformance. The future and blocking APIs use the callback api under the covers. All\noperations on the connection are non-blocking and results of an operation are passed to\ncallback interfaces you implement.\n\nExample:\n\n    final CallbackConnection connection = mqtt.callbackConnection();\n    connection.listener(new Listener() {\n      \n        public void onDisconnected() {\n        }\n        public void onConnected() {\n        }\n\n        public void onPublish(UTF8Buffer topic, Buffer payload, Runnable ack) {\n            // You can now process a received message from a topic.\n            // Once process execute the ack runnable.\n            ack.run();\n        }\n        public void onFailure(Throwable value) {\n            connection.close(null); // a connection failure occured.\n        }\n    })\n    connection.connect(new Callback\u003cVoid\u003e() {\n        public void onFailure(Throwable value) {\n            result.failure(value); // If we could not connect to the server.\n        }\n  \n        // Once we connect..\n        public void onSuccess(Void v) {\n        \n            // Subscribe to a topic\n            Topic[] topics = {new Topic(\"foo\", QoS.AT_LEAST_ONCE)};\n            connection.subscribe(topics, new Callback\u003cbyte[]\u003e() {\n                public void onSuccess(byte[] qoses) {\n                    // The result of the subcribe request.\n                }\n                public void onFailure(Throwable value) {\n                    connection.close(null); // subscribe failed.\n                }\n            });\n\n            // Send a message to a topic\n            connection.publish(\"foo\", \"Hello\".getBytes(), QoS.AT_LEAST_ONCE, false, new Callback\u003cVoid\u003e() {\n                public void onSuccess(Void v) {\n                  // the pubish operation completed successfully.\n                }\n                public void onFailure(Throwable value) {\n                    connection.close(null); // publish failed.\n                }\n            });\n            \n            // To disconnect..\n            connection.disconnect(new Callback\u003cVoid\u003e() {\n                public void onSuccess(Void v) {\n                  // called once the connection is disconnected.\n                }\n                public void onFailure(Throwable value) {\n                  // Disconnects never fail.\n                }\n            });\n        }\n    });\n\nEvery connection has a [HawtDispatch](http://hawtdispatch.fusesource.org/) dispatch queue\nwhich it uses to process IO events for the socket. The dispatch queue is an Executor that\nprovides serial execution of IO and processing events and is used to ensure synchronized\naccess of connection.\n\nThe callbacks will be executing the dispatch queue associated with the connection so\nit safe to use the connection from the callback but you MUST NOT perform any blocking\noperations within the callback. If you need to perform some processing which MAY block, you\nmust send it to another thread pool for processing. Furthermore, if another thread needs to\ninteract with the connection it can only do it by using a Runnable submitted to the\nconnection's dispatch queue.\n\nExample of executing a Runnable on the connection's dispatch queue:\n\n    connection.getDispatchQueue().execute(new Runnable(){\n        public void run() {\n          connection.publish( ..... );\n        }\n    });\n","funding_links":[],"categories":["Java","Protocol Library"],"sub_categories":["MQTT"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffusesource%2Fmqtt-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffusesource%2Fmqtt-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffusesource%2Fmqtt-client/lists"}