CAMEL-24340: camel-salesforce: improve option and header documentation

components/camel-salesforce/camel-salesforce-component/src/main/java/org/apache/camel/component/salesforce/SalesforceComponent.java

@@ -166,11 +166,13 @@ public class SalesforceComponent extends DefaultComponent implements SSLContextP
               defaultValue = "false", label = "common,security")
     private boolean lazyLogin;
 
-    @Metadata(description = "Pub/Sub host",
+    @Metadata(description = "Host name of the Salesforce Pub/Sub API gRPC service used by the pubSubSubscribe and"
+                            + " pubSubPublish operations. Give a bare host name, without scheme or port.",
               defaultValue = "api.pubsub.salesforce.com", label = "common,security")
     private String pubSubHost = "api.pubsub.salesforce.com";
 
-    @Metadata(description = "Pub/Sub port",
+    @Metadata(description = "TCP port of the Salesforce Pub/Sub API gRPC service used by the pubSubSubscribe and"
+                            + " pubSubPublish operations.",
               defaultValue = "7443", label = "common,security")
     private int pubSubPort = 7443;
 

components/camel-salesforce/camel-salesforce-component/src/main/java/org/apache/camel/component/salesforce/SalesforceConstants.java

@@ -27,37 +27,83 @@ public final class SalesforceConstants {
     public static final String HEADER_SALESFORCE_EVENT_UUID = "CamelSalesforceEventUuid";
     @Metadata(label = "consumer", description = "The change event schema.", javaType = "Object")
     public static final String HEADER_SALESFORCE_CHANGE_EVENT_SCHEMA = "CamelSalesforceChangeEventSchema";
-    @Metadata(label = "consumer", description = "The event type.", javaType = "String")
+    @Metadata(label = "consumer",
+              description = "For change and platform events, the last segment of the configured topic name, such as"
+                            + " AccountChangeEvent. For PushTopic messages, the Salesforce event type of the"
+                            + " notification, such as created.",
+              javaType = "String")
     public static final String HEADER_SALESFORCE_EVENT_TYPE = "CamelSalesforceEventType";
-    @Metadata(label = "consumer", description = "The commit timestamp.", javaType = "Object")
+    @Metadata(label = "consumer",
+              description = "Time of the Salesforce transaction that produced the change event, from the"
+                            + " ChangeEventHeader.",
+              javaType = "Object")
     public static final String HEADER_SALESFORCE_COMMIT_TIMESTAMP = "CamelSalesforceCommitTimestamp";
-    @Metadata(label = "consumer", description = "The commit user.", javaType = "Object")
+    @Metadata(label = "consumer",
+              description = "Id of the Salesforce user whose transaction produced the change event, from the"
+                            + " ChangeEventHeader.",
+              javaType = "Object")
     public static final String HEADER_SALESFORCE_COMMIT_USER = "CamelSalesforceCommitUser";
-    @Metadata(label = "consumer", description = "The commit number.", javaType = "Object")
+    @Metadata(label = "consumer",
+              description = "System change number of the Salesforce transaction that produced the change event, from"
+                            + " the ChangeEventHeader.",
+              javaType = "Object")
     public static final String HEADER_SALESFORCE_COMMIT_NUMBER = "CamelSalesforceCommitNumber";
-    @Metadata(label = "consumer", description = "The record ids.", javaType = "Object")
+    @Metadata(label = "consumer",
+              description = "Ids of the records affected by the change event, from the ChangeEventHeader. Holds more"
+                            + " than one id when a single transaction changed several records.",
+              javaType = "Object")
     public static final String HEADER_SALESFORCE_RECORD_IDS = "CamelSalesforceRecordIds";
-    @Metadata(label = "consumer", description = "The change type.", javaType = "Object")
+    @Metadata(label = "consumer",
+              description = "Kind of change carried by the change event, from the ChangeEventHeader, for example"
+                            + " CREATE or UPDATE.",
+              javaType = "Object")
     public static final String HEADER_SALESFORCE_CHANGE_TYPE = "CamelSalesforceChangeType";
-    @Metadata(label = "consumer", description = "The change origin.", javaType = "Object")
+    @Metadata(label = "consumer",
+              description = "Identifies the Salesforce API and client that made the change, from the"
+                            + " ChangeEventHeader.",
+              javaType = "Object")
     public static final String HEADER_SALESFORCE_CHANGE_ORIGIN = "CamelSalesforceChangeOrigin";
-    @Metadata(label = "consumer", description = "The transaction key.", javaType = "Object")
+    @Metadata(label = "consumer",
+              description = "Key shared by every change event produced by the same Salesforce transaction, from the"
+                            + " ChangeEventHeader. Use it to group events that belong to one transaction.",
+              javaType = "Object")
     public static final String HEADER_SALESFORCE_TRANSACTION_KEY = "CamelSalesforceTransactionKey";
-    @Metadata(label = "consumer", description = "The sequence number.", javaType = "Object")
+    @Metadata(label = "consumer",
+              description = "Position of this change event within its Salesforce transaction, from the"
+                            + " ChangeEventHeader.",
+              javaType = "Object")
     public static final String HEADER_SALESFORCE_SEQUENCE_NUMBER = "CamelSalesforceSequenceNumber";
-    @Metadata(label = "consumer", description = "Is transaction end.", javaType = "Object")
+    @Metadata(label = "consumer",
+              description = "True when this change event is the last one of its Salesforce transaction, from the"
+                            + " ChangeEventHeader. Use it together with CamelSalesforceTransactionKey to detect the"
+                            + " end of a transaction.",
+              javaType = "Object")
     public static final String HEADER_SALESFORCE_IS_TRANSACTION_END = "CamelSalesforceIsTransactionEnd";
-    @Metadata(label = "consumer", description = "The entity name.", javaType = "Object")
+    @Metadata(label = "consumer",
+              description = "Name of the Salesforce object the change event applies to, such as Account, from the"
+                            + " ChangeEventHeader.",
+              javaType = "Object")
     public static final String HEADER_SALESFORCE_ENTITY_NAME = "CamelSalesforceEntityName";
     @Metadata(label = "consumer", description = "The platform event schema.", javaType = "Object")
     public static final String HEADER_SALESFORCE_PLATFORM_EVENT_SCHEMA = "CamelSalesforcePlatformEventSchema";
-    @Metadata(label = "consumer", description = "The created date.", javaType = "java.time.ZonedDateTime")
+    @Metadata(label = "consumer",
+              description = "Creation time of the event. Platform events supply a ZonedDateTime taken from the event"
+                            + " payload, while PushTopic notifications supply the raw createdDate value as a String.",
+              javaType = "java.time.ZonedDateTime")
     public static final String HEADER_SALESFORCE_CREATED_DATE = "CamelSalesforceCreatedDate";
-    @Metadata(label = "consumer", description = "The topic name.", javaType = "String")
+    @Metadata(label = "consumer",
+              description = "Name of the PushTopic the message was received from. Set for PushTopic messages only.",
+              javaType = "String")
     public static final String HEADER_SALESFORCE_TOPIC_NAME = "CamelSalesforceTopicName";
-    @Metadata(label = "consumer", description = "The channel.", javaType = "String")
+    @Metadata(label = "consumer",
+              description = "Streaming API channel the message was received on, such as /topic/MyTopic or"
+                            + " /data/AccountChangeEvent.",
+              javaType = "String")
     public static final String HEADER_SALESFORCE_CHANNEL = "CamelSalesforceChannel";
-    @Metadata(label = "consumer", description = "The client id.", javaType = "String")
+    @Metadata(label = "consumer",
+              description = "Client id of the Streaming API subscription that received the message. Set only when the"
+                            + " server supplies one.",
+              javaType = "String")
     public static final String HEADER_SALESFORCE_CLIENT_ID = "CamelSalesforceClientId";
 
     // Pub/Sub API headers

components/camel-salesforce/camel-salesforce-component/src/main/java/org/apache/camel/component/salesforce/SalesforceEndpointConfig.java

@@ -155,7 +155,7 @@ public class SalesforceEndpointConfig implements Cloneable {
     private Boolean streamQueryResult = false;
     @UriParam(displayName = "SObject Search")
     private String sObjectSearch;
-    @UriParam
+    @UriParam(defaultValue = "GET")
     private String apexMethod;
     @UriParam(displayName = "Event Name", label = "producer")
     private String eventName;
@@ -456,7 +456,8 @@ public String getApexMethod() {
     }
 
     /**
-     * APEX method name
+     * HTTP verb used for the Apex REST invocation, such as GET, POST, PUT, PATCH or DELETE. Applies to the apexCall
+     * operation and defaults to GET. Can be overridden per message with the CamelSalesforceApexMethod header.
      */
     public void setApexMethod(String apexMethod) {
         this.apexMethod = apexMethod;
@@ -467,7 +468,10 @@ public String getApexUrl() {
     }
 
     /**
-     * APEX method URL
+     * Path of the Apex REST resource to invoke, appended to /services/apexrest/ on the instance URL, for example
+     * MyApexClass/. The apexCall operation needs this value, which can be given as this option, in the endpoint path as
+     * apexCall/MyApexClass/, or in the CamelSalesforceApexUrl header. Placeholders written in curly braces are resolved
+     * from message headers of the same name.
      */
     public void setApexUrl(String apexUrl) {
         this.apexUrl = apexUrl;
@@ -534,7 +538,9 @@ public String getJobId() {
     }
 
     /**
-     * Bulk API Job ID
+     * Identifies the Bulk API job to act on, for Bulk API v1 operations such as getJob, closeJob, abortJob, createBatch
+     * and getResults, and for the bulk2 operations that target an existing job. Operations that accept a JobInfo or
+     * BatchInfo message body can take the id from there instead.
      */
     public void setJobId(String jobId) {
         this.jobId = jobId;
@@ -545,7 +551,8 @@ public String getBatchId() {
     }
 
     /**
-     * Bulk API Batch ID
+     * Identifies a batch within a Bulk API v1 job. Required by getBatch, getRequest, getResults, getQueryResultIds and
+     * getQueryResult unless a BatchInfo message body supplies it. Not used by Bulk API 2.0.
      */
     public void setBatchId(String batchId) {
         this.batchId = batchId;
@@ -556,7 +563,8 @@ public String getResultId() {
     }
 
     /**
-     * Bulk API Result ID
+     * Identifies one result set of a completed Bulk API v1 query batch, as returned by the getQueryResultIds operation.
+     * Used only by getQueryResult, together with jobId and batchId.
      */
     public void setResultId(String resultId) {
         this.resultId = resultId;

dsl/camel-componentdsl/src/generated/java/org/apache/camel/builder/component/dsl/SalesforceComponentBuilderFactory.java

@@ -50,11 +50,16 @@ static SalesforceComponentBuilder salesforce() {
      */
     interface SalesforceComponentBuilder extends ComponentBuilder<SalesforceComponent> {
 
+
         /**
-         * APEX method name.
+         * HTTP verb used for the Apex REST invocation, such as GET, POST, PUT,
+         * PATCH or DELETE. Applies to the apexCall operation and defaults to
+         * GET. Can be overridden per message with the CamelSalesforceApexMethod
+         * header.
          * 
          * The option is a: &lt;code&gt;java.lang.String&lt;/code&gt; type.
          * 
+         * Default: GET
          * Group: common
          * 
          * @param apexMethod the value to set
@@ -117,7 +122,9 @@ default SalesforceComponentBuilder backoffIncrement(long backoffIncrement) {
         }
 
         /**
-         * Bulk API Batch ID.
+         * Identifies a batch within a Bulk API v1 job. Required by getBatch,
+         * getRequest, getResults, getQueryResultIds and getQueryResult unless a
+         * BatchInfo message body supplies it. Not used by Bulk API 2.0.
          * 
          * The option is a: &lt;code&gt;java.lang.String&lt;/code&gt; type.
          * 
@@ -350,7 +357,11 @@ default SalesforceComponentBuilder instanceId(java.lang.String instanceId) {
         }
 
         /**
-         * Bulk API Job ID.
+         * Identifies the Bulk API job to act on, for Bulk API v1 operations
+         * such as getJob, closeJob, abortJob, createBatch and getResults, and
+         * for the bulk2 operations that target an existing job. Operations that
+         * accept a JobInfo or BatchInfo message body can take the id from there
+         * instead.
          * 
          * The option is a: &lt;code&gt;java.lang.String&lt;/code&gt; type.
          * 
@@ -737,7 +748,9 @@ default SalesforceComponentBuilder reportMetadata(org.apache.camel.component.sal
         }
 
         /**
-         * Bulk API Result ID.
+         * Identifies one result set of a completed Bulk API v1 query batch, as
+         * returned by the getQueryResultIds operation. Used only by
+         * getQueryResult, together with jobId and batchId.
          * 
          * The option is a: &lt;code&gt;java.lang.String&lt;/code&gt; type.
          * 
@@ -1235,7 +1248,12 @@ default SalesforceComponentBuilder allOrNone(boolean allOrNone) {
         }
 
         /**
-         * APEX method URL.
+         * Path of the Apex REST resource to invoke, appended to
+         * /services/apexrest/ on the instance URL, for example MyApexClass/.
+         * The apexCall operation needs this value, which can be given as this
+         * option, in the endpoint path as apexCall/MyApexClass/, or in the
+         * CamelSalesforceApexUrl header. Placeholders written in curly braces
+         * are resolved from message headers of the same name.
          * 
          * The option is a: &lt;code&gt;java.lang.String&lt;/code&gt; type.
          * 
@@ -1802,7 +1820,9 @@ default SalesforceComponentBuilder password(java.lang.String password) {
 
 
         /**
-         * Pub/Sub host.
+         * Host name of the Salesforce Pub/Sub API gRPC service used by the
+         * pubSubSubscribe and pubSubPublish operations. Give a bare host name,
+         * without scheme or port.
          * 
          * The option is a: &lt;code&gt;java.lang.String&lt;/code&gt; type.
          * 
@@ -1819,7 +1839,8 @@ default SalesforceComponentBuilder pubSubHost(java.lang.String pubSubHost) {
 
 
         /**
-         * Pub/Sub port.
+         * TCP port of the Salesforce Pub/Sub API gRPC service used by the
+         * pubSubSubscribe and pubSubPublish operations.
          * 
          * The option is a: &lt;code&gt;int&lt;/code&gt; type.
          *