====================================
Kurento Java Tutorial - RTP Receiver
====================================

This web application consists of a simple RTP stream pipeline: an *RtpEndpoint* is configured in KMS to listen for one incoming video stream. This stream must be generated by an external program. Visual feedback is provided in this page, by connecting the *RtpEndpoint* to a *WebRtcEndpoint* in receive-only mode.

The Java Application Server **connects to all events** emitted from KMS and prints log messages for each one, so this application is also a good reference to understand what are those events and their relationship with how KMS works. Check :doc:`/features/events` for more information about events that can be emitted by KMS.

.. note::

   Web browsers require using *HTTPS* to enable WebRTC, so the web server must use SSL and a certificate file. For instructions, check :ref:`features-security-java-https`.

   For convenience, this tutorial already provides dummy self-signed certificates (which will cause a security warning in the browser).



Quick start
===========

Follow these steps to run this demo application:

1. Install and run Kurento Media Server: :doc:`/user/installation`.

2. Install Java JDK and Maven:

   .. code-block:: shell

      sudo apt-get update
      sudo apt-get install default-jdk maven

3. Run these commands:

   .. code-block:: shell

      git clone https://github.com/Kurento/kurento.git
      cd kurento/tutorials/java/rtp-receiver/
      git checkout 7.3.0
      mvn -U clean spring-boot:run \
          -Dspring-boot.run.jvmArguments="-Dkms.url=ws://{KMS_HOST}:8888/kurento"

4. Open the demo page with a WebRTC-compliant browser (Chrome, Firefox): https://localhost:8443/
5. Click on *Start* to begin the demo.
6. Copy the KMS **IP** and **Port** values to the external streaming program.
7. As soon as the external streaming program starts sending RTP packets to the IP and Port where KMS is listening for incoming data, the video should appear in the page.
8. Click on *Stop* to finish the demo.



Understanding this example
==========================

To implement this behavior we have to create a :term:`Media Pipeline`, composed of an **RtpEndpoint** and a **WebRtcEndpoint**. The former acts as an RTP receiver, and the latter is used to show the video in the demo page.

This is a web application, and therefore it follows a client-server architecture. At the client-side, the logic is implemented in **JavaScript**. At the server-side, we use a Spring-Boot based application server consuming the **Kurento Java Client** API, to control **Kurento Media Server** capabilities. All in all, the high level architecture of this demo is three-tier.

To communicate these entities, two WebSockets channels are used:

1. A WebSocket is created between the Application Server and the browser client, to implement a custom signaling protocol.
2. Another WebSocket is used to perform the communication between the Application Server and the Kurento Media Server. For this, the Application Server uses the Kurento Java Client library. This communication takes place using the **Kurento Protocol** (see :doc:`/features/kurento_protocol`).

The complete source code for this tutorial can be found in `GitHub <https://github.com/Kurento/kurento/tree/main/tutorials/java/rtp-receiver>`__.



Application Server Logic
========================

This demo has been developed using **Java** in the server side, based on the :term:`Spring Boot` framework, which embeds a Tomcat web server within the resulting program, and thus simplifies the development and deployment process.

.. note::

   You can use whatever Java server side technology you prefer to build web applications with Kurento. For example, a pure Java EE application, SIP Servlets, Play, Vert.x, etc. Here we chose Spring Boot for convenience.

This graph shows the class diagram of the Application Server:

.. graphviz:: /images/graphs/tutorial-kurento-rtp-receiver.dot
   :align: center
   :caption: Server-side class diagram of the Application Server



Client-Side Logic
=================

We use a specific Kurento JavaScript library called **kurento-utils.js** to simplify the WebRTC interaction between browser and application server. This library depends on **adapter.js**, which is a JavaScript WebRTC utility maintained by Google that abstracts away browser differences.

These libraries are linked in the *index.html* page, and are used in the *index.js* file.