Same prescription, two answers
Two lines from a pharmacy chain's refill log, eleven minutes apart:
09:02 http rx 55120 refill rejected: new prescription required09:13 queue rx 55120 refill accepted, pickup Thursday
The first came from the chain's own app, where a patient tapped Refill. The second came from the e-prescribing hub that doctors' offices use, which sends refill requests as messages on a queue, refill-requests, and expects an answer to each. Both paths were meant to apply the same rules, and once they did. When the hub integration was built, the developer wrote a queue listener and copied the refill checks into it from RefillService, the class the app's HTTP API calls. In March the chain tightened its rule for controlled substances, the team changed RefillService, and nobody remembered the copy. The two paths drifted apart, and the copy kept accepting refills the service refused.
The message calls the method
The listener never needed to know the rules. A Service Activator is a receiving endpoint whose job is to turn a message into a call to a service method that already exists, and the result of that call back into whatever the sender expects. For each refill request, it reads requestId, rxId and pharmacyId from the message, calls RefillService.requestRefill(requestId, rxId, pharmacyId), the same method the HTTP API calls, and turns the RefillDecision it returns into a reply. It is a Message Endpoint like any other, so it takes its messages by polling or by being called, as that article describes.
The app reaches RefillService through its HTTP API; the hub's messages reach the same method through the activator, which sends each answer back as a reply.
RefillService does not know that messages exist. It takes a request id, a prescription id and a pharmacy id and returns a decision, exactly as it did before the hub arrived, so the controlled-substance rule lives in one place and both paths get it. The asynchronous messages and the synchronous API now share one implementation; the activator is only the messaging adapter in front of it.
What stays in the activator is translation, and on the success path it is smaller than it sounds: read fields, call a method, build a reply. A check on whether a refill is allowed does not belong in it, and neither does the database query behind such a check. If the activator seems to need one, the service is missing a method.
That translation is also what keeps two contracts apart. The hub's message format is agreed with the hub and changes slowly; the method's signature belongs to the pharmacy team and changes when they need it to. When requestRefill gains a fourth parameter, a preferred pickup date, the activator passes the field if the message has it and, if not, a default that keeps an old request's meaning, such as no preference; the hub, which still sends last year's format, notices nothing. A message format wired straight to the method's signature would expose the hub to the method's changes.
Where the answer goes
Each request names the channel the hub reads its replies from and carries an id. The activator sends the reply to that channel, the request's Return Address, and copies the id onto it, so the hub can match it; matching replies to pending requests is the hub's side of a Correlation Identifier. Whether a reply goes back is set by what the sender expects, not by the method's return type: for a note that a label was printed, which expects no answer, the activator sends none.
Exceptions are several different failures
The harder half of the job is what happens when the call does not simply return a decision. The service speaks in return values and exceptions; the queue understands acknowledgements and redeliveries. The activator translates one into the other, case by case:
- A refusal is an answer. "No refills remaining" or "new prescription required" comes back as a
RefillDecision, like an acceptance. The activator replies with it and acknowledges the request: the message was processed, and the outcome was no. The same goes for aPrescriptionNotFoundexception, which the hub needs to hear about as a rejection, not as a redelivery. - A message the activator cannot read, a body that is not valid JSON or one with no
rxId, never reaches the service. Delivering it again will not make it readable, so the activator moves it to an Invalid Message Channel and only then acknowledges the original. - A failure that may pass, a database timeout or a refused connection, is the case where the request should come back. The activator does not acknowledge it, or rejects it back to the queue, depending on the broker, and the request is delivered again. Retry decides how long to wait and how many times to try.
- A failure that does not pass, a bug that throws on this one request every time, looks like the previous case until the attempts run out. With a bound on deliveries, the request then goes to a Dead Letter Channel, moved there by the broker or by the activator; a broker that reaches the bound with no dead-letter channel configured drops the request instead. With no bound, it keeps coming back.
The two shortcuts both go wrong. Catch every exception, log it and acknowledge, and the database timeout at 09:30 becomes a request the hub never hears about again. Let every exception escape, and the request with no rxId is redelivered again and again, failing each time before the service is even called. And every redelivered request reaches requestRefill again, so a refill already written must be recognised by the request id the activator passes in, as Idempotent Consumer shows; making the receive and the reply send one unit is a separate design, Transactional Client.
One rule, one place, one way back
In the Messaging Endpoints & Broker Challenge, make one of the Message Endpoints a Service Activator. The palette has no Service node, so let the activator's edge end at the application node and name on it the method the synchronous callers already use. Then follow the reply: when the requester names its reply channel, as the hub does, the reply should leave the activator for that Return Address, not for a channel fixed in the activator's configuration. A reviewer looking for the controlled-substance rule should find it behind that method, and nowhere on the activator.