How to use DROID internal API

DROID Internal API

NOTE: This API has been developed for internal use at The National Archives and it may change as we release newer versions of DROID. Future releases of this API are not guaranteed to be backwards compatible.

DROID [Internal] API is a simple way of embedding DROID's file format identification capability into your own application.

To use the DROID internal API, add the droid-api module to your project.

Dependency

For Maven, this can be done by including the following snippet into pom.xml:

<dependencies>
    <dependency>
        <groupId>uk.gov.nationalarchives</groupId>
        <artifactId>droid-api</artifactId>
        <version>6.7.0</version>
    </dependency>
</dependencies>

Steps

DROID has a class called DroidAPI which is used to run the file format identification using DROID. The result of the identification can be one or more format identifiers (PUIDs). The result of the identification is returned using a class called ApiResult. Before we run the identification, we need to include these in our code

import uk.gov.nationalarchives.droid.internal.api.DroidAPI;
import uk.gov.nationalarchives.droid.internal.api.ApiResult;

We need to create an instance of DroidAPI to be used for the format identification. This can be done using the getInstance method on the DroidAPI. The method takes path to the binary signature file and a container signature file.

DroidAPI api = DroidAPI.getInstance(
            Paths.get("/home/signatures/binary/DROID_SignatureFile_V112.xml"),
            Paths.get("/home/signatures/container/container-signature-20230510.xml")
        );

Once we have the instance of DroidAPI, we can submit our file that needs to be identified. This can be done using the submit method on the API. This method returns a List of ApiResult

List<ApiResult> results = api.submit(Paths.get("/home/files/for/identification/northern_lights.pdf"));

We can print the results or use them for further processing. Here we are printing the results to the console.

for (ApiResult result : results) {
    System.out.println("Format Name: " + result.getName());
    System.out.println("Puid: " + result.getPuid());
    System.out.println("Identification Method: " + result.getMethod().getMethod());
    System.out.println("Extension: " + result.getExtension());
    System.out.println("Extension Mismatch: " + result.isFileExtensionMismatch());
}

Putting it all together

import uk.gov.nationalarchives.droid.core.SignatureParseException;
import uk.gov.nationalarchives.droid.internal.api.ApiResult;
import uk.gov.nationalarchives.droid.internal.api.DroidAPI;

import java.io.IOException;
import java.nio.file.Paths;
import java.util.List;

public class FileFormatIdentifier {
    public static void main(String args[]) throws IOException, SignatureParseException{
        DroidAPI api = DroidAPI.getInstance(
                Paths.get("/home/signatures/binary/DROID_SignatureFile_V112.xml"),
                Paths.get("/home/signatures/container/container-signature-20230510.xml")
        );
        List<ApiResult> results = api.submit(Paths.get("/home/files/for/identification/northern_lights.pdf"));
        for (ApiResult result : results) {
            System.out.println("Format Name: " + result.getName());
            System.out.println("Puid: " + result.getPuid());
            System.out.println("Identification Method: " + result.getMethod().getMethod());
            System.out.println("Extension: " + result.getExtension());
            System.out.println("Extension Mismatch: " + result.isFileExtensionMismatch());
        }
    }
}

An example output from the above code is given below:

Format Name: Acrobat PDF 1.4 - Portable Document Format
Puid: fmt/18
Identification Method: Signature
Extension: pdf
Extension Mismatch: false