GH-3166 Deprecate defineInput/OutputBinding

Add documentation for create input and output binding

Author: olegz

core/spring-cloud-stream/src/main/java/org/springframework/cloud/stream/binding/BindingsLifecycleController.java

@@ -95,24 +95,20 @@ public BindingsLifecycleController(List<InputBindingLifecycle> inputBindingLifec
 
 	/**
 	 * Allows to dynamically create a new input binding returning its consumer properties for further customization.
-	 * Unlike {@link #defineBinding(BindableFunctionProxyFactory)} this method will not initialize the binding. 
-	 * You have to call {@link #defineBinding(BindableFunctionProxyFactory)} explicitly after you create a binding.
 	 * @param <P> the type of consumer properties. For example, if binding derives from Kafka, it will return KafkaConsumerProperties.
 	 * @param bindingName the name of the binding.
 	 * @param binderName the name of the binder.
 	 * @param bindingProperties instance of BindingProperties.
 	 * @return instance of the consumer properties.
 	 */
-	@SuppressWarnings("unchecked")
 	public <P> P createInputBinding(String bindingName, String binderName, BindingProperties bindingProperties) {
 		Assert.hasText(bindingProperties.getGroup(), "Anonymous bindings are not allowed for explicit creation. You must define 'group'");
 		DefaultBinderFactory binderFactory = this.applicationContext.getBean(DefaultBinderFactory.class);
 		Object binder = binderFactory.getBinder(binderName, MessageChannel.class);
 		BindingServiceProperties bindingServiceProperties = this.applicationContext.getBean(BindingServiceProperties.class);
 		bindingServiceProperties.setBindings(Collections.singletonMap(bindingName, bindingProperties));
-		if (binder instanceof ExtendedPropertiesBinder extendedPropertiesBinder) {
-			Object extensionPropertries = extendedPropertiesBinder.getExtendedConsumerProperties(bindingName);
-			return (P) extensionPropertries;
+		if (binder instanceof ExtendedPropertiesBinder) {
+			return this.defineInputBinding(bindingName);
 		}
 		else {
 			throw new IllegalStateException("Binder must be an instance of ExtendedPropertiesBinder");
@@ -121,23 +117,19 @@ public <P> P createInputBinding(String bindingName, String binderName, BindingPr
 
 	/**
 	 * Allows to dynamically create a new input binding returning its consumer properties for further customization.
-	 * Unlike {@link #defineBinding(BindableFunctionProxyFactory)} this method will not initialize the binding. 
-	 * You have to call {@link #defineBinding(BindableFunctionProxyFactory)} explicitly after you create a binding.
 	 * @param <P> the type of consumer properties. For example, if binding derives from Kafka, it will return KafkaConsumerProperties.
 	 * @param bindingName the name of the binding.
 	 * @param binderName the name of the binder.
 	 * @param bindingProperties instance of BindingProperties.
 	 * @return instance of the consumer properties.
 	 */
-	@SuppressWarnings("unchecked")
 	public <P> P createOutputBinding(String bindingName, String binderName, BindingProperties bindingProperties) {
 		DefaultBinderFactory binderFactory = this.applicationContext.getBean(DefaultBinderFactory.class);
 		Object binder = binderFactory.getBinder(binderName, MessageChannel.class);
 		BindingServiceProperties bindingServiceProperties = this.applicationContext.getBean(BindingServiceProperties.class);
 		bindingServiceProperties.setBindings(Collections.singletonMap(bindingName, bindingProperties));
-		if (binder instanceof ExtendedPropertiesBinder extendedPropertiesBinder) {
-			Object extensionPropertries = extendedPropertiesBinder.getExtendedProducerProperties(bindingName);
-			return (P) extensionPropertries;
+		if (binder instanceof ExtendedPropertiesBinder) {
+			return this.defineOutputBinding(bindingName);
 		}
 		else {
 			throw new IllegalStateException("Binder must be an instance of ExtendedPropertiesBinder");
@@ -149,7 +141,9 @@ public <P> P createOutputBinding(String bindingName, String binderName, BindingP
 	 * @param <P> the type of consumer properties. For example, if binding derives from Kafka, it will return KafkaConsumerProperties.
 	 * @param bindingName the name of the binding.
 	 * @return instance of the consumer properties.
+	 * @deprecated since 5.0.2
 	 */
+	@Deprecated
 	public <P> P defineInputBinding(String bindingName) {
 		BindableFunctionProxyFactory bindingProxyFactory =
 				new BindableFunctionProxyFactory(bindingName, 1, 0, this.applicationContext.getBean(StreamFunctionProperties.class), false);
@@ -162,7 +156,9 @@ public <P> P defineInputBinding(String bindingName) {
 	 * @param <P> the type of producer properties. For example, if binding derives from Kafka, it will return KafkaProducerProperties.
 	 * @param bindingName the name of the binding.
 	 * @return instance of the producer properties.
+	 *  @deprecated since 5.0.2
 	 */
+	@Deprecated
 	public <P> P defineOutputBinding(String bindingName) {
 		BindableFunctionProxyFactory bindingProxyFactory =
 				new BindableFunctionProxyFactory(bindingName, 0, 1, this.applicationContext.getBean(StreamFunctionProperties.class), false);

docs/modules/ROOT/pages/spring-cloud-stream/binding_visualization_control.adoc

@@ -30,12 +30,24 @@ its Consumer and Producer configuration properties for more dynamic management o
 
 For example.
 
-To define new input binding you can call `BindingsLifecycleController.defineInputBinding(..)` method (see below). There is equivalent of `defineOutputBinding(..)` method.
+To define new input binding you can call `BindingsLifecycleController.createInputBinding(..)` method (see below). There is equivalent of `createOutputBinding(..)` method.
 
 [source,java]
 ----
+DefaultBinderFactory binderFactory = context.getBean(DefaultBinderFactory.class);
+Object binder = binderFactory.getBinder("rabbit", MessageChannel.class);
+		
+String inputName = "test-output-binding";
+		
 BindingsLifecycleController controller = context.getBean(BindingsLifecycleController.class);
-KafkaConsumerProperties consumerProperties = controller.defineInputBinding("test-input-binding"); 
+		
+BindingProperties bindingProperties = new BindingProperties();
+bindingProperties.setDestination("myDest");
+bindingProperties.setGroup("myGroup"); // must define group for input binding
+ConsumerProperties consumerProperties = new ConsumerProperties();
+bindingProperties.setConsumer(consumerProperties);	
+		
+RabbitConsumerProperties extendedConsumerProperties = controller.createInputBinding(inputName, "rabbit", bindingProperties);
 ----
 
 You can than manage its properties by calling `getExtensionProperties(..)` method.