Supported versions

DataDome supports versions until they are unsupported by the maintainers.
You can find the support policy on these pages:

• For Tomcat
• For Jetty

This module is compatible with the following minimal versions:

• Tomcat version 10 and above
• Jetty version 10 and above

Installation

<project>
...
    <dependencies>
    ...
        <dependency>
          <groupId>co.datadome.module</groupId>
          <artifactId>datadome-java-module</artifactId>
          <version>2.1.1</version>
        </dependency>
    ...
    </dependencies>
...
</project>

Manual Installation

1. Download and extract the archive:

wget https://package.datadome.co/linux/DataDome-Java-latest.tgz
tar zxvf DataDome-Java-latest.tgz

2. The downloaded archive includes sources, so you can directly install it to your local Maven repository.

By default it is built with servlet-api-6.0. If your installation is dependant on servlet-api-4.0 or servlet-api-5.0, you need to build it manually with a different profile:

cd DataDome-JavaModuleDome-*
mvn install

cd DataDome-JavaModuleDome-*
mvn -P servlet-api-4.0 install

cd DataDome-JavaModuleDome-*
mvn -P servlet-api-5.0 install

3. Copy the target/datadome-java-module-xx.jarfile to the server lib directory, similarly to the below:

/lib

Usage

The filter has been tested on Jetty 10+, Tomcat 10+ and works with any other servers supporting Servlet API.

To use the filter you need to add it to web.xml as first server.

Example:

<web-app>
...
    <filter>
        <filter-name>datadome-filter</filter-name>
        <filter-class>co.datadome.api.servlet.DataDomeFilter</filter-class>
        <init-param>
            <param-name>datadome.apikey</param-name>
            <param-value>YOUR_DATADOME_SERVER_SIDE_KEY</param-value>
        </init-param>
    </filter>
    <filter-mapping>
        <filter-name>datadome-filter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>
...
</web-app>

List of possible init parameters:

You can use environment variables inside the DataDome filter's param-value.

For example, if you have the system environment variable DATADOME_SERVER_SIDE_KEY with your API key, you can input it in web.xml as follows:

<init-param>
  <param-name>datadome.apikey</param-name>
  <param-value>${DATADOME_SERVER_SIDE_KEY}</param-value>
</init-param>

Logging

Enriched Headers

You can log the values of DataDome Enriched Headers inside your Tomcat access logs.
Modify the AccessLogValve pattern inside the server.xml file to log the values that are attributes in the ServletRequestlike this:

                    <Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
                         prefix="localhost_access_log" suffix=".txt"
                         pattern="%h %l %u %t &quot;%r&quot; %s %{X-DataDome-isbot}r %{X-DataDome-requestid}r %{X-DataDome-devicecheckpassed}r %{X-DataDome}o" />

You can also access these values inside the code of HttpServletRequestlike this:

public class HelloServlet extends HttpServlet {

    protected void doGet(HttpServletRequest request,
            HttpServletResponse response) throws ServletException, IOException {

        System.out.println("Time spent by DataDome:" + request.getAttribute("datadome.spent_time"));
        System.out.println("DataDome-isbot:" + request.getHeader("X-DataDome-isbot"));
        System.out.println("DataDome-botname:" + request.getHeader("X-DataDome-botname"));
        
        PrintWriter writer = response.getWriter();
        writer.print("Hello World");
    }
}

Time spent calling DataDome Bot Protection API

Just as for Enriched Headers, the DataDome filter adds the attribute datadome.spent_time (number of milliseconds spent for building request/getting response from DataDome Bot Protection API).

To get this latency information in your logs, modify the AccessLogValve pattern inside the server.xml file like this:

                    <Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
                         prefix="localhost_access_log" suffix=".txt"
                         pattern="%h %l %u %t &quot;%r&quot; %s %{datadome.spent_time}r" />

FAQ

Can DataDome API be called via an outbound proxy?

The DataDome module can be used with an outbound proxy. Two options are available for proxy configuration:

• Use system settings such as -Dhttp.proxyHost=1.2.3.4 -Dhttp.proxyPort=8080 -Dhttps.proxyHost=1.2.3.4 -Dhttps.proxyPort=8443 when running your java application.

• Use optional DataDome init parameters datadome.proxy_server, datadome.proxy_port, datadome.proxy_ssl in web.xml.

📘

Network latency

Using the DataDome module with an outbound proxy can slow down the total time spent calling DataDome API and increase timeouts. Please adjust timeout settings accordingly.