Infinispan Embedded
Since Camel 2.13
Both producer and consumer are supported
This component allows you to interact with Infinispan distributed data grid / cache. Infinispan is an extremely scalable, highly available key/value data store and data grid platform written in Java.
The camel-infinispan-embedded
component includes the following features:
-
Local Camel Consumer - Receives cache change notifications and sends them to be processed. This can be done synchronously or asynchronously, and is also supported with a replicated or distributed cache.
-
Local Camel Producer - A producer creates and sends messages to an endpoint. The
camel-infinispan
producer usesGET
,PUT
,REMOVE
, andCLEAR
operations. The local producer is also supported with a replicated or distributed cache.
The events are processed asynchronously.
If you use Maven, you must add the following dependency to your pom.xml
:
<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-infinispan-embedded</artifactId>
<version>x.x.x</version>
<!-- use the same version as your Camel core version -->
</dependency>
URI format
infinispan-embedded://cacheName?[options]
The producer allows sending messages to a local infinispan cache. The consumer allows listening for events from local infinispan cache.
If no cache configuration is provided, embedded cacheContainer is created directly in the component.
Configuring Options
Camel components are configured on two separate levels:
-
component level
-
endpoint level
Configuring Component Options
The component level is the highest level which holds general and common configurations that are inherited by the endpoints. For example a component may have security settings, credentials for authentication, urls for network connection and so forth.
Some components only have a few options, and others may have many. Because components typically have pre configured defaults that are commonly used, then you may often only need to configure a few options on a component; or none at all.
Configuring components can be done with the Component DSL, in a configuration file (application.properties|yaml), or directly with Java code.
Configuring Endpoint Options
Where you find yourself configuring the most is on endpoints, as endpoints often have many options, which allows you to configure what you need the endpoint to do. The options are also categorized into whether the endpoint is used as consumer (from) or as a producer (to), or used for both.
Configuring endpoints is most often done directly in the endpoint URI as path and query parameters. You can also use the Endpoint DSL and DataFormat DSL as a type safe way of configuring endpoints and data formats in Java.
A good practice when configuring options is to use Property Placeholders, 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.
The following two sections lists all the options, firstly for the component followed by the endpoint.
Component Options
The Infinispan Embedded component supports 20 options, which are listed below.
Name | Description | Default | Type |
---|---|---|---|
Component configuration. |
InfinispanEmbeddedConfiguration |
||
Specifies the query builder. |
InfinispanQueryBuilder |
||
Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. |
false |
boolean |
|
If true, the listener will be installed for the entire cluster. |
false |
boolean |
|
Returns the custom listener in use, if provided. |
InfinispanEmbeddedCustomListener |
||
Specifies the set of event types to register by the consumer.Multiple event can be separated by comma. The possible event types are: CACHE_ENTRY_ACTIVATED, CACHE_ENTRY_PASSIVATED, CACHE_ENTRY_VISITED, CACHE_ENTRY_LOADED, CACHE_ENTRY_EVICTED, CACHE_ENTRY_CREATED, CACHE_ENTRY_REMOVED, CACHE_ENTRY_MODIFIED, TRANSACTION_COMPLETED, TRANSACTION_REGISTERED, CACHE_ENTRY_INVALIDATED, CACHE_ENTRY_EXPIRED, DATA_REHASHED, TOPOLOGY_CHANGED, PARTITION_STATUS_CHANGED, PERSISTENCE_AVAILABILITY_CHANGED. |
String |
||
If true, the consumer will receive notifications synchronously. |
true |
boolean |
|
Set a specific default value for some producer operations. |
Object |
||
Set a specific key for producer operations. |
Object |
||
Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. |
false |
boolean |
|
Set a specific old value for some producer operations. |
Object |
||
The operation to perform. Enum values:
|
PUT |
InfinispanOperation |
|
Set a specific value for producer operations. |
Object |
||
Whether autowiring is enabled. This is used for automatic autowiring options (the option must be marked as autowired) by looking up in the registry to find if there is a single instance of matching type, which then gets configured on the component. This can be used for automatic configuring JDBC data sources, JMS connection factories, AWS Clients, etc. |
true |
boolean |
|
Autowired Specifies the cache Container to connect. |
EmbeddedCacheManager |
||
Autowired The CacheContainer configuration. Used if the cacheContainer is not defined. |
Configuration |
||
An implementation specific URI for the CacheManager. |
String |
||
A comma separated list of org.infinispan.context.Flag to be applied by default on each cache invocation. |
String |
||
Set a specific remappingFunction to use in a compute operation. |
BiFunction |
||
Store the operation result in a header instead of the message body. By default, resultHeader == null and the query result is stored in the message body, any existing content in the message body is discarded. If resultHeader is set, the value is used as the name of the header to store the query result and the original message body is preserved. This value can be overridden by an in message header named: CamelInfinispanOperationResultHeader. |
String |
Endpoint Options
The Infinispan Embedded endpoint is configured using URI syntax:
infinispan-embedded:cacheName
with the following path and query parameters:
Query Parameters (20 parameters)
Name | Description | Default | Type |
---|---|---|---|
Specifies the query builder. |
InfinispanQueryBuilder |
||
If true, the listener will be installed for the entire cluster. |
false |
boolean |
|
Returns the custom listener in use, if provided. |
InfinispanEmbeddedCustomListener |
||
Specifies the set of event types to register by the consumer.Multiple event can be separated by comma. The possible event types are: CACHE_ENTRY_ACTIVATED, CACHE_ENTRY_PASSIVATED, CACHE_ENTRY_VISITED, CACHE_ENTRY_LOADED, CACHE_ENTRY_EVICTED, CACHE_ENTRY_CREATED, CACHE_ENTRY_REMOVED, CACHE_ENTRY_MODIFIED, TRANSACTION_COMPLETED, TRANSACTION_REGISTERED, CACHE_ENTRY_INVALIDATED, CACHE_ENTRY_EXPIRED, DATA_REHASHED, TOPOLOGY_CHANGED, PARTITION_STATUS_CHANGED, PERSISTENCE_AVAILABILITY_CHANGED. |
String |
||
If true, the consumer will receive notifications synchronously. |
true |
boolean |
|
Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. |
false |
boolean |
|
To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this option is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored. |
ExceptionHandler |
||
Sets the exchange pattern when the consumer creates an exchange. Enum values:
|
ExchangePattern |
||
Set a specific default value for some producer operations. |
Object |
||
Set a specific key for producer operations. |
Object |
||
Set a specific old value for some producer operations. |
Object |
||
The operation to perform. Enum values:
|
PUT |
InfinispanOperation |
|
Set a specific value for producer operations. |
Object |
||
Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. |
false |
boolean |
|
Autowired Specifies the cache Container to connect. |
EmbeddedCacheManager |
||
Autowired The CacheContainer configuration. Used if the cacheContainer is not defined. |
Configuration |
||
An implementation specific URI for the CacheManager. |
String |
||
A comma separated list of org.infinispan.context.Flag to be applied by default on each cache invocation. |
String |
||
Set a specific remappingFunction to use in a compute operation. |
BiFunction |
||
Store the operation result in a header instead of the message body. By default, resultHeader == null and the query result is stored in the message body, any existing content in the message body is discarded. If resultHeader is set, the value is used as the name of the header to store the query result and the original message body is preserved. This value can be overridden by an in message header named: CamelInfinispanOperationResultHeader. |
String |
Message Headers
The Infinispan Embedded component supports 22 message header(s), which is/are listed below:
Name | Description | Default | Type |
---|---|---|---|
CamelInfinispanEventType (consumer) Constant: |
The type of the received event. |
String |
|
CamelInfinispanIsPre (consumer) Constant: |
true if the notification is before the event has occurred, false if after the event has occurred. |
boolean |
|
CamelInfinispanCacheName (common) Constant: |
The cache participating in the operation or event. |
String |
|
Constant: |
The key to perform the operation to or the key generating the event. |
Object |
|
CamelInfinispanValue (producer) Constant: |
The value to use for the operation. |
Object |
|
CamelInfinispanDefaultValue (producer) Constant: |
The default value to use for a getOrDefault. |
Object |
|
CamelInfinispanOldValue (producer) Constant: |
The old value to use for a replace. |
Object |
|
Constant: |
A Map to use in case of CamelInfinispanOperationPutAll operation. |
Map |
|
CamelInfinispanOperation (producer) Constant: |
The operation to perform. Enum values:
|
InfinispanOperation |
|
CamelInfinispanOperationResult (producer) Constant: |
The name of the header whose value is the result. |
String |
|
CamelInfinispanOperationResultHeader (producer) Constant: |
Store the operation result in a header instead of the message body. |
String |
|
CamelInfinispanLifespanTime (producer) Constant: |
The Lifespan time of a value inside the cache. Negative values are interpreted as infinity. |
long |
|
CamelInfinispanTimeUnit (producer) Constant: |
The Time Unit of an entry Lifespan Time. Enum values:
|
TimeUnit |
|
CamelInfinispanMaxIdleTime (producer) Constant: |
The maximum amount of time an entry is allowed to be idle for before it is considered as expired. |
long |
|
CamelInfinispanMaxIdleTimeUnit (producer) Constant: |
The Time Unit of an entry Max Idle Time. Enum values:
|
TimeUnit |
|
CamelInfinispanIgnoreReturnValues (consumer) Constant: |
Signals that a write operation’s return value will be ignored, so reading the existing value from a store or from a remote node is not necessary. |
false |
boolean |
CamelInfinispanEventData (consumer) Constant: |
The event data. |
Object |
|
CamelInfinispanQueryBuilder (producer) Constant: |
The QueryBuilder to use for QUERY command, if not present the command defaults to InifinispanConfiguration’s one. |
InfinispanQueryBuilder |
|
CamelInfinispanCommandRetried (consumer) Constant: |
This will be true if the write command that caused this had to be retried again due to a topology change. |
boolean |
|
CamelInfinispanEntryCreated (consumer) Constant: |
Indicates whether the cache entry modification event is the result of the cache entry being created. |
boolean |
|
CamelInfinispanOriginLocal (consumer) Constant: |
true if the call originated on the local cache instance; false if originated from a remote one. |
boolean |
|
CamelInfinispanCurrentState (consumer) Constant: |
True if this event is generated from an existing entry as the listener has Listener. |
boolean |
Camel Operations
This section lists all available operations, along with their header information.
Operation Name | Description |
---|---|
InfinispanOperation.PUT |
Puts a key/value pair in the cache, optionally with expiration |
InfinispanOperation.PUTASYNC |
Asynchronously puts a key/value pair in the cache, optionally with expiration |
InfinispanOperation.PUTIFABSENT |
Puts a key/value pair in the cache if it did not exist, optionally with expiration |
InfinispanOperation.PUTIFABSENTASYNC |
Asynchronously puts a key/value pair in the cache if it did not exist, optionally with expiration |
-
Required Headers:
-
CamelInfinispanKey
-
CamelInfinispanValue
-
-
Optional Headers:
-
CamelInfinispanLifespanTime
-
CamelInfinispanLifespanTimeUnit
-
CamelInfinispanMaxIdleTime
-
CamelInfinispanMaxIdleTimeUnit
-
-
Result Header:
-
CamelInfinispanOperationResult
-
Operation Name | Description |
---|---|
InfinispanOperation.PUTALL |
Adds multiple entries to a cache, optionally with expiration |
CamelInfinispanOperation.PUTALLASYNC |
Asynchronously adds multiple entries to a cache, optionally with expiration |
-
Required Headers:
-
CamelInfinispanMap
-
-
Optional Headers:
-
CamelInfinispanLifespanTime
-
CamelInfinispanLifespanTimeUnit
-
CamelInfinispanMaxIdleTime
-
CamelInfinispanMaxIdleTimeUnit
-
Operation Name | Description |
---|---|
InfinispanOperation.GET |
Retrieves the value associated with a specific key from the cache |
InfinispanOperation.GETORDEFAULT |
Retrieves the value, or default value, associated with a specific key from the cache |
-
Required Headers:
-
CamelInfinispanKey
-
Operation Name | Description |
---|---|
InfinispanOperation.CONTAINSKEY |
Determines whether a cache contains a specific key |
-
Required Headers
-
CamelInfinispanKey
-
-
Result Header
-
CamelInfinispanOperationResult
-
Operation Name | Description |
---|---|
InfinispanOperation.CONTAINSVALUE |
Determines whether a cache contains a specific value |
-
Required Headers:
-
CamelInfinispanKey
-
Operation Name | Description |
---|---|
InfinispanOperation.REMOVE |
Removes an entry from a cache, optionally only if the value matches a given one |
InfinispanOperation.REMOVEASYNC |
Asynchronously removes an entry from a cache, optionally only if the value matches a given one |
-
Required Headers:
-
CamelInfinispanKey
-
-
Optional Headers:
-
CamelInfinispanValue
-
-
Result Header:
-
CamelInfinispanOperationResult
-
Operation Name | Description |
---|---|
InfinispanOperation.REPLACE |
Conditionally replaces an entry in the cache, optionally with expiration |
InfinispanOperation.REPLACEASYNC |
Asynchronously conditionally replaces an entry in the cache, optionally with expiration |
-
Required Headers:
-
CamelInfinispanKey
-
CamelInfinispanValue
-
CamelInfinispanOldValue
-
-
Optional Headers:
-
CamelInfinispanLifespanTime
-
CamelInfinispanLifespanTimeUnit
-
CamelInfinispanMaxIdleTime
-
CamelInfinispanMaxIdleTimeUnit
-
-
Result Header:
-
CamelInfinispanOperationResult
-
Operation Name | Description |
---|---|
InfinispanOperation.CLEAR |
Clears the cache |
InfinispanOperation.CLEARASYNC |
Asynchronously clears the cache |
Operation Name | Description |
---|---|
InfinispanOperation.SIZE |
Returns the number of entries in the cache |
-
Result Header
-
CamelInfinispanOperationResult
-
Operation Name | Description |
---|---|
InfinispanOperation.STATS |
Returns statistics about the cache |
-
Result Header:
-
CamelInfinispanOperationResult
-
Operation Name | Description |
---|---|
InfinispanOperation.QUERY |
Executes a query on the cache |
-
Required Headers:
-
CamelInfinispanQueryBuilder
-
-
Result Header:
-
CamelInfinispanOperationResult
-
Write methods like put(key, value) and remove(key) do not return the previous value by default. |
Examples
-
Put a key/value into a named cache:
from("direct:start") .setHeader(InfinispanConstants.OPERATION).constant(InfinispanOperation.PUT) (1) .setHeader(InfinispanConstants.KEY).constant("123") (2) .to("infinispan:myCacheName&cacheContainer=#cacheContainer"); (3)
1 Set the operation to perform 2 Set the key used to identify the element in the cache 3 Use the configured cache manager cacheContainer
from the registry to put an element to the cache namedmyCacheName
It is possible to configure the lifetime and/or the idle time before the entry expires and gets evicted from the cache, as example:
from("direct:start") .setHeader(InfinispanConstants.OPERATION).constant(InfinispanOperation.GET) .setHeader(InfinispanConstants.KEY).constant("123") .setHeader(InfinispanConstants.LIFESPAN_TIME).constant(100L) (1) .setHeader(InfinispanConstants.LIFESPAN_TIME_UNIT.constant(TimeUnit.MILLISECONDS.toString()) (2) .to("infinispan:myCacheName");
1 Set the lifespan of the entry 2 Set the time unit for the lifespan -
Queries
from("direct:start") .setHeader(InfinispanConstants.OPERATION, InfinispanConstants.QUERY) .setHeader(InfinispanConstants.QUERY_BUILDER, new InfinispanQueryBuilder() { @Override public Query build(QueryFactory<Query> qf) { return qf.from(User.class).having("name").like("%abc%").build(); } }) .to("infinispan:myCacheName?cacheContainer=#cacheManager") ;
-
Custom Listeners
from("infinispan://?cacheContainer=#cacheManager&customListener=#myCustomListener") .to("mock:result");
The instance of
myCustomListener
must exist and Camel should be able to look it up from theRegistry
. Users are encouraged to extend theorg.apache.camel.component.infinispan.embedded.InfinispanEmbeddedCustomListener
class and annotate the resulting class with@Listener
which can be found found in packageorg.infinispan.notifications
.
Using the Infinispan based idempotent repository
In this section we will use the Infinispan based idempotent repository.
InfinispanEmbeddedConfiguration conf = new InfinispanEmbeddedConfiguration(); (1)
conf.setConfigurationUri("classpath:infinispan.xml")
InfinispanEmbeddedIdempotentRepository repo = new InfinispanEmbeddedIdempotentRepository("idempotent"); (2)
repo.setConfiguration(conf);
context.addRoutes(new RouteBuilder() {
@Override
public void configure() {
from("direct:start")
.idempotentConsumer(header("MessageID"), repo) (3)
.to("mock:result");
}
});
1 | Configure the cache |
2 | Configure the repository bean |
3 | Set the repository to the route |
<bean id="infinispanRepo" class="org.apache.camel.component.infinispan.embedded.InfinispanEmbeddedIdempotentRepository" destroy-method="stop">
<constructor-arg value="idempotent"/> (1)
<property name="configuration"> (2)
<bean class="org.apache.camel.component.infinispan.embedded.InfinispanEmbeddedConfiguration">
<property name="configurationUrl" value="classpath:infinispan.xml"/>
</bean>
</property>
</bean>
<camelContext xmlns="http://camel.apache.org/schema/spring">
<route>
<from uri="direct:start" />
<idempotentConsumer idempotentRepository="infinispanRepo"> (3)
<header>MessageID</header>
<to uri="mock:result" />
</idempotentConsumer>
</route>
</camelContext>
1 | Set the name of the cache that will be used by the repository |
2 | Configure the repository bean |
3 | Set the repository to the route |
Using the Infinispan based aggregation repository
In this section we will use the Infinispan based aggregation repository.
InfinispanEmbeddedConfiguration conf = new InfinispanEmbeddedConfiguration(); (1)
conf.setConfigurationUri("classpath:infinispan.xml")
InfinispanEmbeddedAggregationRepository repo = new InfinispanEmbeddedAggregationRepository("aggregation"); (2)
repo.setConfiguration(conf);
context.addRoutes(new RouteBuilder() {
@Override
public void configure() {
from("direct:start")
.aggregate(header("MessageID"))
.completionSize(3)
.aggregationRepository(repo) (3)
.aggregationStrategy("myStrategy")
.to("mock:result");
}
});
1 | Configure the cache |
2 | Create the repository bean |
3 | Set the repository to the route |
<bean id="infinispanRepo" class="org.apache.camel.component.infinispan.embedded.InfinispanEmbeddedAggregationRepository" destroy-method="stop">
<constructor-arg value="aggregation"/> (1)
<property name="configuration"> (2)
<bean class="org.apache.camel.component.infinispan.embedded.InfinispanEmbeddedConfiguration">
<property name="configurationUrl" value="classpath:infinispan.xml"/>
</bean>
</property>
</bean>
<camelContext xmlns="http://camel.apache.org/schema/spring">
<route>
<from uri="direct:start" />
<aggregate aggregationStrategy="myStrategy"
completionSize="3"
aggregationRepository="infinispanRepo"> (3)
<correlationExpression>
<header>MessageID</header>
</correlationExpression>
<to uri="mock:result"/>
</aggregate>
</route>
</camelContext>
1 | Set the name of the cache that will be used by the repository |
2 | Configure the repository bean |
3 | Set the repository to the route |
With the release of Infinispan 11, it is required to set the encoding configuration on any cache created. This is critical for consuming events too. For more information have a look at Data Encoding and MediaTypes in the official Infinispan documentation. |
Spring Boot Auto-Configuration
When using infinispan-embedded with Spring Boot make sure to use the following Maven dependency to have support for auto configuration:
<dependency>
<groupId>org.apache.camel.springboot</groupId>
<artifactId>camel-infinispan-embedded-starter</artifactId>
<version>x.x.x</version>
<!-- use the same version as your Camel core version -->
</dependency>
The component supports 17 options, which are listed below.