Readme for IBM Mobile Messaging and M2M Client Pack MA9B

Content

Description
This pack provides an SDK for building MQTT based Mobile Messaging and M2M applications. This can be downloaded at https://www.ibm.com/developerworks/connect/IBMmessaging

MQTT is an open light weight messaging protocol that is well suited for use in Mobile, device and Machine to Machine (M2M) applications. The SDK contains client libraries and samples for use in building these types of applications.

Versions
v1.0.0.5 - Remove build in OpenSSL, include source, update all client code to latest.
v1.0.0.4 - iOS Objective C client plus fixes.
v1.0.0.3 - High Availability Support for WMQ and MessageSight, plus fixes.
v1.0.0.2 - SHA-2 Support plus fixes.
v1.0.0.1 - JavaScript Clients plus fixes.
v1.0.0.0 - Java, C, Android & iOS Clients.

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
SDK Structure

WebContent
¦ ¦
¦ ¦-------> doc
¦ ¦
¦ WebSocket
¦ ¦
¦ ¦-------> WebMessagingUtility.html
¦
clients
¦ ¦-------> java
¦ ¦ ¦
¦ ¦ ------> samples
¦ ¦ ¦
¦ ¦ ¦-----> doc
¦ ¦ ¦
¦ ¦ ¦-----> src
¦ ¦
¦ ¦-------> c
¦ ¦ ¦
¦ ¦ ¦-----> doc
¦ ¦ ¦
¦ ¦ ¦-----> include
¦ ¦ ¦
¦ ¦ ¦-----> samples
¦ ¦ ¦
¦ ¦ ¦-----> src
¦ ¦
¦ ¦-------> android
¦ ¦ ¦
¦ ¦ ¦-----> doc
¦ ¦ ¦
¦ ¦ ¦-----> samples
¦ ¦
¦ ¦-------> iOS
¦ ¦ ¦
¦ ¦ ¦-----> doc
¦ ¦ ¦
¦ ¦ ¦-----> samples
¦
licenses
¦
readme.txt
¦
REDIST.TXT

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Client Libraries

Two Java client libraries are provided:

1) Java Client - org.eclipse.paho.client.mqttv3
Found in directory: ../SDK/clients/java

A Java library implementing the client half of the MQTT protocol, versions 3.1 and 3.1.1.
The Java client will run on any suitable Java runtime from Java 1.5 onwards
including Android. Separate interfaces are provided for synchronous and
asynchronous styles of operation.

The synchronous API supports a style where an operation only returns to the
caller when the operation has completed. This is a traditional style which
may be used to implement a simple client. However the blocking nature of
this api limits its usage in environments where threads are not allowed to
block, or when high performance or large numbers of clients are required.

The asynchronous API supports a different style in which a call returns
immediately. The application can then either be notified via a callback when
the operation completes or can use a token returned to the application to
block until the operation completes.
This style of API is better suited to mobile, event oriented and high
performing applications.
Applications where it may take time to complete an operation or where a
thread must not be blocked are good candidates for the asynchronous API.

This client is a version of the open source MQTT client that is available
from the Eclipse.org Paho project. If used with an entitled IBM product
such as WebSphere MQ full support is provided.


Java Samples
A set of Java Samples that show how to program using both synchronous
and asynchronous programming styles are provided.

Source is available in directory: ../SDK/clients/java/samples


Android™ Sample
Found in directory: ../SDK/clients/android

Native Android apps are made up of one or more Activities and optionally
one or more Services. While you can call the asynchronous Java client
directly from an Activity, it often makes more sense to call it from a
Service. A Service can continue running (and in particular can be receiving
incoming messages) when the app's Activities have stopped.

We provide a sample Android app (called mqttExerciser) that connects to
an MQTT server and sends and receives messages. This app is made up of an
Android Activity which is bound to an Android Service that encapsulates all
its MQTT API calls.

C client
Found in directory: ../SDK/clients/c

The C implementation of the MQTT protocol, versions 3.1 and 3.1.1, like the
Java equivalent has separate interfaces provided for synchronous and asynchronous
styles of operation.

These clients are provided for a variety of platforms and for the iOS
Operating system we supply the source only.

This client is a version of the open source MQTT client that is available
from the Eclipse.org Paho project. If used with an entitled IBM product
such as WebSphere MQ full support is provided.

iOS client
Found in directory: ../SDK/clients/iOS

Objective-C extension of the C client implementation of the MQTT
protocol, versions 3.1 and 3.1.1, for use when developing native apps for Apple
mobile devices, providing an asynchronous interface only.

If used with an entitled IBM product such as WebSphere MQ full support is
provided.

