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 <[email protected]> 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);
