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 582ef354aa7650f4d240f55fbc20d86eaf4b57dd
Author: Claus Ibsen <claus.ib...@gmail.com>
AuthorDate: Wed Aug 11 15:30:27 2021 +0200
Polish and cleanup documentation
---
.../ROOT/pages/pluggable-class-resolvers.adoc | 73 ++--------
.../modules/ROOT/pages/pojo-consuming.adoc | 154 +++++----------------
2 files changed, 49 insertions(+), 178 deletions(-)
diff --git a/docs/user-manual/modules/ROOT/pages/pluggable-class-resolvers.adoc
b/docs/user-manual/modules/ROOT/pages/pluggable-class-resolvers.adoc
index 81cc1d0..b54fdd1 100644
--- a/docs/user-manual/modules/ROOT/pages/pluggable-class-resolvers.adoc
+++ b/docs/user-manual/modules/ROOT/pages/pluggable-class-resolvers.adoc
@@ -2,70 +2,25 @@
Camel provides pluggable class resolvers allowing third party platforms
and containers to provide their own resolvers in case the default ones
-would not fit. For example we provide a
-`WebSpherePackageScanClassResolver` out of the box to
-integrate Camel with IBM WebSphere.
+would not fit.
-Platform providers should look in the `org.apache.camel.spi` package for
-the pluggable resolvers below:
-
-* `PackageScanClassResolver`
-* `ClassResolver`
-* `FactoryFinderResolver`
-
-In *camel-osgi* we provide OSGi aware class resolver allowing Camel to
-run in any OSGi container.
+When running Camel on platforms such as Spring Boot, Quarkus, or OSGi on
Apache Karaf,
+then Camel uses platform specific resolvers to support classloading in these
runtimes.
== Configuration of a custom class resolver
To instruct Camel to use your own custom class resolver, you set the
-resolver on the `CamelContext` using the appropriate setters.
-
-== Easy configuration of a custom class resolver in Spring XML
-
-We have provided easy configuration in Spring XML as you just need to
-declare a spring bean with your custom resolver and Camel will pick it
-up automatically.
-
-[source,xml]
-----
-<bean id="jbossresolver"
class="com.mycompany.jboss.JBossPackageScanClassResolver"/>
+resolver on the `CamelContext` using the appropriate setters;
+or register a custom resolver in the xref:registry.adoc[Registry] then Camel
+will automatic detect this during startup.
-<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring";>
- <route>
- <from uri="seda:start"/>
- <to uri="mock:result"/>
- </route>
-</camelContext>
-----
+=== SPI providers
-In the sample above the CamelContext will automatic detect the
-`jbossresolver` bean and use it instead of its default one.
-
-== Configuration of a custom factory finder resolver
-
-FactoryFinderResolver is used to get an instance of `FactoryFinder` that
-is used for lookup of resource files in the classpath in the
-`META-INF/services`. It is used internally by Camel to look in .jars for
-Camel components. For instance to look for the `file` component Camel
-will use the `FactoryFinder` to look the file named `file` in
-`META-INF/services/org/apache/camel/component`. The `CamelContext` have
-methods to inject a custom `FactoryFinderResolver`.
-
-== Easy configuration of a custom factory finder resolver in Spring XML
-
-We have provided easy configuration in Spring XML as you just need to
-declare a spring bean with your custom factory finder resolver and Camel
-will pick it up automatically.
-
-[source,xml]
-----
-<bean id="jbossFactoryFinderResolver"
class="com.mycompany.jboss.JBossFactoryFinderResolver"/>
+Platform providers should look in the `org.apache.camel.spi` package for
+the pluggable resolvers, such as:
-<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring";>
- <route>
- <from uri="seda:start"/>
- <to uri="mock:result"/>
- </route>
-</camelContext>
-----
+* `ClassResolver`
+* `FactoryFinderResolver`
+* `PackageScanClassResolver`
+* `PackageScanResourceResolver`
+* `ResourceResolver`
diff --git a/docs/user-manual/modules/ROOT/pages/pojo-consuming.adoc
b/docs/user-manual/modules/ROOT/pages/pojo-consuming.adoc
index a39c1bc..b1bb55d 100644
--- a/docs/user-manual/modules/ROOT/pages/pojo-consuming.adoc
+++ b/docs/user-manual/modules/ROOT/pages/pojo-consuming.adoc
@@ -1,24 +1,23 @@
= POJO Consuming
-To consume a message you use the
-`org.apache.camel.Consume`
+To consume a message you use the `@Consume`
annotation to mark a particular method of a bean as being a consumer
-method. The uri of the annotation defines the Camel
+method. The value of the annotation defines the Camel
xref:endpoint.adoc[Endpoint] to consume from.
-e.g. lets invoke the `onCheese()` method with the String body of the
+For example lets invoke the `onCheese()` method with the String body of the
inbound JMS message from xref:components::activemq-component.adoc[ActiveMQ] on
the cheese
queue; this will use the xref:type-converter.adoc[Type Converter] to
convert the JMS ObjectMessage or BytesMessage to a String - or just use
a TextMessage from JMS
-[source,syntaxhighlighter-pre]
+[source,java]
----
public class Foo {
@Consume("activemq:cheese")
public void onCheese(String name) {
- ...
+ // do something here
}
}
----
@@ -27,93 +26,23 @@ The xref:bean-binding.adoc[Bean Binding] is then used to
convert the
inbound xref:{eip-vc}:eips:message.adoc[Message] to the parameter list used to
invoke
the method .
-What this does is basically create a route that looks kinda like this
+This basically creates a route that looks kinda like this:
-[source,syntaxhighlighter-pre]
+[source,java]
----
from(uri).bean(theBean, "methodName");
----
-**When using more than one CamelContext**
-
-When you use more than 1 xref:camelcontext.adoc[CamelContext] you might
-end up with each of them creating a xref:pojo-consuming.adoc[POJO
-Consuming]; therefore use the option `context` on *@Consume* that allows
-you to specify which xref:camelcontext.adoc[CamelContext] id/name you
-want it to apply for.
-
-[[POJOConsuming-UsingcontextoptiontoapplyonlyacertainCamelContext]]
-== Using context option to apply only a certain CamelContext
-
-See the warning above.
-
-You can use the `context` option to specify which
-xref:camelcontext.adoc[CamelContext] the consumer should only apply for.
-For example:
-
-[source,syntaxhighlighter-pre]
-----
- @Consume(uri="activemq:cheese", context="camel-1")
- public void onCheese(String name) {
-----
-
-The consumer above will only be created for the
-xref:camelcontext.adoc[CamelContext] that have the context id =
-`camel-1`. You set this id in the XML tag:
-
-[source,syntaxhighlighter-pre]
-----
-<camelContext id="camel-1" ...>
-----
-
-[[POJOConsuming-Usinganexplicitroute]]
-== Using an explicit route
-
-If you want to invoke a bean method from many different endpoints or
-within different complex routes in different circumstances you can just
-use the normal routing xref:dsl.adoc[DSL] or the
-xref:spring.adoc[Spring] XML configuration file.
-
-For example
-
-[source,syntaxhighlighter-pre]
-----
-from(uri).beanRef("myBean", "methodName");
-----
-
-which will then look up in the xref:registry.adoc[Registry] and find the
-bean and invoke the given bean name. (You can omit the method name and
-have Camel figure out the right method based on the method annotations
-and body type).
-
-[[POJOConsuming-UsetheBeanendpoint]]
-== Use the Bean endpoint
-
-You can always use the bean endpoint
-
-[source,syntaxhighlighter-pre]
-----
-from(uri).to("bean:myBean?method=methodName");
-----
-
-[[POJOConsuming-Usingapropertytodefinetheendpoint]]
== Using a property to define the endpoint
-*Since Camel 2.11*
-
-The following annotations @Consume, @Produce, @EndpointInject, now
+The following annotations `@Consume`, `@Produce`, `@EndpointInject`, now
offers a `property` attribute you can use to define the endpoint as a
property on the bean. Then Camel will use the getter method to access
the property.
-**This applies for them all**
-
-The explanation below applies for all the three annotations, eg
-@Consume, @Produce, and @EndpointInject
-
-For example
+For example:
-[source,syntaxhighlighter-pre]
+[source,java]
----
public class MyService {
private String serviceEndpoint;
@@ -123,64 +52,60 @@ public class MyService {
}
public String getServiceEndpoint() {
- return serviceEndpoint
+ return serviceEndpoint;
}
@Consume(property = "serviceEndpoint")
public void onService(String input) {
- ...
+ // do something
}
}
----
The bean `MyService` has a property named `serviceEndpoint` which has
getter/setter for the property. Now we want to use the bean for
-xref:pojo-consuming.adoc[POJO Consuming], and hence why we use @Consume
-in the onService method. Notice how we use the
+xref:pojo-consuming.adoc[POJO Consuming], and hence why we use `@Consume`
+in the `onService` method. Notice how we use the
`property = "serviceEndpoint` to configure the property that has the
endpoint url.
-If you define the bean in Spring XML or Blueprint, then you can
-configure the property as follows:
+If you define the bean in Spring XML, then you can configure the property as
follows:
-[source,syntaxhighlighter-pre]
+[source,xml]
----
<bean id="myService" class="com.foo.MyService">
<property name="serviceEndpoint" value="activemq:queue:foo"/>
</bean>
----
-This allows you to configure the bean using any standard IoC style.
+This allows you to configure the bean without with any dependency injection
style.
+
+=== Advanced use with property naming convention
Camel offers a naming convention which allows you to not have to
-explicit name the property. +
-Camel uses this algorithm to find the getter method. The method must be
-a getXXX method.
-
-1. Use the property name if explicit given
-2. If no property name was configured, then use the method name +
-3. Try to get the property with name*Endpoint* (eg with Endpoint as
-postfix)
-4. Try to get the property with the name as is (eg no postfix or
-postfix)
-5. If the property name starts with *on* then omit that, and try step 3
-and 4 again.
-
-So in the example above, we could have defined the @Consume annotation
-as
-
-[source,syntaxhighlighter-pre]
+explicit name the property. Camel uses this algorithm to find the getter
method.
+The method must be a `getXXX` method.
+
+. Use the property name if explicit given
+. If no property name was configured, then use the method name
+. Try to get the property with name**Endpoint** (eg with Endpoint as postfix)
+. Try to get the property with the name as is (eg no postfix or postfix)
+. If the property name starts with **on** then omit that, and try step 3 and 4
again.
+
+So in the example above, we could have defined the `@Consume` annotation as:
+
+[source,java]
----
@Consume(property = "service")
public void onService(String input) {
----
-Now the property is named 'service' which then would match step 3 from
-the algorithm, and have Camel invoke the getServiceEndpoint method.
+Now the property is named "service" which then would match step 3 from
+the algorithm, and have Camel invoke the `getServiceEndpoint` method.
We could also have omitted the property attribute, to make it implicit
-[source,syntaxhighlighter-pre]
+[source,java]
----
@Consume
public void onService(String input) {
@@ -188,14 +113,5 @@ We could also have omitted the property attribute, to make
it implicit
Now Camel matches step 5, and loses the prefix *on* in the name, and
looks for 'service' as the property. And because there is a
-getServiceEndpoint method, Camel will use that.
-
-[[POJOConsuming-Whichapproachtouse]]
-== Which approach to use?
-
-Using the @Consume annotations are simpler when you are creating a
-simple route with a single well defined input URI.
+`getServiceEndpoint` method, Camel will use this method.
-However if you require more complex routes or the same bean method needs
-to be invoked from many places then please use the routing
-xref:dsl.adoc[DSL] as shown above.
