Java/Tomcat-Jetty

Compatibility

  • Tomcat 10+
  • Jetty 10+

🚧

Deprecated JavaEE support

Version 1.x of the DataDome Java Module is compatible with the deprecated JavaEE.

Add dependency for DataDome Java Module

When using Maven, update your pom.xml file with the following content:

<project>
...
    <dependencies>
    ...
        <dependency>
          <groupId>co.datadome.module</groupId>
          <artifactId>datadome-java-module</artifactId>
          <version>2.0.0</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
  1. 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
  1. 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:

SettingsDescriptionDefault
datadome.apikeyLicense key to access API
datadome.hostnameAPI server's hostname
Available endpoints
api.datadome.co
datadome.sslUse SSL between the filter and the API servertrue
datadome.regexInclusion Regex""
datadome.exclusion_regexExclusion Regex\.(js|css|jpg|jpeg|png|ico|gif|tiff|svg|woff|woff2|ttf|eot|mp4|otf)$
datadome.connection_timeoutConnection timeout (in ms)150
datadome.read_timeoutRead timeout (in ms)50
datadome.max_connectionsMaximum open connections to the API server100
datadome.use_x_forwarded_hostuse the request header x-forwarded-host instead of host (used for cookie, dashboard domain...)false
datadome.proxy_serverHost that will be used as proxy server
See here
datadome.proxy_portTCP port at the proxy server
See here
datadome.proxy_sslIs the connection to the proxy established through TLS
See here
false
datadome.skip_ipsIPv4 or IPv6 subnetwork list on which datadome validation is not executed, e.g.: "2a03:2880:1000::/36,124.66.0.0/17"

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>

FAQ

How can I log the time spent calling DataDome API?

The DataDome filter adds the attribute datadome.spent_time (number of milliseconds spent for building request/getting response from DataDome API) so it could be easily retrieved inside your servlet.

Here is how you can use it:

@Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
        resp.getWriter().println("Example servlet");
        System.out.println("Time spent by DataDome:" + req.getAttribute("datadome.spent_time"));
        resp.setStatus(200);
    }

Note: the above example is for demonstration purposes only.
Your use case could be different, such as sending spent_time value to your monitoring system, etc.

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.