[
https://issues.apache.org/jira/browse/CAMEL-24988?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Luigi De Masi reassigned CAMEL-24988:
-------------------------------------
Assignee: Luigi De Masi
> camel-core: Add switch EIP for literal value-based endpoint dispatch
> --------------------------------------------------------------------
>
> Key: CAMEL-24988
> URL: https://issues.apache.org/jira/browse/CAMEL-24988
> Project: Camel
> Issue Type: New Feature
> Reporter: Claus Ibsen
> Assignee: Luigi De Masi
> Priority: Minor
>
> h2. Problem
> Camel has no concise, safe way to dispatch a message to one of a fixed set of
> endpoints based on a value carried in the message.
> The short form today is:
> {code:java}
> .toD("direct:${header.department}")
> {code}
> which takes the endpoint name straight out of message data. Camel's threat
> model treats external message senders as untrusted, so this hands endpoint
> selection to the sender. The safe form is Choice:
> {code:java}
> .choice()
> .when(simple("${header.department} == 'billing'")).to("direct:billing")
> .when(simple("${header.department} ==
> 'technical'")).to("direct:technical")
> .otherwise().to("direct:general")
> .end();
> {code}
> Correct, but verbose, it repeats the selector in every branch, and it costs
> an O(n) predicate scan per message.
> h2. Proposal
> A new {{switch}} EIP: a decision table mapping literal values to endpoint
> URIs.
> * A {{selector}} expression is evaluated once per entry and produces the
> value to match.
> * Each {{case}} carries a literal {{value}} and a target {{uri}}, both as
> attributes. Matching is *case-insensitive*: real-world data spells the same
> thing {{customerID}} and {{customerId}}, and a router that silently drops a
> message over letter case is a poor trade for strictness.
> * {{otherwise}} is a fallback uri. Null and unmatched selector results use
> it. With no {{otherwise}}, processing simply continues.
> * Dispatch is a map lookup rather than a scan. Case-insensitivity costs
> nothing here: the map is keyed on the normalised value and looked up with the
> normalised selector result, so it stays O(1).
> The identity of this EIP is *the safe alternative to toD*, not "Choice with
> less". The set of destinations is closed and declared in the route; message
> data selects among them but cannot name a new one.
> h2. Non-goals
> Choice is a foundational EIP and is *not modified by this issue*. It keeps
> every advanced capability: nested steps per branch, arbitrary predicates,
> precondition mode, disabled branches.
> {{switch}} deliberately has none of those. One value, one destination, no
> nested steps. The moment a branch needs more than a single destination, the
> route goes back to Choice. That cliff is intentional and is what keeps
> {{switch}} readable as a table.
> Specifically out of scope: nested {{steps}}, {{to}}/{{toD}} sub-elements,
> predicates, precondition mode. Simple expressions in {{uri}} are not
> supported either; {{uri}} takes property placeholders resolved at build time,
> and anything genuinely dynamic remains toD's job.
> h2. DSL
> {{switch}} and {{case}} are both reserved words in Java, so the Java DSL
> follows the existing doTry/doCatch/doFinally precedent.
> Java:
> {code:java}
> from("direct:tickets")
> .doSwitch(header("department"))
> .doCase("billing", "direct:billing")
> .doCase("technical", "direct:technical")
> .otherwise("direct:general")
> .end();
> {code}
> XML:
> {code:xml}
> <switch otherwise="direct:general">
> <selector><header>department</header></selector>
> <case value="billing" uri="direct:billing"/>
> <case value="technical" uri="direct:technical"/>
> </switch>
> {code}
> YAML:
> {code:yaml}
> - switch:
> selector:
> header:
> expression: department
> case:
> - value: billing
> uri: direct:billing
> - value: orders
> uri: kafka
> parameters:
> topic: cheese
> otherwise: direct:general
> {code}
> h2. Model design
> Two new definitions in {{camel-core-model}}:
> {code:java}
> @XmlRootElement(name = "switch")
> @XmlType(propOrder = { "selector", "cases" })
> public class SwitchDefinition extends NoOutputDefinition<SwitchDefinition> {
> @XmlElement
> private ExpressionSubElementDefinition selector;
> @XmlElement(name = "case")
> private List<SwitchCaseDefinition> cases = new ArrayList<>();
> @XmlAttribute
> private String otherwise;
> }
> @XmlRootElement(name = "case")
> public class SwitchCaseDefinition extends
> OptionalIdentifiedDefinition<SwitchCaseDefinition>
> implements EndpointRequiredDefinition {
> @XmlAttribute(required = true) private String value;
> @XmlAttribute(required = true) private String uri;
> }
> {code}
> Notes:
> * The Java field is {{cases}} with {{@XmlElement(name = "case")}}, mirroring
> how {{ChoiceDefinition.whenClauses}} already maps to the {{when}} element.
> This is the established way the model works around a Java keyword.
> * {{cases}} is a *List*, not a Map. Two reasons: each case needs an identity
> to hang an id on (see Management below), and declaration order becomes
> significant if pattern matching is added later (see Follow-up).
> * {{OtherwiseDefinition}} is *not* reusable here. It holds a nested
> {{List<ProcessorDefinition<?>>}} outputs list, i.e. it is a steps block.
> Hence {{otherwise}} as a plain uri attribute on {{switch}}.
> * Do *not* extract a shared base class from {{ChoiceDefinition}}. Inserting
> an abstract parent between it and {{NoOutputDefinition}} changes choice's
> {{<xs:extension base=...>}} in the generated XSD, which is itself a change to
> Choice.
> h2. Runtime design
> * New {{SwitchProcessor}} in {{camel-core-processor}}, backed by a
> {{Map<String, Processor>}} built at reify time. Evaluate the selector once as
> a String, look up, dispatch. Null or unmatched goes to the otherwise
> processor if configured, otherwise processing continues.
> * Selector evaluation follows normal Camel error handling. A selector that
> throws does *not* fall through to otherwise.
> * Reset the stream cache once after selector evaluation, not per branch.
> * New {{SwitchReifier}} in {{camel-core-reifier}}. Registration in
> {{ProcessorReifier}} is an additive branch; it does not touch the Choice
> branch.
> Validation at reify time:
> * duplicate {{value}} across cases is rejected, *compared
> case-insensitively*. {{value="Billing"}} and {{value="billing"}} are the same
> case and must be an error rather than one silently shadowing the other.
> * a case with no {{value}} or no {{uri}} is rejected
> * an empty {{<selector/>}} with no nested expression is rejected with a clear
> message rather than an NPE
> Normalisation must use {{Locale.ENGLISH}} explicitly, never the default
> locale. Lowercasing with the platform locale breaks on a JVM running in a
> Turkish locale, where {{"I".toLowerCase()}} yields a dotless i and route
> dispatch would silently stop matching. {{PatternHelper}} already lowercases
> with {{Locale.ENGLISH}} for exactly this reason.
> h2. YAML uri and parameters
> {{case}} should accept the canonical form that visual tooling such as Karavan
> and Kaoto emits, rather than requiring a single assembled URI string:
> {code:yaml}
> - value: orders
> uri: kafka
> parameters:
> topic: cheese
> {code}
> This is a YAML-DSL parse-time affordance only.
> {{YamlDeserializerEndpointAwareBase}} collapses uri plus parameters into one
> URI via {{YamlSupport.createEndpointUri(...)}} before the model is built, so
> the model only ever holds a single uri String. XML keeps the assembled form.
> The opt-in currently lives in {{GenerateYamlDeserializersMojo}} (around line
> 591) as a hard-coded check on three class names: {{SendDefinition}},
> {{ToDynamicDefinition}}, {{PollDefinition}}.
> *Preferred approach:* replace that condition with the existing
> {{EndpointRequiredDefinition}} marker interface in {{camel-core-model}},
> which already declares {{getEndpointUri()}} and is already implemented by
> {{SendDefinition}}, {{PollDefinition}} and {{FromDefinition}}.
> {{SwitchCaseDefinition}} then implements it and gets uri plus parameters for
> free, with no new hard-coded model names in the generator. There is precedent
> in the very next branch of the same method, which tests the
> {{HasExpressionType}} interface rather than class names.
> Caveat to verify during implementation: {{ToDynamicDefinition}} does not
> implement {{EndpointRequiredDefinition}} today. It either gains the
> interface, or stays as an extra term in the condition.
> Rejected alternatives: making {{SwitchCaseDefinition}} extend
> {{SendDefinition}} (drags in pattern and variableSend, too heavy for a table
> row), and adding a fourth hard-coded class name to the generator.
> h2. Management and observability
> * New {{ManagedSwitch}} MBean, registered through an additive branch in
> {{DefaultManagementObjectStrategy}}. {{ManagedChoice}} is not modified.
> * Each case gets an id via {{idOrCreate(...)}} at reify time, the way
> {{ChoiceReifier}} already does for {{when}}, so individual cases appear in
> JMX, tracing and the debugger.
> * {{extendedInformation()}} reports the table: value, uri and per-case hit
> count.
> h2. Testing
> * {{camel-core}}: exact match, no match with and without otherwise, null
> selector result, empty string value, nested switch, repeated entry via loop,
> selector throwing an exception, duplicate value rejection, missing uri
> rejection.
> * {{camel-xml-io-dsl}} and {{camel-spring-xml}}: XML round trip including
> JAXB namespace handling for an xpath selector.
> * {{camel-yaml-dsl}}: YAML round trip, plus the uri-with-parameters form.
> * {{camel-java-io}}: Java DSL export.
> * {{camel-management}}: MBean table contents and per-case counts.
> h2. Documentation
> * New {{switch-eip.adoc}} EIP page with all three DSLs.
> * Explicitly document the relationship to Choice and to toD, including when
> *not* to use switch.
> * Document that {{value}} is literal and matched case-insensitively, and that
> {{uri}} supports property placeholders but not simple expressions.
> h2. Possible follow-up, not in scope here
> Pattern matching on cases, so a case could match {{billing*}}.
> Design constraints to preserve now so this stays possible later:
> * Do *not* extend {{value}} to mean a pattern. A route written today with a
> literal asterisk in {{value}} would silently change meaning on upgrade. A
> separate {{pattern}} attribute alongside {{value}} avoids any
> reinterpretation.
> * Keep {{cases}} an ordered List. Exact matching is order-independent, but
> first-match-wins pattern matching is not.
> * The fast path survives: exact values stay in the map for O(1), pattern
> cases are scanned in declaration order only after a map miss, so routes
> without patterns pay nothing.
> Camel's house matcher is {{PatternHelper.matchPattern(name, pattern)}} in
> {{camel-support}}, used by Camel* header filtering and intercept. Its
> documented rule order is exact match, then wildcard (pattern ends with {{*}}
> and name starts with the prefix), then regex.
> {{PatternHelper}} being case-insensitive throughout, in both the exact branch
> ({{equalsIgnoreCase}}) and the wildcard branch, now lines up with this EIP
> rather than fighting it, since {{value}} is case-insensitive too. No change
> is needed there for the base feature.
> One thing to decide deliberately at that point: {{PatternHelper}} also
> accepts regular expressions, which may be more than a decision table should
> offer. If wildcard-only matching is wanted, that is a small wildcard-only
> variant in {{camel-support}} rather than a change to the existing helper,
> which other call sites depend on.
> h2. Origin
> Split out of the review of CAMEL-24977 and PR #26813, where this capability
> was originally proposed as a modification to the Choice EIP. That approach
> changed {{ChoiceDefinition}}, {{WhenDefinition}}, {{ChoiceProcessor}},
> {{ChoiceReifier}}, {{ManagedChoice}}, the generated choice and when metadata,
> both XSDs and the YAML schemas, and relaxed {{BasicExpressionNode}} so a
> {{<when>}} no longer required a predicate. Choice has been stable for twenty
> years and should stay that way, so the capability is being proposed here as
> its own EIP instead.
> ----
> _Filed by Claude Code on behalf of [~davsclaus]. cc [~ldemasi], whose work on
> CAMEL-24977 this design is derived from._
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
