spring-projects / spring-projects/spring-integration

Better documentation for writing custom channel adapters for JavaDSL

Open
#3,725 8 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

type: documentation
Dominant language
Java
Stars
1.6k
Forks
1.2k
Avg merge
17h 48m
Merged PRs (30d)
62

Description

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).

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the reference channel-adapter section linked in the issue, then inspect the named interfaces: MessageProducerSupport, AbstractMessageSource, AbstractReactiveMessageHandler, AbstractMessageHandler, and AbstractReplyProducingMessageHandler. Done means the documentation includes simple Java DSL examples for each listed adapter style and explains the interfaces, their differences, use cases, and reactive support.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, spring
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.