Federico Mariani created CAMEL-25534:
----------------------------------------
Summary: camel-mail - subject option description still says the
Subject header takes precedence, but useHeaderSubject defaults to false
Key: CAMEL-25534
URL: https://issues.apache.org/jira/browse/CAMEL-25534
Project: Camel
Issue Type: Bug
Components: camel-mail
Affects Versions: 4.22.1
Reporter: Federico Mariani
Follow-up to CAMEL-24848, which corrected the useHeader* descriptions on main
and camel-4.22.x. The description of the {{subject}} endpoint option was not
touched and still states the opposite of the actual behaviour since CAMEL-23747
made {{useHeaderSubject}} default to false.
h3. Reproduction
Catalog metadata for smtp (same in imap/imaps/pop3/pop3s/smtps), on
camel-4.22.1, camel-4.22.x and main:
{noformat}
"subject": { ... "description": "The Subject of the message being sent. Note:
Setting the subject in the header takes precedence over this option." }
"useHeaderSubject": { ... "defaultValue": false, ... }
{noformat}
A route that sets the header and leaves the URI without {{subject}}:
{code}
from("direct:a").setHeader("subject",
constant("Alert")).to("smtp://[email protected]");
{code}
sends a mail with an empty subject, because
{{MailBinding.appendHeadersFromCamelMessage}} only copies the Subject header
when {{configuration.isUseHeaderSubject()}} is true. With {{subject=X}} on the
URI and a Subject header, X wins, again the opposite of the note.
In an evaluation of coding agents (Claude Code and IBM Bob) on Mule-to-Camel
migration tasks, 25 sessions read this description through camel-jbang-mcp
4.22.1 ({{camel_catalog_component_doc smtp}}); at least one concluded from it
that the Subject header overrides the URI subject, and a mail sent with an
empty subject (Subject set only as a header) was the most frequent remaining
defect in the generated routes (10 sessions).
h3. Cause
*
{{components/camel-mail/src/main/java/org/apache/camel/component/mail/MailConfiguration.java}},
javadoc of {{setSubject}}: "Note: Setting the subject in the header takes
precedence over this option."
* {{components/camel-mail/src/main/docs/mail-component.adoc}}, section on the
message content: "The subject of the MimeMessage can be configured using a
header property on the IN message" with a {{setHeader("subject", ...)}}
example, followed by "The same applies for other MimeMessage headers such as
recipients, so you can use a header property as To" and a ProducerTemplate
example with To/From/Subject headers. With the 4.22 defaults none of these
headers are used unless the matching useHeader* option is enabled.
* {{MailBinding.populateMailMessage}} code comments ("the headers win UNLESS
useHeaderSubject is set to false", same for replyTo) describe the old default.
h3. Fix
* Change the {{subject}} javadoc to something like: "The Subject of the message
being sent. The Subject message header is ignored unless useHeaderSubject=true,
in which case it overrides this option." and regenerate the component/catalog
JSON and the endpoint DSL builders.
* In mail-component.adoc, add {{useHeaderSubject=true}} (and
{{useHeaderRecipients=true}}/{{useHeaderFrom=true}} for the To/From example) to
the examples, or state next to them that the headers are only honoured when the
useHeader* options are enabled.
* Update the two comments in {{MailBinding.populateMailMessage}}.
Documentation only, no runtime change. A backport to camel-4.22.x alongside
CAMEL-24848 would keep the 4.22.2 catalog consistent.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
