Class CloudEventBinding
The CloudEvents protocol binding a transport speaks, which decides how binary-mode attributes are named on the wire.
public sealed class CloudEventBinding
- Inheritance
-
CloudEventBinding
- Inherited Members
- Extension Methods
Remarks
Binary mode is exactly the thing a protocol binding defines, so a transport with no binding has no
conformant binary mode — and that is a limit on what we may CLAIM, not on what we may read.
Structured mode is defined by the core specification rather than by any binding — the whole event as
JSON under application/cloudevents+json — so it is conformant anywhere bytes and a content type
travel together, and StructuredOnly is the honest answer where nothing binary is written
or received.
Where this framework already writes attribute names on an unbound transport, it must also read them. That is HouseConvention, and it is not an invented prefix filling a gap: the spelling is already on the wire, and refusing to recognise it would publish events this library cannot itself consume. What must never happen is calling such a spelling a protocol binding — a private convention described as spec compliance is the failure the distinction exists to prevent. The convention is legitimate; the claim about it is what has to stay honest.
The binding is supplied by the transport rather than looked up. A lookup keyed by transport is a second place to forget one; a required argument cannot be forgotten, because the registration does not compile without it.
Properties
Amqp10
Gets the AMQP 1.0 binding, used by transports whose wire protocol is AMQP 1.0.
public static CloudEventBinding Amqp10 { get; }
Property Value
Remarks
Reads three spellings and they are not the same kind of thing:
-
cloudEvents_— what this framework writes, and what the binding's current revision prefers. The underscore is preferred for a concrete reason: a colon is not permitted in a JMS 2.0 property identifier, so the colon form cannot be used in a JMS message selector, and AMQP-to-JMS bridging is ordinary on these transports. -
cloudEvents:— the only spelling the released revision of the binding permitted. A publisher conformant to it writes the colon exclusively and stays conformant forever, so this read is permanent. It is compatibility with the standard, not with our own history, and it must never be scheduled for removal. -
ce-— the HTTP binding's prefix, which this framework wrongly emitted over AMQP in earlier releases. This one is compatibility with our past and is the only member of this set that may eventually be withdrawn.
HouseConvention
Gets the ce- spelling this framework uses on transports the CloudEvents specification
assigns no protocol binding to.
public static CloudEventBinding HouseConvention { get; }
Property Value
Remarks
A documented house convention, not a protocol binding, and it must not be described as one. It applies where the specification is silent — AMQP 0-9-1, SQS/SNS and Pub/Sub — and the spelling is borrowed from the HTTP binding because that is what this framework has always written there.
IBM MQ was in that list and is not any more: it cannot carry this spelling at all. The two questions below both assume the wire can hold the name being argued about, and on IBM MQ it cannot — a property name is validated as a Java identifier, so the hyphen is refused outright. That is a third question, prior to both, and answering only the first two put the transport here for a year: not do we write it or can we be sent it, but can this platform express it. Where the answer is no, the assignment is unreachable rather than merely unconventional — see IbmMq.
A binding answers two independent questions, and deriving both from one fact is what put these transports in the wrong row twice.
- What do we EMIT? A transport whose adapter writes these names and whose receiver refuses to read them publishes events it cannot itself consume. The format is on the wire either way, so declining to read it buys no conformance and costs the round trip.
- What can we BE SENT? Independent of the first, and it is the one that gets skipped — because emission is easy to check and a criterion that is easy to check gets applied to questions it does not answer. A transport that emits nothing may still receive these names from a third-party publisher, and its receiver may have been arranged deliberately to carry them.
IbmMq
Gets the IBM MQ spelling, which assigns ce_ because an IBM MQ property name cannot carry a
hyphen.
public static CloudEventBinding IbmMq { get; }
Property Value
Remarks
Like HouseConvention this is a house spelling and not a protocol binding — the
specification assigns IBM MQ none, and calling a private convention a binding is the claim this type
exists to keep honest. It is separate from HouseConvention for a platform reason rather
than a stylistic one: IBM MQ validates a property name as a Java identifier, so the hyphenated
spelling is not merely unconventional there but unsettable — the queue manager refuses it with
MQRC_PROPERTY_NAME_ERROR (2442).
The refusal is silent by design, which is what made this expensive. Both the sender's property loop and a real queue catch that rejection, log it, and carry on — so a hyphenated attribute is simply absent from the message rather than failing the send. A binary-mode CloudEvent published over a HouseConvention-bound IBM MQ transport therefore arrived at a consumer of this framework as ordinary traffic, indistinguishable from a message that never carried CloudEvents markers.
Changing the spelling here breaks nothing, because the old one was never on the wire. The
platform refused it in both directions: we could not write ce- and no third-party publisher
could set it either. There is no deployed message carrying the hyphenated names to stay compatible
with — which is the difference between this and Amqp10, where the superseded
ce- spelling really was emitted and must keep being read.
It shares Kafka's underscore for the same class of reason and is declared separately anyway: two transports whose prefixes agree by coincidence of platform rules are one edit away from disagreeing, and a shared constant would make that edit silent.
Kafka
Gets the Kafka binding, which assigns ce_ because a Kafka header key cannot carry a hyphen.
public static CloudEventBinding Kafka { get; }
Property Value
Mqtt
Gets the MQTT binding, which assigns bare attribute names carried as user properties.
public static CloudEventBinding Mqtt { get; }
Property Value
Remarks
Bare names are honoured only here. Probing them on a transport whose binding does not assign
them is how an ordinary application property called id or type becomes a CloudEvents
attribute by accident.
StructuredOnly
Gets the binding for a transport the specification assigns none to, which therefore offers structured mode only.
public static CloudEventBinding StructuredOnly { get; }
Property Value
Remarks
Carries no attribute prefixes, so no inbound message is read as a binary-mode CloudEvent. Structured mode is unaffected: it is recognised by content type and needs no binding at all, so these transports send and receive CloudEvents conformantly — just not in binary mode, which for them does not exist to be conformant with.