Embedded Documents & Recursive Parsing

import java.io.IOException;
import java.nio.file.Path;

import org.apache.tika.exception.TikaException;
import org.apache.tika.io.TikaInputStream;
import org.apache.tika.metadata.Metadata;
import org.apache.tika.metadata.TikaCoreProperties;
import org.apache.tika.parser.AutoDetectParser;
import org.apache.tika.parser.ParseContext;
import org.apache.tika.parser.RecursiveParserWrapper;
import org.apache.tika.sax.AbstractRecursiveParserWrapperHandler;
import org.apache.tika.sax.BasicContentHandlerFactory;
import org.xml.sax.ContentHandler;
import org.xml.sax.SAXException;

/** Handles each document as soon as it ends; nothing is kept in a list. */
public class StreamingHandler extends AbstractRecursiveParserWrapperHandler {

    public StreamingHandler() {
        super(new BasicContentHandlerFactory(BasicContentHandlerFactory.HANDLER_TYPE.TEXT, 100_000));
    }

    @Override
    public void endEmbeddedDocument(ContentHandler contentHandler, Metadata metadata)
            throws SAXException {
        super.endEmbeddedDocument(contentHandler, metadata);   // keeps the depth counter right
        report(contentHandler, metadata);
    }

    @Override
    public void endDocument(ContentHandler contentHandler, Metadata metadata) throws SAXException {
        super.endDocument(contentHandler, metadata);
        report(contentHandler, metadata);
    }

    private void report(ContentHandler contentHandler, Metadata metadata) {
        String text = contentHandler.toString();
        String idPath = metadata.get(TikaCoreProperties.EMBEDDED_ID_PATH);
        System.out.printf("%-10s depth=%s chars=%d%n", idPath == null ? "(root)" : idPath,
                metadata.get(TikaCoreProperties.EMBEDDED_DEPTH), text.length());
        // index or store the document here, then let it be garbage collected
    }

    public static void main(String[] args) throws IOException, SAXException, TikaException {
        RecursiveParserWrapper wrapper = new RecursiveParserWrapper(new AutoDetectParser());
        try (TikaInputStream tis = TikaInputStream.get(Path.of(args[0]))) {
            wrapper.parse(tis, new StreamingHandler(), new Metadata(), new ParseContext());
        }
    }
}

/1/2/3     depth=3 chars=36
/1/2       depth=2 chars=105
/1/4       depth=2 chars=136
/1/5       depth=2 chars=144
/1         depth=1 chars=77
(root)     depth=0 chars=134

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

import org.apache.tika.config.EmbeddedLimits;
import org.apache.tika.exception.TikaException;
import org.apache.tika.extractor.DocumentSelector;
import org.apache.tika.io.TikaInputStream;
import org.apache.tika.metadata.Metadata;
import org.apache.tika.metadata.TikaCoreProperties;
import org.apache.tika.parser.AutoDetectParser;
import org.apache.tika.parser.ParseContext;
import org.apache.tika.parser.RecursiveParserWrapper;
import org.apache.tika.sax.BasicContentHandlerFactory;
import org.apache.tika.sax.RecursiveParserWrapperHandler;
import org.xml.sax.SAXException;

public class LimitsAndSelection {

    static List<Metadata> parse(Path file, ParseContext context)
            throws IOException, SAXException, TikaException {
        RecursiveParserWrapper wrapper = new RecursiveParserWrapper(new AutoDetectParser());
        RecursiveParserWrapperHandler handler = new RecursiveParserWrapperHandler(
                new BasicContentHandlerFactory(BasicContentHandlerFactory.HANDLER_TYPE.IGNORE, -1));
        try (TikaInputStream tis = TikaInputStream.get(file)) {
            wrapper.parse(tis, handler, new Metadata(), context);
        }
        return handler.getMetadataList();
    }

