The jpa component enables you to store and retrieve Java objects from persistent storage using EJB 3's Java Persistence Architecture (JPA), which is a standard interface layer that wraps Object/Relational Mapping (ORM) products such as OpenJPA, Hibernate, TopLink, and so on.
Maven users will need to add the following dependency to their pom.xml
for
this component:
<dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-jpa</artifactId> <!-- use the same version as your Camel core version --> <version>x.x.x</version> </dependency>
You can store a Java entity bean in a database by sending it to a JPA producer endpoint. The body of the In message is assumed to be an entity bean (that is, a POJO with an @Entity annotation on it) or a collection or array of entity beans.
If the body does not contain one of the previous listed types, put a Message Translator in front of the endpoint to perform the necessary conversion first.
Consuming messages from a JPA consumer endpoint removes (or updates) entity beans in the database. This allows you to use a database table as a logical queue: consumers take messages from the queue and then delete/update them to logically remove them from the queue.
If you do not wish to delete the entity bean when it has been processed (and when
routing is done), you can specify consumeDelete=false
on the URI. This will
result in the entity being processed each poll.
If you would rather perform some update on the entity to mark it as processed (such as to exclude it from a future query) then you can annotate a method with @Consumed which will be invoked on your entity bean when it has been processed (and when routing is done).
From Camel 2.13 onwards you can use @PreConsumed which will be invoked on your entity bean before it has been processed (before routing).
jpa:[entityClassName][?options]
For sending to the endpoint, the entityClassName is optional. If specified, it helps the Type Converter to ensure the body is of the correct type.
For consuming, the entityClassName is mandatory.
You can append query options to the URI in the following format,
?option=value&option=value&...
Name |
Default Value |
Description |
---|---|---|
|
entityClassName |
Overrides the entityClassName from the URI. |
|
|
The JPA persistence unit used by default. |
|
|
JPA consumer only: If |
|
|
JPA consumer only: Specifies whether or not to set an exclusive lock on each entity bean while processing the results from polling. |
|
|
JPA producer only: Flushes the EntityManager after the entity bean has been persisted. |
|
|
JPA consumer only: Set the maximum number of results to retrieve on the Query. |
|
|
This option is Registry based which requires the
|
|
|
JPA consumer only: Delay in milliseconds between each poll. |
|
|
JPA consumer only: Milliseconds before polling starts. |
|
|
JPA consumer only: Set to |
|
|
JPA consumer only: An integer value to define the maximum number of messages to gather per poll. By default, no maximum is set. Can be used to avoid polling many thousands of messages when starting up the server. Set a value of 0 or negative to disable. |
|
|
JPA consumer only: To use a custom query when consuming data. |
|
|
JPA consumer only: To use a named query when consuming data. |
|
|
JPA consumer only: To use a custom native
query when consuming data. You may want to use the option
|
|
|
Camel 2.12: JPA consumer only: This option is
Registry based
which requires the |
|
|
Camel 2.7: JPA consumer only: Defines the
type of the returned payload (we will call |
|
|
Camel 2.7.5/2.8.3/2.9: JPA consumer only: Whether to run the consumer in transacted mode, by which all messages will either commit or rollback, when the entire batch has been processed. The default behavior (false) is to commit all the previously successfully processed messages, and only rollback the last failed message. |
|
|
Camel 2.11.2/2.12: To configure the lock mode on the
consumer. The possible values is defined in the enum
|
|
|
Camel 2.13: To configure whether to use NOWAIT on lock and silently skip the entity. |
|
|
JPA producer only: Indicates to use
|
|
|
Camel 2.12.3: camel-jpa will join transaction by
default from Camel 2.12 onwards. You can use this option to turn this off, for
example if you use LOCAL_RESOURCE and join transaction doesn't work with your
JPA provider. This option can also be set globally on the
|
|
|
Camel 2.12.4/2.13.1 JPA producer only: If set to true,
then Camel will use the EntityManager from the header
|
Camel adds the following message headers to the exchange:
Header |
Type |
Description |
---|---|---|
|
|
Not supported anymore since Camel 2.12: The
|
|
|
Camel 2.12: JPA consumer / Camel 2.12.2: JPA
producer: The JPA |
It is strongly advised to configure the JPA component to use a specific
EntityManagerFactory
instance. If failed to do so each
JpaEndpoint
will auto create their own instance of
EntityManagerFactory
which most often is not what you want.
For example, you can instantiate a JPA component that references the
myEMFactory
entity manager factory, as follows:
<bean id="jpa" class="org.apache.camel.component.jpa.JpaComponent"> <property name="entityManagerFactory" ref="myEMFactory"/> </bean>
In Camel 2.3 the JpaComponent
will auto
lookup the EntityManagerFactory
from the Registry which means you do not
need to configure this on the JpaComponent
as shown above. You only need to do
so if there is ambiguity, in which case Camel will log a WARN.
Since Camel 2.3 the JpaComponent
will auto
lookup the TransactionManager
from the Registry. If Camel won't find
any TransactionManager
instance registered, it will also look up for the
TransactionTemplate
and try to extract TransactionManager
from
it.
If none TransactionTemplate
is available in the registry,
JpaEndpoint
will auto create their own instance of
TransactionManager
which most often is not what you want.
If more than single instance of the TransactionManager
is found, Camel will
log a WARN. In such cases you might want to instantiate and explicitly configure a JPA
component that references the myTransactionManager
transaction manager, as
follows:
<bean id="jpa" class="org.apache.camel.component.jpa.JpaComponent"> <property name="entityManagerFactory" ref="myEMFactory"/> <property name="transactionManager" ref="myTransactionManager"/> </bean>
For consuming only selected entities, you can use the consumer.namedQuery
URI query option. First, you have to define the named query in the JPA Entity class:
@Entity @NamedQuery(name = "step1", query = "select x from MultiSteps x where x.step = 1") public class MultiSteps { ... }
After that you can define a consumer uri like this one:
from("jpa://org.apache.camel.examples.MultiSteps?consumer.namedQuery=step1") .to("bean:myBusinessLogic");
For consuming only selected entities, you can use the consumer.query
URI
query option. You only have to define the query option:
from("jpa://org.apache.camel.examples.MultiSteps?consumer.query= select o from org.apache.camel.examples.MultiSteps o where o.step = 1") .to("bean:myBusinessLogic");
For consuming only selected entities, you can use the consumer.nativeQuery
URI query option. You only have to define the native query option:
from("jpa://org.apache.camel.examples.MultiSteps?consumer.nativeQuery= select * from MultiSteps where step = 1") .to("bean:myBusinessLogic");
If you use the native query option, you will receive an object array in the message body.
See Tracer Example for an example using Camel Component: JPA to store traced messages into a database.