Example: Deploying the Diffusion server within Tomcat

Run the Diffusion™ server inside Tomcat™ as a Java™ servlet.

The Tomcat servlet container and the Diffusion server run in the same Java process and can communicate directly through shared memory. Tomcat and the Diffusion server listen on different ports. Clients can connect directly to the Diffusion server without going through Tomcat.

Configure an installation of the Diffusion server for how you want your Diffusion servlet to behave.
Ensure, when editing the configuration files in the etc directory, that all paths are expressed as absolute paths.

Ensure that a valid license file is present in the etc directory.

Place any additional JARs that are required by your servlet in the ext directory of your Diffusion installation.
Use the war.xml Ant script in the tools directory of your Diffusion to package the Diffusion server as a WAR file.
```
ant -f war.xml
```
The script creates the diffusion.war file in the build directory of your Diffusion installation.
The diffusion.war file includes the following files and directories:

META-INF/manifest.xml

The manifest file for the WAR

WEB-INF/web.xml

This file contains information about the servlet.

WEB-INF/classes

This directory contains the configuration files for the Diffusion server. These files are copied from the etc directory of the Diffusion installation.

WEB-INF/lib/diffusion.jar

The diffusion.jar file contains the Diffusion server

WEB-INF/lib

This directory also contains JAR files copied from the ext directory of the Diffusion installation.

WEB-INF/lib/thirdparty

This directory contains the third-party libraries that are required by the Diffusion server. These files are copied from the lib/thirdparty directory of the Diffusion installation.

lib/DIFFUSION

This directory contains the browser API libraries. These files are copied from the html/lib/DIFFUSION directory of the Diffusion installation.

Additional files and directories

The WAR file contains additional files and directories that are not listed here.

The top level of the WAR file contains resources that can be served by Tomcat.
Verify the WAR file.
1. Check that the WAR structure is the same as described in the previous step and that all necessary files have been copied into the WAR structure.
2. Check that the WEB-INF/web.xml file contains the following information.
```
<servlet>
    <servlet-name>Diffusion</servlet-name>
    <display-name>Diffusion Servlet</display-name>
    <servlet-class>com.pushtechnology.diffusion.servlet.DiffusionServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
</servlet>
```

The WAR is now ready to be deployed inside a Java web application server. The rest of this task describes how to run the WAR inside of Tomcat, but you can use any Java web application server.

Define the Tomcat connectors for incoming connections in the Server.xml file.
A connector defines the port, protocol, and various properties of how the connection is handled. The following is an example connector for handling HTTP 1.1 connections on port 8080:
```
<Connector port="8080" 
        connectionTimeout="20000" 
        URIEncoding="UTF-8"
        maxThreads="3"
        protocol="HTTP/1.1" />
```
See the Tomcat documentation for more information.
When starting Tomcat, ensure that the following parameters are set:
1. Set the diffusion.home parameter to the path to the Diffusion JAR file.
  -Ddiffusion.home=diffusion_installation/lib
  
  Tomcat must be aware of Diffusion.
2. Set the java.util.prefs.userRoot parameter to a directory that Tomcat can write to.
  For example:
```
-Djava.util.prefs.userRoot=/var/lib/tomcat/diffusion/prefs/user
```
  Diffusion uses the java.utils.prefs mechanism to store preference information. If Tomcat, does not set this parameter, the Diffusion server logs warning messages.

Accessing publishers from Tomcat

Diffusion started within Tomcat allows Tomcat to access the publishers. Tomcat can be used to serve JSP files providing dynamically generated content. These files can access publishers using the publishers class static methods.

<%@ page import="java.util.List,com.pushtechnology.api.publisher.*" %>
<html>
    <head>
        <title>Publisher Information</title>
    </head>
    <body>
        <table>
            <tr>
                <th>Publisher Name</th>
                <th>Topics</th>
            </tr>
            <% for (Publisher pub : Publishers.getPublishers()) { %>
            <tr>
                <td><%= pub.getPublisherName() %></td>
                <td><%= pub.getNumberOfTopics() %></td>
            </tr>
            <% } %>
        </table>
    </body>
</html>

The above is the content of a JSP file that return a list of the publisher Diffusion is running with the number of topics each publisher owns.