    public static void main(String[] args) throws Exception {
        Path eml = Path.of(args[0]);

        ParseContext depth = new ParseContext();
        depth.set(EmbeddedLimits.class, new EmbeddedLimits(2, false, -1, false));   // maxDepth 2

        ParseContext count = new ParseContext();
        count.set(EmbeddedLimits.class, new EmbeddedLimits(-1, false, 3, false));   // maxCount 3

        ParseContext select = new ParseContext();
        select.set(DocumentSelector.class, metadata -> {
            String type = metadata.get("Content-Type");
            return type == null || !type.startsWith("image/");
        });

        ParseContext strict = new ParseContext();
        strict.set(EmbeddedLimits.class, new EmbeddedLimits(-1, false, 2, true));   // throw at the 3rd

        for (ParseContext context : List.of(new ParseContext(), depth, count, select)) {
            for (Metadata m : parse(eml, context)) {
                System.out.printf("   %-10s %s%n", m.get(TikaCoreProperties.EMBEDDED_ID_PATH),
                        m.get(TikaCoreProperties.FINAL_EMBEDDED_RESOURCE_PATH));
            }
            System.out.println();
        }
        try {
            parse(eml, strict);
        } catch (Exception e) {
            System.out.println(e.getClass().getName() + ": " + e.getMessage());
        }
    }
}

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.regex.Pattern;

import org.apache.tika.exception.TikaException;
import org.apache.tika.extractor.EmbeddedDocumentExtractor;
import org.apache.tika.extractor.ParsingEmbeddedDocumentExtractor;
import org.apache.tika.io.TikaInputStream;
import org.apache.tika.metadata.Metadata;
import org.apache.tika.metadata.TikaCoreProperties;
import org.apache.tika.parser.AutoDetectParser;
import org.apache.tika.parser.ParseContext;
import org.apache.tika.parser.RecursiveParserWrapper;
import org.apache.tika.sax.BasicContentHandlerFactory;
import org.apache.tika.sax.RecursiveParserWrapperHandler;
import org.xml.sax.ContentHandler;
import org.xml.sax.SAXException;

/** Saves the bytes of every embedded document, then lets Tika parse it as usual. */
public class SaveAttachments {

    /** Per-parse state lives in the ParseContext, never in the (shared) extractor. */
    record SaveState(Path outDir, AtomicInteger counter) { }

    /** Stateless: one instance can serve every parse on every thread. */
    static class SavingExtractor implements EmbeddedDocumentExtractor {
        private static final Pattern SAFE_EXTENSION = Pattern.compile("[A-Za-z0-9]{1,8}");

        @Override
        public boolean shouldParseEmbedded(Metadata metadata, ParseContext context) {
            return ParsingEmbeddedDocumentExtractor.INSTANCE.shouldParseEmbedded(metadata, context);
        }

        @Override
        public void parseEmbedded(TikaInputStream stream, ContentHandler handler, Metadata metadata,
                                  ParseContext context, boolean outputHtml)
                throws SAXException, IOException {
            SaveState state = context.get(SaveState.class);
            if (state != null) {
                String target = String.format("%03d%s", state.counter().incrementAndGet(),
                        extensionOf(metadata.get(TikaCoreProperties.RESOURCE_NAME_KEY)));
                // getPath() spools the stream to a temporary file when needed;
                // the stream stays usable for the parse that follows
                Files.copy(stream.getPath(), state.outDir().resolve(target),
                        StandardCopyOption.REPLACE_EXISTING);
            }
            ParsingEmbeddedDocumentExtractor.INSTANCE.parseEmbedded(
                    stream, handler, metadata, context, outputHtml);
        }

        private static String extensionOf(String resourceName) {
            if (resourceName == null) {
                return ".bin";
            }
            int dot = resourceName.lastIndexOf('.');
            String ext = dot < 0 ? "" : resourceName.substring(dot + 1);
            return SAFE_EXTENSION.matcher(ext).matches() ? "." + ext.toLowerCase() : ".bin";
        }
    }

