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/13 15:13:37 UTC
[camel] branch main updated (3c7f0123fe7 -> 08e013e80b7)
This is an automated email from the ASF dual-hosted git repository.
orpiske pushed a change to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
from 3c7f0123fe7 (chores) documentation: added link to the CamelContext reference
new 292283af110 (chores) documentation: reworked the component section on the getting started
new 33432372861 (chores) documentation: moved additional component details to the component page
new 08e013e80b7 (chores) documentation: formatting fixes
The 3 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
docs/main/modules/getting-started/pages/index.adoc | 128 ++-------------------
docs/user-manual/modules/ROOT/pages/component.adoc | 67 ++++++++++-
2 files changed, 74 insertions(+), 121 deletions(-)
[camel] 03/03: (chores) documentation: formatting fixes
Posted by or...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
orpiske pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
commit 08e013e80b7d3f547fdfa1b86bb3843dff5d5e00
Author: Otavio Rodolfo Piske <an...@gmail.com>
AuthorDate: Tue Dec 13 15:08:59 2022 +0100
(chores) documentation: formatting fixes
---
docs/main/modules/getting-started/pages/index.adoc | 7 ++-----
docs/user-manual/modules/ROOT/pages/component.adoc | 3 +--
2 files changed, 3 insertions(+), 7 deletions(-)
diff --git a/docs/main/modules/getting-started/pages/index.adoc b/docs/main/modules/getting-started/pages/index.adoc
index 36de0f27935..d7386da0fa0 100644
--- a/docs/main/modules/getting-started/pages/index.adoc
+++ b/docs/main/modules/getting-started/pages/index.adoc
@@ -308,12 +308,9 @@ You did not manipulate the _CamelContext_ in the sample application you created,
threads.
*Note*: 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.
+`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, Camel will not process the messages because internal threads will not have
-been created.
+If you neglect to call `CamelContext.start()` in your application, Camel will not process the messages because internal threads will not have been created.
If you neglect to call `CamelContext.stop()` before terminating your application, it may terminate in an inconsistent state.
If you neglect to call `CamelContext.stop()` in a JUnit test, it may fail because the messages did not have a chance to be fully processed.
diff --git a/docs/user-manual/modules/ROOT/pages/component.adoc b/docs/user-manual/modules/ROOT/pages/component.adoc
index c6295e2cf14..9bf941a8fca 100644
--- a/docs/user-manual/modules/ROOT/pages/component.adoc
+++ b/docs/user-manual/modules/ROOT/pages/component.adoc
@@ -94,8 +94,7 @@ 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 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 that you should consider the parameter to the method `getEndpoint()` as being a URL rather than (as claimed) a URI.
+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 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 that you should consider the paramete [...]
[NOTE]
====
[camel] 01/03: (chores) documentation: reworked the component section on the getting started
Posted by or...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
orpiske pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
commit 292283af11009f3a76efe67cfa2aec953a11c9d6
Author: Otavio Rodolfo Piske <an...@gmail.com>
AuthorDate: Tue Dec 13 14:46:00 2022 +0100
(chores) documentation: reworked the component section on the getting started
---
docs/main/modules/getting-started/pages/index.adoc | 120 +--------------------
1 file changed, 5 insertions(+), 115 deletions(-)
diff --git a/docs/main/modules/getting-started/pages/index.adoc b/docs/main/modules/getting-started/pages/index.adoc
index a8697f9d739..6a5e40a8a4f 100644
--- a/docs/main/modules/getting-started/pages/index.adoc
+++ b/docs/main/modules/getting-started/pages/index.adoc
@@ -236,7 +236,7 @@ In Camel, the URIs that represent the addresses of the endpoints take the follow
The scheme part of the URI represents the component used to consume or produce data. Camel contains more than xref:components::index.adoc[300 components] that allow your application to communicate with many systems, protocols, and applications.
-These are some examples of valid URIs for Camel: `jms:queue:order`, `kafka:myTopic?groupId=KafkaConsumerFullIT`, `direct:result`.
+These are some examples of valid URIs for Camel: `jms:queue:order`, `kafka:myTopic?groupId=KafkaConsumerFullIT`, `direct:result`. By looking at these URIs we can identify that they are using the `jms`, `kafka`, and the `direct` component.
Every component has its own specific set of features, constraints, and requirements that we must observe when working with them. Camel exposes them through the `resource` and `options`. What this means varies according to the component we are working with. For instance, in the xref:components::file-component.adoc[file] component, the _resource_ is a directory; in the xref:components::kafka-component.adoc[Kafka] component, the _resource_ is the _topic_; etc.
@@ -323,128 +323,18 @@ If you neglect to call `CamelContext.stop()` in a JUnit test, it may fail becaus
[[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:
+A Component is essentially a factory of Endpoint instances. Typically, Camel-based applications shouldn't need to interact directly with a component. However, they are some circumstances where manipulating the component may be beneficial for the application, performance, operation, or scalability of the application. In such cases, the applications may use the context to get access to an instance of the endpoint they need to manipulate. The applications can do so by using the method `Came [...]
[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.
+For the URI given in the above example, the `CamelContext` object would map the `pop3` prefix to an instance of the `MailComponent` class.
-[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: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`:
-
-[source,java]
-----
-myCamelContext.getEndpoint("pop3:...");
-myCamelContext.getEndpoint("jms:...");
-myCamelContext.getEndpoint("urn:foo:...");
-myCamelContext.getEndpoint("urn:bar:...");
-----
+The parameter to `getEndpoint()` is a URI. The URI _scheme_ (that is,
+the part before `:`) specifies the name of a component. Internally, the `CamelContext` object maintains a mapping from the names of components to `Component` objects.
-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]]
[camel] 02/03: (chores) documentation: moved additional component details to the component page
Posted by or...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
orpiske pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
commit 33432372861196e07873da05f8726b33fe96c501
Author: Otavio Rodolfo Piske <an...@gmail.com>
AuthorDate: Tue Dec 13 15:08:30 2022 +0100
(chores) documentation: moved additional component details to the component page
---
docs/main/modules/getting-started/pages/index.adoc | 1 +
docs/user-manual/modules/ROOT/pages/component.adoc | 68 +++++++++++++++++++++-
2 files changed, 68 insertions(+), 1 deletion(-)
diff --git a/docs/main/modules/getting-started/pages/index.adoc b/docs/main/modules/getting-started/pages/index.adoc
index 6a5e40a8a4f..36de0f27935 100644
--- a/docs/main/modules/getting-started/pages/index.adoc
+++ b/docs/main/modules/getting-started/pages/index.adoc
@@ -335,6 +335,7 @@ For the URI given in the above example, the `CamelContext` object would map the
The parameter to `getEndpoint()` is a URI. The URI _scheme_ (that is,
the part before `:`) specifies the name of a component. Internally, the `CamelContext` object maintains a mapping from the names of components to `Component` objects.
+*Note*: our documentation contains an in-depth overview of the xref:manual::component.adoc[Component] if you want to learn more about it, including important details necessary to write your own.
[[BookGettingStarted-message-and-exchange]]
diff --git a/docs/user-manual/modules/ROOT/pages/component.adoc b/docs/user-manual/modules/ROOT/pages/component.adoc
index 5f3ca9a722a..c6295e2cf14 100644
--- a/docs/user-manual/modules/ROOT/pages/component.adoc
+++ b/docs/user-manual/modules/ROOT/pages/component.adoc
@@ -31,6 +31,72 @@ A good practice when configuring options is to use xref:using-propertyplaceholde
which allows to not hardcode urls, port numbers, sensitive information, and other settings.
In other words placeholders allows to externalize the configuration from your code, and gives more flexibility and reuse.
+=== How Camel maps names to components
+
+In the getting started guide, we explained that Camel maintains a map of names to components. This raises the question of how Camel populates this map with named `Component` objects.
+
+*Note*: normally application developers don't need to worry about this. However, this information is fundamental if you are writing a custom component.
+
+There are two ways of populating the map.
+
+* Programmatically, using the context
+* Via lazy-initialization
+
+=== Programmatically
+
+The programmatic 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);
+----
+
+=== Lazy-initialization
+
+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. For instance, 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 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 t [...]
+
+.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"" [...]
+
+Camel provides out-of-the-box support for various communication technologies. This 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.
+
+In the "Getting Started" guide, we provided the following example of calling `CamelContext.getEndpoint()`:
+
+[source,java]
+----
+myCamelContext.getEndpoint("pop3://john.smith@mailserv.example.com?password=myPassword");
+----
+
+We originally referred to the parameter as a URI 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.
+
+*Note*: to understand, why recall from the Getting Started 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 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 that you should consider the parameter to the method `getEndpoint()` as being a URL rather than (as claimed) a URI.
+
[NOTE]
====
Make sure to read xref:faq:how-do-i-configure-endpoints.adoc[How do I configure endpoints?]
@@ -42,4 +108,4 @@ xref:using-propertyplaceholder.adoc[property placeholders] etc.
== See Also
-- List of all Camel xref:components::index.adoc[Components]
\ No newline at end of file
+- List of all Camel xref:components::index.adoc[Components]