GH-3772 Add Protobuf transformation support

Fixes #3772

* Add basic To/From Protocol Buffer's com.google.protobuf.Message transformers.
* Allow the proto_type header to specify the type.
* Add tests.
* add Protobuf docs
* Leverage the Spring ProtobufMessageConverter
* move protobuf-java-util to test dependecies as optional
* protobuf docs improvements
* improve the expected type handling
* expected type expression
* fix indentation
* fix indentation for generated test classes
* suppress style check for proto generated classes
* address the transformer doc format
* fix whats new merge conflict
* fix doc sample code
* Some code clean up; fixing typos

Author: tzolov

.gitignore

@@ -31,3 +31,4 @@ vf.gf.dmn-*
 hostkey.ser
 .springBeans
 .sts4-cache
+.vscode/

build.gradle

@@ -94,6 +94,7 @@ ext {
     mysqlVersion = '8.0.32'
     pahoMqttClientVersion = '1.2.5'
     postgresVersion = '42.5.4'
+    protobufVersion = '3.21.12'
     r2dbch2Version = '1.0.0.RELEASE'
     reactorVersion = '2022.0.3'
     resilience4jVersion = '2.0.2'
@@ -542,7 +543,7 @@ project('spring-integration-core') {
         optionalApi('com.fasterxml.jackson.module:jackson-module-kotlin') {
             exclude group: 'org.jetbrains.kotlin'
         }
-
+        optionalApi "com.google.protobuf:protobuf-java:$protobufVersion"
         optionalApi "com.jayway.jsonpath:json-path:$jsonpathVersion"
         optionalApi "com.esotericsoftware:kryo:$kryoVersion"
         optionalApi 'io.micrometer:micrometer-core'
@@ -553,6 +554,7 @@ project('spring-integration-core') {
         optionalApi "org.apache.avro:avro:$avroVersion"
         optionalApi 'org.jetbrains.kotlinx:kotlinx-coroutines-reactor'
 
+        testImplementation "com.google.protobuf:protobuf-java-util:$protobufVersion"
         testImplementation "org.aspectj:aspectjweaver:$aspectjVersion"
         testImplementation 'io.micrometer:micrometer-observation-test'
         testImplementation ('io.micrometer:micrometer-tracing-integration-test') {

spring-integration-core/src/main/java/org/springframework/integration/transformer/FromProtobufTransformer.java

@@ -0,0 +1,140 @@
+/*
+ * Copyright 2023 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.integration.transformer;
+
+import org.springframework.beans.factory.BeanClassLoaderAware;
+import org.springframework.expression.EvaluationContext;
+import org.springframework.expression.Expression;
+import org.springframework.integration.context.IntegrationContextUtils;
+import org.springframework.integration.expression.FunctionExpression;
+import org.springframework.integration.expression.ValueExpression;
+import org.springframework.integration.transformer.support.ProtoHeaders;
+import org.springframework.messaging.Message;
+import org.springframework.messaging.converter.ProtobufMessageConverter;
+import org.springframework.util.Assert;
+import org.springframework.util.ClassUtils;
+
+/**
+ * A Protocol Buffer transformer to instantiate {@link com.google.protobuf.Message} objects
+ * from either {@code byte[]} if content type is {@code application/x-protobuf}
+ * or from {@code String} in case of {@code application/json} content type.
+ *
+ * @author Christian Tzolov
+ *
+ * @since 6.1
+ */
+public class FromProtobufTransformer extends AbstractTransformer implements BeanClassLoaderAware {
+
+	private final ProtobufMessageConverter protobufMessageConverter;
+
+	private ClassLoader beanClassLoader;
+
+	private Expression expectedTypeExpression =
+			new FunctionExpression<Message<?>>((message) -> message.getHeaders().get(ProtoHeaders.TYPE));
+
+	private EvaluationContext evaluationContext;
+
+	/**
+	 * Construct an instance with the supplied default type to create.
+	 */
+	public FromProtobufTransformer() {
+		this(new ProtobufMessageConverter());
+	}
+
+	/**
+	 * Construct an instance with the supplied default type and ProtobufMessageConverter instance.
+	 * @param protobufMessageConverter the message converter used.
+	 */
+	public FromProtobufTransformer(ProtobufMessageConverter protobufMessageConverter) {
+		Assert.notNull(protobufMessageConverter, "'protobufMessageConverter' must not be null");
+		this.protobufMessageConverter = protobufMessageConverter;
+	}
+
+	@Override
+	public void setBeanClassLoader(ClassLoader classLoader) {
+		this.beanClassLoader = classLoader;
+	}
+
+	/**
+	 * Set an expected protobuf class type.
+	 * Mutually exclusive with {@link #setExpectedTypeExpression} and
+	 * {@link #setExpectedTypeExpressionString}.
+	 * @param expectedType expected protobuf class type.
+	 * @return updated FromProtobufTransformer instance.
+	 */
+	public FromProtobufTransformer setExpectedType(Class<? extends com.google.protobuf.Message> expectedType) {
+		return setExpectedTypeExpression(new ValueExpression<>(expectedType));
+	}
+
+	/**
+	 * Set an expression to evaluate against the message to determine the type id.
+	 * Defaults to{@code headers['proto_type']}. Mutually exclusive with
+	 * {@link #setExpectedType} and {@link #setExpectedTypeExpression}.
+	 * @param expression the expression.
+	 * @return updated FromProtobufTransformer instance.
+	 */
+	public FromProtobufTransformer setExpectedTypeExpressionString(String expression) {
+		return setExpectedTypeExpression(EXPRESSION_PARSER.parseExpression(expression));
+	}
+
+	/**
+	 * Set an expression to evaluate against the message to determine the type.
+	 * Default {@code headers['proto_type']}.
+	 * Mutually exclusive with {@link #setExpectedType} and
+	 * {@link #setExpectedTypeExpressionString}.
+	 * @param expression the expression.
+	 * @return updated FromProtobufTransformer instance.
+	 */
+	public FromProtobufTransformer setExpectedTypeExpression(Expression expression) {
+		Assert.notNull(expression, "'expression' must not be null");
+		this.expectedTypeExpression = expression;
+		return this;
+	}
+
+	@Override
+	protected void onInit() {
+		this.evaluationContext = IntegrationContextUtils.getEvaluationContext(getBeanFactory());
+	}
+
+	@SuppressWarnings("unchecked")
+	@Override
+	protected Object doTransform(Message<?> message) {
+		Class<? extends com.google.protobuf.Message> targetClass = null;
+		Object value = this.expectedTypeExpression.getValue(this.evaluationContext, message);
+		if (value instanceof Class<?>) {
+			targetClass = (Class<? extends com.google.protobuf.Message>) value;
+		}
+		else if (value instanceof String) {
+			try {
+				targetClass =
+						(Class<? extends com.google.protobuf.Message>)
+								ClassUtils.forName((String) value, this.beanClassLoader);
+			}
+			catch (ClassNotFoundException | LinkageError e) {
+				throw new IllegalStateException(e);
+			}
+		}
+
+		if (targetClass == null) {
+			throw new MessageTransformationException(message,
+					"The 'expectedTypeExpression' (" + this.expectedTypeExpression + ") returned 'null'.");
+		}
+
+		return this.protobufMessageConverter.fromMessage(message, targetClass);
+	}
+
+}

spring-integration-core/src/main/java/org/springframework/integration/transformer/ToProtobufTransformer.java

@@ -0,0 +1,67 @@
+/*
+ * Copyright 2023 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.integration.transformer;
+
+import org.springframework.integration.transformer.support.ProtoHeaders;
+import org.springframework.messaging.Message;
+import org.springframework.messaging.MessageHeaders;
+import org.springframework.messaging.converter.ProtobufMessageConverter;
+import org.springframework.messaging.support.MessageHeaderAccessor;
+import org.springframework.util.Assert;
+
+/**
+ * A Protocol Buffer transformer for generated {@link com.google.protobuf.Message} objects.
+ * <p>
+ * If the content type is set to {@code application/x-protobuf} (default if no content type),
+ * then the output message payload is of type byte array.
+ * <p>
+ * If the content type is set to {@code application/json} and
+ * the {@code com.google.protobuf:protobuf-java-util} dependency is on the
+ * classpath, the output message payload if of type String.
+ *
+ * @author Christian Tzolov
+ *
+ * @since 6.1
+ */
+public class ToProtobufTransformer extends AbstractTransformer {
+
+	private final ProtobufMessageConverter protobufMessageConverter;
+
+	public ToProtobufTransformer() {
+		this(new ProtobufMessageConverter());
+	}
+
+	public ToProtobufTransformer(ProtobufMessageConverter protobufMessageConverter) {
+		Assert.notNull(protobufMessageConverter, "'protobufMessageConverter' must not be null");
+		this.protobufMessageConverter = protobufMessageConverter;
+	}
+
+	@Override
+	protected Object doTransform(Message<?> message) {
+		Assert.isInstanceOf(com.google.protobuf.Message.class, message.getPayload(),
+				"Payload must be an implementation of 'com.google.protobuf.Message'");
+
+		MessageHeaderAccessor accessor = new MessageHeaderAccessor(message);
+		accessor.setHeader(ProtoHeaders.TYPE, message.getPayload().getClass().getName());
+		if (!message.getHeaders().containsKey(MessageHeaders.CONTENT_TYPE)) {
+			accessor.setContentType(ProtobufMessageConverter.PROTOBUF);
+		}
+
+		return this.protobufMessageConverter.toMessage(message.getPayload(), accessor.getMessageHeaders());
+	}
+
+}

spring-integration-core/src/main/java/org/springframework/integration/transformer/support/ProtoHeaders.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2023 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.integration.transformer.support;
+
+/**
+ * Pre-defined names and prefixes for Protocol Buffers related headers.
+ *
+ * @author Christian Tzolov
+ *
+ * @since 6.1
+ */
+public final class ProtoHeaders {
+
+	private ProtoHeaders() {
+	}
+
+	/**
+	 * The prefix for Protocol Buffers specific message headers.
+	 */
+	public static final String PREFIX = "proto_";
+
+	/**
+	 * The {@code com.google.protobuf.Message} type. By default, it's the fully qualified
+	 * {@code com.google.protobuf.Message} type but can be a key that is mapped to the actual type.
+	 */
+	public static final String TYPE = PREFIX + "type";
+
+}