Red5 Pro Web Handler

Today’s post comes from Rajdeep Rath, who has been with the Red5 team from Open Source to Pro. He is very active on our Slack Channel responding to customer inquiries at all hours. He put together [Windows installation tutorials](https://www.youtube.com/user/sparkzdemon/videos) also builds applications for us, many of which can be found on his [GitHub page](https://github.com/rajdeeprath).

Most importantly, he has built many of Red5 Pro’s core features including the autoscaling solution. Though many have contributed, Rajdeep created the foundation and we are very grateful to him for that.

So without further adieu, I will turn it over to Rajdeep:

#A Glance At the Heart of a Red5 Pro Web App
## About Web apps

A Web App, or better said, a Web Application is the primary point of contact within the Red5 Pro software which acts as the negotiation point or handler for your ingest and egress requests. The term Web app comes from Apache Tomcat as Red5 Pro is based on the popular application JEE server.

So when you need to broadcast or subscribe, you point your application to a Web application on Red5 Pro and make the appropriate request. The application negotiates your request with the server on your behalf and the service is rendered.

Now let’s dive a little deeper and take a look at the heart of a Web Application and try to understand the component where the negotiation happens. At the center of a web application lies a Java class called an application adapter. In the context of a Red5 Pro web app, it is also called the web handler. For more on the anatomy of a web application and various parts that make it functional, check out this informative GitHub article on Red5 Pro application structure.

In this post, I won’t go into the nitty-gritty details of coding a complete web application. For a deeper dive into creating the web handler and configuration files from scratch, I recommend taking a look at Red5 Pro developer series by Dominick Accattato.

Introduction to the Red5 Web Handler

The application adapter J
ava class extends the Red5 base class MultiThreadedApplicationAdapter to inherit various properties and methods that are geared towards controlling negotiation requests as well as a host of exciting features.

If you have been using the popular Red5 Pro web app called live for most of your streaming needs, you can go ahead and open the file {RED5_HOME}\webapps\live\WEB-INF\red5-web.xml in your favorite text editor and locate the following line: <bean id="web.handler" class="com.infrared5.red5pro.live.Red5ProLive" />. That is the application adapter for your live app! As stated before, the Red5ProLive is a custom Java class then extends the MultiThreadedApplicationAdapter class.

Anatomy of a Red5 Web Handler

When a web handler is created inheriting the MultiThreadedApplicationAdapter it provides a few important handler methods that can be used to intercept various key events in the lifecycle of a ingest / egress mechanism. A few of the important methods are given below:

• public boolean appStart(IScope app): Invoked when your handler successfully registers with Red5 core during startup.
• public void app stop(IScope app): Invoked when your handler is stopped when the server shuts down gracefully.Avoid using this to trigger critical business logic
• public boolean appConnect(IConnection conn, Object[] params): Invoked when a client tries to connect to your application. Return false or throw ClientRejectedException to deny connection or return true to accept.
• public void appDisconnect(IConnection conn): Invoked when a client disconnects from the application.
• public void streamBroadcastStart(IBroadcastStream stream): Invoked when a publisher stream starts
• public void streamBroadcastClose(IBroadcastStream stream): Invoked when a publisher stream stops
• public void streamSubscriberStart(ISubscriberStream stream): Invoked when a stream subscription starts
• public void streamSubscriberClose(ISubscriberStream stream): Invoked when a stream subscription stops

For more information on these methods as well as other available methods that can be useful in your application check out our Java docs on MultiThreadedApplicationAdapter and the MultiThreadedApplicationAdapter source code on github

Any of the methods for which you need to implement a custom business logic must be overridden in your own handler class.

@Overridepublic boolean appConnect(IConnection conn, Object[] params) {    return super.appConnect(conn, params);}

A call to the super ensures that you relinquish control back to Red5 core after your own logic is done executing.

If you need an example of a web app that shows how to override and implement the common handler methods for a custom web app, check out the application-adapter-demo sample web app on github.

Special Notes and Gotchas

While a Red5 pro web handler is rather simple to implement, there are few things to be aware of to avoid potential pitfalls.

• The handler method appConnect is not executed when a client gets connected successfully. It is executed when a client is trying to connect. To affirm a successful connection, you need to use the IConnectionListener with your handler. For more info check out connection-listener-demo example on github.
• appStop should not be used to detect server shutdown/termination. It should only be used to unregister or stop Java components at best.
• streamBroadcastStart method implies that the broadcast started. This should not be used to implement publish security. For intercepting publish or playback request, IStreamPublishSecurity or IStreamPlaybackSecurity interfaces should be used respectively. For more information on the subject, refer to *Securing publish & playback in the Red5 Pro streams documentation and the Red5 Pro simple authentication plugin documentation.

You can also refer to the sample webapp on github demonstrating how to intercept publish/playback requests in Red5 Pro.

• Always make a call to super in the overridden method (when applicable), within your web handler after your custom logic to prevent breaking the flow of control in Red5 core.

When Do You Need to Implement a Custom Red5 Web Handler

Although a custom web application and thereby a custom application adapter (Red5 Pro web handler) is recommended for every professional streaming business, let me highlight a few specific examples that will help you better understand the need for an application adapter. A custom application adapter extending theMultiThreadedApplicationAdapter could be used to:

• Execute a custom business logic to be executed when your server starts up
• Send a notification to a remote server when a stream broadcast starts
• Upload a recording to a remote server after your publisher disconnects
• Run a custom logic each time a subscriber request comes in

Obviously, this is not a comprehensive list by any means but should help illustrate the concept.

Conclusion

Red5 Pro web applications might seem a little alien to you if you come from a non-Java background. However, they are quite straightforward and easy to implement once you get accustomed to the concepts. With just a little practice, you will quickly find yourself building advance streaming apps, real-time data apps and much more.

Take advantage of the extensive Java library base from across the globe coupled with our extensive documentation and dedicated support to build anything and deploy anywhere.

For more examples and snippets on server side Red5 Java API, check out red5-development-series repository on github.