Repository navigation
camel-pdf: deprecate CamelPdfDecryptionMaterial, which nothing reads - #29972
Dhairya-007 wants to merge 8 commits into
Conversation
The header is documented as the *Mandatory* header if the PDF document
is encrypted, but the component never looks it up - PdfProducer reads
CamelPdfDocument and CamelPdfProtectionPolicy by name and never this
one, and the only other references to it are two tests that decrypt the
document themselves with Loader.loadPDF(bytes, userPass) before sending
it, so the header they set alongside is decoration.
The one place it could be applied loads without a password:
@converter
public PDDocument convertToPDF(byte[] bytes) throws Exception {
return Loader.loadPDF(bytes);
}
so sending an encrypted PDF as bytes with the documented header fails in
the type converter with InvalidPasswordException, before the producer
runs. A PDDocument in the body is already decrypted by whatever loaded
it, which is why the tests pass.
It looks like a leftover of the PDFBox 1.x API, where the document was
opened first and decrypted afterwards with
document.openProtection(decryptionMaterial); PDFBox 2 and 3 take the
password at load time instead.
Deprecate it with a note saying so.
gnodet-bot
left a comment
There was a problem hiding this comment.
The diagnosis in the PR description is correct and well-researched. The deprecationNote and @Deprecated are the right tools here.
Two issues to address before merge:
1. Base description still says "Mandatory header if PDF document is encrypted"
The @Metadata(description = ...) text is unchanged — it still presents the header as working and mandatory, which is now actively misleading. With deprecated: true, the catalog renders the base description alongside the deprecation note. Users who read the base description will still follow the broken advice. The description should be updated to reflect the actual behavior.
2. Missing upgrade guide entry
Per the project's deprecation conventions (AGENTS.md), changes that affect users upgrading go in the upgrade guide. A user currently passing CamelPdfDecryptionMaterial will find their route silently ignoring it after this change is surfaced by the catalog — an upgrade guide entry in camel-4x-upgrade-guide-4_24.adoc documents this so they're not left guessing.
This review was generated by an AI agent, Hermès on behalf of @gnodet.
…pdf/PdfHeaderConstants.java Co-authored-by: Guillaume Nodet - AI Bot <gnodet+bot@gmail.com>
gnodet-bot
left a comment
There was a problem hiding this comment.
Following up on my earlier review — 1 of the 2 issues has been addressed.
[Issue 1] Description still says "Mandatory header" — ✅ addressed. The @Metadata(description = ...) text has been rewritten to lead with "Deprecated." and explain the PDFBox 2 load-time constraint. The deprecation note is accurate and actionable.
[Issue 2] Missing upgrade guide entry — camel-4x-upgrade-guide-4_24.adoc already has a camel-pdf section but does not mention the CamelPdfDecryptionMaterial deprecation. Users who set this header today will silently see it ignored after upgrading — an upgrade guide entry is the right place to document that and point them to the workaround.
Suggested addition to the existing camel-pdf section in docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc:
* The `CamelPdfDecryptionMaterial` header is now deprecated. It has never been read by
the component: PDFBox 2+ decrypts documents at load time, so by the time the producer
receives a `PDDocument` the decryption has already occurred or failed. Pass the password
to `Loader.loadPDF(bytes, password)` in a type converter or a `Processor` before the
PDF endpoint instead.This review was generated by an AI agent, Hermès on behalf of @gnodet.
|
🌟 Thank you for your contribution to the Apache Camel project! 🌟 🐫 Apache Camel Committers, please review the following items:
|
davsclaus
left a comment
There was a problem hiding this comment.
Thanks for digging into this. I checked that nothing on main reads the header: the only loadPDF call is the password-less one in PdfConverter.java:36, and PdfProducer reads only the document, protection-policy and files-to-merge headers. Deprecating it makes sense, and the deprecationNote + @Deprecated style matches the influxdb2 deprecation (#29709).
PdfHeaderConstants.java:38says the header "has never been read by the component". Up to Camel 2.20,PdfProducerdid read it and calleddocument.openProtection(decryptionMaterial)in the append and extractText paths; that went away in 2.21 with the move to PDFBox 2 (which matches your own diagnosis in the description). Could it say "is no longer read by the component", and thedeprecationNotelikewise "Not read by the component: ..." instead of "Never read"?- The second commit changed the Java description, but the two
pdf.jsonfiles were not regenerated after it: they still have "Mandatory* header if PDF document is encrypted.", so CI's regen check will flag them. Also, the generator appends "Deprecation note: ..." to the description, so having a "Deprecated." sentence in the description itself makes the catalog say it twice. Keeping the description short (the expected type, without "Mandatory") and leaving the reason todeprecationNoteand the workaround to the upgrade guide would read better. dsl/camel-endpointdsl/src/generated/java/org/apache/camel/builder/endpoint/dsl/PdfEndpointBuilderFactory.java:432-445:pdfDecryptionMaterial()still has the old javadoc and no@Deprecated. Buildingcomponents/camel-pdf(e.g.mvn install -Dquickly -pl components/camel-pdf) and committing the regenerated files fixes 2 and 3.- As gnodet-bot noted, please add a short entry to
docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc: the header has had no effect since 2.21, and an encrypted PDF should be loaded with its password (e.g. aProcessorcallingLoader.loadPDF(bytes, password)) before it reaches the endpoint. - [Nit]
PdfAppendTest.java:107andPdfTextExtractionTest.java:84still set the header, which now gives deprecation warnings and plays no part in those tests. Dropping it there would keep the tests honest.
Claude Code on behalf of davsclaus. This review was generated by an AI agent and may contain inaccuracies; please verify all suggestions before applying.
✅ Generated files are up to dateAn earlier CI run reported uncommitted generated changes; the latest run no longer does. |
gnodet-bot
left a comment
There was a problem hiding this comment.
Following up on my earlier review — 1 of the 3 open items has been addressed.
[@Deprecated on pdfDecryptionMaterial() in PdfEndpointBuilderFactory] — ✅ addressed by the Regen commit. The DSL method is now properly annotated.
Two items remain from davsclaus's review:
Upgrade guide entry — camel-4x-upgrade-guide-4_24.adoc. The header has been silently ineffective since Camel 2.21; users who rely on it today need a migration note.
"never" → "no longer" wording — document.openProtection(decryptionMaterial)); it has not been read since the PDFBox 2 migration in 2.21. "Never read" is incorrect and "No longer read" is what davsclaus asked for.
Description duplication — The @Metadata(description = ...) text already explains the deprecation fully, and the generator then appends Deprecation note: <deprecationNote> automatically. The catalog ends up showing the reason three times. The cleaner pattern (matching other deprecated headers in the codebase) is to keep the description short and let deprecationNote carry the explanation.
This review was generated by an AI agent, Hermès on behalf of @gnodet.
davsclaus
left a comment
There was a problem hiding this comment.
Thanks, the Regen commit gave pdfDecryptionMaterial() in PdfEndpointBuilderFactory its @Deprecated, and the two pdf.json files now match the Java. These points from my last review are still open:
PdfHeaderConstants.java:38("has never been read by the component") and thedeprecationNoteat:43("Never read by the component") are inaccurate: up to Camel 2.20PdfProducerdid read the header, so "is no longer read" / "Not read by the component" would be correct.- The description at
:36-41still carries the full deprecation paragraph. The generator appends "Deprecation note: ..." to it, so the catalog gives the reason twice (and strips the leading*, hence "Deprecated.*" inpdf.json). gnodet-bot's inline suggestion on line 44 fixes 1 and 2; if you apply it, please change "(deprecated since Camel 2.21)": the header is deprecated now, in 4.24, and has had no effect since 2.21, so "No longer read by the component (no effect since Camel 2.21)." would be accurate. Then rebuildcomponents/camel-pdfand commit the regeneratedpdf.jsonfiles andPdfEndpointBuilderFactory.java. - There is still no entry in
docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc. A short section would do: the header has had no effect since 2.21, and an encrypted PDF should be loaded with its password (aProcessorcallingLoader.loadPDF(bytes, password)) before it reaches the endpoint. This one I'd like before merge, since users who set the header get no other signal. - Nit:
PdfAppendTest.java:107andPdfTextExtractionTest.java:84still set the header, which now gives deprecation warnings and does nothing in those tests.
Claude Code on behalf of davsclaus. This review was generated by an AI agent and may contain inaccuracies; please verify all suggestions before applying.
|
🧪 CI tested the following changed modules:
🔬 Scalpel shadow comparison — Scalpel: 9 of 726 tested, 24 compile-only — current: 9 all testedMaveniverse Scalpel detected 9 affected modules (current approach: 9). Skip-tests mode would test 9 modules (4 direct + 8 downstream), skip tests for 24 (generated code, meta-modules) Modules Scalpel would test (9)
Modules with tests skipped (24)
All tested modules (36 modules, 6m 18s total)Total reactor time: 6m 18s
Top 20 slowest modules:
|
…n, add an upgrade note Four things from review: 1. "never been read" was wrong. PdfProducer did read the header and call PDDocument.openProtection(decryptionMaterial) up to Camel 2.20; the read went away with CAMEL-11976, which aligned the component on PDFBox 2.0.6. So it is "no longer read", with no effect since 2.21. 2. The description carried the whole deprecation paragraph, and the generator appends "Deprecation note: ..." to it, so the catalog gave the reason twice; the leading asterisk of *Deprecated.* was also stripped, leaving "Deprecated.*" mid-sentence. The description is now one short sentence and the reason lives only in deprecationNote. 3. Added a section to the 4.24 upgrade guide, with the Processor that loads an encrypted document with its password. 4. PdfAppendTest and PdfTextExtractionTest no longer set the header, which did nothing there and now warns. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
All four done, thanks.
Regenerated the two |
gnodet-bot
left a comment
There was a problem hiding this comment.
Following up on my earlier review — 3 of the 4 issues have been addressed.
[Wording: "never" → "no longer"] — ✅ addressed. The description and deprecationNote now correctly say "No longer read by the component since Camel 2.21".
[Upgrade guide entry] — ✅ addressed. The camel-4x-upgrade-guide-4_24.adoc now has a camel-pdf section with the Processor workaround and an explanation of why the byte[] converter can't decrypt.
[Test nit: header set in PdfAppendTest / PdfTextExtractionTest] — ✅ addressed. Both tests no longer import or set StandardDecryptionMaterial.
[Description duplication] — @Metadata(description = ...) text ends with "No longer read by the component (no effect since Camel 2.21).", and the catalog generator then appends "Deprecation note: No longer read by the component since Camel 2.21: ..." automatically. The result is visible in the generated pdf.json:
"description": "... No longer read by the component (no effect since Camel 2.21). Deprecation note: No longer read by the component since Camel 2.21: ..."
The fix is to strip the sentence from the description and let the deprecationNote carry the full explanation alone. The inline suggestion below shows the change — after it, rebuild components/camel-pdf and commit the regenerated pdf.json files and PdfEndpointBuilderFactory.java.
This review was generated by an AI agent, Hermès on behalf of @gnodet.
# Conflicts: # docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc
davsclaus
left a comment
There was a problem hiding this comment.
Thanks @Dhairya-007, every point from my last review is in now:
- The note says "No longer read by the component since Camel 2.21" (
PdfHeaderConstants.java:39-42), and the description is down to the expected type and one sentence. Bothpdf.jsonfiles andPdfEndpointBuilderFactorymatch it. - The upgrade-guide section explains why the header does nothing (PDFBox 2 decrypts at load time). Its example loads the document with its password in a
Processor, which fitsextractText, as that operation reads aPDDocumentbody (PdfProducer.java:145). PdfAppendTestandPdfTextExtractionTestno longer set the header, and the unusedStandardDecryptionMaterialimports are gone.
- [Nit, optional] The catalog says "no longer read" twice: in the description at
PdfHeaderConstants.java:38, and again in the "Deprecation note:" that the generator appends. If you drop line 38, as gnodet-bot suggests, regenerate the twopdf.jsonfiles andPdfEndpointBuilderFactory. It is fine as it is, too.
LGTM.
Claude Code on behalf of davsclaus. This review was generated by an AI agent and may contain inaccuracies; please verify all suggestions before applying.
gnodet-bot
left a comment
There was a problem hiding this comment.
Following up on my earlier review — 3 of 4 findings addressed. One remains open.
Previous findings status:
- Wording fix: ✅ Addressed
- Upgrade guide entry: ✅ Addressed
- Test cleanup: ✅ Addressed
- Description duplication in generated output: ❌ NOT addressed
Open finding — description duplication: The @Metadata(description) on PdfHeaderConstants.java ends with "No longer read by the component (no effect since Camel 2.21)." The catalog generator then auto-appends the deprecationNote which also says "No longer read by the component since Camel 2.21", causing "No longer read" to appear three times in the generated catalog JSON description field.
Fix: remove the trailing deprecation sentence from the description attribute. Let deprecationNote carry the full deprecation explanation alone. The description should end after the type information: "The decryption material to decrypt the PDF document. ..." — stop there, don't repeat what deprecationNote already says.
The deprecation mechanics are otherwise correct (@Deprecated annotation, deprecationNote, catalog JSON "deprecated": true, DSL method deprecated).
This review was generated by an AI agent, Hermès on behalf of @gnodet.
oscerd
left a comment
There was a problem hiding this comment.
Verified the claim, and it holds: CamelPdfDecryptionMaterial is dead.
PdfProducer does read PROTECTION_POLICY_HEADER_NAME (for the protection policy on append and on the standard-protection path), but it never reads DECRYPTION_MATERIAL_HEADER_NAME, and there is no endpoint option that carries decryption material either. So a header the docs call "Mandatory if the PDF is encrypted" in fact does nothing.
The nice part is that the tests confirm it rather than hide it. PdfAppendTest and PdfTextExtractionTest set the header with a real StandardDecryptionMaterial, but the document they send was already opened with its password through Loader.loadPDF(bytes, userPass), so the producer received an already-decrypted PDDocument and the header was never the thing doing the work. Removing the header-set and sending the loaded document, with CI still green, shows the coverage was never relying on it.
Marking it @Deprecated with a deprecationNote, plus the upgrade-guide entry, is the right conservative path: you cannot remove a documented public header outright, and keeping it one cycle while telling users it is inert is honest. The catalog and DSL regen is included and green. Good cleanup that makes the header table match the code.
Claude Code on behalf of oscerd
…ts its deprecation note Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Claus Ibsen <claus.ibsen@gmail.com>
Resolves the conflict with main in the 4.24 upgrade guide (both entries kept), and drops the repeated sentence from the generated endpoint DSL Javadoc as well. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Claus Ibsen <claus.ibsen@gmail.com>
gnodet-bot
left a comment
There was a problem hiding this comment.
Following up on my earlier review — the remaining open finding is now addressed.
[Description duplication in generated output] — ✅ addressed. The trailing sentence "No longer read by the component (no effect since Camel 2.21)." has been removed from @Metadata(description = ...) in PdfHeaderConstants.java. The catalog generator now appends only the deprecationNote once — no repetition. The PdfEndpointBuilderFactory Javadoc likewise no longer says "Mandatory* header if PDF document is encrypted." (which was incorrect); it now correctly reflects the deprecation note.
All findings from previous reviews are fully resolved. LGTM.
This review was generated by an AI agent, Hermès on behalf of @gnodet.
Problem
The header is documented as mandatory for encrypted documents:
The component never looks it up.
PdfProducerstatically imports the constants and readsPDF_DOCUMENT_HEADER_NAMEandPROTECTION_POLICY_HEADER_NAMEby name, butDECRYPTION_MATERIAL_HEADER_NAMEappears nowhere in the main sources. The only other references are two tests, which decrypt the document themselves before sending it:so the header they set alongside is decoration - the body is a
PDDocumentthat is already decrypted, and that is why the tests pass.Following the documentation instead does not work. The one point where the material could be applied is the converter, which loads without a password:
so sending an encrypted PDF as
byte[]withCamelPdfDecryptionMaterialset fails inside the type converter with PDFBox'sInvalidPasswordException, before the producer is even entered - with nothing to connect that to the header the docs said was mandatory.It reads like a leftover of the PDFBox 1.x API, where you opened the document and then decrypted it with
document.openProtection(decryptionMaterial). PDFBox 2 and 3 take the password at load time, so by the time the component has aPDDocumentthere is nothing left to decrypt.Fix
Deprecate the constant with a
deprecationNotesaying why, so the catalog and the header table stop presenting it as the way to read an encrypted PDF. The constant stays, so nothing stops compiling.The alternative is to make it work: give
PdfConverteranExchangeparameter, read the header there and pass the password toLoader.loadPDF(bytes, password). That coversStandardDecryptionMaterialonly -Loaderhas no overload forPublicKeyDecryptionMaterial- and it changes a shared type converter, so I did not want to decide it here. Happy to do it instead if you would rather have the header work.