You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by nf...@apache.org on 2022/04/01 09:14:14 UTC
[camel] 14/18: CAMEL-17792: Add doc about the message headers of camel-mongodb
This is an automated email from the ASF dual-hosted git repository.
nfilotto pushed a commit to branch CAMEL-17792/doc-message-headers
in repository https://gitbox.apache.org/repos/asf/camel.git
commit 59ae141b5d750506435426680a214d8f02450d9f
Author: Nicolas Filotto <nf...@talend.com>
AuthorDate: Thu Mar 31 18:16:32 2022 +0200
CAMEL-17792: Add doc about the message headers of camel-mongodb
---
.../apache/camel/component/mongodb/mongodb.json | 26 +++++++
.../src/main/docs/mongodb-component.adoc | 91 +---------------------
.../camel/component/mongodb/MongoDbConstants.java | 47 ++++++++++-
.../camel/component/mongodb/MongoDbEndpoint.java | 2 +-
4 files changed, 77 insertions(+), 89 deletions(-)
diff --git a/components/camel-mongodb/src/generated/resources/org/apache/camel/component/mongodb/mongodb.json b/components/camel-mongodb/src/generated/resources/org/apache/camel/component/mongodb/mongodb.json
index c678d48..c048ad5 100644
--- a/components/camel-mongodb/src/generated/resources/org/apache/camel/component/mongodb/mongodb.json
+++ b/components/camel-mongodb/src/generated/resources/org/apache/camel/component/mongodb/mongodb.json
@@ -27,6 +27,32 @@
"lazyStartProducer": { "kind": "property", "displayName": "Lazy Start Producer", "group": "producer", "label": "producer", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "autowired": false, "secret": false, "defaultValue": false, "description": "Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during star [...]
"autowiredEnabled": { "kind": "property", "displayName": "Autowired Enabled", "group": "advanced", "label": "advanced", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "autowired": false, "secret": false, "defaultValue": true, "description": "Whether autowiring is enabled. This is used for automatic autowiring options (the option must be marked as autowired) by looking up in the registry to find if there is a single instance of matching type, which t [...]
},
+ "headers": {
+ "CamelMongoDbOperation": { "kind": "header", "displayName": "", "group": "producer", "label": "producer", "required": false, "javaType": "org.apache.camel.component.mongodb.MongoDbOperation or String", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "The operation this endpoint will execute against MongoDB." },
+ "CamelMongoDbResultTotalSize": { "kind": "header", "displayName": "", "group": "producer findAll", "label": "producer findAll", "required": false, "javaType": "Integer", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "Number of objects matching the query. This does not take limit\/skip into consideration." },
+ "CamelMongoDbResultPageSize": { "kind": "header", "displayName": "", "group": "producer findAll", "label": "producer findAll", "required": false, "javaType": "Integer", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "Number of objects matching the query. This does not take limit\/skip into consideration." },
+ "CamelMongoDbCriteria": { "kind": "header", "displayName": "", "group": "producer", "label": "producer", "required": false, "javaType": "org.bson.conversions.Bson", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "The query to execute against MongoDB." },
+ "CamelMongoDbFieldsProjection": { "kind": "header", "displayName": "", "group": "producer", "label": "producer", "required": false, "javaType": "org.bson.conversions.Bson", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "The project document." },
+ "CamelMongoDbBatchSize": { "kind": "header", "displayName": "", "group": "producer findAll aggregate", "label": "producer findAll aggregate", "required": false, "javaType": "Integer", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "The number of documents per batch." },
+ "CamelMongoDbNumToSkip": { "kind": "header", "displayName": "", "group": "producer findAll", "label": "producer findAll", "required": false, "javaType": "Integer", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "Discards a given number of elements at the beginning of the cursor." },
+ "CamelMongoDbMultiUpdate": { "kind": "header", "displayName": "", "group": "producer update", "label": "producer update", "required": false, "javaType": "Boolean", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "If the update should be applied to all objects matching. See\nhttp:\/\/www.mongodb.org\/display\/DOCS\/Atomic+Operations[Atomic Operations]" },
+ "CamelMongoDbUpsert": { "kind": "header", "displayName": "", "group": "producer update", "label": "producer update", "required": false, "javaType": "Boolean", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "If the database should create the element if it does not exist" },
+ "CamelMongoDbRecordsAffected": { "kind": "header", "displayName": "", "group": "producer", "label": "producer", "required": false, "javaType": "long", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "The number of modified or deleted records" },
+ "CamelMongoDbRecordsMatched": { "kind": "header", "displayName": "", "group": "producer", "label": "producer", "required": false, "javaType": "long", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "The number of documents matched by the query." },
+ "CamelMongoDbSortBy": { "kind": "header", "displayName": "", "group": "producer", "label": "producer", "required": false, "javaType": "Bson or Document", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "The sort criteria." },
+ "CamelMongoDbDatabase": { "kind": "header", "displayName": "", "group": "common", "label": "", "required": false, "javaType": "String", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "The name of the MongoDB database to target" },
+ "CamelMongoDbCollection": { "kind": "header", "displayName": "", "group": "common", "label": "", "required": false, "javaType": "String", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "The name of the MongoDB collection to bind to this endpoint" },
+ "CamelMongoDbCollectionIndex": { "kind": "header", "displayName": "", "group": "producer", "label": "producer", "required": false, "javaType": "List<Bson>", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "The list of dynamic indexes to create on the fly" },
+ "CamelMongoDbLimit": { "kind": "header", "displayName": "", "group": "producer findAll", "label": "producer findAll", "required": false, "javaType": "Integer", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "Limits the number of elements returned." },
+ "CamelMongoDbTailable": { "kind": "header", "displayName": "", "group": "consumer", "label": "consumer", "required": false, "javaType": "Boolean", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "Is from tailable" },
+ "CamelMongoWriteResult": { "kind": "header", "displayName": "", "group": "producer", "label": "producer", "required": false, "javaType": "Object", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "The result of the write operation" },
+ "CamelMongoOid": { "kind": "header", "displayName": "", "group": "producer", "label": "producer", "required": false, "javaType": "Object or List<Object>", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "The OID(s) of the inserted record(s)" },
+ "CamelMongoDbDistinctQueryField": { "kind": "header", "displayName": "", "group": "producer", "label": "producer", "required": false, "javaType": "String", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "The specified field name fow which we want to get the distinct values." },
+ "CamelMongoDbAllowDiskUse": { "kind": "header", "displayName": "", "group": "producer findAll aggregate", "label": "producer findAll aggregate", "required": false, "javaType": "Boolean", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "Sets allowDiskUse MongoDB flag.\nThis is supported since MongoDB Server 4.3.1. Using this header with older MongoDB Server version can cause query to fail." },
+ "CamelMongoDbBulkOrdered": { "kind": "header", "displayName": "", "group": "producer bulkWrite", "label": "producer bulkWrite", "required": false, "javaType": "Boolean", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "defaultValue": "TRUE", "description": "Perform an ordered or unordered operation execution." },
+ "_id": { "kind": "header", "displayName": "", "group": "consumer changeStreams", "label": "consumer changeStreams", "required": false, "javaType": "org.bson.types.ObjectId", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "A document that contains the _id of the document created or modified by the insert,\nreplace, delete, update operations (i.e. CRUD operations). For sharded collections, also displays the full shard key for\nthe docume [...]
+ "CamelMongoDbStreamOperationType": { "kind": "header", "displayName": "", "group": "consumer changeStreams", "label": "consumer changeStreams", "required": false, "javaType": "String", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "The type of operation that occurred. Can\nbe any of the following values: insert, delete, replace, update, drop, rename, dropDatabase, invalidate." }
+ },
"properties": {
"connectionBean": { "kind": "path", "displayName": "Connection Bean", "group": "common", "label": "", "required": true, "type": "string", "javaType": "java.lang.String", "deprecated": false, "deprecationNote": "", "autowired": false, "secret": false, "description": "Sets the connection bean reference used to lookup a client for connecting to a database if no hosts parameter is present." },
"collection": { "kind": "parameter", "displayName": "Collection", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "description": "Sets the name of the MongoDB collection to bind to this endpoint" },
diff --git a/components/camel-mongodb/src/main/docs/mongodb-component.adoc b/components/camel-mongodb/src/main/docs/mongodb-component.adoc
index 5eea949..7d98334 100644
--- a/components/camel-mongodb/src/main/docs/mongodb-component.adoc
+++ b/components/camel-mongodb/src/main/docs/mongodb-component.adoc
@@ -75,7 +75,9 @@ include::partial$component-endpoint-options.adoc[]
// endpoint options: START
// endpoint options: END
-
+// component headers: START
+include::partial$component-endpoint-headers.adoc[]
+// component headers: END
[[MongoDB-ConfigurationofdatabaseinSpringXML]]
@@ -226,33 +228,6 @@ from("direct:findAll")
.to("mock:resultFindAll");
-----------------------------------------------------------------------------
-Paging and efficient retrieval is supported via the following headers:
-
-[width="100%",cols="10%,10%,60%,20%",options="header",]
-|=======================================================================
-|Header key |Quick constant |Description (extracted from MongoDB API doc) |Expected type
-
-|`CamelMongoDbNumToSkip` |`MongoDbConstants.NUM_TO_SKIP` |Discards a given number of elements at the beginning of the cursor. |int/Integer
-
-|`CamelMongoDbLimit` |`MongoDbConstants.LIMIT` |Limits the number of elements returned. |int/Integer
-
-|`CamelMongoDbBatchSize` |`MongoDbConstants.BATCH_SIZE` |Limits the number of elements returned in one batch. A cursor typically
-fetches a batch of result objects and store them locally. If batchSize
-is positive, it represents the size of each batch of objects retrieved.
-It can be adjusted to optimize performance and limit data transfer. If
-batchSize is negative, it will limit of number objects returned, that
-fit within the max batch size limit (usually 4MB), and cursor will be
-closed. For example if batchSize is -10, then the server will return a
-maximum of 10 documents and as many as can fit in 4MB, then close the
-cursor. Note that this feature is different from limit() in that
-documents must fit within a maximum size, and it removes the need to
-send a request to close the cursor server-side. The batch size can be
-changed even after a cursor is iterated, in which case the setting will
-apply on the next batch retrieval. |int/Integer
-|`CamelMongoDbAllowDiskUse` |`MongoDbConstants.ALLOW_DISK_USE` | Sets allowDiskUse MongoDB flag.
-This is supported since MongoDB Server 4.3.1. Using this header with older MongoDB Server version can cause query to fail. |boolean/Boolean
-|=======================================================================
-
===== Example with option _outputType=MongoIterable_ and batch size
[source,java]
@@ -264,20 +239,6 @@ from("direct:findAll")
.to("mock:resultFindAll");
-----------------------------------------------------------------------------
-The `findAll` operation will also return the following OUT headers to
-enable you to iterate through result pages if you are using paging:
-
-[width="100%",cols="10%,10%,60%,20%",options="header",]
-|=======================================================================
-|Header key |Quick constant |Description (extracted from MongoDB API doc) |Data type
-
-|`CamelMongoDbResultTotalSize` |`MongoDbConstants.RESULT_TOTAL_SIZE` |Number of objects matching the query. This does not take limit/skip into
-consideration. |int/Integer
-
-|`CamelMongoDbResultPageSize` |`MongoDbConstants.RESULT_PAGE_SIZE` |Number of objects matching the query. This does not take limit/skip into
-consideration. |int/Integer
-|=======================================================================
-
[TIP]
====
*Supports optional parameters*
@@ -514,18 +475,6 @@ A header with key `CamelMongoDbRecordsAffected` will be returned
(`MongoDbConstants.RECORDS_AFFECTED` constant) with the number of
records updated (copied from `WriteResult.getN()`).
-Supports the following IN message headers:
-
-[width="100%",cols="10%,10%,10%,70%",options="header",]
-|=======================================================================
-|Header key |Quick constant |Description (extracted from MongoDB API doc) |Expected type
-
-|`CamelMongoDbMultiUpdate` |`MongoDbConstants.MULTIUPDATE` |If the update should be applied to all objects matching. See
-http://www.mongodb.org/display/DOCS/Atomic+Operations[http://www.mongodb.org/display/DOCS/Atomic+Operations] |boolean/Boolean
-
-|`CamelMongoDbUpsert` |`MongoDbConstants.UPSERT` |If the database should create the element if it does not exist |boolean/Boolean
-|=======================================================================
-
For example, the following will update *all* records whose filterField
field equals true by setting the value of the "scientist" field to
"Darwin":
@@ -609,13 +558,6 @@ By default, operations are executed in order and interrupted on the first write
To instruct MongoDB to continue to process remaining write operations in the list, set the `CamelMongoDbBulkOrdered` IN message header to `false`.
Unordered operations are executed in parallel and this behavior is not guaranteed.
-[width="100%",cols="10%,10%,10%,70%",options="header",]
-|=======================================================================
-|Header key |Quick constant |Description (extracted from MongoDB API doc) |Expected type
-
-|`CamelMongoDbBulkOrdered` |`MongoDbConstants.BULK_ORDERED` | Perform an ordered or unordered operation execution. Defaults to true. |boolean/Boolean
-|=======================================================================
-
=== Other operations
@@ -636,18 +578,7 @@ from("direct:aggregate")
.to("mock:resultAggregate");
----------------------------------------------------------------------------------------------------------------------------------------------------------------------
-
-Supports the following IN message headers:
-
-[width="100%",cols="10%,10%,10%,70%",options="header",]
-|=======================================================================
-|Header key |Quick constant |Description (extracted from MongoDB API doc) |Expected type
-
-|`CamelMongoDbBatchSize` |`MongoDbConstants.BATCH_SIZE` | Sets the number of documents to return per batch. |int/Integer
-|`CamelMongoDbAllowDiskUse` |`MongoDbConstants.ALLOW_DISK_USE` | Enable aggregation pipeline stages to write data to temporary files. |boolean/Boolean
-|=======================================================================
-
-By default a List of all results is returned. This can be heavy on memory depending on the size of the results. A safer alternative is to set your
+By default, a List of all results is returned. This can be heavy on memory depending on the size of the results. A safer alternative is to set your
outputType=MongoIterable. The next Processor will see an iterable in the message body allowing it to step through the results one by one. Thus setting
a batch size and returning an iterable allows for efficient retrieval and processing of the result.
@@ -952,20 +883,6 @@ from("mongodb:myDb?consumerType=changeStreams&database=flights&collection=ticket
TIP: You can externalize the streamFilter value into a property placeholder which allows the endpoint
URI parameters to be _cleaner_ and easier to read.
-The `changeStreams` consumer type will also return the following OUT headers:
-
-[width="100%",cols="10%,10%,60%,20%",options="header",]
-|=======================================================================
-|Header key |Quick constant |Description (extracted from MongoDB API doc) |Data type
-
-|`CamelMongoDbStreamOperationType` |`MongoDbConstants.STREAM_OPERATION_TYPE` | The type of operation that occurred. Can
-be any of the following values: insert, delete, replace, update, drop, rename, dropDatabase, invalidate. |String
-
-|`_id` |`MongoDbConstants.MONGO_ID` |A document that contains the _id of the document created or modified by the insert,
-replace, delete, update operations (i.e. CRUD operations). For sharded collections, also displays the full shard key for
-the document. The _id field is not repeated if it is already a part of the shard key. |ObjectId
-|=======================================================================
-
== Type conversions
The `MongoDbBasicConverters` type converter included with the
diff --git a/components/camel-mongodb/src/main/java/org/apache/camel/component/mongodb/MongoDbConstants.java b/components/camel-mongodb/src/main/java/org/apache/camel/component/mongodb/MongoDbConstants.java
index ebcde5c..9a228f9 100644
--- a/components/camel-mongodb/src/main/java/org/apache/camel/component/mongodb/MongoDbConstants.java
+++ b/components/camel-mongodb/src/main/java/org/apache/camel/component/mongodb/MongoDbConstants.java
@@ -16,33 +16,78 @@
*/
package org.apache.camel.component.mongodb;
+import org.apache.camel.spi.Metadata;
+
public final class MongoDbConstants {
+ @Metadata(label = "producer", description = "The operation this endpoint will execute against MongoDB.",
+ javaType = "org.apache.camel.component.mongodb.MongoDbOperation or String")
public static final String OPERATION_HEADER = "CamelMongoDbOperation";
+ @Metadata(label = "producer findAll",
+ description = "Number of objects matching the query. This does not take limit/skip into consideration.",
+ javaType = "Integer")
public static final String RESULT_TOTAL_SIZE = "CamelMongoDbResultTotalSize";
+ @Metadata(label = "producer findAll",
+ description = "Number of objects matching the query. This does not take limit/skip into consideration.",
+ javaType = "Integer")
public static final String RESULT_PAGE_SIZE = "CamelMongoDbResultPageSize";
-
+ @Metadata(label = "producer", description = "The query to execute against MongoDB.", javaType = "org.bson.conversions.Bson")
public static final String CRITERIA = "CamelMongoDbCriteria";
+ @Metadata(label = "producer", description = "The project document.", javaType = "org.bson.conversions.Bson")
public static final String FIELDS_PROJECTION = "CamelMongoDbFieldsProjection";
+ @Metadata(label = "producer findAll aggregate", description = "The number of documents per batch.", javaType = "Integer")
public static final String BATCH_SIZE = "CamelMongoDbBatchSize";
+ @Metadata(label = "producer findAll", description = "Discards a given number of elements at the beginning of the cursor.",
+ javaType = "Integer")
public static final String NUM_TO_SKIP = "CamelMongoDbNumToSkip";
public static final String INSERT_RECORDS_AFFECTED = "CamelMongoDbInsertRecordsAffected";
+ @Metadata(label = "producer update", description = "If the update should be applied to all objects matching. See\n" +
+ "http://www.mongodb.org/display/DOCS/Atomic+Operations[Atomic Operations]",
+ javaType = "Boolean")
public static final String MULTIUPDATE = "CamelMongoDbMultiUpdate";
+ @Metadata(label = "producer update", description = "If the database should create the element if it does not exist",
+ javaType = "Boolean")
public static final String UPSERT = "CamelMongoDbUpsert";
+ @Metadata(label = "producer", description = "The number of modified or deleted records", javaType = "long")
public static final String RECORDS_AFFECTED = "CamelMongoDbRecordsAffected";
+ @Metadata(label = "producer", description = "The number of documents matched by the query.", javaType = "long")
public static final String RECORDS_MATCHED = "CamelMongoDbRecordsMatched";
+ @Metadata(label = "producer", description = "The sort criteria.", javaType = "Bson or Document")
public static final String SORT_BY = "CamelMongoDbSortBy";
+ @Metadata(description = "The name of the MongoDB database to target", javaType = "String")
public static final String DATABASE = "CamelMongoDbDatabase";
+ @Metadata(description = "The name of the MongoDB collection to bind to this endpoint", javaType = "String")
public static final String COLLECTION = "CamelMongoDbCollection";
+ @Metadata(label = "producer", description = "The list of dynamic indexes to create on the fly", javaType = "List<Bson>")
public static final String COLLECTION_INDEX = "CamelMongoDbCollectionIndex";
+ @Metadata(label = "producer findAll", description = "Limits the number of elements returned.", javaType = "Integer")
public static final String LIMIT = "CamelMongoDbLimit";
+ @Metadata(label = "consumer", description = "Is from tailable", javaType = "Boolean")
public static final String FROM_TAILABLE = "CamelMongoDbTailable";
+ @Metadata(label = "producer", description = "The result of the write operation", javaType = "Object")
public static final String WRITERESULT = "CamelMongoWriteResult";
+ @Metadata(label = "producer", description = "The OID(s) of the inserted record(s)", javaType = "Object or List<Object>")
public static final String OID = "CamelMongoOid";
+ @Metadata(label = "producer", description = "The specified field name fow which we want to get the distinct values.",
+ javaType = "String")
public static final String DISTINCT_QUERY_FIELD = "CamelMongoDbDistinctQueryField";
+ @Metadata(label = "producer findAll aggregate", description = "Sets allowDiskUse MongoDB flag.\n" +
+ "This is supported since MongoDB Server 4.3.1. Using this header with older MongoDB Server version can cause query to fail.",
+ javaType = "Boolean")
public static final String ALLOW_DISK_USE = "CamelMongoDbAllowDiskUse";
+ @Metadata(label = "producer bulkWrite", description = "Perform an ordered or unordered operation execution. ",
+ javaType = "Boolean", defaultValue = "TRUE")
public static final String BULK_ORDERED = "CamelMongoDbBulkOrdered";
+ @Metadata(label = "consumer changeStreams",
+ description = "A document that contains the _id of the document created or modified by the insert,\n" +
+ "replace, delete, update operations (i.e. CRUD operations). For sharded collections, also displays the full shard key for\n"
+ +
+ "the document. The _id field is not repeated if it is already a part of the shard key.",
+ javaType = "org.bson.types.ObjectId")
public static final String MONGO_ID = "_id"; // default id field
+ @Metadata(label = "consumer changeStreams", description = "The type of operation that occurred. Can\n" +
+ "be any of the following values: insert, delete, replace, update, drop, rename, dropDatabase, invalidate.",
+ javaType = "String")
public static final String STREAM_OPERATION_TYPE = "CamelMongoDbStreamOperationType";
private MongoDbConstants() {
diff --git a/components/camel-mongodb/src/main/java/org/apache/camel/component/mongodb/MongoDbEndpoint.java b/components/camel-mongodb/src/main/java/org/apache/camel/component/mongodb/MongoDbEndpoint.java
index ed614ec..99c8dce 100644
--- a/components/camel-mongodb/src/main/java/org/apache/camel/component/mongodb/MongoDbEndpoint.java
+++ b/components/camel-mongodb/src/main/java/org/apache/camel/component/mongodb/MongoDbEndpoint.java
@@ -58,7 +58,7 @@ import static org.apache.camel.component.mongodb.MongoDbOutputType.MongoIterable
* Perform operations on MongoDB documents and collections.
*/
@UriEndpoint(firstVersion = "2.19.0", scheme = "mongodb", title = "MongoDB", syntax = "mongodb:connectionBean",
- category = { Category.DATABASE, Category.NOSQL })
+ category = { Category.DATABASE, Category.NOSQL }, headersClass = MongoDbConstants.class)
public class MongoDbEndpoint extends DefaultEndpoint {
private static final Logger LOG = LoggerFactory.getLogger(MongoDbEndpoint.class);