[
https://issues.apache.org/jira/browse/CAMEL-24988?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18120240#comment-18120240
]
Luigi De Masi commented on CAMEL-24988:
---------------------------------------
I'd like to propose an *additive extension* to support matching a combination
of named literal values, while retaining the scalar form and the architectural
boundaries described here.
The motivating use case is CAMEL-25049: a single semantic expression can
evaluate several questions and return a map such as {{department: "billing",
urgent: true}}. Switch could use that combination to select one destination.
This would remain language-independent: any Camel expression returning the same
structure could participate.
The existing {{value}} form would remain unchanged. An optional composite form
could look like:
{code:yaml}
- switch:
selector:
language:
language: semantic
expression: refs:department,urgent
keys: [department, urgent]
case:
- values: [department: billing, urgent: true]
uri: direct:urgent-billing
- values: [department: billing, urgent: false]
uri: direct:billing
- values: [department: technical, urgent: true]
uri: direct:incident
otherwise: direct:review
{code}
Here, {{values}} is a YAML sequence of single-entry mappings. Each case
declares a complete combination of literal values; all entries must match.
There are no predicates or expression strings inside a case.
The proposed rules would be:
* {{keys}} identifies the fields to read from the selector's result map.
Additional result fields are ignored.
* Every case must specify each declared key exactly once. Entry order is
irrelevant.
* Missing required result keys or an incompatible result shape are errors. A
valid combination with no matching case uses {{otherwise}}.
* Duplicate keys and duplicate combinations are rejected at startup.
* Scalar {{value}} cases and composite {{values}} cases cannot be mixed within
one Switch.
* Field names are matched exactly. String values follow the same
case-insensitive matching policy as scalar cases.
* Values retain their scalar types. The model must define their representation
consistently across Java, XML, and YAML, including Boolean and numeric matching.
The runtime would still evaluate the selector once per entry. Cases would be
compiled into a lookup table using composite keys in the declared {{keys}}
order. Constructing the lookup key involves the selected fields, but dispatch
would not scan the cases or evaluate a predicate for each row.
The existing boundaries remain: one declared destination per case, static URI
configuration with property placeholders, YAML {{uri}} plus {{parameters}},
normal Camel error handling, and no changes to Choice. Batching stays in the
semantic language/provider; Switch would simply consume the returned values.
The additional work is primarily the portable model for named, typed literals,
its DSL/schema representations, and the corresponding validation and tests.
Would this optional composite form fit the intended scope, while preserving the
simple scalar form as the default?
_Comment written by Codex on behalf of [~ldemasi]_
> 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
> Attachments: CAMEL-24988-reference-choice-selector.diff
>
>
> 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:java}
> - 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)