    public static void main(String[] args) throws IOException, SAXException, TikaException {
        Path outDir = Files.createDirectories(Path.of(args[1]));

        ParseContext context = new ParseContext();
        context.set(EmbeddedDocumentExtractor.class, new SavingExtractor());
        context.set(SaveState.class, new SaveState(outDir, new AtomicInteger()));

        RecursiveParserWrapper wrapper = new RecursiveParserWrapper(new AutoDetectParser());
        RecursiveParserWrapperHandler handler = new RecursiveParserWrapperHandler(
                new BasicContentHandlerFactory(BasicContentHandlerFactory.HANDLER_TYPE.IGNORE, -1));

        try (TikaInputStream tis = TikaInputStream.get(Path.of(args[0]))) {
            wrapper.parse(tis, handler, new Metadata(), context);
        }
    }
}

001.zip  2975 bytes
002.docx  2487 bytes
003.png  463 bytes
004.pdf  785 bytes
005.txt  116 bytes

# the list of metadata for one file, as JSON on stdout (shown here as a summary)
java -jar tika-app.jar -J publisher-email.eml

# every embedded document of every file in ./intake, as files in ./unpacked
java -jar tika-app.jar -Z -i ./intake -o ./unpacked

# the same, as a Frictionless data package
java -jar tika-app.jar -Z --unpack-format=FRICTIONLESS -i ./intake -o ./unpacked

(none)  Spring submissions: samples attached.eml  message/rfc822
/1/2/3  figure1.png                               image/png
/1/2    chapter-one.docx                          application/vnd.openxmlformats-officedocument.wordprocessingml.document
/1/4    catalogue.pdf                             application/pdf
/1/5    notes/cover-note.txt                      text/plain; charset=windows-1252
/1      samples.zip                               application/zip

unpacked/publisher-email.eml.json
unpacked/publisher-email.eml-embed/00000001.zip
unpacked/publisher-email.eml-embed/00000002.docx
unpacked/publisher-email.eml-embed/00000003.png
unpacked/publisher-email.eml-embed/00000004.pdf
unpacked/publisher-email.eml-embed/00000005.bin

unpacked/publisher-email.eml.json
unpacked/publisher-email.eml/datapackage.json
unpacked/publisher-email.eml/metadata.json
unpacked/publisher-email.eml/unpacked/00000001.zip
unpacked/publisher-email.eml/unpacked/00000002.docx
unpacked/publisher-email.eml/unpacked/00000003.png
unpacked/publisher-email.eml/unpacked/00000004.pdf
unpacked/publisher-email.eml/unpacked/00000005.bin

{
  "name" : "publisher-email.eml",
  "created" : "2026-10-12T15:08:30Z",
  "resources" : [ {
    "path" : "unpacked/00000003.png",
    "mediatype" : "image/png",
    "bytes" : 463,
    "hash" : "sha256:ecb71bed7ea8b05203fc06df89614662cff90c2a4d3536064c53fd85929e2bef",
    "name" : "figure1.png"
  }, {
    "path" : "unpacked/00000005.bin",
    "mediatype" : "text/plain",
    "bytes" : 116,
    "hash" : "sha256:2ed7f4f38f861dcd91867ca18ae6c50afbdd1180148ecb51f7b0e43603ebcf60",
    "name" : "notes/cover-note.txt"
  } ]
}

{
  "pipes": {
    "parseMode": "UNPACK"
  },
  "parse-context": {
    "unpack-config": {
      "maxUnpackBytes": 104857600,
      "zipEmbeddedFiles": true,
      "includeMetadata": true,
      "suffixStrategy": "DETECTED"
    }
  }
}

# the list of metadata, as JSON; Markdown content by default in 4.x
curl -T publisher-email.eml http://localhost:9998/rmeta

# the same with plain text content
curl -T publisher-email.eml http://localhost:9998/rmeta/text

# the embedded files as one zip, and with the metadata and the original
curl -T publisher-email.eml http://localhost:9998/unpack -o unpacked.zip
curl -T publisher-email.eml http://localhost:9998/unpack/all -o unpacked-all.zip