DDB Public Domain Calculator
The DDB Public Domain Calculator (or DDB-PDC in short) is a service which, based on the the database of the Deutsche Digitale Bibliothek, is able to determine if an artistic or literary work is likely to be in the public domain. It consists of two parts:
A backend service which provides a REST API for calculating the public-domain status of any work in the DDB.
A Drupal module which allows querying the public domain calculator through a simple web interface.
Installation and Setup
The following sections describe how to set up both the DDB-PDC backend and Drupal module on a server. Both were mainly tested on Ubuntu Server, but are likely to work on any other Unix-based system.
Installing and running the DDB-PDC backend requires the following:
An API key for access to the Deutsche Digitable Bibliothek API. See the DDB API documentation for instructions.
Java 7 or newer (both OpenJDK and the Oracle Java work). For being able to build the code, install the full JDK. Maven is also required for building. On Ubuntu, you can use the following command for installing:
sudo apt-get install openjdk-7-jdk maven
On OS X, the easiest way to install Maven is with Homebrew:
brew install maven
# Ubuntu sudo apt-get install mongodb-server # OS X + Homebrew brew install mongodb
The Drupal module needs Drupal 7 or higher; see the Drupal Installation Guide for setup instructions.
Building the Backend
After cloning this repository, move to its root folder and run
This will compile the DDB-PDC backend, test it, and finally create an
executable JAR file named
ddb-pdc-<version>.jar in the
sub-directory. You can copy it anywhere you want, e.g.:
mkdir -p /opt/ddb-pdc cp target/ddb-pdc-<version>.jar /opt/ddb-pdc/ddb-pdc.jar
Configuring the Backend
Configuration of the DDB-PDC backend is done in the file
application.properties, which can be found in
running the backend, this file must be either in the current working
directory or in the
config/ sub-directory thereof. The easiest
approach is to copy
application.properties into the same folder as
the backend JAR file.
You can pretty much leave the default configuration as-is. However,
you do need to fill out the
ddb.apikey option, which tells the
backend which API key to use for accessing the DDB API:
Configuring the PDC Result Database
Optionally, you can configure the backend to save the result of every public-domain calculation - including a trace explaining why a work was considered public-domain or not - to a MongoDB database. If the same work is queried afterwards, the backend will serve the result directly from the database instead of hitting the DDB API and re-calculating the public-domain status. (If the stored result is outdated because it is from an earlier year, it is re-calculated anyway.)
This feature doesn't only speed up multiple public-domain calculation requests for the same work, but also makes it possible to do further processing on the collected results in the future, for instance to generate reports.
To enable the result database, set
application.properties and configure the database connection
ddb.storage.enable=true spring.data.mongodb.host=127.0.0.1 spring.data.mongodb.port=27017 spring.data.mongodb.database=pdc spring.data.mongodb.collection=pdc_results
Running the Backend
To start the backend server, simply run the JAR file with
cd /opt/ddb-pdc java -jar ddb-pdc.jar
Make sure that you are in the directory containing
config/application.properties) when you
run the command. The backend will now listen for HTTP requests on the
port configured through the
server.port option (8080 by default).
For Ubuntu, this repository contains a
Upstart job file that lets you run the
backend as a background service. Simply copy
/etc/init and adapt it to suit your needs. After this is done, you
can control the backend server like any other Upstart job:
sudo start ddb-pdc sudo restart ddb-pdc sudo stop ddb-pdc
Installing the Drupal Module
The Drupal module is contained in
drupal/ddb_pdc/. To install it,
copy the directory to
sites/<your_site>/modules/ in your Drupal installation. An
accompanying example theme is available in
can be installed by copying it to
sites/<your_site>/themes/. After that, enable everything through the
Drupal admin controls as usual.
ddb_pdc module needs to know where to find the backend service.
By default, it looks for it at
http://localhost:8000. To change this
URL in the module's configuration.
The backend service is a Java-based Spring Boot application. See the Spring Boot Manual for more information about the general structure of Spring Boot projects and the available Maven goals. Below is a quick overview of the most common commands.
The backend is accompanied by a suite of unit and integration tests based on JUnit. To run them, execute
mvn verify will also generate a code coverage report with
JaCoCo and save it to
By default, the tests for the PDC result database are skipped so that
running the test suite doesn't require a running MongoDB. To enable
You can run the backend server from the command line during development with
The configuration in
config/application.properties will be used. Of
course, you can also run the server from your IDE as normal (the main