This project includes the resources needed to develop a Metadata Adapter for the Lightstreamer - Basic Chat Demo - iOS Client - Swift that is pluggable into Lightstreamer Server.
The Lightstreamer Basic Chat Demo is a very simple chat application based on Lightstreamer for its real-time communication needs. It supports Mobile Push Notifications (MPN).
The project is comprised of source code and a deployment example.
The MPN Chat Metadata Adapter is comprised of one Java class.
The Metadata Adapter inherits from the reusable LiteralBasedProvider and just adds a simple support for message submission. It should not be used as a reference for a real case of client-originated message handling, as no guaranteed delivery and no clustering support is shown.
In addition the code shows a few best practices to ensure safety of Mobile Push Notifications (MPN) activity. See the source code comments for further details.
The Data Adapter functionalities are absolved by the ChatDataAdapter, a full implementation of a Data Adapter, explained in Lightstreamer - Basic Chat Demo - Java Adapter.
This Adapter Set is configured and will be referenced by the clients as CHAT.
The adapters.xml file for the Basic Chat Demo, should look like:
<?xml version="1.0"?>
<adapters_conf id="CHAT">
<metadata_adapter_initialised_first>Y</metadata_adapter_initialised_first>
<metadata_provider>
<adapter_class>com.lightstreamer.examples.chat_demo.adapters.MPNChatMetadataAdapter</adapter_class>
<!-- Optional, managed by the inherited LiteralBasedProvider.
See LiteralBasedProvider javadoc. -->
<!--
<param name="max_bandwidth">40</param>
<param name="max_frequency">3</param>
<param name="buffer_size">30</param>
<param name="prefilter_frequency">5</param>
<param name="allowed_users">user123,user456</param>
-->
<param name="distinct_snapshot_length">30</param>
<!-- Optional, managed by the inherited LiteralBasedProvider.
See LiteralBasedProvider javadoc. -->
<param name="item_family_1">chat_room.*</param>
<param name="modes_for_item_family_1">DISTINCT</param>
</metadata_provider>
<data_provider name="CHAT_ROOM">
<adapter_class>com.lightstreamer.examples.chat_demo.adapters.ChatDataAdapter</adapter_class>
<!-- Optional for ChatDataAdapter.
Configuration flag for periodic flush of the snapshot.
Default: false. -->
<param name="flush_snapshot">true</param>
<!-- Optional for ChatDataAdapter.
Configuration interval in millis for snapshot flush.
Default: 30 minutes. -->
<!-- <param name="flush_snapshot_interval">1800000</param> -->
</data_provider>
</adapters_conf>NOTE: not all configuration options of an Adapter Set are exposed by the file suggested above. You can easily expand your configurations using the generic template, see the Java In-Process Adapter Interface Project for details.
Please refer to the General Concepts document for more details about Lightstreamer Adapters.
If you want to install a version of the Chat Demo in your local Lightstreamer Server, follow these steps:
- Download Lightstreamer Server (Lightstreamer Server comes with a free non-expiring demo license for 20 connected users) from Lightstreamer Download page, and install it, as explained in the
GETTING_STARTED.TXTfile in the installation home directory. - Make sure that Lightstreamer Server is not running.
- Get the
deploy.zipfile of the Metadata Adapter latest release, unzip it, and copy theChatfolder into theadaptersfolder of your Lightstreamer Server installation. - [Optional] Customize logging settings in log4j configuration file
Chat/classes/log4j2.xml.
The Mobile Push Notifications (MPN) module of Lightstreamer is not enabled by default and requires configuration.
- Open the
lightstreamer_conf.xmlfile under theconfdirectory of your Lightstreamer Server installation. - Find the
<mpn>tag. - Set the
<enabled>tag toY.
The MPN module currently supports two MPN providers:
- Apple™ APNs for iOS, macOS, tvOS, watchOS and Safari
- Google™ FCM for Android, Chrome and Firefox
Currently the MPN Basic Chat Demo only supports the iOS Client, hence you only to configure the apple_notifier_conf.xml file under conf/mpn/apple. For an example of configuration of the MPN module for Google FCM, refer to the MPN Stock-List Demos and in particular the Lightstreamer - MPN Stock-List Demo Metadata - Java Adapter.
For the APNs provider, you need the following material in order to configure it correctly:
- the app ID of your app;
- a development or production APNs client certificate, exported in p12 format and related to the app ID above;
- the password for the p12 client certificate above.
All this may be obtained on the Apple Developer Center. Exporting the client certificate in p12 format may be done easily from the Keychain Access system app. This guide describes the full procedure in details.
Once you have the required material, add the following segment to the apple_notifier_conf.xml file:
<app id="your.app.id">
<service_level>development</service_level>
<keystore_file>your_client_certificate.p12</keystore_file>
<keystore_password>your certificate password</keystore_password>
</app>Replace your.app.id, your_client_certificate.p12 and your certificate password with the corresponding information. The certificate file must be located in the same folder of apple_notifier_conf.xml, unless an absolute path is specified. The <service_level> tag must be set accordingly to your client certificate type: development (sandbox) or production. For more information on the meaning of these tags please consult the apple_notifier_conf.xml itself or the Mobile Push Notifications section of the General Concepts document.
The MPN module requires a working SQL database in order to store persistent data regarding devices and subscriptions. The database configuration must be specified in the hibernate.cfg.xml file under conf/mpn in your Lightstreamer Server installation.
If you don't have a working database instance, an HSQL test database may be installed and configured quickly following these steps:
- Download the latest stable release of HSQL from hsqldb.org and unzip it in a folder of your choice.
- Copy the
hsqldb.jarfile from thelibfolder of your HSQL installation to thelib/mpn/hibernatefolder of your Lightstreamer Server installation. - Launch the HSQL instance by running the
runServer.shorrunServer.batscript in thebinfolder of your HSQL installation. - Open the
hibernate.cfg.xmlfile and locate the pre-enabled section indicated by Sample database connection settings for HSQL. - If your HSQL instance is running on a separate machine than the Lightstreamer Server, specify its IP address in place of
localhostin the following property:<property name="connection.url">jdbc:hsqldb:hsql://localhost</property>.
If you have a working database instance, follow these steps:
- Copy the JDBC driver jar file (or files) to the
lib/mpn/hibernatefolder of your Lightstreamer Server installation. - Open the
hibernate.cfg.xmlfile. - Specify the appropriate connection properties and SQL dialect (samples are provided for MySQL, HSQL and Oracle), including the IP address.
A complete guide on configuring the Hibernate JDBC connection may be found here (and here is a list of available SQL dialects). Avoid introducing optional parameters, like those from tables 3.3 - 3.7, if they are not already present in the hibernate.cfg.xml file, as they may have not been tested and may lead to unexpected behavior. Do it only if you know what you are doing.
You may download the source code for the Chat Demo iOS Client here:
The project must be modified in order to work with your app ID and certificate and to point to your Lightstreamer Server:
- your app ID must be set as the Bundle Identifier of the project (in Xcode, it may be found in the General tab of the project);
- the IP address of your Lightstreamer Server must be set in the
SERVER_URLconstant in theSwiftChat/ViewController.swiftfile.
Also, remember to install an appropriate provisioning profile for the app, enabled for push notifications, before building or running the code.
Done all this, the installation is finished and ready to be tested:
- Launch the Lightstreamer Server.
- Launch the iOS Client on your device (remember the iOS Simulator does not support push notifications).
- Accept push notifications.
If everything is correct, as soon as someone writes on the chat, you will receive a push notification within. You may try for yourself running the app on both the emulator and a device.
In case of any problem, first double check all the steps above, then check for any errors reported on the Lightstreamer Server log.
To build your own version of example-MPNChatMetadata-adapter-java-x.y.z-SNAPSHOT.jar instead of using the one provided in the deploy.zip file from the Install section above, you have two options:
either use Maven (or other build tools) to take care of dependencies and building (recommended) or gather the necessary jars yourself and build it manually.
As a precondition for compiling you need to download the Chat Data Adapter class and copy the source into src\main\java\com\lightstreamer\examples\chat_demo\adapters folder of this project.
For the sake of simplicity only the Maven case is detailed here.
You can easily build and run this application using Maven through the pom.xml file located in the root folder of this project. As an alternative, you can use an alternative build tool (e.g. Gradle, Ivy, etc.) by converting the provided pom.xml file.
Assuming Maven is installed and available in your path you can build the demo by running
mvn install dependency:copy-dependencies - Lightstreamer - Basic Chat Demo - Node.js Adapter
- LiteralBasedProvider Metadata Adapter
- Lightstreamer - Basic Messenger Demo - Java Adapter
- Lightstreamer - Basic Messenger Demo - HTML Client
- Compatible with Lightstreamer SDK for Java Adapters Since version 8.0
- For an example compatible with Lightstreamer SDK for Java Adapters versions 7.3 to 7.4, please refer to this tag.
- For an example compatible with Lightstreamer SDK for Java Adapters version 6.x, please refer to the non-MPN version of the Chat Data and Metadata Adapters.