You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by da...@apache.org on 2018/05/02 13:56:32 UTC
[camel] 02/02: Polished docs
This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel.git
commit 3bb049711d24893fb1f5b0c814786f8af7792fba
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Wed May 2 15:56:15 2018 +0200
Polished docs
---
.../src/main/docs/jetty-component.adoc | 151 ++++++++++-----------
1 file changed, 73 insertions(+), 78 deletions(-)
diff --git a/components/camel-jetty9/src/main/docs/jetty-component.adoc b/components/camel-jetty9/src/main/docs/jetty-component.adoc
index 4ca422b..66971fc 100644
--- a/components/camel-jetty9/src/main/docs/jetty-component.adoc
+++ b/components/camel-jetty9/src/main/docs/jetty-component.adoc
@@ -27,26 +27,26 @@ Maven users will need to add the following dependency to their `pom.xml`
for this component:
[source,xml]
-------------------------------------------------------------
+----
<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-jetty</artifactId>
<version>x.x.x</version>
<!-- use the same version as your Camel core version -->
</dependency>
-------------------------------------------------------------
+----
-### URI format
+=== URI format
-[source,java]
-----------------------------------------------------
+[source,text]
+----
jetty:http://hostname[:port][/resourceUri][?options]
-----------------------------------------------------
+----
You can append query options to the URI in the following format,
`?option=value&option=value&...`
-### Options
+=== Options
@@ -190,7 +190,7 @@ with the following path and query parameters:
-### Message Headers
+=== Message Headers
Camel uses the same message headers as the <<http-component,HTTP>>
component.
@@ -206,13 +206,13 @@ header named `orderid` with the value 123.
Starting with Camel 2.2.0, you can get the request.parameter from the
message header not only from Get Method, but also other HTTP method.
-### Usage
+=== Usage
The Jetty component supports both consumer and producer endpoints.
Another option for producing to other HTTP endpoints, is to use the
<<http-component,HTTP Component>>
-### Producer Example
+=== Producer Example
WARNING: The producer is deprecated - do not use. We only recommend using jetty as consumer (eg from jetty)
@@ -222,21 +222,22 @@ existing HTTP endpoint.
in Java DSL
[source,java]
----------------------------------------------------------
-from("direct:start").to("jetty://http://www.google.com");
----------------------------------------------------------
+----
+from("direct:start")
+ .to("jetty://http://www.google.com");
+----
or in Spring XML
[source,xml]
----------------------------------------------
+----
<route>
<from uri="direct:start"/>
<to uri="jetty://http://www.google.com"/>
<route>
----------------------------------------------
+----
-### Consumer Example
+=== Consumer Example
In this sample we define a route that exposes a HTTP service at
`http://localhost:8080/myapp/myservice`:
@@ -279,40 +280,40 @@ to another. If we used a language more powerful than
<<ognl-language,OGNL>>) we could also test for the parameter value and do
routing based on the header value as well.
-### Session Support
+=== Session Support
The session support option, `sessionSupport`, can be used to enable a
`HttpSession` object and access the session object while processing the
exchange. For example, the following route enables sessions:
[source,xml]
----------------------------------------------------------------------------
+----
<route>
<from uri="jetty:http://0.0.0.0/myapp/myservice/?sessionSupport=true"/>
<processRef ref="myCode"/>
<route>
----------------------------------------------------------------------------
+----
The `myCode` Processor can be instantiated by a
Spring `bean` element:
[source,xml]
---------------------------------------------------------
+----
<bean id="myCode"class="com.mycompany.MyCodeProcessor"/>
---------------------------------------------------------
+----
Where the processor implementation can access the `HttpSession` as
follows:
[source,java]
---------------------------------------------------------------------------------------
+----
public void process(Exchange exchange) throws Exception {
HttpSession session = exchange.getIn(HttpMessage.class).getRequest().getSession();
...
}
---------------------------------------------------------------------------------------
+----
-### SSL Support (HTTPS)
+=== SSL Support (HTTPS)
[[Jetty-UsingtheJSSEConfigurationUtility]]
Using the JSSE Configuration Utility
@@ -328,7 +329,7 @@ to use the utility with the Jetty component.
Programmatic configuration of the component
[source,java]
------------------------------------------------------------------------------------------
+----
KeyStoreParameters ksp = new KeyStoreParameters();
ksp.setResource("/users/home/server/keystore.jks");
ksp.setPassword("keystorePassword");
@@ -342,13 +343,13 @@ scp.setKeyManagers(kmp);
JettyComponent jettyComponent = getContext().getComponent("jetty", JettyComponent.class);
jettyComponent.setSslContextParameters(scp);
------------------------------------------------------------------------------------------
+----
[[Jetty-SpringDSLbasedconfigurationofendpoint]]
Spring DSL based configuration of endpoint
[source,xml]
-----------------------------------------------------------------------------------------
+----
...
<camel:sslContextParameters
id="sslContextParameters">
@@ -362,7 +363,7 @@ Spring DSL based configuration of endpoint
...
<to uri="jetty:https://127.0.0.1/mail/?sslContextParameters=#sslContextParameters"/>
...
-----------------------------------------------------------------------------------------
+----
[[Jetty-ConfiguringJettyDirectly]]
Configuring Jetty Directly
@@ -371,9 +372,9 @@ 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:
[source,xml]
-----------------------------------------------------
+----
<from uri="jetty:https://0.0.0.0/myapp/myservice/"/>
-----------------------------------------------------
+----
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
@@ -420,7 +421,7 @@ difference between the various Camel versions:
*Up to Camel 2.2*
[source,xml]
------------------------------------------------------------------------------
+----
<bean id="jetty" class="org.apache.camel.component.jetty.JettyHttpComponent">
<property name="sslSocketConnectors">
<map>
@@ -436,12 +437,12 @@ difference between the various Camel versions:
</map>
</property>
</bean>
------------------------------------------------------------------------------
+----
*Camel 2.3, 2.4*
[source,xml]
-------------------------------------------------------------------------------
+----
<bean id="jetty" class="org.apache.camel.component.jetty.JettyHttpComponent">
<property name="sslSocketConnectors">
<map>
@@ -457,12 +458,12 @@ difference between the various Camel versions:
</map>
</property>
</bean>
-------------------------------------------------------------------------------
+----
*From Camel 2.5 we switch to use SslSelectChannelConnector *
[source,xml]
--------------------------------------------------------------------------------------
+----
<bean id="jetty" class="org.apache.camel.component.jetty.JettyHttpComponent">
<property name="sslSocketConnectors">
<map>
@@ -478,12 +479,12 @@ difference between the various Camel versions:
</map>
</property>
</bean>
--------------------------------------------------------------------------------------
+----
The value you use as keys in the above map is the port you configure
Jetty to listen on.
-#### Configuring general SSL properties
+==== Configuring general SSL properties
*Available as of Camel 2.5*
@@ -493,7 +494,7 @@ SSL socket connectors (which is not explicit configured as above with
the port number as entry).
[source,xml]
------------------------------------------------------------------------------
+----
<bean id="jetty" class="org.apache.camel.component.jetty.JettyHttpComponent">
<property name="sslSocketConnectorProperties">
<map>
@@ -505,20 +506,20 @@ the port number as entry).
</map>
</property>
</bean>
------------------------------------------------------------------------------
+----
-#### How to obtain reference to the X509Certificate
+==== How to obtain reference to the X509Certificate
Jetty stores a reference to the certificate in the HttpServletRequest
which you can access from code as follows:
[source,java]
---------------------------------------------------------------------------------------------------
+----
HttpServletRequest req = exchange.getIn().getBody(HttpServletRequest.class);
X509Certificate cert = (X509Certificate) req.getAttribute("javax.servlet.request.X509Certificate")
---------------------------------------------------------------------------------------------------
+----
-#### Configuring general HTTP properties
+==== Configuring general HTTP properties
*Available as of Camel 2.5*
@@ -528,7 +529,7 @@ HTTP socket connectors (which is not explicit configured as above with
the port number as entry).
[source,xml]
------------------------------------------------------------------------------
+----
<bean id="jetty" class="org.apache.camel.component.jetty.JettyHttpComponent">
<property name="socketConnectorProperties">
<map>
@@ -537,9 +538,9 @@ the port number as entry).
</map>
</property>
</bean>
------------------------------------------------------------------------------
+----
-#### Obtaining X-Forwarded-For header with HttpServletRequest.getRemoteAddr()
+==== Obtaining X-Forwarded-For header with HttpServletRequest.getRemoteAddr()
If the HTTP requests are handled by an Apache server and forwarded to
jetty with mod_proxy, the original client IP address is in the
@@ -553,7 +554,7 @@ configuration but it can be easily added using the socketConnectors
property:
[source,xml]
-----------------------------------------------------------------------------------
+----
<bean id="jetty" class="org.apache.camel.component.jetty.JettyHttpComponent">
<property name="socketConnectors">
<map>
@@ -565,13 +566,13 @@ property:
</map>
</property>
</bean>
-----------------------------------------------------------------------------------
+----
This is particularly useful when an existing Apache server handles TLS
connections for a domain and proxies them to application servers
internally.
-### Default behavior for returning HTTP status codes
+=== Default behavior for returning HTTP status codes
The default behavior of HTTP status codes is defined by the
`org.apache.camel.component.http.DefaultHttpBinding` class, which
@@ -584,7 +585,7 @@ returned, and the stacktrace is returned in the body. If you want to
specify which HTTP status code to return, set the code in the
`Exchange.HTTP_RESPONSE_CODE` header of the OUT message.
-### Customizing HttpBinding
+=== Customizing HttpBinding
By default, Camel uses the
`org.apache.camel.component.http.DefaultHttpBinding` to handle how a
@@ -599,25 +600,28 @@ We can then create an instance of our binding and register it in the
Spring registry as follows:
[source,xml]
----------------------------------------------------------
+----
<bean id="mybinding"class="com.mycompany.MyHttpBinding"/>
----------------------------------------------------------
+----
And then we can reference this binding when we define the route:
[source,xml]
----------------------------------------------------------------------------------------------------------------------------
-<route><from uri="jetty:http://0.0.0.0:8080/myapp/myservice?httpBindingRef=mybinding"/><to uri="bean:doSomething"/></route>
----------------------------------------------------------------------------------------------------------------------------
+----
+<route>
+ <from uri="jetty:http://0.0.0.0:8080/myapp/myservice?httpBindingRef=mybinding"/>
+ <to uri="bean:doSomething"/>
+</route>
+----
-### Jetty handlers and security configuration
+=== Jetty handlers and security configuration
You can configure a list of Jetty handlers on the endpoint, which can be
useful for enabling advanced Jetty security features. These handlers are
configured in Spring XML as follows:
[source,xml]
-----------------------------------------------------------------------------------
+----
<-- Jetty Security handling -->
<bean id="userRealm" class="org.mortbay.jetty.plus.jaas.JAASUserRealm">
<property name="name" value="tracker-users"/>
@@ -639,13 +643,13 @@ configured in Spring XML as follows:
<property name="userRealm" ref="userRealm"/>
<property name="constraintMappings" ref="constraintMapping"/>
</bean>
-----------------------------------------------------------------------------------
+----
*And from Camel 2.3 onwards* you can configure a list of Jetty handlers
as follows:
[source,xml]
-----------------------------------------------------------------------------------------
+----
<-- Jetty Security handling -->
<bean id="constraint" class="org.eclipse.jetty.http.security.Constraint">
<property name="name" value="BASIC"/>
@@ -668,19 +672,19 @@ as follows:
</list>
</property>
</bean>
-----------------------------------------------------------------------------------------
+----
You can then define the endpoint as:
[source,java]
---------------------------------------------------------------------
+----
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.
-### How to return a custom HTTP 500 reply message
+=== 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 <<jetty-component,Jetty>>
@@ -691,7 +695,7 @@ Exception Clause to construct the custom
reply message. For example as show here, where we return
`Dude something went wrong` with HTTP error code 500:
-### Multi-part Form support
+=== Multi-part Form support
From Camel 2.3.0, camel-jetty support to multipart form post out of box.
The submitted form-data are mapped into the message header. Camel-jetty
@@ -703,7 +707,7 @@ of the attachment file name. You can find the example here.
earlier versions you receive the temporary file name for the attachment
instead*
-### Jetty JMX support
+=== Jetty JMX support
From Camel 2.3.0, camel-jetty supports the enabling of Jetty's JMX
capabilities at the component and endpoint level with the endpoint
@@ -718,14 +722,14 @@ two routes created from the following XML fragments, JMX support would
remain enabled for all endpoints listening on "https://0.0.0.0".
[source,xml]
---------------------------------------------------------------------
+----
<from uri="jetty:https://0.0.0.0/myapp/myservice1/?enableJmx=true"/>
---------------------------------------------------------------------
+----
[source,xml]
----------------------------------------------------------------------
+----
<from uri="jetty:https://0.0.0.0/myapp/myservice2/?enableJmx=false"/>
----------------------------------------------------------------------
+----
The camel-jetty component also provides for direct configuration of the
Jetty MBeanContainer. Jetty creates MBean names dynamically. If you are
@@ -733,12 +737,3 @@ 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
name collisions when registering Jetty MBeans.
-
-### See Also
-
-* Configuring Camel
-* Component
-* Endpoint
-* Getting Started
-
-* <<http-component,HTTP>>
--
To stop receiving notification emails like this one, please contact
davsclaus@apache.org.