diff --git a/src/docbkx/message-publishing.xml b/src/docbkx/message-publishing.xml index 4f6d108c79..a2e38e9874 100644 --- a/src/docbkx/message-publishing.xml +++ b/src/docbkx/message-publishing.xml @@ -3,32 +3,32 @@ Message Publishing - Message Publishing feature will allow you to construct and send a message as a by-product of method invocation. For example; Imagine you - have a component and every time the state of this components changes you would like to get notified. The easiest - way to send notification would be to send a message to a dedicated channel, but how would you connect the method invocation that - changes the state of the object to a message sending process and what should be the structure of the - message? Message Publishing feature will allow you to do just that. + The AOP Message Publishing feature allows you to construct and send a message as a by-product of method invocation. For example, imagine you + have a component and every time the state of this component changes you would like to be notified via a Message. The easiest + way to send such notifications would be to send a message to a dedicated channel, but how would you connect the method invocation that + changes the state of the object to a message sending process, and how should the notification Message be structured? + The AOP Message Publishing feature handles these responsibilities with a configuration-driven approach.
Message Publishing Configuration - Spring Integration provides two approaches - XML and Annotation. + Spring Integration provides two approaches: XML and Annotation-driven.
- Annotation-based approach via @Publisher annotation + Annotation-driven approach via @Publisher annotation - Annotation bassed approach allows you to annotate any method with @Publisher annotation and - provide configuration attributes which will dictate the structure of a Message. Invocation of such + The annotation-driven approach allows you to annotate any method with the @Publisher annotation and + provide configuration attributes which will dictate the structure of a Message. The invocation of the annotated method will be proxied through PublisherAnnotationAdvisor which will - construct a Message and send it to a channel. + construct a Message and send it to a Message Channel. - Internally PublisherAnnotationAdvisor uses Spring 3.0 Expression Language support giving you - the flexibility and control over the structure of a Message it will build. + Internally PublisherAnnotationAdvisor uses the Spring 3.0 Expression Language support, giving you + considerable flexibility and control over the structure of the Message it will build. Here's an example: -@Publisher(value="#return", channel="testChannel", headers="bar='123',fname=#args.fname") +@Publisher(payload="#return", channel="testChannel", headers="bar='123',fname=#args.fname") public String setName(String fname, String lname){ return fname + " " + lname; } @@ -43,7 +43,7 @@ public String setName(String fname, String lname){ #return) - #exception - will bind to an exception if one is thrown. + #exception - will bind to an exception if one is thrown by the method invocation. #args - will bind to method arguments, so individual arguments could be extracted by name @@ -53,39 +53,41 @@ public String setName(String fname, String lname){ - In the above example the Message will be constructed and its structure will be as follows: + In the above example the Message will be constructed with the following structure: Message payload - will be of type String and contain the value returned by the method. - Message headers will be 'bar' with value of "123" and 'fname' with value of 'fname' argument of the method. + Message headers will contain 'bar' with a value of "123" and 'fname' with the value of the 'fname' argument passed to the method at runtime. - As with any other annotation you will need to register PublisherAnnotationBeanPostProcessor + As with most other annotation-driven features in Spring, you will need to register a post-processor + (PublisherAnnotationBeanPostProcessor). <bean class="org.springframework.integration.aop.PublisherAnnotationBeanPostProcessor"/>
+
XML-based approach via <publisher> element - XML-based approach allows you to configure Message Publishing via AOP-based configuration and - simple namespace-based configuration of MessagePublishingInterceptor. - It certainly has certain benefits over annotation based approach since it + The XML-based approach allows you to configure the same AOP-based Message Publishing functionality with + simple namespace-based configuration of a MessagePublishingInterceptor. + It certainly has some benefits over the annotation-driven approach since it allows you to use AOP pointcut expressions, thus possibly intercepting multiple methods at once or - intercepting and publishing methods to which you don't have a source code. + intercepting and publishing methods to which you don't have the source code. - To configure Message Publishing via XML all you need is the following two things: + To configure Message Publishing via XML, you only need to do the following two things: Provide configuration for MessagePublishingInterceptor - via <publisher> XML element + via the <publisher> XML element. - Provide AOP configuration to apply MessagePublishingInterceptor + Provide AOP configuration to apply the MessagePublishingInterceptor to managed objects. @@ -104,50 +106,49 @@ public String setName(String fname, String lname){ - As you can see <publisher> uses the same variables as - PublisherAnnotationAdvisor to utilize the power of Spring 3.0 Expression Langage. + As you can see the <publisher> element expects the same variables as the + PublisherAnnotationAdvisor and also utilizes the power of the Spring 3.0 Expression Language. - In the above example the execution of echo method of a testBean will - rander the Message with the following structure: + In the above example the execution of the echo method of a testBean will + render a Message with the following structure: - Message payload - will be of type String and value of "Echoing: [value]" where value is the value + The Message payload will be of type String and value of "Echoing: [value]" where value is the value returned by an executed method. - Message headers will be 'foo' with value of "bar". + The Message headers will contain the key "foo" with a value of "bar". - Message will be sent to echoChannel. + The Message will be sent to echoChannel. - In the second method mapping the execution of any method that begins with echoDef of testBean will result in the + The second method, mapping the execution of any method that begins with echoDef of testBean, will produce a Message with the following structure. - Message payload - will be the value - returned by an executed method. + The Message payload will be the value returned by an executed method. - Since channel attriute is not provided, the Message will be sent to the + Since the channel attribute is not provided explicitly, the Message will be sent to the defaultChannel defined by the publisher. - The third mapping is almost identical to the previous (with the exceptipon of method pattern), - since the return value will be mapped to the Message paylad by default if nothing else is specifued. + The third mapping is almost identical to the previous one (with the exception of method pattern), + since the return value will be mapped to the Message payload by default if nothing else is specified. - For a simple maping rules you can rely on publisher defaults. For example: + For simple mapping rules you can rely on the publisher defaults. For example: <publisher id="anotherInterceptor"/> This will map the return value of every method that matches the pointcut expression to a payload and will be sent to a default-channel. - If the defaultChannelis not specified (as above) the messages will be sent to nullChannel + If the defaultChannelis not specified (as above) the messages will be sent to the global nullChannel.