[
https://issues.apache.org/jira/browse/CAMEL-19129?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Peter Palaga updated CAMEL-19129:
---------------------------------
Description:
Camel CXF documentation could be improved, here are some ideas:
h4. 1. Out of date content
Some sections may explain problems or use cases that do not exist anymore and
could thus be removed:
* [HOW TO MAKE THE CAMEL-CXF COMPONENT USE LOG4J INSTEAD OF
JAVA.UTIL.LOGGING|https://camel.apache.org/components/3.20.x/cxf-component.html#_how_to_make_the_camel_cxf_component_use_log4j_instead_of_java_util_logging]
- is this still an issue?
* Remove [CONFIGURING THE CXF ENDPOINTS WITH APACHE ARIES
BLUEPRINT|https://camel.apache.org/components/3.20.x/cxf-component.html#_configuring_the_cxf_endpoints_with_apache_aries_blueprint]
- blueprint is not supported since Camel 4, is it?
* [HOW TO OVERRIDE THE CXF PRODUCER ADDRESS FROM MESSAGE
HEADER|https://camel.apache.org/components/3.20.x/cxf-component.html#_how_to_override_the_cxf_producer_address_from_message_header]
probably doesn't need to be under high level use cases and can be removed, as
this header is described under headers section
h4. 2. Spring-specific parts that should be moved to a Spring-specific
documentation page
This points to a more general problem, that Camel component documentation is
oftentimes Spring-centric, although the given component can be used on a number
of different runtimes or even with plain Camel. The Spring details may confuse
users who do not use Spring. There should be a separate place for Spring
specific details. It could perhaps work the same way like with Camel Quarkus,
where each extension hast its own page documenting Quarkus specific GAV,
configuration, limitations, etc.
* [CONFIGURE THE CXF ENDPOINTS WITH
SPRING|https://camel.apache.org/components/3.20.x/cxf-component.html#_configure_the_cxf_endpoints_with_spring]
h4. 3. General
* Link to PersonProcessor at [HOW TO CONSUME A MESSAGE FROM A CAMEL-CXF
ENDPOINT IN POJO DATA
FORMAT|https://camel.apache.org/components/3.20.x/cxf-component.html#_how_to_consume_a_message_from_a_camel_cxf_endpoint_in_pojo_data_format]
doesn't exist
* Shouldn't be artifactId = camel-cxf-soap ?
* Inconsistent definition of dataFormats in [QUERY
PARAMETERS|https://camel.apache.org/components/3.20.x/cxf-component.html#_endpoint_query_option_dataFormat]
and [DESCRIPTIONS OF THE
DATAFORMATS|https://camel.apache.org/components/3.20.x/cxf-component.html#_descriptions_of_the_dataformats]
* Make consistent section names - eg. "HOW TO DEAL WITH THE MESSAGE" vs "HOW
TO CONSUME A MESSAGE"
* What does "Both SOAP with Attachment and MTOM are supported. However, SOAP
with Attachment is not tested." mean in [ATTACHMENT
SUPPORT|https://camel.apache.org/components/3.20.x/cxf-component.html#_attachment_support]
?
* This sentence "To enable MTOM, set the CXF endpoint property "mtom-enabled"
to true. (I believe you can only do it with Spring.)" at [ATTACHMENT
SUPPORT|https://camel.apache.org/components/3.20.x/cxf-component.html#_attachment_support]
should be ideally rewritten
* Maybe re-order the sections, so it starts with some really simple example of
consumer/producer (WSDL first/Java first approaches) and not with "How to ... "
- as it seems more like corner cases sections
* Nice to have - having some best practice security section
was:
Camel CXF documentation could be improved, here are some ideas:
* Remove [HOW TO MAKE THE CAMEL-CXF COMPONENT USE LOG4J INSTEAD OF
JAVA.UTIL.LOGGING|https://camel.apache.org/components/3.20.x/cxf-component.html#_how_to_make_the_camel_cxf_component_use_log4j_instead_of_java_util_logging]
* Remove [CONFIGURING THE CXF ENDPOINTS WITH APACHE ARIES
BLUEPRINT|https://camel.apache.org/components/3.20.x/cxf-component.html#_configuring_the_cxf_endpoints_with_apache_aries_blueprint]
Spring-specific parts that should be moved to a Spring-specific documentation
page
* Ideally move to some spring boot related documenation [CONFIGURE THE CXF
ENDPOINTS WITH
SPRING|https://camel.apache.org/components/3.20.x/cxf-component.html#_configure_the_cxf_endpoints_with_spring]
* [HOW TO OVERRIDE THE CXF PRODUCER ADDRESS FROM MESSAGE
HEADER|https://camel.apache.org/components/3.20.x/cxf-component.html#_how_to_override_the_cxf_producer_address_from_message_header]
probably doesn't need to be under high level use cases and can be removed, as
this header is described under headers section
* Link to PersonProcessor at [HOW TO CONSUME A MESSAGE FROM A CAMEL-CXF
ENDPOINT IN POJO DATA
FORMAT|https://camel.apache.org/components/3.20.x/cxf-component.html#_how_to_consume_a_message_from_a_camel_cxf_endpoint_in_pojo_data_format]
doesn't exist
* Shouldn't be artifactId = camel-cxf-soap ?
* Inconsistent definition of dataFormats in [QUERY
PARAMETERS|https://camel.apache.org/components/3.20.x/cxf-component.html#_endpoint_query_option_dataFormat]
and [DESCRIPTIONS OF THE
DATAFORMATS|https://camel.apache.org/components/3.20.x/cxf-component.html#_descriptions_of_the_dataformats]
* Make consistent section names - eg. "HOW TO DEAL WITH THE MESSAGE" vs "HOW
TO CONSUME A MESSAGE"
* What does "Both SOAP with Attachment and MTOM are supported. However, SOAP
with Attachment is not tested." mean in [ATTACHMENT
SUPPORT|https://camel.apache.org/components/3.20.x/cxf-component.html#_attachment_support]
?
* This sentence "To enable MTOM, set the CXF endpoint property "mtom-enabled"
to true. (I believe you can only do it with Spring.)" at [ATTACHMENT
SUPPORT|https://camel.apache.org/components/3.20.x/cxf-component.html#_attachment_support]
should be ideally rewritten
* Maybe re-order the sections, so it starts with some really simple example of
consumer/producer (WSDL first/Java first approaches) and not with "How to ... "
- as it seems more like corner cases sections
* Nice to have - having some best practice security section
> Improve Camel CXF documentation
> -------------------------------
>
> Key: CAMEL-19129
> URL: https://issues.apache.org/jira/browse/CAMEL-19129
> Project: Camel
> Issue Type: Improvement
> Components: camel-cxf, documentation
> Affects Versions: 3.20.2
> Reporter: Lukas Lowinger
> Priority: Major
>
> Camel CXF documentation could be improved, here are some ideas:
> h4. 1. Out of date content
> Some sections may explain problems or use cases that do not exist anymore and
> could thus be removed:
> * [HOW TO MAKE THE CAMEL-CXF COMPONENT USE LOG4J INSTEAD OF
> JAVA.UTIL.LOGGING|https://camel.apache.org/components/3.20.x/cxf-component.html#_how_to_make_the_camel_cxf_component_use_log4j_instead_of_java_util_logging]
> - is this still an issue?
> * Remove [CONFIGURING THE CXF ENDPOINTS WITH APACHE ARIES
> BLUEPRINT|https://camel.apache.org/components/3.20.x/cxf-component.html#_configuring_the_cxf_endpoints_with_apache_aries_blueprint]
> - blueprint is not supported since Camel 4, is it?
> * [HOW TO OVERRIDE THE CXF PRODUCER ADDRESS FROM MESSAGE
> HEADER|https://camel.apache.org/components/3.20.x/cxf-component.html#_how_to_override_the_cxf_producer_address_from_message_header]
> probably doesn't need to be under high level use cases and can be removed,
> as this header is described under headers section
> h4. 2. Spring-specific parts that should be moved to a Spring-specific
> documentation page
> This points to a more general problem, that Camel component documentation is
> oftentimes Spring-centric, although the given component can be used on a
> number of different runtimes or even with plain Camel. The Spring details may
> confuse users who do not use Spring. There should be a separate place for
> Spring specific details. It could perhaps work the same way like with Camel
> Quarkus, where each extension hast its own page documenting Quarkus specific
> GAV, configuration, limitations, etc.
> * [CONFIGURE THE CXF ENDPOINTS WITH
> SPRING|https://camel.apache.org/components/3.20.x/cxf-component.html#_configure_the_cxf_endpoints_with_spring]
> h4. 3. General
> * Link to PersonProcessor at [HOW TO CONSUME A MESSAGE FROM A CAMEL-CXF
> ENDPOINT IN POJO DATA
> FORMAT|https://camel.apache.org/components/3.20.x/cxf-component.html#_how_to_consume_a_message_from_a_camel_cxf_endpoint_in_pojo_data_format]
> doesn't exist
> * Shouldn't be artifactId = camel-cxf-soap ?
> * Inconsistent definition of dataFormats in [QUERY
> PARAMETERS|https://camel.apache.org/components/3.20.x/cxf-component.html#_endpoint_query_option_dataFormat]
> and [DESCRIPTIONS OF THE
> DATAFORMATS|https://camel.apache.org/components/3.20.x/cxf-component.html#_descriptions_of_the_dataformats]
> * Make consistent section names - eg. "HOW TO DEAL WITH THE MESSAGE" vs "HOW
> TO CONSUME A MESSAGE"
> * What does "Both SOAP with Attachment and MTOM are supported. However, SOAP
> with Attachment is not tested." mean in [ATTACHMENT
> SUPPORT|https://camel.apache.org/components/3.20.x/cxf-component.html#_attachment_support]
> ?
> * This sentence "To enable MTOM, set the CXF endpoint property
> "mtom-enabled" to true. (I believe you can only do it with Spring.)" at
> [ATTACHMENT
> SUPPORT|https://camel.apache.org/components/3.20.x/cxf-component.html#_attachment_support]
> should be ideally rewritten
> * Maybe re-order the sections, so it starts with some really simple example
> of consumer/producer (WSDL first/Java first approaches) and not with "How to
> ... " - as it seems more like corner cases sections
> * Nice to have - having some best practice security section
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
