Skip to content

camel-docling: document that html_split_page cannot be used #29720

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
WMK666666 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

camel-docling: document that html_split_page cannot be used #29720

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions ...-docling/src/generated/resources/META-INF/org/apache/camel/component/docling/docling.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@
"includeLayoutInfo": { "index": 4, "kind": "property", "displayName": "Include Layout Info", "group": "common", "label": "", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "autowired": false, "secret": false, "defaultValue": false, "configurationClass": "org.apache.camel.component.docling.DoclingConfiguration", "configurationField": "configuration", "description": "Show layout information with bounding boxes" },
"ocrLanguage": { "index": 5, "kind": "property", "displayName": "Ocr Language", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "defaultValue": "en", "configurationClass": "org.apache.camel.component.docling.DoclingConfiguration", "configurationField": "configuration", "description": "Language code for OCR processing" },
"operation": { "index": 6, "kind": "property", "displayName": "Operation", "group": "common", "label": "", "required": true, "type": "enum", "javaType": "org.apache.camel.component.docling.DoclingOperations", "enum": [ "CONVERT_TO_MARKDOWN", "CONVERT_TO_HTML", "CONVERT_TO_JSON", "EXTRACT_TEXT", "EXTRACT_STRUCTURED_DATA", "SUBMIT_ASYNC_CONVERSION", "CHECK_CONVERSION_STATUS", "BATCH_CONVERT_TO_MARKDOWN", "BATCH_CONVERT_TO_HTML", "BATCH_CONVERT_TO_JSON", "BATCH_EXTRACT_TEXT", "BATCH_EXTRACT_STRUCTURED_DATA", "EXTRACT_METADATA", "CHUNK_HYBRID", "CHUNK_HIERARCHICAL" ], "deprecated": false, "autowired": false, "secret": false, "defaultValue": "CONVERT_TO_MARKDOWN", "configurationClass": "org.apache.camel.component.docling.DoclingConfiguration", "configurationField": "configuration", "description": "The operation to perform" },
"outputFormat": { "index": 7, "kind": "property", "displayName": "Output Format", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "defaultValue": "markdown", "configurationClass": "org.apache.camel.component.docling.DoclingConfiguration", "configurationField": "configuration", "description": "Output format for document conversion" },
"outputFormat": { "index": 7, "kind": "property", "displayName": "Output Format", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "defaultValue": "markdown", "configurationClass": "org.apache.camel.component.docling.DoclingConfiguration", "configurationField": "configuration", "description": "Output format for document conversion. The html_split_page value is rejected when useDoclingServe is true, as docling-serve returns no split pages, and the CLI operations pass their own format; use html instead" },
"useDoclingServe": { "index": 8, "kind": "property", "displayName": "Use Docling Serve", "group": "common", "label": "", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "autowired": false, "secret": false, "defaultValue": false, "configurationClass": "org.apache.camel.component.docling.DoclingConfiguration", "configurationField": "configuration", "description": "Use docling-serve API instead of CLI command" },
"bridgeErrorHandler": { "index": 9, "kind": "property", "displayName": "Bridge Error Handler", "group": "consumer", "label": "consumer", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "autowired": false, "secret": false, "defaultValue": false, "description": "Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions (if possible) occurred while the Camel consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. Important: This is only possible if the 3rd party component allows Camel to be alerted if an exception was thrown. Some components handle this internally only, and therefore bridgeErrorHandler is not possible. In other situations we may improve the Camel component to hook into the 3rd party component and make this possible for future releases. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored." },
"lazyStartProducer": { "index": 10, "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 starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing." },
Expand Down Expand Up @@ -134,7 +134,7 @@
"includeLayoutInfo": { "index": 4, "kind": "parameter", "displayName": "Include Layout Info", "group": "common", "label": "", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "autowired": false, "secret": false, "defaultValue": false, "configurationClass": "org.apache.camel.component.docling.DoclingConfiguration", "configurationField": "configuration", "description": "Show layout information with bounding boxes" },
"ocrLanguage": { "index": 5, "kind": "parameter", "displayName": "Ocr Language", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "defaultValue": "en", "configurationClass": "org.apache.camel.component.docling.DoclingConfiguration", "configurationField": "configuration", "description": "Language code for OCR processing" },
"operation": { "index": 6, "kind": "parameter", "displayName": "Operation", "group": "common", "label": "", "required": true, "type": "enum", "javaType": "org.apache.camel.component.docling.DoclingOperations", "enum": [ "CONVERT_TO_MARKDOWN", "CONVERT_TO_HTML", "CONVERT_TO_JSON", "EXTRACT_TEXT", "EXTRACT_STRUCTURED_DATA", "SUBMIT_ASYNC_CONVERSION", "CHECK_CONVERSION_STATUS", "BATCH_CONVERT_TO_MARKDOWN", "BATCH_CONVERT_TO_HTML", "BATCH_CONVERT_TO_JSON", "BATCH_EXTRACT_TEXT", "BATCH_EXTRACT_STRUCTURED_DATA", "EXTRACT_METADATA", "CHUNK_HYBRID", "CHUNK_HIERARCHICAL" ], "deprecated": false, "autowired": false, "secret": false, "defaultValue": "CONVERT_TO_MARKDOWN", "configurationClass": "org.apache.camel.component.docling.DoclingConfiguration", "configurationField": "configuration", "description": "The operation to perform" },
"outputFormat": { "index": 7, "kind": "parameter", "displayName": "Output Format", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "defaultValue": "markdown", "configurationClass": "org.apache.camel.component.docling.DoclingConfiguration", "configurationField": "configuration", "description": "Output format for document conversion" },
"outputFormat": { "index": 7, "kind": "parameter", "displayName": "Output Format", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "autowired": false, "secret": false, "defaultValue": "markdown", "configurationClass": "org.apache.camel.component.docling.DoclingConfiguration", "configurationField": "configuration", "description": "Output format for document conversion. The html_split_page value is rejected when useDoclingServe is true, as docling-serve returns no split pages, and the CLI operations pass their own format; use html instead" },
"useDoclingServe": { "index": 8, "kind": "parameter", "displayName": "Use Docling Serve", "group": "common", "label": "", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "autowired": false, "secret": false, "defaultValue": false, "configurationClass": "org.apache.camel.component.docling.DoclingConfiguration", "configurationField": "configuration", "description": "Use docling-serve API instead of CLI command" },
"sendEmptyMessageWhenIdle": { "index": 9, "kind": "parameter", "displayName": "Send Empty Message When Idle", "group": "consumer", "label": "consumer", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "autowired": false, "secret": false, "defaultValue": false, "description": "If the polling consumer did not poll any files, you can enable this option to send an empty message (no body) instead." },
"bridgeErrorHandler": { "index": 10, "kind": "parameter", "displayName": "Bridge Error Handler", "group": "consumer (advanced)", "label": "consumer,advanced", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "autowired": false, "secret": false, "defaultValue": false, "description": "Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions (if possible) occurred while the Camel consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. Important: This is only possible if the 3rd party component allows Camel to be alerted if an exception was thrown. Some components handle this internally only, and therefore bridgeErrorHandler is not possible. In other situations we may improve the Camel component to hook into the 3rd party component and make this possible for future releases. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored." },
Expand Down
3 changes: 2 additions & 1 deletion .../camel-docling/src/main/java/org/apache/camel/component/docling/DoclingConfiguration.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,8 @@ public class DoclingConfiguration implements Cloneable {
private String ocrLanguage = "en";

@UriParam
@Metadata(description = "Output format for document conversion", defaultValue = "markdown",
@Metadata(description = "Output format for document conversion. The html_split_page value is rejected when useDoclingServe is true, as docling-serve returns no split pages, and the CLI operations pass their own format; use html instead",
defaultValue = "markdown",

@gnodet-bot gnodet-bot Nov 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ html_split_page is still listed in enums, so the catalog and IDE autocomplete will continue to present it as a valid choice. The description now says it doesn't work, but users who rely on catalog-driven configuration rather than reading the full description will still pick it and get unexpected behaviour.

Consider removing it from enums, or throwing an explicit IllegalArgumentException during configuration validation rather than silently falling back to markdown (which is what the CLI path does in mapToDoclingFormat — there is no case for html_split_page, so it defaults to "md" without any warning).

Suggested change
defaultValue = "markdown",
@Metadata(description = "Output format for document conversion. The html_split_page value is not supported"
+ " and will be removed in a future release; use html instead.",
defaultValue = "markdown",
enums = "md,json,html,text,doctags")

enums = "md,json,html,html_split_page,text,doctags")
private String outputFormat = "markdown";

Expand Down