LIGHTSTREAMER JMS EXTENDER QUICK SETUP
======================================

Thanks for downloading Lightstreamer JMS Extender!

These notes will guide you through the installation of Lightstreamer JMS
Extender, to to see it running in a blink of an eye.

Lightstreamer JMS Extender enables you to use the Java Message Service
API from within your JavaScript code. This way, any HTML page running inside
a web browser, as well as any Node.js application, can easily become a JMS client.
The full JMS API is provided as part of the JavaScript client library.

By default, JMS Extender ENTERPRISE Edition runs with a
Demo License, which can be used for evaluation, development, and
testing, but not for production. The Demo license has a limit of
maximum 20 users' sessions at the same time. If you need to
evaluate JMS Extender without this limit, or need any information
on the other license types, please contact info@lightstreamer.com.

Lightstreamer Server, COMMUNITY Edition, does not require a license
key and can be used for free for any purpose, including production
(see the Software License Agreement for full details).

Please read the Software License Agreement carefully before using
JMS Extender.


===================
SYSTEM REQUIREMENTS
===================

You need a Java SE platform implementation installed on your system.
You can get the latest version from Oracle (you can choose either the
Server JRE or the JDK):
http://www.oracle.com/technetwork/java/javase/downloads/index.html

Alternatively, you can go for other Java implementations, including OpenJDK.

JMS Extender's minimum requirement is Java 8, but a more recent version is
recommended for best performance.

Of course, a JMS 1.1- or 2.0-compliant broker is necessary. JMS Extender has
been tested with most mainstream JMS brokers, including Apache ActiveMQ,
Apache ActiveMQ Artemis, TIBCO EMS, IBM MQ, Oracle WebLogic, and others.

Unless you have configured the COMMUNITY Edition, or a Demo license,
or you are leveraging FILE validation,
your system needs to access the Internet in order to validate the license.


==========
QUICKSTART
==========

----------------------
1) Extract the Archive
----------------------

* On a Linux, Mac, or Unix system:
Extract the contents of the "Lightstreamer_JMS_Extender" tar.gz archive
to your hard drive. A "Lightstreamer_JMS_Extender" directory will be created,
which is your installation home directory.

* On a Windows system:
Unzip the "Lightstreamer_JMS_Extender" zip file to your hard drive.
A "Lightstreamer_JMS_Extender" directory will be created, which is your
installation home directory.

-----------------------
2) Add Third-party Jars
-----------------------

Copy the client library jars of your JMS broker to the
"Lightstreamer_JMS_Extender/jms_connectors/lib" directory.

For example, here is the list of needed jars for some mainstream brokers:

* Apache ActiveMQ:
- activemq-client-X.Y.Z.jar
- geronimo-j2ee-management_1.1_spec-1.0.1.jar
- hawtbuf-X.Y.jar

* Apache ActiveMQ Artemis
- artemis-jms-client-all-2.11.0.jar

* TIBCO EMS:
- tibjms.jar


You can even use multiple client libraries (for different brokers or
different versions of the same broker) by copying them in the "lib" folder
of specific subdirectories of "Lightstreamer_JMS_Extender/jms_connectors",
e.g.: "Lightstreamer_JMS_Extender/jms_connectors/ActiveMQ/lib",
"Lightstreamer_JMS_Extender/jms_connectors/TIBCO/lib", ecc.

See how to configure your JMS Connectors below.

------------------------
3) Choose Your TCP Ports
------------------------

By default, this installation uses TCP ports 8080 and 8888.
If any of these ports are already in use on your system, please change
them by editing the following elements in "lightstreamer_conf.xml":
     <port> (inside the <http_server> block)
     <port> (inside the <rmi_connector> block)

-----------------
4) Configure Java
-----------------

JAVA_HOME must point to your JRE or JDK installation.

* On a Linux, Mac, or Unix system:
If a JAVA_HOME variable is not available in your environment,
edit the "LS.sh" file under the "bin/unix-like" directory and set
JAVA_HOME according to the Java SE installations available.

* On a Windows system:
If a JAVA_HOME variable is not available in your environment,
edit the "LS.bat" file under the "bin\windows" directory and set
JAVA_HOME according to the Java SE installations available.

-------------------------------
5) Configure Your JMS Connector
-------------------------------

Open the "Lightstreamer_JMS_Extender/jms_connectors/jms_connectors_conf.xml"
configuration file. You will find several sample connectors configured for
different JMS brokers. Find yours or create a new one, enable it by changing
the "disabled" param and set specific connection parameters (host name, port, etc.).

