GH-8586: Deprecate IntegrationComponentSpec.get() (#8594)

* GH-8586: Deprecate IntegrationComponentSpec.get()

Fixes https://github.com/spring-projects/spring-integration/issues/8586

The `IntegrationComponentSpec` is not a plain wrapper around single component.
Sometimes it comes with several components where all of them must be registered
as beans.
If `IntegrationComponentSpec.get()` is called from end-user code, we may lose
other related components, for example filters in the `FileInboundChannelAdapterSpec`.

* Deprecate `IntegrationComponentSpec.get()` with no-op for end-user,
rather encourage to leave it as is and let the framework take care about its lifecycle
and related components registration
* Fix `IntegrationComponentSpec` logic to deal as a simple `FactoryBean` instead of
extra overhead via `AbstractFactoryBean`
* Use `IntegrationComponentSpec.getObject()` in the framework code where `get()` was called
* Fix tests to expose `IntegrationComponentSpec` as beans instead of previously called `get()`
* Some other clean up and typos fixes in the affected classes
* Document the change

* * Revert `ObjectStringMapBuilder` in the `KafkaInboundGatewaySpec.getComponentsToRegister()`

* Fix language in docs

Co-authored-by: Gary Russell <grussell@vmware.com>

* * Remove trailing whitespace in the `ScriptMessageSourceSpec`

---------

Co-authored-by: Gary Russell <grussell@vmware.com>

src/reference/asciidoc/dsl.adoc

@@ -39,8 +39,8 @@ public class MyConfiguration {
     }
 
     @Bean
-    public IntegrationFlow myFlow() {
-        return IntegrationFlow.fromSupplier(integerSource()::getAndIncrement,
+    public IntegrationFlow myFlow(AtomicInteger integerSource) {
+        return IntegrationFlow.fromSupplier(integerSource::getAndIncrement,
                                          c -> c.poller(Pollers.fixedRate(100)))
                     .channel("inputChannel")
                     .filter((Integer p) -> p > 0)
@@ -63,6 +63,10 @@ You need not replace all of your existing XML configuration to use Java configur
 The `org.springframework.integration.dsl` package contains the `IntegrationFlowBuilder` API mentioned earlier and a number of `IntegrationComponentSpec` implementations, which are also builders and provide the fluent API to configure concrete endpoints.
 The `IntegrationFlowBuilder` infrastructure provides common https://www.enterpriseintegrationpatterns.com/[enterprise integration patterns] (EIP) for message-based applications, such as channels, endpoints, pollers, and channel interceptors.
 
+IMPORTANT:: The `IntegrationComponentSpec` is a `FactoryBean` implementation, therefore its `getObject()` method must not be called from bean definitions.
+The `IntegrationComponentSpec` implementation must be left as is for bean definitions and the framework will manage its lifecycle.
+Bean method parameter injection for the target `IntegrationComponentSpec` type (a `FactoryBean` value) must be used for `IntegrationFlow` bean definitions instead of bean method references.
+
 Endpoints are expressed as verbs in the DSL to improve readability.
 The following list includes the common DSL method names and the associated EIP endpoint:
 
@@ -163,10 +167,9 @@ The following example shows how to use it:
 [source,java]
 ----
 @Bean
-public MessageChannel priorityChannel() {
+public PriorityChannelSpec priorityChannel() {
     return MessageChannels.priority(this.mongoDbChannelMessageStore, "priorityGroup")
-                        .interceptor(wireTap())
-                        .get();
+                        .interceptor(wireTap());
 }
 ----
 ====
@@ -181,13 +184,13 @@ The following example shows the possible ways to use the `channel()` EIP method:
 [source,java]
 ----
 @Bean
-public MessageChannel queueChannel() {
-    return MessageChannels.queue().get();
+public QueueChannelSpec queueChannel() {
+    return MessageChannels.queue();
 }
 
 @Bean
-public MessageChannel publishSubscribe() {
-    return MessageChannels.publishSubscribe().get();
+public PublishSubscribeChannelSpec<?> publishSubscribe() {
+    return MessageChannels.publishSubscribe();
 }
 
 @Bean
@@ -261,7 +264,7 @@ public PollerSpec poller() {
 
 See https://docs.spring.io/spring-integration/api/org/springframework/integration/dsl/Pollers.html[`Pollers`] and https://docs.spring.io/spring-integration/api/org/springframework/integration/dsl/PollerSpec.html[`PollerSpec`] in the Javadoc for more information.
 
-IMPORTANT: If you use the DSL to construct a `PollerSpec` as a `@Bean`, do not call the `get()` method in the bean definition.
+IMPORTANT: If you use the DSL to construct a `PollerSpec` as a `@Bean`, do not call the `getObject()` method in the bean definition.
 The `PollerSpec` is a `FactoryBean` that generates the `PollerMetadata` object from the specification and initializes all of its properties.
 
 [[java-dsl-reactive]]
@@ -833,30 +836,21 @@ For example, we now can configure several subscribers as sub-flows on the `Jms.p
 [source,java]
 ----
 @Bean
-public BroadcastCapableChannel jmsPublishSubscribeChannel() {
+public JmsPublishSubscribeMessageChannelSpec jmsPublishSubscribeChannel() {
     return Jms.publishSubscribeChannel(jmsConnectionFactory())
-                .destination("pubsub")
-                .get();
+                .destination("pubsub");
 }
 
 @Bean
-public IntegrationFlow pubSubFlow() {
+public IntegrationFlow pubSubFlow(BroadcastCapableChannel jmsPublishSubscribeChannel) {
     return f -> f
-            .publishSubscribeChannel(jmsPublishSubscribeChannel(),
+            .publishSubscribeChannel(jmsPublishSubscribeChannel,
                     pubsub -> pubsub
                             .subscribe(subFlow -> subFlow
                                 .channel(c -> c.queue("jmsPubSubBridgeChannel1")))
                             .subscribe(subFlow -> subFlow
                                 .channel(c -> c.queue("jmsPubSubBridgeChannel2"))));
 }
-
-@Bean
-public BroadcastCapableChannel jmsPublishSubscribeChannel(ConnectionFactory jmsConnectionFactory) {
-    return (BroadcastCapableChannel) Jms.publishSubscribeChannel(jmsConnectionFactory)
-            .destination("pubsub")
-            .get();
-}
-
 ----
 ====
 

src/reference/asciidoc/whats-new.adoc

@@ -41,6 +41,11 @@ See <<./filter.adoc#filter, Filter>> for more information.
  - The default timeout for send and receive operations in gateways and replying channel adapters has been changed from infinity to `30` seconds.
 Only one left as a `1` second is a `receiveTimeout` for `PollingConsumer` to not block a scheduler thread too long and let other queued tasks to be performed with the `TaskScheduler`.
 
+ - The `IntegrationComponentSpec.get()` method has been deprecated with removal planned for the next version.
+Since `IntegrationComponentSpec` is a `FactoryBean`, its bean definition must stay as is without any target object resolutions.
+The Java DSL and the framework by itself will manage the `IntegrationComponentSpec` lifecycle.
+See <<./dsl.adoc#java-dsl, Java DSL>> for more information.
+
 [[x6.1-web-sockets]]
 === Web Sockets Changes