@Publisher and @Gateway JavaDocs

PR Comments

Additional info

Polishing

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.
  *
  * <p>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.
  *
+ * <p>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)

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 <gateway/>}).
+ * A stereotype annotation to provide an Integration Messaging Gateway Proxy
+ * ({@code <gateway/>}) 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

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.
+ * <p>
+ * 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.
+ * <p>
+ * 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.
+ * <p>
+ * The XML equivalent is {@code <int:publishing-interceptor>}
  *
  * @author Mark Fisher
+ *
  * @since 2.0
+ * @see org.springframework.integration.aop.MessagePublishingInterceptor
  */
 @Target({ElementType.METHOD, ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)

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: