You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by or...@apache.org on 2022/12/02 09:24:29 UTC
[camel] branch main updated: CAMEL-18786: skeleton for reorganizing the Camel Core documentation
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
The following commit(s) were added to refs/heads/main by this push:
new 3cb23b3f01a CAMEL-18786: skeleton for reorganizing the Camel Core documentation
3cb23b3f01a is described below
commit 3cb23b3f01a6291aac1c0272c3a11abbb434da1e
Author: Otavio Rodolfo Piske <an...@gmail.com>
AuthorDate: Wed Nov 30 17:54:42 2022 +0100
CAMEL-18786: skeleton for reorganizing the Camel Core documentation
These changes introduce a new documentation module with the intention of creating a project page for Camel Core. Within that page, the documentation for the project is categorized and separated according to the audience.
---
docs/main/antora.yml | 22 +
.../modules/ROOT/attachments/contents-table.html | 97 ++++
docs/main/modules/ROOT/nav.adoc | 1 +
docs/main/modules/ROOT/pages/index.adoc | 10 +
.../modules/advanced-camel-core-guides/nav.adoc | 0
.../advanced-camel-core-guides/pages/index.adoc | 43 ++
docs/main/modules/getting-started/nav.adoc | 0
.../modules/getting-started/pages/index.adoc} | 16 +-
docs/main/modules/reference/nav.adoc | 0
docs/main/modules/reference/pages/index.adoc | 12 +
docs/main/modules/working-with-camel-core/nav.adoc | 0
.../working-with-camel-core/pages/index.adoc | 71 +++
.../modules/ROOT/pages/book-getting-started.adoc | 526 +--------------------
13 files changed, 266 insertions(+), 532 deletions(-)
diff --git a/docs/main/antora.yml b/docs/main/antora.yml
new file mode 100644
index 00000000000..efaa1a14fd4
--- /dev/null
+++ b/docs/main/antora.yml
@@ -0,0 +1,22 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+name: camel-core
+title: Camel Core
+version: ~
+nav:
+- modules/ROOT/nav.adoc
diff --git a/docs/main/modules/ROOT/attachments/contents-table.html b/docs/main/modules/ROOT/attachments/contents-table.html
new file mode 100644
index 00000000000..d5e07710d5a
--- /dev/null
+++ b/docs/main/modules/ROOT/attachments/contents-table.html
@@ -0,0 +1,97 @@
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one or more
+ ~ contributor license agreements. See the NOTICE file distributed with
+ ~ this work for additional information regarding copyright ownership.
+ ~ The ASF licenses this file to You under the Apache License, Version 2.0
+ ~ (the "License"); you may not use this file except in compliance with
+ ~ the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing, software
+ ~ distributed under the License is distributed on an "AS IS" BASIS,
+ ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ~ See the License for the specific language governing permissions and
+ ~ limitations under the License.
+ -->
+
+<style>
+.column {
+ float: left;
+ width: 33.33%;
+}
+
+.row:after {
+ content: "";
+ display: table;
+ clear: both;
+}
+
+</style>
+
+<div class="row">
+ <div class="column">
+ <h2>Get started</h2>
+ <p>
+ Get started with the Camel Core project. Discover if it is the right project for your needs. <b>Learn basic concepts</b> of integrating systems, the <b>fundamentals</b> of the Camel Core project and <b>create your first project</b>.
+ </p>
+ <a class="button dark" href="getting-started">Learn More</a>
+ </div>
+ <div class="column">
+ <h2>Working with Camel Core</h2>
+ <p>
+ Get started with the Camel Core project. Discover if it is the right project for your needs. <b>Learn basic concepts</b> of integrating systems, the <b>fundamentals</b> of the Camel Core project and <b>create your first project</b>.
+ </p>
+ <a class="button dark" href="working-with-camel-core">Learn More</a>
+ </div>
+ <div class="column">
+ <h2>Advanced Camel Core Guides</h2>
+ <p>
+ Learn about additional ways to <b>customize</b> your integrations. Explore <b>alternatives to consume and produce</b> data and to <b>write and define</b> routes.
+ </p>
+
+ <a class="button dark" href="advanced-camel-core-guides">Learn More</a>
+ </div>
+</div>
+<div class="row">
+ <div class="column">
+ <h2>Reference Documentation</h2>
+ <p>
+ The comprehensive <b>reference documentation</b> for all 300+ Camel <bcomponents, enterprise integration patterns (EIPs)</b> and links to the <b>JavaDoc</b> documentation.
+ </p>
+ <a class="button dark" href="reference">Learn More</a>
+ </div>
+ <div class="column">
+ <h2>Migration and Upgrade</h2>
+ <p>
+ The <b>migration</b> and <b>upgrade</b> guides you need to follow to keep your Camel Core integrations <b>up-to-date</b>.
+ </p>
+ <a class="button dark" href="../manual/camel-3x-upgrade-guide.html">Learn More</a>
+ </div>
+ <div class="column">
+ <h2>Support</h2>
+ <p>
+ Find out how to <b>obtain help</b> using the Camel Core project, how to <b>report problems</b> and where to find our our community on the web.
+ </p>
+ <a class="button dark" href="../community/support">Learn More</a>
+ </div>
+</div>
+<div class="row">
+ <div class="column">
+ <h2>Contribute</h2>
+ <p>
+ Everything you need to know to make a <b>contribution</b> to the Camel Core project. Learn how to <b>build, test, document</b> and improve the project.
+ </p>
+ <a class="button dark" href="../community/contributing">Learn More</a>
+ </div>
+ <div class="column">
+ <h2>Use Cases and Success Stories</h2>
+ <p>
+ Discover <b>who is using</b> Apache Camel and read about <b>success stories</b> of developers and organizations using Camel.
+ </p>
+ <a class="button dark" href="../community/user-stories">Learn More</a>
+ </div>
+ <div class="column">
+
+ </div>
+</div>
diff --git a/docs/main/modules/ROOT/nav.adoc b/docs/main/modules/ROOT/nav.adoc
new file mode 100644
index 00000000000..042e3ed22e6
--- /dev/null
+++ b/docs/main/modules/ROOT/nav.adoc
@@ -0,0 +1 @@
+* xref:index.adoc[Index]
diff --git a/docs/main/modules/ROOT/pages/index.adoc b/docs/main/modules/ROOT/pages/index.adoc
new file mode 100644
index 00000000000..c8110f6313e
--- /dev/null
+++ b/docs/main/modules/ROOT/pages/index.adoc
@@ -0,0 +1,10 @@
+= Apache Camel Core
+
+Apache Camel is an Open Source integration framework that empowers you to quickly and easily integrate various systems consuming or producing data.
+
+The Apache Camel Core is the foundation for all other projects. Ideal for experienced Java developers or architects willing to innovate and build upon a lower level integration framework.
+
+++++
+include::attachment$contents-table.html[]
+++++
+
diff --git a/docs/main/modules/advanced-camel-core-guides/nav.adoc b/docs/main/modules/advanced-camel-core-guides/nav.adoc
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/docs/main/modules/advanced-camel-core-guides/pages/index.adoc b/docs/main/modules/advanced-camel-core-guides/pages/index.adoc
new file mode 100644
index 00000000000..c47b2f82908
--- /dev/null
+++ b/docs/main/modules/advanced-camel-core-guides/pages/index.adoc
@@ -0,0 +1,43 @@
+= Advanced Camel Core Guides
+
+In these page you can find guides and documents that can help you to discover how to observe, scale and debug integrations. You can Learn about more advanced features of Camel Core and how you can build upon those for creating highly customized integrations for all projects and products.
+
+* xref:manual::camel-component-maven-plugin.adoc[Camel Maven Component]
+* xref:manual::batch-consumer.adoc[Batch Consumer]
+* xref:manual::graceful-shutdown.adoc[Graceful Shutdown]
+* xref:manual::backlog-debugger.adoc[Backlog Debugger]
+* xref:manual::backlog-tracer.adoc[Backlog Tracer]
+* xref:manual::clustering.adoc[Clustering]
+* xref:manual::injector.adoc[Injector]
+* xref:manual::jmx.adoc[JMX]
+* xref:manual::route-controller.adoc[Route Controller]
+* xref:manual::route-policy.adoc[Route Policy]
+* xref:manual::cronscheduledroutepolicy.adoc[Cron Scheduled Route Policy]
+* xref:manual::scheduledroutepolicy.adoc[Scheduled Route Policy]
+* xref:manual::simplescheduledroutepolicy.adoc[Simple Scheduled Route Policy]
+* xref:manual::threading-model.adoc[Threading Model]
+* xref:manual::context-reload.adoc[Context Reload]
+* xref:manual::route-reload.adoc[Route Reload]
+* xref:manual::pluggable-class-resolvers.adoc[Pluggable Class Resolvers]
+* xref:manual::transformer.adoc[Transformer]
+* xref:manual::tracer.adoc[Tracer]
+* xref:manual::type-converter.adoc[Type Converter]
+* xref:manual::uuidgenerator.adoc[UUID Generator]
+* xref:manual::debugger.adoc[Debugger]
+* xref:manual::health-check.adoc[Health Check]
+* xref:manual::writing-components.adoc[Writing Custom Camel Components]
+* xref:manual::endpoint-annotations.adoc[Endpoint Annotations]
+* xref:manual::http-session-handling.adoc[HTTP Session Handling]
+* xref:manual::browsable-endpoint.adoc[Browsable Endpoint]
+* xref:manual::camel-configuration-utilities.adoc[Configuration Utilities]
+
+If you are looking at contributing to Apache Camel, these guides may also help:
+
+* xref:manual::test-infra.adoc[Test Infra]
+* xref:manual::notify-builder.adoc[Notify builder]
+* xref:manual::building.adoc[Building Camel From Source]
+* xref:manual::improving-the-documentation.adoc[Improving the documentation]
+* xref:manual::release-guide.adoc[Release Guide]
+* xref:manual::release-guide-website.adoc[Release Guide for the Website]
+
+You can find additional documentation in the xref:manual::architecture.adoc[architecture documentation] in the old user manual.
diff --git a/docs/main/modules/getting-started/nav.adoc b/docs/main/modules/getting-started/nav.adoc
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/docs/user-manual/modules/ROOT/pages/book-getting-started.adoc b/docs/main/modules/getting-started/pages/index.adoc
similarity index 97%
copy from docs/user-manual/modules/ROOT/pages/book-getting-started.adoc
copy to docs/main/modules/getting-started/pages/index.adoc
index eb2ef5399c1..68d8e6b7ed8 100644
--- a/docs/user-manual/modules/ROOT/pages/book-getting-started.adoc
+++ b/docs/main/modules/getting-started/pages/index.adoc
@@ -1,4 +1,6 @@
-= Getting Started with Apache Camel
+= Getting Started
+
+This document will guide you through the fundamentals of the Apache Camel Core. At the end of it you will have a basic understanding of integrating systems, have learned some of the most important concepts of the project, and will be able to create and run your first project.
[[BookGettingStarted-eip-book]]
@@ -71,7 +73,7 @@ bookmarks to pages that you frequently reference can also save time.
[[BookGettingStarted-OnlineJavadocdocumentation]]
== Online Javadoc documentation
-The Apache Camel Javadoc documentation can be accessed from
+The Apache Camel Javadoc documentation can be accessed from
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:
@@ -150,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 ("Routes,
+discuss later in xref:index.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 ("Online Javadoc
+xref:index.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
@@ -208,11 +210,11 @@ 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 ("Message and
+discussed in xref:index.adoc[Section ("Message and
Exchange")]) – to an `Endpoint` – discussed in
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
+move along routes – discussed in xref:index.adoc[Section
("Routes, RouteBuilders and Java DSL")] – to destination endpoints.
[[BookGettingStarted-url-uri-urn-iri]]
@@ -367,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 ("The
+why, recall from xref:index.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`:
diff --git a/docs/main/modules/reference/nav.adoc b/docs/main/modules/reference/nav.adoc
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/docs/main/modules/reference/pages/index.adoc b/docs/main/modules/reference/pages/index.adoc
new file mode 100644
index 00000000000..23133e786ab
--- /dev/null
+++ b/docs/main/modules/reference/pages/index.adoc
@@ -0,0 +1,12 @@
+= Reference Documentation
+
+* *Reference*
+* xref:components::index.adoc[Components]
+* xref:components:dataformats:index.adoc[Data Formats]
+* xref:components:languages:index.adoc[Languages]
+* xref:components:eips:enterprise-integration-patterns.adoc[EIPs]
+* xref:manual::examples.adoc[Examples]
+* https://www.javadoc.io/doc/org.apache.camel/camel-api/latest/index.html[API Documentation] for the latest version
+
+
+
diff --git a/docs/main/modules/working-with-camel-core/nav.adoc b/docs/main/modules/working-with-camel-core/nav.adoc
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/docs/main/modules/working-with-camel-core/pages/index.adoc b/docs/main/modules/working-with-camel-core/pages/index.adoc
new file mode 100644
index 00000000000..9fa2ca11722
--- /dev/null
+++ b/docs/main/modules/working-with-camel-core/pages/index.adoc
@@ -0,0 +1,71 @@
+= Working with Camel Core
+
+Learn about additional ways to customize your integrations. Explore alternatives to consume and produce data as well as writing and defining routes.
+
+* xref:manual::component-dsl.adoc[Component DSL]
+* xref:manual::dataformat-dsl.adoc[Data Format DSL]
+* xref:manual::Endpoint-dsl.adoc[Endpoint DSL]
+* xref:manual::language-dsl.adoc[Language DSL]
+* xref:manual::dsl.adoc[DSL overview]
+* xref:manual::java-dsl.adoc[Java DSL]
+* xref:manual::camel-maven-archetypes.adoc[Camel Maven Archetypes]
+* xref:manual::lifecycle.adoc[Camel Lifecycle]
+* xref:manual::stream-caching.adoc[Stream caching]
+* xref:manual::bean-binding.adoc[Bean Binding]
+* xref:manual::bean-injection.adoc[Bean Injection]
+* xref:manual::bean-integration.adoc[Bean Integration]
+* xref:manual::advice-with.adoc[Advice With]
+* xref:manual::camel-console.adoc[Camel Console]
+* xref:manual::camelcontext.adoc[Camel Context]
+* xref:manual::camelcontext-autoconfigure.adoc[Camel Context Auto Configuration]
+* xref:manual::advanced-configuration-of-camelcontext-using-spring.adoc[Advanced Configuration of Camel Context]
+* xref:manual::camel-maven-plugin.adoc[Camel Maven Plugin]
+* xref:manual::camel-report-maven-plugin.adoc[Camel Report Maven Plugin]
+* xref:manual::component.adoc[Component]
+* xref:manual::consumertemplate.adoc[Consumer Template]
+* xref:manual::producertemplate.adoc[Producer Template]
+* xref:manual::pojo-consuming.adoc[POJO Consuming]
+* xref:manual::pojo-producing.adoc[POJO Producing]
+* xref:manual::error-handler.adoc[Error Handler]
+* xref:manual::defaulterrorhandler.adoc[Default Error Handler]
+* xref:manual::delay-interceptor.adoc[Delayer]
+* xref:manual::configuring-route-startup-ordering-and-autostartup.adoc[Configuring Route Startup Ordering]
+* xref:manual::endpoint.adoc[Endpoint]
+* xref:manual::examples.adoc[Examples]
+* xref:manual::exception-clause.adoc[Exception Clause]
+* xref:manual::exchange.adoc[Exchange]
+* xref:manual::exchange-pattern.adoc[Exchange Pattern]
+* xref:manual::exchange-pooling.adoc[Exchange Pooling]
+* xref:manual::expression.adoc[Expression]
+* xref:manual::json.adoc[JSON Data Format]
+* xref:manual::lambda-route-builder.adoc[Lambda Route Builder]
+* xref:manual::languages.adoc[Languages]
+* xref:manual::oncompletion.adoc[On Completion]
+* xref:manual::parameter-binding-annotations.adoc[Parameter Binding Annotations]
+* xref:manual::predicate.adoc[Predicate]
+* xref:manual::processor.adoc[Processor]
+* xref:manual::property-binding.adoc[Property Binding]
+* xref:manual::registry.adoc[Registry]
+* xref:manual::rest-dsl.adoc[Rest DSL]
+* xref:manual::route-builder.adoc[Route Builder]
+* xref:manual::route-configuration.adoc[Route Configuration]
+* xref:manual::route-controller.adoc[Route Controller]
+* xref:manual::route-policy.adoc[Route Policy]
+* xref:manual::routes.adoc[Routes]
+* xref:manual::route-template.adoc[Route Template]
+* xref:manual::security.adoc[Security]
+* xref:manual::service-registry.adoc[Service Registry]
+* xref:manual::spring.adoc[Spring]
+* xref:manual::spring-xml-extensions.adoc[Spring XML Extensions]
+* xref:manual::try-catch-finally.adoc[Try, Catch and Finally]
+* xref:manual::uris.adoc[URIs]
+* xref:manual::using-exchange-pattern-annotations.adoc[Using Exchange Pattern Annotations]
+* xref:manual::using-propertyplaceholder.adoc[Using Property Placeholder]
+* xref:manual::validator.adoc[Validator]
+* xref:manual::walk-through-an-example.adoc[Example Walk-through 1]
+* xref:manual::walk-through-another-example.adoc[Example Walk-through 2]
+* xref:manual::what-are-the-dependencies.adoc[Camel Requirements]
+* xref:manual::testing.adoc[Testing]
+
+
+You can find additional documentation in the xref:manual::architecture.adoc[architecture documentation] in the old user manual.
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 eb2ef5399c1..327295dda4c 100644
--- a/docs/user-manual/modules/ROOT/pages/book-getting-started.adoc
+++ b/docs/user-manual/modules/ROOT/pages/book-getting-started.adoc
@@ -1,527 +1,3 @@
= Getting Started with Apache Camel
-[[BookGettingStarted-eip-book]]
-
-[[BookGettingStarted-TheEnterpriseIntegrationPatternsEIPBook]]
-== The _Enterprise Integration Patterns_ (EIP) book
-
-The purpose of a _patterns_ book is not to advocate new techniques that
-the authors have invented, but rather to document existing best
-practices within a particular field. By doing this, the authors of a
-patterns book hope to spread knowledge of best practices and promote a
-vocabulary for discussing architectural designs. +
-One of the most famous patterns books is
-http://www.amazon.com/Design-Patterns-Elements-Reusable-Object-Oriented/dp/0201633612[_Design
-Patterns: Elements of Reusable Object-oriented Software_] by Erich
-Gamma, Richard Helm, Ralph Johnson and John Vlissides, commonly known as
-the http://en.wikipedia.org/wiki/Design_Patterns["Gang of Four" (GoF)]
-book. Since the publication of __Design Patterns__, many other pattern
-books, of varying quality, have been written. One famous patterns book
-is called
-http://www.amazon.com/Enterprise-Integration-Patterns-Designing-Deploying/dp/0321200683[_Enterprise
-Integration Patterns: Designing, Building, and Deploying Messaging
-Solutions_] by Gregor Hohpe and Bobby Woolf. It is common for people to
-refer to this book by its initials __EIP__. As the subtitle of EIP
-suggests, the book focuses on design patterns for asynchronous messaging
-systems. The book discusses 65 patterns. Each pattern is given a textual
-name and most are also given a graphical symbol, intended to be used in
-architectural diagrams.
-
-[[BookGettingStarted-TheCamelproject]]
-== The Camel project
-
-Camel (http://camel.apache.org) is an open-source, Java-based project
-that helps the user implement many of the design patterns in the EIP
-book. Because Camel implements many of the design patterns in the EIP
-book, it would be a good idea for people who work with Camel to have the
-EIP book as a reference.
-
-[[BookGettingStarted-OnlinedocumentationforCamel]]
-== Online documentation for Camel
-
-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 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]]
-=== A useful tip for navigating the online documentation
-
-The breadcrumbs at the top of the online Camel documentation can help
-you navigate between parent and child subsections. +
-For example, If you are on the "Languages" documentation page then the
-left-hand side of the reddish bar contains the following links.
-
-[source,java]
-----
-Apache Camel > Documentation > Languages
-----
-
-As you might expect, clicking on "Apache Camel" takes you back to the
-home page of the Apache Camel project, and clicking on "Documentation"
-takes you to the main documentation page. You can interpret the
-"Architecture" and "Languages" buttons as indicating you are in the
-"Languages" section of the "Architecture" chapter. Adding browser
-bookmarks to pages that you frequently reference can also save time.
-
-[[BookGettingStarted-online-javadoc-docs]]
-
-[[BookGettingStarted-OnlineJavadocdocumentation]]
-== 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].
-
-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
-
-In this section some of the concepts and terminology that are
-fundamental to Camel are explained. This section is not meant as a
-complete Camel tutorial, but as a first step in that direction.
-
-[[BookGettingStarted-endpoint]]
-
-[[BookGettingStarted-Endpoint]]
-=== Endpoint
-
-The term _endpoint_ is often used when talking about inter-process
-communication. For example, in client-server communication, the client
-is one endpoint and the server is the other endpoint. Depending on the
-context, an endpoint might refer to an _address_, such as a `host:port`
-pair for TCP-based communication, or it might refer to a _software
-entity_ that is contactable at that address. For example, if somebody
-uses `www.example.com:80` as an example of an endpoint, they might be
-referring to the actual port at that host name (that is, an address), or
-they might be referring to the web server (that is, software contactable
-at that address). Often, the distinction between the address and
-software contactable at that address is not an important one.
-
-Some middleware technologies make it possible for several software
-entities to be contactable at the same physical address. For example,
-CORBA is an object-oriented, remote-procedure-call (RPC) middleware
-standard. If a CORBA server process contains several objects then a
-client can communicate with any of these objects at the same _physical_
-address (host:port), but a client communicates with a particular object
-via that object's _logical_ address (called an _IOR_ in CORBA
-terminology), which consists of the physical address (`host:port`) plus an
-id that uniquely identifies the object within its server process. (An
-IOR contains some additional information that is not relevant to this
-present discussion.) When talking about CORBA, some people may use the
-term "endpoint" to refer to a CORBA server's _physical address_, while
-other people may use the term to refer to the _logical address_ of a
-single CORBA object, and other people still might use the term to refer
-to any of the following:
-
-* The physical address (`host:port`) of the CORBA server process
-* The logical address (`host:port` plus `id`) of a CORBA object
-* The CORBA server process (a relatively heavyweight software entity)
-* A CORBA object (a lightweight software entity)
-
-Because of this, you can see that the term _endpoint_ is ambiguous in at
-least two ways. First, it is ambiguous because it might refer to an
-address or to a software entity contactable at that address. Second, it
-is ambiguous in the _granularity_ of what it refers to: a heavyweight
-versus lightweight software entity, or physical address versus logical
-address. It is useful to understand that different people use the term
-_endpoint_ in slightly different (and hence ambiguous) ways because
-Camel's usage of this term might be different to whatever meaning you
-had previously associated with the term.
-
-Camel provides out-of-the-box support for endpoints implemented with
-many different communication technologies. Here are some examples of the
-Camel-supported endpoint technologies.
-
-* A JMS queue.
-* A web service.
-* A file. A file may sound like an unlikely type of endpoint, until you
-realize that in some systems one application might write information to
-a file and, later, another application might read that file.
-* An FTP server.
-* An email address. A client can send a message to an email address, and
-a server can read an incoming message from a mail server.
-* A POJO (plain old Java object).
-
-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 ("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 ("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
-http://javadoc.io/doc/org.apache.camel/camel-jms/latest/[JMS Javadoc
-hierarchy], while documentation for, say, the `FtpEndpoint` class is in
-the http://javadoc.io/doc/org.apache.camel/camel-ftp/latest/[FTP Javadoc
-hierarchy].
-
-[[BookGettingStarted-CamelContext]]
-=== CamelContext
-
-A `CamelContext` object represents the Camel runtime system. You
-typically have one `CamelContext` object in an application. A typical
-application executes the following steps:
-
-1. Create a `CamelContext` object.
-2. Add endpoints – and possibly components, which are discussed in
-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
-starts Camel-internal threads that are used to process the sending,
-receiving and processing of messages in the endpoints.
-5. Eventually invoke the `stop()` operation on the `CamelContext`
-object. Doing this gracefully stops all the endpoints and Camel-internal
-threads.
-
-Note that the `CamelContext.start()` operation does not block
-indefinitely. Rather, it starts threads internal to each `Component` and
-`Endpoint` and then `start()` returns. Conversely, `CamelContext.stop()`
-waits for all the threads internal to each `Endpoint` and `Component` to
-terminate and then `stop()` returns.
-
-If you neglect to call `CamelContext.start()` in your application then
-messages will not be processed because internal threads will not have
-been created.
-
-If you neglect to call `CamelContext.stop()` before terminating your
-application then the application may terminate in an inconsistent state.
-If you neglect to call `CamelContext.stop()` in a JUnit test then the
-test may fail due to messages not having had a chance to be fully
-processed.
-
-[[BookGettingStarted-CamelTemplate]]
-=== CamelTemplate
-
-Camel used to have a class called `CamelClient`, but this was renamed to
-be `CamelTemplate` to be similar to a naming convention used in some
-other open-source projects, such as the `TransactionTemplate` and
-`JmsTemplate` classes in http://www.springframework.org/[Spring].
-
-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 ("Message and
-Exchange")]) – to an `Endpoint` – discussed in
-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
- ("Routes, RouteBuilders and Java DSL")] – to destination endpoints.
-
-[[BookGettingStarted-url-uri-urn-iri]]
-
-[[BookGettingStarted-TheMeaningofURL,URI,URNandIRI]]
-=== The Meaning of URL, URI, URN and IRI
-
-Some Camel methods take a parameter that is a _URI_ string. Many people
-know that a URI is "something like a URL" but do not properly understand
-the relationship between URI and URL, or indeed its relationship with
-other acronyms such as IRI and URN.
-
-Most people are familiar with _URLs_ (uniform resource locators), such
-as `\http://...`, `\ftp://...`, `\mailto:...:`. Put simply, a URL specifies
-the _location_ of a resource.
-
-A _URI_ (uniform resource identifier) is a URL _or_ a URN. So, to fully
-understand what URI means, you need to first understand what is a URN. +
-_URN_ is an acronym for __uniform resource name__. There are many "unique
-identifier" schemes in the world, for example, ISBNs (globally unique
-for books), social security numbers (unique within a country), customer
-numbers (unique within a company's customers database) and telephone
-numbers. Each "unique identifier" scheme has its own notation. A URN is
-a wrapper for different "unique identifier" schemes. The syntax of a URN
-is `urn:<scheme-name>:<unique-identifier>`. A URN uniquely identifies a
-_resource_, such as a book, person or piece of equipment. By itself, a
-URN does not specify the _location_ of the resource. Instead, it is
-assumed that a _registry_ provides a mapping from a resource's URN to
-its location. The URN specification does not state what form a registry
-takes, but it might be a database, a server application, a wall chart or
-anything else that is convenient. Some hypothetical examples of URNs are
-`urn:employee:08765245`, `urn:customer:uk:3458:hul8` and
-`urn:foo:0000-0000-9E59-0000-5E-2`. The `<scheme-name>` (`employee`,
-`customer` and `foo` in these examples) part of a URN implicitly defines
-how to parse and interpret the `<unique-identifier>` that follows it. An
-arbitrary URN is meaningless unless: (1) you know the semantics implied
-by the `<scheme-name>`, and (2) you have access to the registry
-appropriate for the `<scheme-name>`. A registry does not have to be public
-or globally accessible. For example, `urn:employee:08765245` might be
-meaningful only within a specific company.
-
-To date, URNs are not (yet) as popular as URLs. For this reason, URI is
-widely misused as a synonym for URL.
-
-_IRI_ is an acronym for __internationalized resource identifier__. An
-IRI is simply an internationalized version of a URI. In particular, a
-URI can contain letters and digits in the US-ASCII character set, while
-a IRI can contain those same letters and digits, and _also_ European
-accented characters, Greek letters, Chinese ideograms and so on.
-
-[[BookGettingStarted-Components]]
-=== Components
-
-_Component_ is confusing terminology; _EndpointFactory_ would have been
-more appropriate because a `Component` is a factory for creating
-`Endpoint` instances. For example, if a Camel-based application uses
-several JMS queues then the application will create one instance of the
-`JmsComponent` class (which implements the `Component` interface), and
-then the application invokes the `createEndpoint()` operation on this
-`JmsComponent` object several times. Each invocation of
-`JmsComponent.createEndpoint()` creates an instance of the `JmsEndpoint`
-class (which implements the `Endpoint` interface). Actually,
-application-level code does not invoke `Component.createEndpoint()`
-directly. Instead, application-level code normally invokes
-`CamelContext.getEndpoint()`; internally, the `CamelContext` object
-finds the desired `Component` object (as I will discuss shortly) and
-then invokes `createEndpoint()` on it.
-
-Consider the following code:
-
-[source,java]
-----
-myCamelContext.getEndpoint("pop3://john.smith@mailserv.example.com?password=myPassword");
-----
-
-The parameter to `getEndpoint()` is a URI. The URI _prefix_ (that is,
-the part before `:`) specifies the name of a component. Internally, the
-`CamelContext` object maintains a mapping from names of components to
-`Component` objects. For the URI given in the above example, the
-`CamelContext` object would probably map the `pop3` prefix to an
-instance of the `MailComponent` class. Then the `CamelContext` object
-invokes
-`createEndpoint("pop3://john.smith@mailserv.example.com?password=myPassword")`
-on that `MailComponent` object. The `createEndpoint()` operation splits
-the URI into its component parts and uses these parts to create and
-configure an `Endpoint` object. +
-In the previous paragraph, I mentioned that a `CamelContext` object
-maintains a mapping from component names to `Component` objects. This
-raises the question of how this map is populated with named `Component`
-objects. There are two ways of populating the map. The first way is for
-application-level code to invoke
-`CamelContext.addComponent(String componentName, Component component)`.
-The example below shows a single `MailComponent` object being registered
-in the map under 3 different names.
-
-[source,java]
-----
-Component mailComponent = new org.apache.camel.component.mail.MailComponent();
-myCamelContext.addComponent("pop3", mailComponent);
-myCamelContext.addComponent("imap", mailComponent);
-myCamelContext.addComponent("smtp", mailComponent);
-----
-
-The second (and preferred) way to populate the map of named `Component`
-objects in the `CamelContext` object is to let the `CamelContext` object
-perform lazy initialization. This approach relies on developers
-following a convention when they write a class that implements the
-`Component` interface. I illustrate the convention by an example. Let's
-assume you write a class called `com.example.myproject.FooComponent` and
-you want Camel to automatically recognize this by the name `foo`. To do
-this, you have to write a properties file called
-`META-INF/services/org/apache/camel/component/foo` (without a
-`.properties` file extension) that has a single entry in it called
-`class`, the value of which is the fully-scoped name of your class. This
-is shown below:
-
-.META-INF/services/org/apache/camel/component/foo
-[source]
-----
-class=com.example.myproject.FooComponent
-----
-
-If you want Camel to also recognize the class by the name `bar` then you
-write another properties file in the same directory called `bar` that
-has the same contents. Once you have written the properties file(s), you
-create a JAR file that contains the `com.example.myproject.FooComponent`
-class and the properties file(s), and you add this jar file to your
-CLASSPATH. Then, when application-level code invokes
-`createEndpoint("foo:...")` on a `CamelContext` object, Camel will find
-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 ("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
-`CamelContext` object to populate its map of named `Component`
-objects.
-
-Earlier in this section I gave the following example of calling
-`CamelContext.getEndpoint()`:
-
-[source,java]
-----
-myCamelContext.getEndpoint("pop3://john.smith@mailserv.example.com?password=myPassword");
-----
-
-When I originally gave that example, I said that the parameter to
-`getEndpoint()` was a URI. I said that because the online Camel
-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 ("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`:
-
-[source,java]
-----
-myCamelContext.getEndpoint("pop3:...");
-myCamelContext.getEndpoint("jms:...");
-myCamelContext.getEndpoint("urn:foo:...");
-myCamelContext.getEndpoint("urn:bar:...");
-----
-
-Camel identifies the components in the above example as `pop3`, `jms`,
-`urn` and `urn`. It would be more useful if the latter components were
-identified as `urn:foo` and `urn:bar` or, alternatively, as `foo` and
-`bar` (that is, by skipping over the `urn:` prefix). So, in practice you
-must identify an endpoint with a URL (a string of the form
-`<scheme>:...`) rather than with a URN (a string of the form
-`urn:<scheme>:...`). This lack of proper support for URNs means the you
-should consider the parameter to `getEndpoint()` as being a URL rather
-than (as claimed) a URI.
-
-[[BookGettingStarted-message-and-exchange]]
-
-[[BookGettingStarted-MessageandExchange]]
-=== Message and Exchange
-
-The `Message` interface provides an abstraction for a single message,
-such as a request, reply or exception message.
-
-There are concrete classes that implement the `Message` interface for
-each Camel-supported communications technology. For example, the
-`JmsMessage` class provides a JMS-specific implementation of the
-`Message` interface. The public API of the `Message` interface provides
-get- and set-style methods to access the _message id_, _body_ and
-individual _header_ fields of a message.
-
-The `Exchange` interface provides an abstraction for an exchange of
-messages, that is, a request message and its corresponding reply or
-exception message. In Camel terminology, the request, reply and
-exception messages are called _in_, _out_ and _fault_ messages.
-
-There are concrete classes that implement the `Exchange` interface for
-each Camel-supported communications technology. For example, the
-`JmsExchange` class provides a JMS-specific implementation of the
-`Exchange` interface. The public API of the `Exchange` interface is
-quite limited. This is intentional, and it is expected that each class
-that implements this interface will provide its own technology-specific
-operations.
-
-Application-level programmers rarely access the `Exchange` interface (or
-classes that implement it) directly. However, many classes in Camel are
-generic types that are instantiated on (a class that implements)
-`Exchange`. Because of this, the `Exchange` interface appears a lot in
-the generic signatures of classes and methods.
-
-[[BookGettingStarted-Processor]]
-=== Processor
-
-The `Processor` interface represents a class that processes a message.
-The signature of this interface is shown below:
-
-.Processor
-[source,java]
-----
-package org.apache.camel;
-public interface Processor {
- void process(Exchange exchange) throws Exception;
-}
-----
-
-Notice that the parameter to the `process()` method is an `Exchange`
-rather than a `Message`. This provides flexibility. For example, an
-implementation of this method initially might call `exchange.getIn()` to
-get the input message and process it. If an error occurs during
-processing then the method can call `exchange.setException()`.
-
-An application-level developer might implement the `Processor` interface
-with a class that executes some business logic. However, there are many
-classes in the Camel library that implement the `Processor` interface in
-a way that provides support for a design pattern in the
-EIP book. For example, `ChoiceProcessor`
-implements the message router pattern, that is, it uses a cascading
-if-then-else statement to route a message from an input queue to one of
-several output queues. Another example is the `FilterProcessor` class
-which discards messages that do not satisfy a stated _predicate_ (that
-is, condition).
-
-[[BookGettingStarted-routes]]
-
-[[BookGettingStarted-Routes,RouteBuildersandJavaDSL]]
-=== Routes, RouteBuilders and Java DSL
-
-A _route_ is the step-by-step movement of a `Message` from an input
-queue, through arbitrary types of decision making (such as filters and
-routers) to a destination queue (if any). Camel provides three ways for an
-application developer to specify routes. First two ways is to specify route
-information in an XML or YAML file. A discussion of that approach is outside the
-scope of this document. The other way is through what Camel calls a Java
-_DSL_ (domain-specific language).
-
-[[BookGettingStarted-IntroductiontoJavaDSL]]
-==== Introduction to Java DSL
-
-For many people, the term "domain-specific language" implies a compiler
-or interpreter that can process an input file containing keywords and
-syntax specific to a particular domain. This is _not_ the approach taken
-by Camel. Camel documentation consistently uses the term "Java DSL"
-instead of "DSL", but this does not entirely avoid potential confusion.
-The Camel "Java DSL" is a class library that can be used in a way that
-looks almost like a DSL, except that it has a bit of Java syntactic
-baggage. You can see this in the example below. Comments afterwards
-explain some of the constructs used in the example.
-
-.*Example of Camel's "Java DSL"*
-[source,java]
-----
-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")
- .otherwise().to("queue:f");
- }
-};
-CamelContext myCamelContext = new DefaultCamelContext();
-myCamelContext.addRoutes(builder);
-----
-
-The first line in the above example creates an object which is an
-instance of an anonymous subclass of `RouteBuilder` with the specified
-`configure()` method.
-
-The `CamelContext.addRoutes(RouterBuilder builder)` method invokes
-`builder.setContext(this)` – so the `RouteBuilder` object knows which
-`CamelContext` object it is associated with – and then invokes
-`builder.configure()`. The body of `configure()` invokes methods such as
-`from()`, `filter()`, `choice()`, `when()`, `isEqualTo()`, `otherwise()`
-and `to()`.
-
-The `RouteBuilder.from(String uri)` method invokes `getEndpoint(uri)` on
-the `CamelContext` associated with the `RouteBuilder` object to get the
-specified `Endpoint` and then puts a `FromBuilder` _wrapper_ around this
-`Endpoint`. The `FromBuilder.filter(Predicate predicate)` method creates
-a `FilterProcessor` object for the `Predicate` (that is, condition)
-object built from the `header("foo").isEqualTo("bar")` expression. In
-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-ContinueLearningaboutCamel]]
-=== Continue Learning about Camel
-
-Return to the main Getting Started page for
-additional introductory reference information.
+This content was moved to the xref:camel-core:getting-started:index.adoc[getting-started].