This is an automated email from the ASF dual-hosted git repository.
orpiske pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
commit cecaf8b78e2392695491a37832fca38120255cfb
Author: Otavio Rodolfo Piske <angusyo...@gmail.com>
AuthorDate: Wed Feb 21 10:40:39 2024 +0100
CAMEL-20410: documentation fixes for camel-jetty
- Fixed samples
- Fixed grammar and typos
- Fixed punctuation
- Added and/or fixed links
- Converted to use tabs
---
.../camel-jetty/src/main/docs/jetty-component.adoc | 92 +++++++++++-----------
1 file changed, 44 insertions(+), 48 deletions(-)
diff --git a/components/camel-jetty/src/main/docs/jetty-component.adoc
b/components/camel-jetty/src/main/docs/jetty-component.adoc
index 9a7a533ef40..c106e385f9e 100644
--- a/components/camel-jetty/src/main/docs/jetty-component.adoc
+++ b/components/camel-jetty/src/main/docs/jetty-component.adoc
@@ -20,11 +20,10 @@ behaves as a simple Web server.
*Stream*
-The `assert` call appears in this example, because the code is part of
-an unit test.Jetty is stream based, which means the input it receives is
+Jetty is stream-based, which means the input it receives is
submitted to Camel as a stream. That means you will only be able to read
-the content of the stream *once*. +
-If you find a situation where the message body appears to be empty or
+the content of the stream *once*.
+If you find a situation where the message body appears to be empty, or
you need to access the Exchange.HTTP_RESPONSE_CODE data multiple times
(e.g.: doing multicasting, or redelivery error handling), you should use
Stream caching or convert the message body to
@@ -67,17 +66,16 @@ include::partial$component-endpoint-options.adoc[]
Camel uses the same message headers as the xref:http-component.adoc[HTTP]
component.
-It also uses (Exchange.HTTP_CHUNKED,CamelHttpChunked)
-header to turn on or turn off the chunked encoding on the camel-jetty
-consumer.
+It also uses a header (`Exchange.HTTP_CHUNKED`, `CamelHttpChunked`) to turn
+on or turn off the chunked encoding on the camel-jetty consumer.
-Camel also populates *all* request.parameter and request.headers. For
-example, given a client request with the URL,
+Camel also populates *all* `request.parameter` and `request.headers`.
+For example, given a client request with the URL,
`\http://myserver/myserver?orderid=123`, the exchange will contain a
-header named `orderid` with the value 123.
+header named `orderid` with the value `123`.
-You can get the request.parameter from the
-message header not only from Get Method, but also other HTTP method.
+You can get the `request.parameter` from the
+message header not only from Get Method, but also other HTTP methods.
// component headers: START
include::partial$component-endpoint-headers.adoc[]
@@ -89,9 +87,11 @@ The Jetty component supports consumer endpoints.
== Consumer Example
-In this sample we define a route that exposes a HTTP service at
+In this sample we define a route that exposes an HTTP service at
`\http://localhost:8080/myapp/myservice`:
+[NOTE]
+====
*Usage of localhost*
When you specify `localhost` in a URL, Camel exposes the endpoint only
@@ -105,26 +105,22 @@ If you need to expose a Jetty endpoint on all network
interfaces, the
To listen across an entire URI prefix, see
xref:manual:faq:how-do-i-let-jetty-match-wildcards.adoc[How do I let Jetty
match wildcards].
+====
+
+== Servlets
If you actually want to expose routes by HTTP and already have a
Servlet, you should instead refer to the
xref:servlet-component.adoc[Servlet Transport].
-Our business logic is implemented in the `MyBookService` class, which
-accesses the HTTP request contents and then returns a response. +
- *Note:* The `assert` call appears in this example, because the code is
-part of an unit test.
-
-The following sample shows a content-based route that routes all
-requests containing the URI parameter, `one`, to the endpoint,
-`mock:one`, and all others to `mock:other`.
+== HTTP Request Parameters
So if a client sends the HTTP request, `\http://serverUri?one=hello`, the
Jetty component will copy the HTTP request parameter, `one` to the
exchange's `in.header`. We can then use the `simple` language to route
exchanges that contain this header to a specific endpoint and all others
to another. If we used a language more powerful than
-xref:languages:simple-language.adoc[Simple] (such as
xref:languages:ognl-language.adoc[OGNL])
+xref:languages:simple-language.adoc[Simple] (such as
xref:languages:ognl-language.adoc[OGNL]),
we could also test for the parameter value and do routing based on the
header value as well.
@@ -169,7 +165,7 @@ Using the JSSE Configuration Utility
The Jetty component supports SSL/TLS configuration
through the xref:manual::camel-configuration-utilities.adoc[Camel JSSE
Configuration Utility]. This utility greatly decreases the amount of
-component specific code you need to write and is configurable at the
+component-specific code you need to write and is configurable at the
endpoint and component levels. The following examples demonstrate how
to use the utility with the Jetty component.
@@ -249,7 +245,7 @@ Use of the global configuration in other Blueprint XML
files with route definiti
Configuring Jetty Directly
Jetty provides SSL support out of the box. To enable Jetty to run in SSL
-mode, simply format the URI with the `\https://` prefix---for example:
+mode, format the URI with the `\https://` prefix---for example:
[source,xml]
----
@@ -257,10 +253,10 @@ mode, simply format the URI with the `\https://`
prefix---for example:
----
Jetty also needs to know where to load your keystore from and what
-passwords to use in order to load the correct SSL certificate. Set the
+passwords to use to load the correct SSL certificate. Set the
following JVM System Properties:
-* `org.eclipse.jetty.ssl.keystore` specifies the location of the Java
+* `org.eclipse.jetty.ssl.keystore` specify the location of the Java
keystore file, which contains the Jetty server's own X.509 certificate
in a _key entry_. A key entry stores the X.509 certificate (effectively,
the _public key_) and also its associated private key.
@@ -276,7 +272,7 @@ For details of how to configure SSL on a Jetty endpoint,
read the
following documentation at the Jetty Site:
http://docs.codehaus.org/display/JETTY/How+to+configure+SSL[http://docs.codehaus.org/display/JETTY/How+to+configure+SSL]
-Some SSL properties aren't exposed directly by Camel, however Camel does
+Camel doesn't expose some SSL properties directly. However, Camel does
expose the underlying SslSocketConnector, which will allow you to set
properties like needClientAuth for mutual authentication requiring a
client certificate or wantClientAuth for mutual authentication where a
@@ -302,13 +298,13 @@ client doesn't need a certificate but can have one.
----
The value you use as keys in the above map is the port you configure
-Jetty to listen on.
+Jetty to listen to.
=== Configuring general SSL properties
-Instead of a per port number specific SSL socket connector (as shown
-above) you can now configure general properties which applies for all
-SSL socket connectors (which is not explicit configured as above with
+Instead of a per-port number specific SSL socket connector (as shown
+above), you can now configure general properties that apply for all
+SSL socket connectors (that are not explicitly configured as above with
the port number as entry).
[source,xml]
@@ -339,9 +335,9 @@ X509Certificate cert = (X509Certificate)
req.getAttribute("javax.servlet.request
=== Configuring general HTTP properties
-Instead of a per port number specific HTTP socket connector (as shown
-above) you can now configure general properties which applies for all
-HTTP socket connectors (which is not explicit configured as above with
+Instead of a per-port number specific HTTP socket connector (as shown
+above), you can now configure general properties that apply for all
+HTTP socket connectors (that are not explicitly configured as above with
the port number as entry).
[source,xml]
@@ -366,7 +362,7 @@ return the address of the Apache proxy.
Jetty has a forwarded property which takes the value from
X-Forwarded-For and places it in the HttpServletRequest remoteAddr
property. This property is not available directly through the endpoint
-configuration but it can be easily added using the socketConnectors
+configuration, but it can be easily added using the socketConnectors
property:
[source,xml]
@@ -497,7 +493,7 @@
from("jetty:http://0.0.0.0:9080/myservice?handlers=securityHandler";)
If you need more handlers, set the `handlers` option equal to a
comma-separated list of bean IDs.
-Blueprint based definition of basic authentication (based on Jetty 12):
+Blueprint-based definition of basic authentication (based on Jetty 12):
[source,xml]
----
@@ -545,36 +541,36 @@ Blueprint based definition of basic authentication (based
on Jetty 12):
...
----
-The roles.properties files contains
+The `roles.properties` files contain
----
username1=password1,rolename1
username2=password2,rolename1
----
-This file is located in the etc folder and will be reloaded when changed. The
endpoint
+This file is located in the `etc` folder and will be reloaded when changed.
The endpoint:
----
http://0.0.0.0/path
----
-is now secured with basic authentication, only username1 with password1 and
username2 with password2 are able to access the endpoint.
+It is now secured with basic authentication. Only `username1` with `password1`
and `username2` with `password2` are able to access the endpoint.
== How to return a custom HTTP 500 reply message
You may want to return a custom reply message when something goes wrong,
instead of the default reply message Camel xref:jetty-component.adoc[Jetty]
-replies with. +
- You could use a custom `HttpBinding` to be in control of the message
+replies to with.
+You could use a custom `HttpBinding` to be in control of the message
mapping, but often it may be easier to use Camel's
Exception Clause to construct the custom
-reply message. For example as show here, where we return
+reply message. For example, as show here, where we return
`Dude something went wrong` with HTTP error code 500:
-== Multi-part Form support
+== Multipart Form support
-The camel-jetty component supports multipart form post out of box.
-The submitted form-data are mapped into the message header. Camel-jetty
+The camel-jetty component supports multipart form post out of the box.
+The submitted form-data are mapped into the message header. Camel Jetty
creates an attachment for each uploaded file. The file name is mapped to
the name of the attachment. The content type is set as the content type
of the attachment file name. You can find the example here.
@@ -584,14 +580,14 @@ of the attachment file name. You can find the example
here.
The camel-jetty component supports the enabling of Jetty's JMX
capabilities at the component and endpoint level with the endpoint
configuration taking priority. Note that JMX must be enabled within the
-Camel context in order to enable JMX support in this component as the
+Camel context to enable JMX support in this component as the
component provides Jetty with a reference to the MBeanServer registered
with the Camel context. Because the camel-jetty component caches and
reuses Jetty resources for a given protocol/host/port pairing, this
configuration option will only be evaluated during the creation of the
first endpoint to use a protocol/host/port pairing. For example, given
two routes created from the following XML fragments, JMX support would
-remain enabled for all endpoints listening on "https://0.0.0.0";.
+remain enabled for all endpoints listening on `https://0.0.0.0`.
[source,xml]
----
@@ -607,7 +603,7 @@ The camel-jetty component also provides for direct
configuration of the
Jetty MBeanContainer. Jetty creates MBean names dynamically. If you are
running another instance of Jetty outside of the Camel context and
sharing the same MBeanServer between the instances, you can provide both
-instances with a reference to the same MBeanContainer in order to avoid
+instances with a reference to the same MBeanContainer to avoid
name collisions when registering Jetty MBeans.