Below is a minimal sample configuration:

    <jms_connector name="ActiveMQ">

        <!-- JNDI Factory Name -->
        <param name="jndi_factory">org.apache.activemq.jndi.ActiveMQInitialContextFactory</param>

        <!-- JMS Broker Main URL -->
        <param name="jms_url">tcp://localhost:61616</param>

        <!-- Connection Factory Name -->
        <param name="conn_factory_name">ConnectionFactory</param>

        <!-- Connection Timeout -->
        <param name="connect_timeout_millis">5000</param>

        <!-- Reconnection Delay -->
        <param name="retry_delay_millis">2000</param>
    </jms_connector>

As you can see, configuration is really simple and straightforward. Beside
main JMS configuration parameters, the only two other mandatory parameters
are:

- "connect_timeout_millis": this parameter tells the connector how much time
  it has to wait during the initial connection before giving up; it also sets
  the timeout to client requests when the JMS broker is temporarily
  disconnected or not responding;

- "retry_delay_millis": this parameter tells the connection thread of the
  connector how much time it should wait before retrying to connect, in case
  the previous connection did fail.

If you have multiple client libraries, for each JMS Connector please add an
<install_dir> block (there's a commented-out example) to specify where the
connector should find its client libraries. E.g.
- <install_dir>ActiveMQ</install_dir>
- <install_dir>TIBCO</install_dir>, etc.

Check also the connectors log configuration file:
"Lightstreamer_JMS_Extender/jms_connectors/jms_connectors_log_conf.xml" to set the
appropriate logging level.

--------------------
6) Launch the Server
--------------------

Ensure your JMS broker is running, then:

* On a Linux, Mac, or Unix system:
Go to the "bin/unix-like" directory and execute "start.sh".

* On a Windows system:
Go to the "bin\windows" directory and execute
 "Start_LS_as_Application.bat".

------------------
7) Test the Server
------------------

Point your browser to "http://localhost:8080" (change the port number
if you configured a different port in step 3).

You should see a welcome page. In case of problems, errors are reported in
the "Lightstreamer.log" and "JMS_Extender.log" files under the "logs"
directory.

Now, give a try to the Monitoring Dashboard, a tool for monitoring the
state of JMS Extender in real time. By default, the Monitoring
Dashboard is publicly accessible from "http://localhost:8080/dashboard".

Then, install any of the ready-made examples available on GitHub to see
JMS Extender in action. Find the list of available demos at
http://demos.lightstreamer.com/?p=jmsextender (one of the easiest to
install is the Basic Chat Demo).

***IMPORTANT***
Carefully read the "PRODUCTION_SECURITY_NOTES.TXT" document to know what you
must do before making your Lightstreamer installation production ready.
In particular, remember to protect the Monitoring Dashboard before going in
production!

NOTES:
- In production, it is recommended to make JMS Extener listen on
standard HTTP/HTTPS ports (80/443). Using non-standard ports (like default
8080) will prevent some external users from accessing the Server, due to
security constraints. See "bin/unix-like/README.TXT" for tips on how you can
use privileged ports on Linux.
- For best performance, it is important to revise the JVM command line
and determine the optimal arguments, with particular regard to the Garbage
Collection configuration. This should be done by leveraging the JAVA_OPTS
variable, defined next to JAVA_HOME (see point 3 above).
- To use HTTPS instead of HTTP, you should activate HTTPS within
lightstreamer_conf.xml and provide a valid certificate or add the default
one as a security exception in your browser.

------------------
8) Stop the Server
------------------

* On a Linux, Mac, or Unix system:
Go to the "bin/unix-like" directory and execute "stop.sh".

* On a Windows system:
Go to the "bin\windows" directory and execute
"Stop_LS_as_Application.bat".

----------------------------
9) Develop Your Applications
----------------------------

To grasp the main concepts of JMS Extender development, you might want to
start from the following readings:

* General concepts:
- "DOCS/Lightstreamer JMS Extender Documentation.pdf"

* Demo Gallery with links to full source code hosted on GitHub:
- https://demos.lightstreamer.com/?p=jmsextender

* API reference for the JS Client SDK:
- https://lightstreamer.com/api/ls-jms-web-client/2.0.0/

* API reference for the Hook SDK:
- https://lightstreamer.com/api/ls-jms-hook-java-api/2.0.0/

* API reference for the JMX SDK:
- https://lightstreamer.com/api/ls-jms-jmx-sdk/1.1.0/

* Online support forums:
- https://forums.lightstreamer.com

Enjoy!