diff --git a/spring-integration-core/src/main/java/org/springframework/integration/annotation/Gateway.java b/spring-integration-core/src/main/java/org/springframework/integration/annotation/Gateway.java index 874531ded8..85defd9707 100644 --- a/spring-integration-core/src/main/java/org/springframework/integration/annotation/Gateway.java +++ b/spring-integration-core/src/main/java/org/springframework/integration/annotation/Gateway.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2014 the original author or authors. + * Copyright 2002-2015 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -24,9 +24,9 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Indicates that a method is capable of mapping its parameters to a message - * or message payload. These method-level annotations are detected by the - * {@link org.springframework.integration.gateway.GatewayProxyFactoryBean} + * Indicates that an interface method is capable of mapping its parameters + * to a message or message payload. These method-level annotations are detected + * by the {@link org.springframework.integration.gateway.GatewayProxyFactoryBean} * where the annotation attributes can override the default channel settings. * *

A method annotated with @Gateway may accept a single non-annotated @@ -44,9 +44,18 @@ import java.lang.annotation.Target; * {@link org.springframework.beans.SimpleTypeConverter} will be applied to * the return value if necessary. * + *

Note: unlike @Publisher, this annotation is for exposing a + * Messaging Endpoint based on a Proxy for the marked interface method. + * The method invocation causes messaging interaction using an + * AOP Advice. Method parameters become the part of sent message (payload, headers). + * The method return value is the result (payload) of the messaging flow invoked by the + * Proxy. + * * @author Mark Fisher * @author Gary Russell * @author Artem Bilan + * + * @see MessagingGateway */ @Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE}) @Retention(RetentionPolicy.RUNTIME) diff --git a/spring-integration-core/src/main/java/org/springframework/integration/annotation/MessagingGateway.java b/spring-integration-core/src/main/java/org/springframework/integration/annotation/MessagingGateway.java index 6ebb392ad9..6ed5924c9c 100644 --- a/spring-integration-core/src/main/java/org/springframework/integration/annotation/MessagingGateway.java +++ b/spring-integration-core/src/main/java/org/springframework/integration/annotation/MessagingGateway.java @@ -1,5 +1,5 @@ /* - * Copyright 2014 the original author or authors. + * Copyright 2014-2015 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -23,7 +23,10 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * The stereotype annotation to provide the Integration Messaging Gateway Proxy ({@code }). + * A stereotype annotation to provide an Integration Messaging Gateway Proxy + * ({@code }) as an abstraction over the messaging API. The target + * application’s business logic may be completely unaware of the Spring Integration + * API, with the code interacting only via the interface. * * @author Artem Bilan * @since 4.0 diff --git a/spring-integration-core/src/main/java/org/springframework/integration/annotation/Publisher.java b/spring-integration-core/src/main/java/org/springframework/integration/annotation/Publisher.java index c02fb5b8f7..b494cc10b3 100644 --- a/spring-integration-core/src/main/java/org/springframework/integration/annotation/Publisher.java +++ b/spring-integration-core/src/main/java/org/springframework/integration/annotation/Publisher.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2014 the original author or authors. + * Copyright 2002-2015 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -23,11 +23,26 @@ import java.lang.annotation.Target; /** * Annotation to indicate that a method, or all public methods if applied at - * class-level, should publish Messages. The @Payload and @Header annotations - * can be used in conjunction with this to determine the content of the Message. + * class-level, should publish Messages. + *

+ * By default, the Message will be constructed from the return value of the method + * invocation + * and sent to a channel specified by the {@link #channel()} attribute. + * However, a combination of both @Payload and @Header annotations + * can be used to further manage the message structure. See the reference manual for + * examples. + *

+ * Note: unlike @Gateway, this annotation is used to generate an AOP Advice for an + * existing service and its method implementation. The message sending is a side effect + * of the real method invocation and is invoked after the method returns. + * The advised method(s) are not aware of the messaging interaction. + *

+ * The XML equivalent is {@code } * * @author Mark Fisher + * * @since 2.0 + * @see org.springframework.integration.aop.MessagePublishingInterceptor */ @Target({ElementType.METHOD, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) diff --git a/src/reference/asciidoc/message-publishing.adoc b/src/reference/asciidoc/message-publishing.adoc index 35e3994293..7e561337de 100644 --- a/src/reference/asciidoc/message-publishing.adoc +++ b/src/reference/asciidoc/message-publishing.adoc @@ -3,7 +3,8 @@ The AOP Message Publishing feature allows you to construct and send a message as a by-product of a 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. +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-config]] === Message Publishing Configuration @@ -17,7 +18,7 @@ The annotation-driven approach allows you to annotate any method with the `@Publ The Message will be constructed from the return value of the method invocation and sent to a channel specified by the 'channel' attribute. To further manage message structure, you can also use a combination of both `@Payload` and `@Header` annotations. -Internally this message publishing feature of Spring Integration uses both Spring AOP by defining `PublisherAnnotationAdvisor` and Spring 3.0's Expression Language (SpEL) support, giving you considerable flexibility and control over the structure of the_Message_ it will publish. +Internally this message publishing feature of Spring Integration uses both Spring AOP by defining `PublisherAnnotationAdvisor` and Spring 3.0's Expression Language (SpEL) support, giving you considerable flexibility and control over the structure of the _Message_ it will publish. The `PublisherAnnotationAdvisor` defines and binds the following variables: