You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by ac...@apache.org on 2022/12/02 08:08:54 UTC
[camel-kamelets] 22/28: Enhance documentation on data type SPI
This is an automated email from the ASF dual-hosted git repository.
acosentino pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-kamelets.git
commit 429011c40a1ec53834975ae0134e71700edb0543
Author: Christoph Deppisch <cd...@redhat.com>
AuthorDate: Tue Nov 29 11:01:13 2022 +0100
Enhance documentation on data type SPI
---
.../utils/format/spi/DataTypeConverter.java | 20 +++++++++---
.../format/spi/DataTypeConverterResolver.java | 26 ++++++++-------
.../kamelets/utils/format/spi/DataTypeLoader.java | 6 ++--
.../utils/format/spi/DataTypeRegistry.java | 38 +++++++++++++---------
.../utils/format/spi/annotations/DataType.java | 15 +++++----
5 files changed, 66 insertions(+), 39 deletions(-)
diff --git a/library/camel-kamelets-utils/src/main/java/org/apache/camel/kamelets/utils/format/spi/DataTypeConverter.java b/library/camel-kamelets-utils/src/main/java/org/apache/camel/kamelets/utils/format/spi/DataTypeConverter.java
index a275b67b..f9c175b0 100644
--- a/library/camel-kamelets-utils/src/main/java/org/apache/camel/kamelets/utils/format/spi/DataTypeConverter.java
+++ b/library/camel-kamelets-utils/src/main/java/org/apache/camel/kamelets/utils/format/spi/DataTypeConverter.java
@@ -20,14 +20,23 @@ package org.apache.camel.kamelets.utils.format.spi;
import org.apache.camel.Exchange;
import org.apache.camel.kamelets.utils.format.spi.annotations.DataType;
+/**
+ * Converter applies custom logic to a given exchange in order to update the message content in that exchange according to
+ * the data type.
+ */
@FunctionalInterface
public interface DataTypeConverter {
+ /**
+ * Changes the exchange message content (body and/or header) to represent the data type.
+ * @param exchange the exchange that should have its message content applied to the data type.
+ */
void convert(Exchange exchange);
/**
- * Gets the data type converter name. Automatically derives the name from given data type annotation.
- * @return
+ * Gets the data type converter name. Automatically derives the name from given data type annotation if any.
+ * Subclasses may add a fallback logic to determine the data type name in case the annotation is missing.
+ * @return the name of the data type.
*/
default String getName() {
if (this.getClass().isAnnotationPresent(DataType.class)) {
@@ -39,7 +48,8 @@ public interface DataTypeConverter {
/**
* Gets the data type component scheme. Automatically derived from given data type annotation.
- * @return
+ * Subclasses may add custom logic to determine the data type scheme. By default, the generic Camel scheme is used.
+ * @return the component scheme of the data type.
*/
default String getScheme() {
if (this.getClass().isAnnotationPresent(DataType.class)) {
@@ -51,7 +61,9 @@ public interface DataTypeConverter {
/**
* Gets the data type media type. Automatically derived from given data type annotation.
- * @return
+ * Subclasses may add additional logic to determine the media type when annotation is missing.
+ * By default, returns empty String as a media type.
+ * @return the media type of the data type.
*/
default String getMediaType() {
if (this.getClass().isAnnotationPresent(DataType.class)) {
diff --git a/library/camel-kamelets-utils/src/main/java/org/apache/camel/kamelets/utils/format/spi/DataTypeConverterResolver.java b/library/camel-kamelets-utils/src/main/java/org/apache/camel/kamelets/utils/format/spi/DataTypeConverterResolver.java
index 17c48664..f54aaa92 100644
--- a/library/camel-kamelets-utils/src/main/java/org/apache/camel/kamelets/utils/format/spi/DataTypeConverterResolver.java
+++ b/library/camel-kamelets-utils/src/main/java/org/apache/camel/kamelets/utils/format/spi/DataTypeConverterResolver.java
@@ -20,30 +20,34 @@ package org.apache.camel.kamelets.utils.format.spi;
import java.util.Optional;
import org.apache.camel.CamelContext;
+import org.apache.camel.kamelets.utils.format.spi.annotations.DataType;
/**
- * Represents a resolver of data type converters from a URI to be able to lazy load them using some discovery mechanism.
+ * Resolves data type converters from URI to be able to lazy load converters using factory finder discovery mechanism.
*/
@FunctionalInterface
public interface DataTypeConverterResolver {
/**
- * Attempts to resolve the converter for the given URI.
+ * Attempts to resolve the converter for the given scheme and name. Usually uses the factory finder URI to resolve the converter.
+ * Scheme and name may be combined in order to resolve component specific converters. Usually implements a fallback
+ * resolving mechanism when no matching converter for scheme and name is found (e.g. search for generic Camel converters just using the name).
*
- * @param scheme
- * @param name
- * @param camelContext
- * @return
+ * @param scheme the data type scheme.
+ * @param name the data type name.
+ * @param camelContext the current Camel context.
+ * @return optional data type resolved via URI factory finder.
*/
Optional<DataTypeConverter> resolve(String scheme, String name, CamelContext camelContext);
/**
- * Attempts to resolve default converter for the given name.
- * @param name
- * @param camelContext
- * @return
+ * Attempts to resolve default converter for the given name. Uses default Camel scheme to resolve the converter via factory finder mechanism.
+ *
+ * @param name the data type name.
+ * @param camelContext the current Camel context.
+ * @return optional data type resolved via URI factory finder.
*/
default Optional<DataTypeConverter> resolve(String name, CamelContext camelContext) {
- return resolve("camel", name, camelContext);
+ return resolve(DataType.DEFAULT_SCHEME, name, camelContext);
}
}
diff --git a/library/camel-kamelets-utils/src/main/java/org/apache/camel/kamelets/utils/format/spi/DataTypeLoader.java b/library/camel-kamelets-utils/src/main/java/org/apache/camel/kamelets/utils/format/spi/DataTypeLoader.java
index 73f87c69..453485fe 100644
--- a/library/camel-kamelets-utils/src/main/java/org/apache/camel/kamelets/utils/format/spi/DataTypeLoader.java
+++ b/library/camel-kamelets-utils/src/main/java/org/apache/camel/kamelets/utils/format/spi/DataTypeLoader.java
@@ -18,14 +18,14 @@
package org.apache.camel.kamelets.utils.format.spi;
/**
- * A pluggable strategy to load data types into a {@link DataTypeRegistry}.
+ * A pluggable strategy to load data types into a {@link DataTypeRegistry}. Loads one to many data type converters to the given registry.
*/
public interface DataTypeLoader {
/**
- * A pluggable strategy to load data types into a registry.
+ * A pluggable strategy to load data types into a given registry.
*
- * @param registry the registry to load the data types into
+ * @param registry the registry to load the data types into.
*/
void load(DataTypeRegistry registry);
}
diff --git a/library/camel-kamelets-utils/src/main/java/org/apache/camel/kamelets/utils/format/spi/DataTypeRegistry.java b/library/camel-kamelets-utils/src/main/java/org/apache/camel/kamelets/utils/format/spi/DataTypeRegistry.java
index cb2bedc9..d4718547 100644
--- a/library/camel-kamelets-utils/src/main/java/org/apache/camel/kamelets/utils/format/spi/DataTypeRegistry.java
+++ b/library/camel-kamelets-utils/src/main/java/org/apache/camel/kamelets/utils/format/spi/DataTypeRegistry.java
@@ -19,42 +19,50 @@ package org.apache.camel.kamelets.utils.format.spi;
import java.util.Optional;
+import org.apache.camel.kamelets.utils.format.spi.annotations.DataType;
+
/**
- * Registry for data types. Data type loaders should be used to add types to the registry.
+ * Registry for data types and its converters. Data type loaders should be used to add members to the registry.
* <p/>
- * The registry is able to perform a lookup of a specific data type.
+ * The registry is able to perform a lookup of a specific data type by its given scheme and name. Usually data types are grouped
+ * by their component scheme so users may use component specific converters and default Camel converters.
*/
public interface DataTypeRegistry {
/**
- * Registers a new default data type converter.
- * @param scheme
- * @param converter
+ * Registers a new default data type converter. Usually used to add default Camel converter implementations.
+ *
+ * @param scheme the data type scheme.
+ * @param converter the converter implementation.
*/
void addDataTypeConverter(String scheme, DataTypeConverter converter);
/**
- * Registers a new default data type converter.
- * @param converter
+ * Registers a new default data type converter. Uses the default Camel scheme to mark this converter as generic one.
+ *
+ * @param converter the data type converter implementation.
*/
default void addDataTypeConverter(DataTypeConverter converter) {
- addDataTypeConverter("camel", converter);
+ addDataTypeConverter(DataType.DEFAULT_SCHEME, converter);
}
/**
- * Find data type for given component scheme and data type name.
- * @param scheme
- * @param name
- * @return
+ * Find data type for given component scheme and data type name. Searches for the component scheme specific converter first.
+ * As a fallback may also try to resolve the converter with only the name in the given set of default Camel converters registered in this registry.
+ *
+ * @param scheme the data type converter scheme (usually a component scheme).
+ * @param name the data type converter name.
+ * @return optional data type converter implementation matching the given scheme and name.
*/
Optional<DataTypeConverter> lookup(String scheme, String name);
/**
- * Find data type for given data type name.
- * @param name
+ * Find data type for given data type name. Just searches the set of default Camel converter implementations registered in this registry.
+ *
+ * @param name the data type converter name.
* @return
*/
default Optional<DataTypeConverter> lookup(String name) {
- return lookup("camel", name);
+ return lookup(DataType.DEFAULT_SCHEME, name);
}
}
diff --git a/library/camel-kamelets-utils/src/main/java/org/apache/camel/kamelets/utils/format/spi/annotations/DataType.java b/library/camel-kamelets-utils/src/main/java/org/apache/camel/kamelets/utils/format/spi/annotations/DataType.java
index 40a3030a..b5208887 100644
--- a/library/camel-kamelets-utils/src/main/java/org/apache/camel/kamelets/utils/format/spi/annotations/DataType.java
+++ b/library/camel-kamelets-utils/src/main/java/org/apache/camel/kamelets/utils/format/spi/annotations/DataType.java
@@ -24,7 +24,10 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * Data type annotation defines a type with its component scheme, a name and input/output types.
+ * Data type annotation defines a data type with its component scheme, a name and optional media types.
+ * <p/>
+ * The annotation is used by specific classpath scanning data type loaders to automatically add the data types to
+ * a registry.
*/
@Retention(RetentionPolicy.RUNTIME)
@Documented
@@ -34,20 +37,20 @@ public @interface DataType {
String DEFAULT_SCHEME = "camel";
/**
- * Camel component scheme.
- * @return
+ * Camel component scheme. Specifies whether a data type is component specific.
+ * @return the data type scheme.
*/
String scheme() default DEFAULT_SCHEME;
/**
- * Data type name.
- * @return
+ * Data type name. Identifies the data type. Should be unique in combination with scheme.
+ * @return the data type name.
*/
String name();
/**
* The media type associated with this data type.
- * @return
+ * @return the media type or empty string as default.
*/
String mediaType() default "";
}