INT-964 javadoc for ChannelInterceptor

org.springframework.integration/src/main/java/org/springframework/integration/channel/ChannelInterceptor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2008 the original author or authors.
+ * Copyright 2002-2010 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.
@@ -28,12 +28,32 @@ import org.springframework.integration.core.MessageChannel;
  */
 public interface ChannelInterceptor {
 
+	/**
+	 * Invoked before the Message is actually sent to the channel.
+	 * This allows for modification of the Message if necessary.
+	 * If this method returns <code>null</code>, then the actual
+	 * send invocation will not occur.
+	 */
 	Message<?> preSend(Message<?> message, MessageChannel channel);
 
+	/**
+	 * Invoked immediately after the send invocation. The boolean
+	 * value argument represents the return value of that invocation.
+	 */
 	void postSend(Message<?> message, MessageChannel channel, boolean sent);
 
+	/**
+	 * Invoked as soon as receive is called and before a Message is
+	 * actually retrieved. If the return value is 'false', then no
+	 * Message will be retrieved. This only applies to PollableChannels.
+	 */
 	boolean preReceive(MessageChannel channel);
 
+	/**
+	 * Invoked immediately after a Message has been retrieved but before
+	 * it is returned to the caller. The Message may be modified if
+	 * necessary. This only applies to PollableChannels. 
+	 */
 	Message<?> postReceive(Message<?> message, MessageChannel channel);
 
 }

org.springframework.integration/src/main/resources/org/springframework/integration/config/xml/spring-integration-2.0.xsd

@@ -67,7 +67,13 @@
 							<xsd:element name="dispatcher" type="dispatcherType" />
 						</xsd:choice>
 						<xsd:element name="interceptors" type="channelInterceptorsType"
-							minOccurs="0" maxOccurs="1" />
+							minOccurs="0" maxOccurs="1">
+							<xsd:annotation>
+								<xsd:documentation><![CDATA[
+	A list of ChannelInterceptor instances to be applied to this channel.
+								]]></xsd:documentation>
+							</xsd:annotation>
+						</xsd:element>
 					</xsd:sequence>
 				</xsd:extension>
 			</xsd:complexContent>
@@ -203,7 +209,15 @@
 				<xsd:extension base="channelType">
 					<xsd:sequence>
 						<xsd:element name="interceptors" type="channelInterceptorsType"
-							minOccurs="0" maxOccurs="1" />
+							minOccurs="0" maxOccurs="1">
+							<xsd:annotation>
+								<xsd:documentation><![CDATA[
+	A list of ChannelInterceptor instances whose preSend and postSend methods
+	will be applied to this channel. Note that the preReceive and postReceive
+	methods have no effect for a SubscribableChannel instance.
+								]]></xsd:documentation>
+							</xsd:annotation>
+						</xsd:element>
 					</xsd:sequence>
 					<xsd:attribute name="task-executor" type="xsd:string">
 						<xsd:annotation>
@@ -1443,9 +1457,7 @@
 	<xsd:complexType name="channelInterceptorsType">
 		<xsd:annotation>
 			<xsd:documentation>
-				Defines a list of interceptors. Each element may
-				be a ChannelInterceptor,
-				ref, or inner-bean.
+	Defines a list of interceptors. Each element may be a ChannelInterceptor, ref, or inner-bean.
 			</xsd:documentation>
 		</xsd:annotation>
 		<xsd:sequence>
@@ -1474,7 +1486,7 @@
 	<xsd:complexType name="wireTapType">
 		<xsd:annotation>
 			<xsd:documentation>
-				Defines a Wire Tap Channel Interceptor.
+	Defines a Wire Tap Channel Interceptor.
 			</xsd:documentation>
 		</xsd:annotation>
 		<xsd:attribute name="channel" type="xsd:string" use="required">
@@ -1582,8 +1594,8 @@
 	<xsd:element name="publisher">
 		<xsd:annotation>
 					<xsd:documentation>
-						Defines a MessagePublishingInterceptor which allows you to generate messages as a by-product of 
-						method invocations on Spring configured components.
+	Defines a MessagePublishingInterceptor which allows you to generate messages
+	as a by-product of method invocations on Spring configured components.
 					</xsd:documentation>
 		</xsd:annotation> 
 		<xsd:complexType>
@@ -1601,7 +1613,7 @@
 			<xsd:attribute name="default-channel" type="xsd:string" default="nullChannel">
 				<xsd:annotation> 
 					<xsd:documentation><![CDATA[
-						Specifies default-channel to publish messages
+	Specifies default-channel to publish messages
 					]]></xsd:documentation>
 				</xsd:annotation>
 			</xsd:attribute>