From aa015b07fc56cff3763d1f26d297c050bc7308c7 Mon Sep 17 00:00:00 2001 From: Mark Fisher Date: Tue, 16 Nov 2010 09:31:42 -0500 Subject: [PATCH] INT-1625 updated docs for 'gateway' and 'jms' (inbound-gateway) to describe the use of the 'error-channel' attribute --- docs/src/reference/docbook/gateway.xml | 45 +++++++++++++++----------- docs/src/reference/docbook/jms.xml | 43 +++++++++++------------- 2 files changed, 45 insertions(+), 43 deletions(-) diff --git a/docs/src/reference/docbook/gateway.xml b/docs/src/reference/docbook/gateway.xml index a09aebe08a..029d85c232 100644 --- a/docs/src/reference/docbook/gateway.xml +++ b/docs/src/reference/docbook/gateway.xml @@ -78,32 +78,39 @@ As with anything else, Gateway invocation might result in errors. By default any error that has occurred downstream will be re-thrown as a MessagingExeption (RuntimeException) - upon the Gateway's method invocation. However there are times when you may want to treat an Exception as a valid reply, - by mapping it to a Message. To accomplish this our Gateway provides support for Exception mappers via the - exception-mapper attribute. + upon the Gateway's method invocation. However there are times when you may want + to simply log the error rather than propagating it, or you may want to treat an + Exception as a valid reply, by mapping it to a Message that will conform to some + "error message" contract that the caller understands. To accomplish this, our + Gateway provides support for a Message Channel dedicated to the errors via the + error-channel attribute. In the example below, you can see + that a 'transformer' is used to create a reply Message from the Exception. + error-channel="exceptionTransformationChannel"/> - - - ]]> - - foo.bar.SampleExceptionMapper is the implementation of - org.springframework.integration.message.InboundMessageMapper which only defines one method: toMessage(Object object). -{ - public Message toMessage(Throwable object) throws Exception { - MessageHandlingException ex = (MessageHandlingException) object; - return MessageBuilder.withPayload("Error happened in message: " + - ex.getFailedMessage().getPayload()).build(); - } - -} - ]]> + +]]> + The exceptionTransformer could be a simple POJO that + knows how to create the expected error response objects. That would then be + the payload that is sent back to the caller. Obviously, you could do many + more elaborate things in such an "error flow" if necessary. It might involve + routers (including Spring Integration's ErrorMessageExceptionTypeRouter), + filters, and so on. Most of the time, a simple 'transformer' should be sufficient, + however. + + + Alternatively, you might want to only log the Exception (or send it somewhere + asynchronously). If you provide a one-way flow, then nothing would be sent + back to the caller. In the case that you want to completely suppress Exceptions, + you can provide a reference to the global "nullChannel" (essentially a /dev/null + approach). Finally, as mentioned above, if no "error-channel" is defined at all, + then the Exceptions will propagate as usual. diff --git a/docs/src/reference/docbook/jms.xml b/docs/src/reference/docbook/jms.xml index 98f875935b..ac64c5b8f4 100644 --- a/docs/src/reference/docbook/jms.xml +++ b/docs/src/reference/docbook/jms.xml @@ -144,32 +144,27 @@ As with anything else, Gateway invocation might result in error. By default Producer will not be notified of the errors thta might have occurredon ythe consumer side and will time out waiting for - the reply. However there might be times when you to communicate error condition back to the consumer, - in other words treat the Exception as a valid reply valid reply by mapping it to a Message. To accomplish this - JMS Inbound Gateway provides support for Exception mappers via exception-mapper - attribute. - - + the reply. However there might be times when you want to communicate an error condition back to the consumer, + in other words treat the Exception as a valid reply by mapping it to a Message. To accomplish this + JMS Inbound Gateway provides support for a Message Channel to which errors + can be sent for processing, potentially resulting in a reply Message payload + that conforms to some contract defining what a caller may expect as an "error" + reply. Such a channel can be configured via the error-channel + attribute. + - - - - ]]> - - foo.bar.SampleExceptionMapper is the implementation of - org.springframework.integration.message.InboundMessageMapper which only defines one method toMessage(Object object). -{ - public Message toMessage(Throwable object) throws Exception { - MessageHandlingException ex = (MessageHandlingException) object; - return MessageBuilder.withPayload("Error happened in message: " + - ex.getFailedMessage().getPayload()).build(); - } - -} - ]]> - + error-channel="errorTransformationChannel"/> + + +]]> + You might notice that this example looks very similar to that included + within . + The same idea applies here: The exceptionTransformer + could be a simple POJO that creates error response objects, you could reference + the "nullChannel" to suppress the errors, or you could leave 'error-channel' out + to let the Exception propagate.