From de21e3f20136788769e1d1e36f28a9a7d3d0a0fb Mon Sep 17 00:00:00 2001 From: Oleg Zhurakousky Date: Tue, 31 Aug 2010 11:30:13 +0000 Subject: [PATCH] INT-1246, INT-1252 - modified docs for Message Publishing interceptor, added docs for schduled-producer --- src/docbkx/message-publishing.xml | 157 ++++++++++++++++++++++++++---- 1 file changed, 137 insertions(+), 20 deletions(-) diff --git a/src/docbkx/message-publishing.xml b/src/docbkx/message-publishing.xml index a2e38e9874..c75bcf9b12 100644 --- a/src/docbkx/message-publishing.xml +++ b/src/docbkx/message-publishing.xml @@ -17,24 +17,15 @@
Annotation-driven approach via @Publisher annotation - 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 Message Channel. + The annotation-driven approach allows you to annotate any method with the @Publisher annotation, specifying 'channel' attribute. + The Message will be constructed from the return value of method invocation and sent to a channel specified by 'channel' attribute. + To further manage message structure you can also use a combination of both @Payload and @Header annotations. - 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: + Internally message publishing feature of Spring Integration uses both Spring AOP by defining PublisherAnnotationAdvisor and + Spring 3.0 Expression Language (SpEL) support, giving you considerable flexibility and control over the structure of the Message it will build. - -@Publisher(payload="#return", channel="testChannel", headers="bar='123',fname=#args.fname") -public String setName(String fname, String lname){ - return fname + " " + lname; -} - - - PublisherAnnotationAdvisor defines and binds the following variables: @@ -51,22 +42,84 @@ public String setName(String fname, String lname){ - + + + Let's look at couple of examples: + + +@Publisher +public String defaultPayload(String fname, String lname) { + return fname + " " + lname; +} + 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 payload - will be the return type and value of the method. This is the default. - 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. + A newly constructed message will be sent to a default publisher channel configured with annotation post processor (see the end of this section). + + +@Publisher(channel="testChannel") +public String defaultPayload(String fname, @Header("last") String lname) { + return fname + " " + lname; +} + + + In this example everything is the same as above, however we are not using default publishing channel. Instead we are specifying + the publishing channel via 'channel' attribute of @Publisher annotation. + We are also adding @Header annotation which results in the Message header with the name 'last' and the value of 'lname' input parameter + to be added to the newly constructed Message. + + +@Publisher(channel="testChannel") +@Payload +public String defaultPayloadButExplicitAnnotation(String fname, @Header String lname) { + return fname + " " + lname; +} + + + The above example is almost identical to the previous one. The only difference here is that we are using @Payload annotation + on the method, thus explicitly specifying that the return value of the method should be used as a payload of the Message. + + + +@Publisher(channel="testChannel") +@Payload("#return + #args.lname") +public String setName(String fname, String lname, @Header("x") int num) { + return fname + " " + lname; +} + + + Here we are expending on the previous configuration by using Spring Expression language in the @Payload annotation further instructing + the framework on how the message should be constructed. In this particular case the message will be a concatenation of the return value of the method invocation and + 'lname' input argument. Message header 'x' with value of 'num' input argument will be added to the newly constructed Message. + + + +@Publisher(channel="testChannel") +public String argumentAsPayload(@Payload String fname, @Header String lname) { + return fname + " " + lname; +} + + + In the above example you see another usage of @Payload annotation. Here we are annotating method argument + which will become a payload of newly constructed message. + + + 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"/> + You can also use namespace support for added convenience: + +<si:annotation-config default-publisher-channel="defaultChannel"/>
@@ -84,7 +137,7 @@ public String setName(String fname, String lname){ Provide configuration for MessagePublishingInterceptor - via the <publisher> XML element. + via the <publishing-interceptor> XML element. Provide AOP configuration to apply the MessagePublishingInterceptor to managed objects. @@ -98,11 +151,11 @@ public String setName(String fname, String lname){ <aop:advisor advice-ref="interceptor" pointcut="bean(testBean)" /> </aop:config> -<publisher id="interceptor" default-channel="defaultChannel"> +<publishing-interceptor id="interceptor" default-channel="defaultChannel"> <method pattern="echo" payload="'Echoing: ' + #return" headers="foo='bar'" channel="echoChannel"/> <method pattern="echoDef*" payload="#return"/> <method pattern="foo*"/> -</publisher> +</publishing-interceptor> @@ -151,5 +204,69 @@ public String setName(String fname, String lname){ If the defaultChannelis not specified (as above) the messages will be sent to the global nullChannel. + +
+ Producing and publishing messages based on schedule + + In the above sections we looked at the Message publishing feature of Spring Intergarion which constructs and publishes messages as by-products of Method invocations. + However you are still respponsible to invoke the method. + With scheduling support added to Spring framework 3.0 we've added another useful feature to Spring Integrarion - support for scheduled Message producers/publishers. Scheduling could be based on several triggers. + Currently we support cron, fixed-rate, fixed-delay as well as the custom triggers implemented by you. + + + Support for scheduled producers/publishers is provided via <scheduled-producer> xml element. + Lets look at couple of examples: + + + + ]]> + + In the above example scheduled producer will be created which will construct the Message with payload being the result of the expression  + defined in payload-expression attribute. Such message will be created and sent every time after a delay specified in the fixed-delay attribute. + + + ]]> + + This example is very similar to the previous one, except that we are using fixed-rate attribute which will allow us to send messages at the fixed rate. + + ]]> + + This example demonstrates how you can apply Cron trigger specified by cron attribute. + + + +
+
+]]> + + Here you can see that in a way very similar to Message publishing feature we are enriching a newly constructed Message with + extra Message headers which could take scalar values as well as Spring expressions. + + + + If you need to implement your own custom trigger you can use trigger attribute pointing to any spring configured + bean which implements org.springframework.scheduling.Trigger interface. + + + + + +]]> + + +
\ No newline at end of file