Better documentation for writing custom channel adapters for JavaDSL

[migroskub]

Expected Behavior
I think there should be an how to write channel adapter guide with examples for:

• Reactive event-driven inbound channel adapters
• Reactive source polling inbound channel adapters
• Reactive outbound channel adapters
• Event-driven inbound channel adapters
• Source polling inbound channel adapters
• Outbound channel adapters

There should be super simple examples for writing each with the JavaDSL, and more important - explanations about the interfaces that are required for each usage (and which ones are supported with nio Reactive Programming). Such as:

• MessageProducerSupport
• AbstractMessageSource
• AbstractReactiveMessageHandler
• AbstractMessageHandler
• AbstractReplyProducingMessageHandler
  and more (I don't know of more relevant interfaces, this is one of the reasons I'm raising this issue).
  There should be examples for the differences between them and use cases for each.

Current Behavior

It's pretty hard to understand what are the correct interfaces that we should use in each case of writing channel adapters with the Java DSL. I think there should be a better guide for writing custom channel adapters (since there are not so many channel adapters, writing custom ones is a pretty common task, if not the most common task when using Spring Integration).

Context
The reference doesn't mention any of the JavaDSL channel adapter interfaces, so that's super hard to understand the purpose of each interface and what fits my needs. The only solution what diving into the source code, which has inconsistency between channel adapters (some channel adapters name is XInboundChannelAdapter, and some channel adapters name is XMessageProducer. I know that there may be some reasons and conventions to it, but this whole part is just not documented).

[artembilan]

Just to be sure that we are on the same page: writing channel adapters is fully irrelevant if they are used in Java DSL or not.
The Java DSL is just a hing-level syntax sugar on top of EIP components. It does not require particular channel adapter to be implemented: you always can use POJO methods to be invoked invoked from generic Service Activator (handle() in terms of Java DSL).
You also may not look deep into reactive inbound channel adapter since Java DSL provides a factory like this: IntegrationFlows.from(Publisher<? extends Message<?>> publisher).

To be honest we don't provide such a guidance because we don't expect it to be regular task for framework users.
It is more advance one for those who wants develop channel adapter libraries or contribute back to the framework.

Anyway, we will look into this in the nearest future.

Thank you!

[migroskub]

It's just super hard to understand if some channel adapter fits my use case. For example if I want to know whether some channel adapter fits my need, for example the S3 message handler, I need to somehow understand if AbstractReplyProducingMessageHandler is supported by Reactive Programming or not (or whether it depends on each implementation).

[artembilan]

See this docs: https://docs.spring.io/spring-integration/docs/current/reference/html/reactive-streams.html#reactive-reply-payload for some insight.
And yes: it is really per MessageHandler impl to determine if it is reactive or not, or can fit to reactive processing downstream if its result is an async.
This is a doc for that S3MessageHandler when it is used for request-reply scenario: https://github.com/spring-projects/spring-integration-aws#outbound-gateway.

I agree that we lack some clearer documentation on the matter yet, so that why this issue is accepted for improvement for the current version.

[artembilan]

Yes, we are planning to address this issue in the current 6.0 timeline.