Client for JavaScript
Found in directory: ../SDK/WebContent/WebSocket

JavaScript implementation of the MQTT protocol, versions 3.1 and 3.1.1.
It enables html web pages to connect to servers and flow MQTT messages
over a WebSocket.

The JavaScript implementation can be loaded by the browser from a suitably
configured WebSphere MQ Queue Manager or from a WebServer.

"User interfaces resulting from the Sample code are not warranted to be
compliant to any accessibility standards or accessibility requirements.”


Servers which support the Mobile Messaging & M2M clients
The C and Java clients work with any IBM MQTT server:

- IBM MessageSight (including IBM MessageSight for Developers virtual appliance)

- WebSphere MQ from version 7.0.1

- IBM Internet of Things Foundation


Further reading
The following sites provide good sources of information:

- IBM Internet of Things Foundation
https://internetofthings.ibmcloud.com

- Mobile Messaging and M2M section of the IBM Messaging Community
https://www.ibm.com/developerworks/connect/IBMmessaging

- IBM MessageSight
https://www.ibmdw.net/messaging/messagesight

- The System Requirements for WebSphere MQ V7.5.0.1 are available at:
http://www.ibm.com/support/docview.wss?uid=swg27027462

- Eclipse Paho
http://www.eclipse.org/paho/

- All things MQTT:
http://mqtt.org



+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Limitations and known problems
The C and iOS client libraries do not support connecting to servers with hostnames longer than 40 characters.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

JavaScript
If SDK/WebContent/index.html is opened in a browser and not from a
WMQ Qmgr, the links to Java, C and MQSever API documentation do not work.
To access these use the link http://www.ibm.com/developerworks/connect/IBMmessaging

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

COPYRIGHT, NOTICES AND TRADEMARKS

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Copyright and trademark information
http://www.ibm.com/legal/copytrade.shtml

Notices
-----------
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION
"AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Some jurisdictions do not allow disclaimer of express or implied
warranties in certain transactions, therefore, this statement may not
apply to you.

This information could include technical inaccuracies or typographical
errors. Changes are periodically made to the information herein; these
changes will be incorporated in new editions of the publication. IBM
may make improvements and/or changes in the product(s) and/or the
program(s) described in this publication at any time without notice.

THIRD-PARTY LICENSE TERMS AND CONDITIONS, NOTICES AND INFORMATION

The license agreement for this product refers you to this file for
details concerning terms and conditions applicable to third party
software code included in this product, and for certain notices and
other information IBM must provide to you under its license to certain
software code. The relevant terms and conditions, notices and other
information are provided or referenced below. Please note that any
non-English version of the licenses below is unofficial and is provided
to you for your convenience only. The English version of the licenses
below, provided as part of the English version of this file, is the
official version.

Notwithstanding the terms and conditions of any other agreement you may
have with IBM or any of its related or affiliated entities
(collectively "IBM"), the third party software code identified below
are "Excluded Components" and are subject to the following terms and
conditions:

* the Excluded Components are provided on an "AS IS" basis
* IBM DISCLAIMS ANY AND ALL EXPRESS AND IMPLIED WARRANTIES AND
CONDITIONS WITH RESPECT TO THE EXCLUDED COMPONENTS, INCLUDING, BUT NOT
LIMITED TO, THE WARRANTY OF NON-INFRINGEMENT OR INTERFERENCE AND THE
IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE
* IBM will not be liable to you or indemnify you for any claims related
to the Excluded Components
* IBM will not be liable for any direct, indirect, incidental, special,
exemplary, punitive or consequential damages with respect to the
Excluded Components.


Trademarks
--------------
The following terms are trademarks of International Business Machines
Corporation in the United States, other countries, or both:
IBM FFST MQSeries SupportPac WebSphere

Android is a trademark of Google Inc

IOS is a trademark or registered trademark of Cisco in the U.S. and other
countries and is used under license by Apple

Microsoft and Windows are trademarks of Microsoft Corporation
in the United States, other countries, or both.

Java and all Java-based trademarks are trademarks of Oracle in
the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States
and other countries

Linux is a registered trademark of Linus Torvalds in the United States,
other countries, or both.

Other company, product, or service names may be trademarks or service marks of
others.


Copyright and trademark information
-----------------------------------
IBM, the IBM logo and ibm.com are trademarks of International Business Machines Corp.,
registered in many jurisdictions worldwide.
Other product and service names might be trademarks of IBM or other companies.
A current list of IBM trademarks is available on the Web at "Copyright and trademark information"
at http://www.ibm.com/legal/copytrade.shtml.