...
Maven users will need to add the following dependency to their pom.xml
for this component:
...
Sending to the endpoint
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 from the endpoint
From Camel 2.19 onwards you can use query, namedQuery and nativeQuery option for the producer as well to retrieve a set of entities or execute bulk update/delete.
Consuming from the endpoint
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 are consuming a lot (100K+) of rows and experience OutOfMemory problems you should set the maximumResults to sensible value.
URI format
Code Block |
---|
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.
Note: Since Camel 2.18, JPA now includes a JpaPollingConsumer
implementation that better supports Content Enricher using pollEnrich()
to do an on-demand poll that returns either none, one or a list of entities as the result.
URI format
...
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 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. Camel 2.19: it's also used for the producer when it executes a 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. |
|
| Camel 2.5: 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 |
usePassedInEntityManager | false | Camel 2.12.4/2.13.1 JPA producer only: If set to true, then Camel will use the EntityManager from the header JpaConstants.ENTITYMANAGER instead of the configured entity manager on the component/endpoint. This allows end users to control which entity manager will be in use. |
sharedEntityManager | false | Camel 2.16: whether to use spring's SharedEntityManager for the consumer/producer. A good idea may be to set joinTransaction=false if this option is true, as sharing the entity manager and mixing transactions is not a good idea. |
query |
Message Headers
Camel adds the following message headers to the exchange:
Div | |||||||||
---|---|---|---|---|---|---|---|---|---|
| |||||||||
|
Configuring EntityManagerFactory
Its 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.
Configuring TransactionManager
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>
To use a custom query. Camel 2.19: it can be used for producer as well. | ||
namedQuery | To use a named query. Camel 2.19: it can be used for producer as well. | |
nativeQuery | To use a custom native query. You may want to use the option resultClass also when using native queries. Camel 2.19: it can be used for producer as well. | |
parameters | This option is Registry based which requires the # notation. This key/value mapping is used for building the query parameters. It is expected to be of the generic type java.util.Map<String, Object> where the keys are the named parameters of a given JPA query and the values are their corresponding effective values you want to select for. Camel 2.19: it can be used for producer as well. When it's used for producer, Simple expression can be used as a parameter value. It allows you to retrieve parameter values from the message body header and etc. | |
resultClass | Defines the type of the returned payload (we will call entityManager.createNativeQuery(nativeQuery, resultClass) instead of entityManager.createNativeQuery(nativeQuery) ). Without this option, we will return an object array. Only has an affect when using in conjunction with native query. Camel 2.19: it can be used for producer as well. | |
useExecuteUpdate | Camel 2.19: JPA producer only: To configure whether to use executeUpdate() when producer executes a query. When you use INSERT, UPDATE or DELETE statement as a named query, you need to specify this option to 'true'. |
Message Headers
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 |
Configuring EntityManagerFactory
Its 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:
...
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.
Configuring TransactionManager
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:
...
Using a consumer with a named query
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:
...
After that you can define a consumer uri like this one:
...
Using a consumer with a query
For consuming only selected entities, you can use the consumer.query
URI query option. You only have to define the query option:
...
Using a consumer with a native query
For consuming only selected entities, you can use the consumer.nativeQuery
URI query option. You only have to define the native query option:
...
If you use the native query option, you will receive an object array in the message body.
Using a producer with a named query
For retrieving selected entities or execute bulk update/delete, you can use the namedQuery
URI
Using a consumer with a named query
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:
...
...
After that you can define a consumer producer uri like this one:
...
...
Using a
...
producer with a query
For consuming only retrieving selected entities or execute bulk update/delete, you can use the consumer.the query
URI URI query option. You only have to define the query option:
...
...
Using a
...
producer with a native query
For consuming only retrieving selected entities or execute bulk update/delete, you can use the consumer.the nativeQuery
URI URI query option. You only have to define the native query option:
...
If you use the native query option without specifying resultClass, you will receive an object array in the message body.
Example
See Tracer Example for an example using JPA to store traced messages into a database.
...
First we need to setup a persistence-unit
in the persistence.xml file: Wiki Markup org.springframework.orm.jpa.JpaTemplate
which is used by the org.apache.camel.processor.idempotent.jpa.JpaMessageIdRepository
: Wiki Markup org.apache.camel.processor.idempotent.jpa.JpaMessageIdRepository
: Wiki Markup
...
...
In case you run the tests of this component directly inside your IDE (and not necessarily through Maven itself) then you could spot exceptions like:
...
...
The problem here is that the source has been compiled/recompiled through your IDE and not through Maven itself which would enhance the byte-code at build time. To overcome this you would need to enable dynamic byte-code enhancement of OpenJPA. As an example assuming the current OpenJPA version being used in Camel itself is 2.2.1, then as running the tests inside your favorite IDE you would need to pass the following argument to the JVM:
...
Then it will all become green again
...