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 2021/08/09 05:10:37 UTC
[camel] 01/02: Polish and cleanup documentation
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 e2e5f1353fa4875793bfa39a5af5ffb73eeee4ac
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Mon Aug 9 07:01:11 2021 +0200
Polish and cleanup documentation
---
.../modules/ROOT/pages/book-getting-started.adoc | 63 +++++++---------------
docs/user-manual/modules/ROOT/pages/index.adoc | 24 +--------
.../ROOT/pages/what-are-the-dependencies.adoc | 54 +++----------------
3 files changed, 26 insertions(+), 115 deletions(-)
diff --git a/docs/user-manual/modules/ROOT/pages/book-getting-started.adoc b/docs/user-manual/modules/ROOT/pages/book-getting-started.adoc
index 2b5b355..ed553ff 100644
--- a/docs/user-manual/modules/ROOT/pages/book-getting-started.adoc
+++ b/docs/user-manual/modules/ROOT/pages/book-getting-started.adoc
@@ -44,9 +44,8 @@ EIP book as a reference.
The documentation is all under the Documentation category on the
right-side menu of the Camel website.
Camel-related books are also available, in particular
-the http://manning.com/ibsen[Camel in Action] book, presently serving as
-the Camel bible -- it has a
-http://www.manning.com/ibsen/chapter1sample.pdf[free Chapter One (pdf)],
+the https://www.manning.com/books/camel-in-action-second-edition[Camel in Action 2nd edition] book,
+presently serving as the Camel bible -- it has a free chapter one,
which is highly recommended to read to get more familiar with Camel.
[[BookGettingStarted-Ausefultipfornavigatingtheonlinedocumentation]]
@@ -59,7 +58,7 @@ left-hand side of the reddish bar contains the following links.
[source,java]
----
-Apache Camel > Documentation > Architecture > Languages
+Apache Camel > Documentation > Languages
----
As you might expect, clicking on "Apache Camel" takes you back to the
@@ -75,18 +74,12 @@ bookmarks to pages that you frequently reference can also save time.
== Online Javadoc documentation
The Apache Camel Javadoc documentation can be accessed from
-https://www.javadoc.io/doc/org.apache.camel/camel-api/current/index.html
-[javadoc.io]. It is important to note that the Javadoc documentation
-is spread over several _independent_ Javadoc hierarchies rather than
-being all contained in a single Javadoc hierarchy. In particular, there
-is one Javadoc hierarchy for the _core_ APIs of Camel, and a separate
-Javadoc hierarchy for each component technology supported by Camel. For
-example, if you will be using Camel with ActiveMQ and FTP then you need
-to look at the Javadoc hierarchies for the
-https://www.javadoc.io/doc/org.apache.camel/camel-api/current/index.html[core
-API] and
-https://www.javadoc.io/doc/org.apache.camel/camel-spring/current/index.html[Spring
-API].
+https://www.javadoc.io/doc/org.apache.camel/camel-api/current/index.html[javadoc.io].
+
+The Javadoc API that are the most relevant for Camel end users are in the following JARs:
+
+- https://www.javadoc.io/doc/org.apache.camel/camel-api/current/index.html[camel-core]
+- https://www.javadoc.io/doc/org.apache.camel/camel-support/latest/index.html[camel-support]
[[BookGettingStarted-ConceptsandterminologyfundamentaltoCamel]]
== Concepts and terminology fundamental to Camel
@@ -159,11 +152,11 @@ a server can read an incoming message from a mail server.
In a Camel-based application, you create (Camel wrappers around) some
endpoints and connect these endpoints with __routes__, which I will
-discuss later in xref:book-getting-started.adoc[Section 4.8 ("Routes,
+discuss later in xref:book-getting-started.adoc[Section ("Routes,
RouteBuilders and Java DSL")]. Camel defines a Java interface called
`Endpoint`. Each Camel-supported endpoint has a class that implements
this `Endpoint` interface. As I discussed in
-xref:book-getting-started.adoc[Section 3.3 ("Online Javadoc
+xref:book-getting-started.adoc[Section ("Online Javadoc
documentation")], Camel provides a separate Javadoc hierarchy for each
communications technology supported by Camel. Because of this, you will
find documentation on, say, the `JmsEndpoint` class in the
@@ -181,7 +174,7 @@ application executes the following steps:
1. Create a `CamelContext` object.
2. Add endpoints – and possibly components, which are discussed in
-Section 4.5 ("Components") – to the
+Section ("Components") – to the
`CamelContext` object.
3. Add routes to the `CamelContext` object to connect the endpoints.
4. Invoke the `start()` operation on the `CamelContext` object. This
@@ -217,12 +210,12 @@ other open-source projects, such as the `TransactionTemplate` and
The `CamelTemplate` class is a thin wrapper around the `CamelContext`
class. It has methods that send a `Message` or `Exchange` – both
-discussed in xref:book-getting-started.adoc[Section 4.6 ("Message and
+discussed in xref:book-getting-started.adoc[Section ("Message and
Exchange")]) – to an `Endpoint` – discussed in
-Section 4.1 ("Endpoint"). This provides
+Section ("Endpoint"). This provides
a way to enter messages into source endpoints, so that the messages will
move along routes – discussed in xref:book-getting-started.adoc[Section
-4.8 ("Routes, RouteBuilders and Java DSL")] – to destination endpoints.
+ ("Routes, RouteBuilders and Java DSL")] – to destination endpoints.
[[BookGettingStarted-url-uri-urn-iri]]
@@ -355,7 +348,7 @@ the "foo"" properties file on the CLASSPATH, get the value of the
`class` property from that properties file, and use reflection APIs to
create an instance of the specified class.
-As I said in Section 4.1 ("Endpoint"),
+As I said in Section ("Endpoint"),
Camel provides out-of-the-box support for numerous communication
technologies. The out-of-the-box support consists of classes that
implement the `Component` interface plus properties files that enable a
@@ -376,7 +369,7 @@ documentation and the Camel source code both claim the parameter is a
URI. In reality, the parameter is restricted to being a URL. This is
because when Camel extracts the component name from the parameter, it
looks for the first ":", which is a simplistic algorithm. To understand
-why, recall from xref:book-getting-started.adoc[Section 4.4 ("The
+why, recall from xref:book-getting-started.adoc[Section ("The
Meaning of URL, URI, URN and IRI")] that a URI can be a URL _or_ a URN.
Now consider the following calls to `getEndpoint`:
@@ -496,6 +489,7 @@ explain some of the constructs used in the example.
RouteBuilder builder = new RouteBuilder() {
public void configure() {
from("queue:a").filter(header("foo").isEqualTo("bar")).to("queue:b");
+
from("queue:c").choice()
.when(header("foo").isEqualTo("bar")).to("queue:d")
.when(header("foo").isEqualTo("cheese")).to("queue:e")
@@ -527,27 +521,6 @@ this way, these operations incrementally build up a `Route` object (with
a `RouteBuilder` wrapper around it) and add it to the `CamelContext`
object associated with the `RouteBuilder`.
-[[BookGettingStarted-CritiqueofJavaDSL]]
-==== Critique of Java DSL
-
-The online Camel documentation compares Java DSL favorably against the
-alternative of configuring routes and endpoints in a XML-based Spring
-configuration file. In particular, Java DSL is less verbose than its XML
-counterpart. In addition, many integrated development environments
-(IDEs) provide an auto-completion feature in their editors. This
-auto-completion feature works with Java DSL, thereby making it easier
-for developers to write Java DSL.
-
-However, there is another option that the Camel documentation neglects
-to consider: that of writing a parser that can process DSL stored in,
-say, an external file. Currently, Camel does not provide such a DSL
-parser, and I do not know if it is on the "to do" list of the Camel
-maintainers. I think that a DSL parser would offer a significant benefit
-over the current Java DSL. In particular, the DSL would have a syntactic
-definition that could be expressed in a relatively short BNF form. The
-effort required by a Camel user to learn how to use DSL by reading this
-BNF would almost certainly be significantly less than the effort
-currently required to study the API of the `RouterBuilder` classes.
[[BookGettingStarted-ContinueLearningaboutCamel]]
=== Continue Learning about Camel
diff --git a/docs/user-manual/modules/ROOT/pages/index.adoc b/docs/user-manual/modules/ROOT/pages/index.adoc
index 36a57b0..c6a8332 100644
--- a/docs/user-manual/modules/ROOT/pages/index.adoc
+++ b/docs/user-manual/modules/ROOT/pages/index.adoc
@@ -15,12 +15,10 @@ routing rules in your IDE, whether in a Java or XML editor.
For a deeper and better understanding of Apache Camel, an xref:faq:what-is-camel.adoc[Introduction] is provided.
-
== Summary
* <<Overview>>
* <<Documentation>>
-* <<Requirements>>
* <<Developers>>
== Overview
@@ -137,26 +135,6 @@ camel routes without them knowing
* xref:using-osgi-blueprint-with-camel.adoc[OSGi Blueprint XML DSL]
* xref:rest-dsl.adoc[Rest DSL]
-
-=== Components, Data Formats, Languages and Enterprise Integration Patterns
-
-Consult the xref:components::index.adoc[components] documentation.
-
-== Requirements
-
-=== Platform Requirements
-
-* Any platform that supports JDK 6 is required.
-
-=== JDK Requirements
-
-- Camel 2.x supports JDK 8
-- Camel 3.0 - 3.4 supports JDK 8 and 11
-- Camel 3.5 or higher supports JDK 8, 11 and 14
-Note: Camel 3.8 (when released), in case of JDK 8's usage, will need at least the JDK 8.0.272 with JFR included
-
== Developers
-* Developer Guide
-* https://github.com/apache/camel/[GitHub]
-* xref:building.adoc[Building]
+* xref:building.adoc[Building Camel from Source]
diff --git a/docs/user-manual/modules/ROOT/pages/what-are-the-dependencies.adoc b/docs/user-manual/modules/ROOT/pages/what-are-the-dependencies.adoc
index 0304456..1dd1796 100644
--- a/docs/user-manual/modules/ROOT/pages/what-are-the-dependencies.adoc
+++ b/docs/user-manual/modules/ROOT/pages/what-are-the-dependencies.adoc
@@ -1,57 +1,17 @@
= What are the dependencies?
-Camel 2.6 or older can run on JDK 1.5 or better. +
-Camel 2.7 onwards requires JDK 1.6 or JDK 1.7. +
-Camel 2.14 onwards requires JDK 1.7 or better. +
-Camel 2.18 onwards requires JDK 1.8.
+== Java support
-== What are the runtime jar dependencies?
-
-Apache Camel is designed to require a minimum number of dependencies for
-us so it is ideal for embedding into smart clients, message brokers, SOA
-frameworks and ESBs.
+- Camel 2 supports JDK 8
+- Camel 3 supports JDK 8 or 11
== Camel JAR Dependencies
-Camel core itself is lightweight and can run with a few .jars.
-
-== `camel-core` dependencies for Camel 2.0 or lower
-
-* `commons-logging-api.jar` - API for commons logging
-* JAXB 2.1.x - XML stuff - Is provided in the JDK core from Java 1.6
-* `activation.jar` - For Attachments support - Is provided in the JDK
-core from Java 1.6
-
-== `camel-core` dependencies for Camel 2.1 - 2.6
-
-* `commons-logging-api-1.1.jar` - API for commons logging
-* `commons-management-1.0.jar` - API for JMX
-* JAXB 2.1.x - XML stuff - Is provided in the JDK core from Java 1.6
-* `activation-1.1.jar` - For Attachments support - Is provided in the
-JDK core from Java 1.6
-
-== `camel-core` dependencies for Camel 2.7 - 2.8
-
-* `slf4j-api-1.5.11.jar` - API for slf4j logging
-* `commons-management-1.0.jar` - API for JMX
-
-== `camel-core` dependencies for Camel 2.9
-
-* `slf4j-api-1.6.1.jar` - API for slf4j logging
-
-== Optional Dependencies for JMX for Camel 1.x - 2.8
-
-* `spring-core.jar`, `spring-beans.jar`,
-`spring-context.jar`, `spring-aop.jar` - All 4 jars needed to use JMX
-with Camel (subject to change in the future).
-
-From *Camel 2.9*: the Spring JARs are no longer required for using JMX.
+Camel core itself is lightweight, and only requires the `sl4j-api` logging API jar.
-== Other Components
+== Components
-All the other xref:components::index.adoc[Components] have a range of 3rd party
-.jars they depend on. They are listed in the maven pom files which files
+All the xref:components::index.adoc[Components] have a range of 3rd party
+jars they depend on. They are listed in the maven pom files which files
they require.
-Other modules require other dependencies; such as camel-jms requires a
-JMS provider.