Skip to content

Migrate to Apache Tika 4.0.0-beta-1#2432

Open
dadoonet wants to merge 12 commits into
masterfrom
tika-4.x
Open

Migrate to Apache Tika 4.0.0-beta-1#2432
dadoonet wants to merge 12 commits into
masterfrom
tika-4.x

Conversation

@dadoonet

@dadoonet dadoonet commented Jul 7, 2026

Copy link
Copy Markdown
Owner

Summary

Migrates FSCrawler from Apache Tika 3.3.1 to Tika 4.0.0-beta-1.

  • Bump tika.version to 4.0.0-beta-1 and mark tika-parsers-standard-package as <type>pom</type> (it is a POM aggregator in Tika 4).
  • Rework TikaInstance for the Tika 4 API:
    • Parser.parse() now requires a TikaInputStream (wrapped in extractText).
    • Tesseract paths moved from the parser to TesseractOCRConfig; the parser is built from that config.
    • PDF OCR strategy moved from PDFParser.setOcrStrategy(String) to PDFParserConfig.setOcr(OcrConfig) with an enum (FSCrawler string values are mapped, ocr_and_text stays the default).
    • Use TikaCoreProperties.RESOURCE_NAME_KEY instead of the literal resourceName (renamed to X-TIKA:resourceName).
  • ExternalParser.check() was removed in Tika 4; the OCR IT now skips via @DisabledIf + TesseractOCRParser.hasTesseract().
  • Transitive dependencies verified: homogeneous Tika 4, no version conflicts, no Jetty/CXF/tika-server pulled in; Tika's Jackson 2 and FSCrawler's Jackson 3 coexist by namespace.

Breaking changes

  • fs.tika_config_path is temporarily unsupported: Tika 4 removed the XML configuration-file mechanism. FSCrawler now fails fast with a clear message if the setting is used. Support is expected to return on top of Tika 4's JSON configuration.
  • Several meta.raw.* metadata key names changed (documented in the 2.10 release notes):
    • Image/EXIF keys are namespaced under img: (e.g. Number of Tablesimg:Number of Tables, Exif IFD0:*img:Exif IFD0:*).
    • resourceNameX-TIKA:resourceName.
    • New keys such as Content-Type-Magic-Detected, X-TIKA:Parsed-By-Full-Set and text encoding-detection keys.

Documentation

  • Refreshed the raw metadata examples (PDF/MP3) and the REST examples to match Tika 4 output.
  • Documented the tika_config_path removal and the meta.raw.* key changes in the 2.10 release notes.

Test plan

  • Unit tests: mvn clean test -DskipIntegTests (tika module green).
  • Full reactor build: mvn clean install -DskipTests -Ddocker.skip (16 modules, enforcer + Spotless pass).
  • Integration tests (TestContainers + local Tesseract): FsCrawlerTestOcrIT (ocr + ocr_disabled) and FsCrawlerRestIT#documentWithExternalTags green.
  • Swept the other metadata ITs for img:/hasSize regressions (RawIT and SubDirsIT unaffected).
  • Full Docker build and OCR image build (not run here).

Known upstream issue

  • Non-ASCII HTML metadata attribute names are mis-decoded by Tika 4 (tracked upstream in TIKA-4774); the affected unit assertion is annotated accordingly.

Follow-up

  • Re-introduce custom Tika configuration on top of Tika 4's JSON configuration mechanism.

🤖 Generated with Claude Code


Note

High Risk
Core document parsing and meta.raw.* field names change across the ingestion path; custom Tika XML config now fails startup, so deployments relying on those settings or fixed metadata keys need migration.

Overview
Upgrades FSCrawler from Tika 3.3.1 to Tika 4.0.0-beta-1, including Maven dependency changes (tika-parsers-standard-package as a POM aggregator) and a rework of TikaInstance for the Tika 4 APIs.

Parsing and OCR: extractText wraps inputs in TikaInputStream; Tesseract paths are applied via TesseractOCRConfig and PDF OCR strategies map to OcrConfig.Strategy; resource names use TikaCoreProperties.RESOURCE_NAME_KEY. fs.tika_config_path is rejected with FsCrawlerIllegalConfigurationException because XML Tika config was removed upstream.

Indexed metadata (meta.raw.*): Keys change with Tika 4—e.g. resourceNameX-TIKA:resourceName, image/EXIF fields under img:, plus new keys like Content-Type-Magic-Detected and encoding-detection fields. Docs, release notes, REST examples, and unit/integration tests are updated to match.

Tests: OCR integration skips when Tesseract is missing via TesseractOCRParser.hasTesseract() instead of removed ExternalParser.check().

Reviewed by Cursor Bugbot for commit a4cdd7c. Bugbot is set up for automated code reviews on this repo. Configure here.

dadoonet and others added 12 commits July 7, 2026 14:05
- Switch metadata listing to .sorted(String.CASE_INSENSITIVE_ORDER) in TikaDocParser
- Reorder the raw-metadata assertions in TikaDocParserTest to match the new order
- Drop a redundant duplicate xmpDM:genre entry in the mp3 assertions

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…Tesseract

- Tika 4 removed the static ExternalParser.check(); replace the Tesseract
  availability probe with the same hasTesseract() check used in production
- Convert the runtime Assumptions skip into a declarative @DisabledIf so the
  test reports as disabled (with a reason) instead of aborted
- Drop the now-unused Assumptions import

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ika 4

- Refresh PDF (47 keys) and MP3 (20 keys) raw metadata examples in local-fs
  to match Tika 4 output (X-TIKA:*, Content-Type-Magic-Detected, pdf:docinfo:*,
  access_permission:*), sorted case-insensitively like the real output
- Fix the REST examples in rest.rst (X-TIKA:Parsed-By and friends)
- Warn that fs.tika_config_path is temporarily unsupported on Tika 4 (XML
  configuration mechanism removed upstream); note it in the 2.10 changelog

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…mespace

- Tika 4 namespaces all metadata-extractor image keys under "img:" (both the
  bare keys like "Number of Tables" and the "Exif IFD0:/SubIFD:" ones); values
  are unchanged, ICC:/tiff:/Content-*/X-TIKA: keys stay as-is
- Bump hasSize(64) -> hasSize(66) (Tika 4 adds Content-Type-Magic-Detected and
  Content-Length) and add the img: prefixes, verified against real output
- Sort the raw-metadata assertions case-insensitively for readability

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Tika 4 renamed the resourceName metadata key to X-TIKA:resourceName; update
  the JsonPath in documentWithExternalTags to bracket notation for the new key

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Note the img: namespace for image/EXIF metadata keys
- Note resourceName -> X-TIKA:resourceName rename
- Note new keys: Content-Type-Magic-Detected, X-TIKA:Parsed-By-Full-Set and the
  text encoding-detection keys (X-TIKA:detectedEncoding/encodingDetectionTrace/encodingDetector)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@mergify

mergify Bot commented Jul 7, 2026

Copy link
Copy Markdown
Contributor

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

  • Queue this pull request

@sonarqubecloud

sonarqubecloud Bot commented Jul 7, 2026

Copy link
Copy Markdown

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant