You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by GitBox <gi...@apache.org> on 2022/03/11 15:49:02 UTC
[GitHub] [camel] essobedo opened a new pull request #7190: CAMEL-16628: Allow to generate doc about message headers
essobedo opened a new pull request #7190:
URL: https://github.com/apache/camel/pull/7190
Fix for https://issues.apache.org/jira/browse/CAMEL-16628
## Motivation
Like we have for endpoint options with @UriParam, we should have a new SPI annotation to markup headers that consumer/producers support.
## Modifications
This PR adds a new element called `headers` to the annotation `@Metadata` to provide the list of all the constants corresponding to the name of the headers supported by the consumers/producers. This element can only be set in the `@Metadata` annotation added to the endpoint class.
In the example below, the endpoint `FooEndpoint` indicates that it supports only one header whose name is `Constants.FILE_NAME`.
```
@Metadata(headers = Constants.FILE_NAME)
public class FooEndpoint extends Endpoint {
// Rest of the class
}
```
The metadata of a given header are retrieved from the annotation `@Metadata` added to the constant.
In the example below, the header `Constants.FILE_NAME` specify a description, a default value and a java type.
```
public final class Constants {
@Metadata(description = "Some description of CamelFileName", defaultValue = "Some default value", javaType = "java.lang.String")
public static final String FILE_NAME = "CamelFileName";
// Rest of the class
}
```
This PR adds a new asciidoctor template called `component-endpoint-headers.adoc` that can be called from a doc file with:
```
// component headers: START
include::partial$component-endpoint-headers.adoc[]
// component headers: END
```
## Result
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@camel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [camel] essobedo merged pull request #7190: CAMEL-16628: Allow to generate doc about message headers
Posted by GitBox <gi...@apache.org>.
essobedo merged pull request #7190:
URL: https://github.com/apache/camel/pull/7190
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@camel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [camel] davsclaus commented on pull request #7190: CAMEL-16628: Allow to generate doc about message headers
Posted by GitBox <gi...@apache.org>.
davsclaus commented on pull request #7190:
URL: https://github.com/apache/camel/pull/7190#issuecomment-1066609256
Awesome work, this looks easy to use and also makes it possible for us to migrate existing components.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@camel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [camel] essobedo commented on pull request #7190: CAMEL-16628: Allow to generate doc about message headers
Posted by GitBox <gi...@apache.org>.
essobedo commented on pull request #7190:
URL: https://github.com/apache/camel/pull/7190#issuecomment-1066601151
@davsclaus I applied your remarks, please check again
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@camel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [camel] davsclaus commented on pull request #7190: CAMEL-16628: Allow to generate doc about message headers
Posted by GitBox <gi...@apache.org>.
davsclaus commented on pull request #7190:
URL: https://github.com/apache/camel/pull/7190#issuecomment-1066042129
@essobedo oh my word is not a rule in law - you are the one that are actual implementing this and find out on the way what is a better solution.
Unfortunately the Camel components was very _open ended_ when Camel was created/designed and this leads to where we are today with endpoint headers that are not well documented, defined consistently in a class named XXX or defined directly on the endpoint class, etc.
But we have the power in our hands where we can implement what you work on, and then "fix" all the components in Apache Camel. We have done this over the years with adding documentation for every endpoint options etc.
In the camel-catalog that prints a summary we can write a report which lists all the components that does not yet have headers marked up with @Metadata - then we can see how many we need to fix. This is what we did in the past.
And some components will not have headers, and if so, then should we still have a header class, but keep it empty?
About number of header classes, then that should be 1 class.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@camel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [camel] essobedo commented on pull request #7190: CAMEL-16628: Allow to generate doc about message headers
Posted by GitBox <gi...@apache.org>.
essobedo commented on pull request #7190:
URL: https://github.com/apache/camel/pull/7190#issuecomment-1065926881
Hum, it is a totally different approach, so I'll need to rewrite nearly everything but ok as you wish. It's my bad, I should have validated my approach first before implementing it. Regarding your suggestion how many headers class do you want to allow? Only one or several classes?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@camel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [camel] davsclaus commented on pull request #7190: CAMEL-16628: Allow to generate doc about message headers
Posted by GitBox <gi...@apache.org>.
davsclaus commented on pull request #7190:
URL: https://github.com/apache/camel/pull/7190#issuecomment-1065837479
Really good start, its not so far again.
I wonder instead of having @Metadata(headers = array here) on the endpoint class which then leads to duplicating effort as you need to add each here here, and as well in the headers class (xxxConstants).
What about instead you add an attribute on @UriEndpoint that refers to the headers class
@UriEndpoint(....
headersClass = KafkaConstants.class)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@camel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [camel] essobedo commented on pull request #7190: CAMEL-16628: Allow to generate doc about message headers
Posted by GitBox <gi...@apache.org>.
essobedo commented on pull request #7190:
URL: https://github.com/apache/camel/pull/7190#issuecomment-1067046661
@oscerd here is the task https://issues.apache.org/jira/browse/CAMEL-17792
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@camel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [camel] davsclaus edited a comment on pull request #7190: CAMEL-16628: Allow to generate doc about message headers
Posted by GitBox <gi...@apache.org>.
davsclaus edited a comment on pull request #7190:
URL: https://github.com/apache/camel/pull/7190#issuecomment-1065837479
Really good start, its not so far again.
I wonder instead of having @Metadata(headers = array here) on the endpoint class which then leads to duplicating effort as you need to add each here here, and as well in the headers class (xxxConstants).
What about instead you add an attribute on @UriEndpoint that refers to the headers class
```
@UriEndpoint(....
headersClass = KafkaConstants.class)
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@camel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [camel] oscerd commented on pull request #7190: CAMEL-16628: Allow to generate doc about message headers
Posted by GitBox <gi...@apache.org>.
oscerd commented on pull request #7190:
URL: https://github.com/apache/camel/pull/7190#issuecomment-1066669989
Once this has been merged, we should create an epic with multiple issue for all the components.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@camel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org