This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
commit c72310ee3ec573ed24553007ba7be792e3a543c2
Author: Claus Ibsen <claus.ib...@gmail.com>
AuthorDate: Thu Aug 12 15:27:48 2021 +0200
Polish and cleanup documentation
---
.../modules/ROOT/pages/scheduledroutepolicy.adoc | 30 +++---
docs/user-manual/modules/ROOT/pages/security.adoc | 67 +++++-------
.../modules/ROOT/pages/service-registry.adoc | 107 ++++++-------------
.../modules/ROOT/pages/servlet-tomcat-example.adoc | 115 ---------------------
4 files changed, 74 insertions(+), 245 deletions(-)
diff --git a/docs/user-manual/modules/ROOT/pages/scheduledroutepolicy.adoc
b/docs/user-manual/modules/ROOT/pages/scheduledroutepolicy.adoc
index 65ddd1c..b2fb688 100644
--- a/docs/user-manual/modules/ROOT/pages/scheduledroutepolicy.adoc
+++ b/docs/user-manual/modules/ROOT/pages/scheduledroutepolicy.adoc
@@ -1,30 +1,34 @@
= ScheduledRoutePolicy
-A scheduled route policy
+A scheduled xref:route-policy.adoc[Route Policy]
`org.apache.camel.routepolicy.quartz.ScheduledRoutePolicy` is an
-extensible abstract policy that is used to provide camel route
+extensible abstract policy that is used to provide Camel routes
scheduling capabilities at runtime.
-Scheduling of routes typically involves the following capabilities
+Scheduling of routes typically involves the following capabilities:
-* Route activation - Starting a route a given start time if the route is
+* _Route activation_ - Starting a route a given start time if the route is
in a stopped state awaiting activation.
-* Route de-activation - Shutting down an otherwise active and started
+* _Route de-activation_ - Shutting down an otherwise active and started
route at a given time.
-* Route suspension - Simply de-activating the route consumer endpoint
-URI declared on the from(...) section of the route from listening on a
+* _Route suspension_ - Simply de-activating the route consumer endpoint
+URI declared on the `from(...)` section of the route from listening on a
given port. The route is still considered as started, however, clients
will not be able to send requests along the route.
-* Route resumption - Resuming the listener on a formerly suspended route
+* _Route resumption_ - Resuming the listener on a formerly suspended route
consumer endpoint URI. This route is ready to accept requests following
route resumption and client requests will be accepted by the route
consumer to be forwarded along the route.
-Camel offers 2 such concrete policies that offer scheduled route policy
-support
+Camel offers two such concrete policies that offer scheduled route policy
+support:
* xref:simplescheduledroutepolicy.adoc[SimpleScheduledRoutePolicy] - An
-ability to offer route scheduling services using a Simple Quartz Trigger
+ability to offer route scheduling services using a Simple
xref:components::quartz-component.adoc[Quartz] trigger.
* xref:cronscheduledroutepolicy.adoc[CronScheduledRoutePolicy] - An
-ability to offer route scheduling services using a Cron based Quartz
-Trigger
+ability to offer route scheduling services using a Cron based
xref:components::quartz-component.adoc[Quartz]
+trigger.
+
+== More Information
+
+See xref:route-policy.adoc[Route Policy]
\ No newline at end of file
diff --git a/docs/user-manual/modules/ROOT/pages/security.adoc
b/docs/user-manual/modules/ROOT/pages/security.adoc
index bb4fd05..ec29d4f 100644
--- a/docs/user-manual/modules/ROOT/pages/security.adoc
+++ b/docs/user-manual/modules/ROOT/pages/security.adoc
@@ -2,43 +2,45 @@
= Security
Camel offers several forms & levels of security capabilities that can be
-utilized on camel routes. These various forms of security may be used in
+utilized on Camel routes. These various forms of security may be used in
conjunction with each other or separately.
-The broad categories offered are
+The broad categories offered are:
-* Route Security - Authentication and Authorization services to proceed
+* _Route Security_ - Authentication and Authorization services to proceed
on a route or route segment
-* Payload Security - Data Formats that offer encryption/decryption
+* _Payload Security_ - Data Formats that offer encryption/decryption
services at the payload level
-* Endpoint Security - Security offered by components that can be
+* _Endpoint Security_ - Security offered by components that can be
utilized by endpointUri associated with the component
-* Configuration Security - Security offered by encrypting sensitive
+* _Configuration Security_ - Security offered by encrypting sensitive
information from configuration files
-[[Security-RouteSecurity-AuthenticationandAuthorizationServices]]
-== Route Security - Authentication and Authorization Services
+Camel offers the xref:camel-configuration-utilities.adoc[JSSE Utility]
+for configuring SSL/TLS related aspects of a number of Camel components.
+
+== Route Security
-Camel offers Policy driven security capabilities that may be wired into
-routes or route segments. A Policy in Camel utilizes a strategy pattern
-for applying interceptors on Camel Processors. It offering the ability
-to apply cross-cutting concerns (for example. security, transactions
-etc) on sections/segments of a camel route.
+Authentication and Authorization Services
-The components offering authentication and authorization Services
-utilizing Route Policies are
+Camel offers xref:route-policy.adoc[Route Policy] driven security capabilities
that may be wired into
+routes or route segments. A route policy in Camel utilizes a strategy pattern
+for applying interceptors on Camel Processors. It's offering the ability
+to apply cross-cutting concerns (for example. security, transactions etc) of a
Camel route.
+
+The components offering authentication and authorization services
+utilizing xref:route-policy.adoc[Route Policy] are:
* xref:components:others:shiro.adoc[Shiro Security]
* xref:components:others:spring-security.adoc[Spring Security]
-[[Security-PayloadSecurity-DataFormatsandProducersConsumersofferingencryptiondecryptionservices]]
-== Payload Security - Data Formats and Producers/Consumers offering
encryption/decryption services
+== Payload Security
Camel offers encryption/decryption services to secure payloads or
selectively apply encryption/decryption capabilities on
portions/sections of a payload.
-These capabilites are offered by the following components
+These capabilities are offered by the following components:
* xref:components:dataformats:secureXML-dataformat.adoc[XMLSecurity
DataFormat] (XML
Encryption support)
@@ -46,42 +48,21 @@ Encryption support)
* xref:components::crypto-component.adoc[Crypto component] (Signature
support)
-[[Security-EndpointSecurity]]
== Endpoint Security
-Some components in camel offer an ability to secure their endpoints
+Some components in Camel offer an ability to secure their endpoints
(using interceptors etc) and therefore ensure that they offer the
ability to secure payloads as well as provide
authentication/authorization capabilities at endpoints created using the
components.
-Some such components are
-
-* xref:components::jetty-component.adoc[Jetty] - HTTP Basic Authentication
support * SSL
-support
-* xref:components::cxf-component.adoc[CXF] - HTTP Basic Authentication &
WS-Security support
-using the CXF Bus driven interceptor chain
-* xref:components::spring-ws-component.adoc[Spring Web Services] - HTTP Basic
-Authentication & WS-Security support
-* xref:components::netty-component.adoc[Netty] - SSL support
-* xref:components::mina-component.adoc[MINA] - SSL support
-* xref:components::cometd-component.adoc[Cometd] - SSL support
-* xref:components::jms-component.adoc[JMS] - JAAS and SSL based security for
client <-->
-broker communication
-
-[[Security-ConfigurationSecurity]]
== Configuration Security
-*Since Camel 2.5*
-
Camel offers the xref:components::properties-component.adoc[Properties]
component to
externalize configuration values to properties files. Those values could
-contain sensitive information such as usernames and passwords. Those
-values can be encrypted and automatic decrypted by Camel.
+contain sensitive information such as usernames and passwords.
-* xref:components:others:jasypt.adoc[Jasypt]
+Those values can be encrypted and automatic decrypted by Camel using:
-*Since Camel 2.8*
+* xref:components:others:jasypt.adoc[Jasypt]
-Camel offers the xref:camel-configuration-utilities.adoc[JSSE Utility]
-for configuring SSL/TLS related aspects of a number of Camel components.
diff --git a/docs/user-manual/modules/ROOT/pages/service-registry.adoc
b/docs/user-manual/modules/ROOT/pages/service-registry.adoc
index 4eddd78..7e8362f 100644
--- a/docs/user-manual/modules/ROOT/pages/service-registry.adoc
+++ b/docs/user-manual/modules/ROOT/pages/service-registry.adoc
@@ -1,18 +1,14 @@
[[ServiceRegistry-ServiceRegistry]]
= Service Registry
-*Since Camel 2.22*
-
-[WARNING]
-====
-*Experimental feature*
-====
-
-Service registration is a key part of service discovery which Camel leverages
through the _Service Call EIP_ and as of v 2.22.0 Camel provides an
experimental support to ease the process to expose routes in a cloud
environment and consume them with minimal configuration.
+Service registration is a key part of service discovery which Camel leverages
through
+the _Service Call EIP_ and support to ease the process to expose routes in a
+cloud environment and consume them with minimal configuration.
== Service Registry Set-Up
-A _Service Registry_ is just like any other camel service so set it up you
only need to register your implementations to the camel context:
+A `ServiceRegistry` is just like any other camel service so set it up you only
need
+to register your implementations to the `CamelContext`:
[source,java]
----
@@ -28,40 +24,39 @@ Out of the box camel provides the following implementations:
|====
|Type |Module | Class
|consul |camel-consul |
org.apache.camel.component.consul.cloud.ConsulServiceRegistry
-|zookeeper |camel-zookeeper |
org.apache.camel.component.zookeeper.cloud.ZooKeeperServiceRegistry
|spring-cloud |camel-spring-cloud |
org.apache.camel.component.spring.cloud.CamelSpringCloudServiceRegistry
+|zookeeper |camel-zookeeper |
org.apache.camel.component.zookeeper.cloud.ZooKeeperServiceRegistry
|====
-On Spring/Blueprint all the _Service Registry_ instances are automatically
added to the camel context.
-
== Service Registry Usage
The _Service Registry SPI_ is leveraged by the following new implementations:
-- *ServiceRegistryRoutePolicy*
-+
-This is an implementation of a RoutePolicy that register/deregister routes to
a given _Service Registry_ according to route's life-cycle
-+
+=== ServiceRegistryRoutePolicy
+
+This is an implementation of a xref:route-policy.adoc[Route Policy] that
register/deregister routes
+to a given `ServiceRegistry` according to route's life-cycle:
+
[source,java]
----
-fiRoutePolicy policy = new ServiceRegistrationRoutePolicy()
+RoutePolicy policy = new ServiceRegistrationRoutePolicy()
// bind the policy to one or more routes
from("undertow:http://0.0.0.0:8080";)
.routePolicy(policy)
.log("Route ${routeId} has been invoked");
----
-+
-To apply the same policy to all the routes a dedicated _RoutePolicyFactory_
can be used:
-+
+
+To apply the same policy to all the routes a dedicated `RoutePolicyFactory`
can be used:
+
[source,java]
----
// add the service registry route policy factory to context
context.addRoutePolicyFactory(new ServiceRegistrationRoutePolicyFactory()));
----
-+
+
To configure how the service is exposed you can add route specific properties
like:
-+
+
[source,java]
----
// bind the policy to one or more routes
@@ -72,9 +67,9 @@ from("undertow:http://0.0.0.0:8080";)
.routeProperty(ServiceDefinition.SERVICE_META_PORT, "8080")
.log("Route ${routeId} has been invoked");
----
-+
-Service name and service id can also be provided by _routeId_ and _routeGroup_
-+
+
+Service name and service id can also be provided by _routeId_ and _routeGroup_:
+
[source,java]
----
// bind the policy to one or more routes
@@ -85,28 +80,24 @@ from("undertow:http://0.0.0.0:8080";)
.routeProperty(ServiceDefinition.SERVICE_META_PORT, "8080")
.log("Route ${routeId} has been invoked");
----
-+
-[TIP]
-====
-Some component such has camel-undertow and those based on camel-http-common
implement _DiscoverableService_ and they can automatically provide the metadata
needed for service registration.
-====
-+
-[TIP]
-====
+
Any property prefixed with _service._ is automatically added to the service's
metadata.
-====
-- *Service Component*
-+
-The service component is similar to a _ServiceRegistrationRoutePolicyFactory_
but let to "tags" routes that need to be registered to the _Service Registry_
by prefixing the related endpoints according to the service component syntax:
-+
-[source]
+TIP: Some component such has camel-undertow and those based on
camel-http-common implement _DiscoverableService_ and they can automatically
provide the metadata needed for service registration.
+
+=== Service Component
+
+The xref:components::service-component.adoc[Service] component is similar to a
`ServiceRegistrationRoutePolicyFactory`
+but is capable of tagging routes that need to be registered to the
`ServiceRegistry`
+by prefixing the related endpoints with `service:name` according to the
following syntax:
+
+[source,text]
----
service:serviceName:delegateUri[?options]
----
-+
-Example:
-+
+
+Let's explain this with an example:
+
[source,java]
----
from("service:my-service:undertow:http://0.0.0.0:8080";)
@@ -121,37 +112,5 @@
from("service:my-service:undertow:http://0.0.0.0:8080?service.id=my-service-id";)
.log("Route ${routeId} has been invoked");
----
-[TIP]
-====
Any option prefixed with _service._ is automatically added to the service's
metadata.
-====
-
-== Spring Cloud
-
-The _Service Registry_ binding for _Spring Cloud_ let you register your route
with minimal code changes a a _Service Registry_ is automatically added to the
Camel Context as soon as the camel-spring-cloud dependency is added to the
classpath.
-
-[WARNING]
-====
-As the spring-cloud backend has some limitations you need to include also some
additional dependencies according to the selected backend. At the moment, the
following implementations are provided:
-
-[options="header"]
-|====
-|Spring Cloud |Camel
-|spring-cloud-consul |camel-spring-cloud-consul
-|spring-cloud-zookeeper |camel-spring-cloud-zookeeper
-|====
-====
-
-Assuming the consul backend has been chosen the following code will configure
and activate the _Service Registry_:
-
-[source,properties]
-----
-# Spring cloud
-spring.cloud.consul.enabled = true
-spring.cloud.consul.discovery.enabled = true
-
-# Camel Cloud
-camel.cloud.service-registry.service-host = localhost
-----
-To register a route, the easy way is then to use the _service_ component as
described above.
diff --git a/docs/user-manual/modules/ROOT/pages/servlet-tomcat-example.adoc
b/docs/user-manual/modules/ROOT/pages/servlet-tomcat-example.adoc
deleted file mode 100644
index e3e40b4..0000000
--- a/docs/user-manual/modules/ROOT/pages/servlet-tomcat-example.adoc
+++ /dev/null
@@ -1,115 +0,0 @@
-[[ServletTomcatExample-ServletTomcatExample]]
-= Servlet Tomcat Example
-
-*Since Camel 2.7*
-
-This example is located in the
-https://github.com/apache/camel-examples/tree/master/examples/camel-example-servlet-tomcat[examples/camel-example-servlet-tomcat]
-directory of the https://github.com/apache/camel-examples[Camel Examples
Repository].
-There is a `README.adoc` file with instructions how to run it.
-
-If you use Maven then you can easily package the example from the command line:
-
-----
-mvn package
-----
-
-[[ServletTomcatExample-About]]
-== About
-
-This example demonstrates how you can use
xref:components::servlet-component.adoc[Servlet] to expose
-a http service in a Camel route.
-
-[[ServletTomcatExample-Implementation]]
-== Implementation
-
-In the `web.xml` file in the `src/main/webapp/WEB-INF` folder the
`CamelServlet`
-is defined. This is mandatory to do when using the
xref:components::servlet-component.adoc[Servlet]
-component.
-
-[source,xml]
-----
-<web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee";
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
- xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd";>
-
- <display-name>My Web Application</display-name>
-
- <!-- location of spring xml files -->
- <context-param>
- <param-name>contextConfigLocation</param-name>
- <param-value>classpath:camel-config.xml</param-value>
- </context-param>
-
- <!-- the listener that kick-starts Spring -->
- <listener>
-
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
- </listener>
-
- <!-- Camel servlet -->
- <servlet>
- <servlet-name>CamelServlet</servlet-name>
-
<servlet-class>org.apache.camel.component.servlet.CamelHttpTransportServlet</servlet-class>
- <load-on-startup>1</load-on-startup>
- </servlet>
-
- <!-- Camel servlet mapping -->
- <servlet-mapping>
- <servlet-name>CamelServlet</servlet-name>
- <url-pattern>/camel/*</url-pattern>
- </servlet-mapping>
-
-</web-app>
-----
-
-The route is a simple xref:{eip-vc}:eips:content-based-router-eip.adoc[Content
Based Router] defined
-in the DSL XML as shown:
-
-[source,xml]
-----
-<beans xmlns="http://www.springframework.org/schema/beans";
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
- xmlns:camel="http://camel.apache.org/schema/spring";
- xsi:schemaLocation="
- http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
- http://camel.apache.org/schema/spring
http://camel.apache.org/schema/spring/camel-spring.xsd";>
-
- <camelContext xmlns="http://camel.apache.org/schema/spring";>
-
- <route id="helloRoute">
- <!-- incoming requests from the servlet is routed -->
- <from uri="servlet:hello"/>
- <choice>
- <when>
- <!-- is there a header with the key name? -->
- <header>name</header>
- <!-- yes so return back a message to the user -->
- <transform>
- <simple>Hi I am ${sysenv.HOSTNAME}. Hello ${header.name} how are
you today?</simple>
- </transform>
- </when>
- <otherwise>
- <!-- if no name parameter then output a syntax to the user -->
- <transform>
- <constant>Add a name parameter to uri, eg ?name=foo</constant>
- </transform>
- </otherwise>
- </choice>
- </route>
-
- </camelContext>
-
-</beans>
-----
-
-[[ServletTomcatExample-Runningtheexample]]
-== Running the example
-
-This example runs in Apache Tomcat, so you will have to package the .war file
and copy
-it to the webapp folder of Tomcat, which is the hot deploy folder.
-
-There is a main page at
-http://localhost:8080/camel-example-servlet-tomcat which has more instructions.
-You can then use a web browser and send a request to the
-http://localhost:8080/camel-example-servlet-tomcat/camel/hello URL.
-
